maml (MAterials Machine Learning) provides high-level interfaces that make machine learning for materials science as easy as possible. It does not reimplement ML algorithms. Instead, it builds on scikit-learn, TensorFlow and MatGL for models, and on pymatgen and matminer for structure handling and featurization.
- Documentation: https://materialyzeai.github.io/maml/
- API reference: https://materialyzeai.github.io/maml/maml.html
- Example notebooks: notebooks
- Tutorial lecture and hosted tool: nanoHUB
Features
| Module | What it does |
|---|---|
maml.describers |
Convert compositions, sites and structures into features: element statistics, Coulomb matrices, radial distribution functions, bispectrum coefficients, Behler-Parrinello symmetry functions, SOAP, and graph-network (MatGL, MEGNet, M3GNet) embeddings. Any matminer featurizer can be wrapped with wrap_matminer_describer. |
maml.models |
Describer-aware wrappers around scikit-learn (SKLModel) and Keras (KerasModel, MLP) models, plus the AtomSets transfer-learning architecture. |
maml.sampling |
DIRECT (DImensionality REduction-Clustering-sTratified) sampling for selecting robust, diverse training sets from large configuration spaces. |
maml.apps.pes |
Fit and evaluate machine-learning interatomic potentials: SNAP/qSNAP, GAP, MTP and NNP, with LAMMPS-based property calculators (elastic constants, lattice constants, defect formation, NEB). |
maml.apps.bowsr |
BOWSR: Bayesian optimization with a surrogate energy model for DFT-free structure relaxation. |
maml.apps.gbe |
Machine-learning model for elemental grain boundary energies. |
maml.apps.symbolic |
Symbolic regression and sparse feature selection: SIS/ISIS, LASSO, adaptive LASSO, SCAD, Dantzig selector and L0 search. |
Installation
pip install maml
Or, with uv:
uv add maml
Optional extras:
pip install "maml[symbolic]" # cvxpy, for maml.apps.symbolic
pip install "maml[deep]" # TensorFlow, for Keras models and AtomSets
maml.apps.pes drives external codes, which must be installed separately and be on your PATH:
| Potential | Required code |
|---|---|
| All potentials (property calculations) | LAMMPS (conda install -c conda-forge lammps) |
| SNAP / qSNAP | LAMMPS (built in) |
| GAP | QUIP with the GAP package, and LAMMPS built with ML-QUIP |
| MTP | MLIP-3 (default; MLIP-2 via MTPotential(version="mlip-2")). LAMMPS-based MTP calculations currently require MLIP-2 and its LAMMPS interface |
| NNP | n2p2 |
Development
git clone https://github.com/materialyzeai/maml.git
cd maml
uv sync --group lint
uv run pytest tests
Quick start
Train a composition model with scikit-learn:
from pymatgen.core import Composition
from sklearn.linear_model import LinearRegression
from maml.describers import ElementStats
from maml.models import SKLModel
describer = ElementStats.from_data("megnet_3", stats=["mean", "std"])
model = SKLModel(describer=describer, model=LinearRegression())
compositions = [Composition(c) for c in ["Li2O", "Na2O", "K2O", "MgO", "CaO"]]
targets = [-2.07, -1.40, -1.13, -3.08, -3.27] # formation energies, eV/atom
model.train(compositions, targets)
print(model.predict_objs([Composition("SrO")]))
See the notebooks for worked examples of each module.
Citing
If you use maml, please cite:
@misc{maml,
author = {Chen, Chi and Zuo, Yunxing and Ye, Weike and Qi, Ji and Ong, Shyue Ping},
title = {{maml - materials machine learning package}},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/materialyzeai/maml}},
}
Please also cite the paper for the module you use:
- ML-IAPs (
maml.apps.pes): Zuo, Y.; Chen, C.; Li, X.; Deng, Z.; Chen, Y.; Behler, J.; Csányi, G.; Shapeev, A. V.; Thompson, A. P.; Wood, M. A.; Ong, S. P. Performance and Cost Assessment of Machine Learning Interatomic Potentials. J. Phys. Chem. A 2020, 124 (4), 731–745. https://doi.org/10.1021/acs.jpca.9b08723 - BOWSR (
maml.apps.bowsr): Zuo, Y.; Qin, M.; Chen, C.; Ye, W.; Li, X.; Luo, J.; Ong, S. P. Accelerating Materials Discovery with Bayesian Optimization and Graph Deep Learning. Mater. Today 2021, 51, 126–135. https://doi.org/10.1016/j.mattod.2021.08.012 - AtomSets (
maml.models.AtomSets): Chen, C.; Ong, S. P. AtomSets as a Hierarchical Transfer Learning Framework for Small and Large Materials Datasets. npj Comput. Mater. 2021, 7, 173. https://doi.org/10.1038/s41524-021-00639-w - DIRECT sampling (
maml.sampling): Qi, J.; Ko, T. W.; Wood, B. C.; Pham, T. A.; Ong, S. P. Robust Training of Machine Learning Interatomic Potentials with Dimensionality Reduction and Stratified Sampling. npj Comput. Mater. 2024, 10, 43. https://doi.org/10.1038/s41524-024-01227-4 - Grain boundary energies (
maml.apps.gbe): Ye, W.; Zheng, H.; Chen, C.; Ong, S. P. A Universal Machine Learning Model for Elemental Grain Boundary Energies. Scr. Mater. 2022, 218, 114803. https://doi.org/10.1016/j.scriptamat.2022.114803
Metadata
Release files for maml 2026.11.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maml-2026.11.17.tar.gz | 2.2 MB | With provenance | Details for maml-2026.11.17.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maml-2026.11.17-py3-none-any.whl | Python 3 | none | any | Details for maml-2026.11.17-py3-none-any.whl |
Total release size: 4.5 MB
Release files / maml-2026.11.17.tar.gz
| Download URL | maml-2026.11.17.tar.gz |
|---|---|
| Size | 2.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69435a0c302585e75b64432b6a1ce53d3aee8eab3eac72ab22dfa6f67aa3ce75
|
|
BLAKE2b-256 checksum How to use checksums |
85c39c78f3e7b15c642eed71a8565add32cdf60ab522485a3d36532cf1fb802b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / maml-2026.11.17-py3-none-any.whl
| Download URL | maml-2026.11.17-py3-none-any.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a7ebb72798f09c179d51642ceff4885fa742e55d417dec9d8ea34122b0acb68
|
|
BLAKE2b-256 checksum How to use checksums |
74cef4bdc528d6f238d1fd658408131458cac60572d45a1ff2e1a1e107b51d86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for maml 2026.11.17
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for maml-2026.11.17.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.