Skip to main content
maml

GitHub license Linting Testing Downloads codecov

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.

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.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maml 2026.11.12
File Size Uploaded Provenance Actions
maml-2026.11.12.tar.gz 2.2 MB With provenance Details for maml-2026.11.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maml 2026.11.12
File Interpreter ABI Platform Actions
maml-2026.11.12-py3-none-any.whl Python 3 none any Details for maml-2026.11.12-py3-none-any.whl

Total release size: 4.5 MB

Release files / maml-2026.11.12.tar.gz

Download URL maml-2026.11.12.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
09a4bd6bd730a1001bffbf25a5099b93e0c04c78703530b170ed75d568bae5cc
BLAKE2b-256 checksum
How to use checksums
5373927bdd57f515f49ae81c6a1b3bce13dbb0556cdd862a304ceac27d8dee4e
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 12, 2026.

Transparency log

Release files / maml-2026.11.12-py3-none-any.whl

Download URL maml-2026.11.12-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
45431262739004f7e2520c558c2a4e2b129fe1732813d1cded0d6f896785ff7d
BLAKE2b-256 checksum
How to use checksums
d4e7fb615f4b6af68ed0eced3286e6e617a06c4809741c8788cf43d6a1be20a8
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 12, 2026.

Transparency log

Security for maml 2026.11.12

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.

Select from 2 files

Attestation for maml-2026.11.12.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 12, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page