maml: A High-Level Python Layer for Materials Machine Learning

What maml Is Actually For

The README states the goal directly: maml aims to provide high-level interfaces that make ML for materials science as easy as possible, and it explicitly does not try to duplicate functionality available elsewhere. That sentence is the whole design contract. The package is a coordination layer over scikit-learn, TensorFlow, pymatgen and matminer. If you already have a working pymatgen pipeline and you are tired of writing the same conversion code between a Structure object and a feature matrix, maml is aimed at you. If you want a library that owns its own numerical kernels, it is not.

The audience is narrower than the topic list suggests. The features are organised around crystals and molecules, so the natural user is a computational materials scientist or a graduate student who already knows what a bispectrum coefficient is and wants a shorter path from structure files to a trained model. The primary language of the repository is Jupyter Notebook, which tells you how the maintainers expect the package to be learned: through worked examples rather than through reading source. The README points to a notebooks directory and to a tool and tutorial lecture hosted on nanoHUB.

Descriptors, Models and the Three Application Modules

The feature generation layer converts crystals and molecules into numerical representations. Beyond what the README calls common compositional, site and structural features, maml adds four families of local environment descriptors: bispectrum coefficients, Behler Parrinello symmetry functions, Smooth Overlap of Atom Position (SOAP), and graph network features at composition, site and structure level. Those are the descriptors that matter for force fields, because they encode the neighbourhood of each atom rather than a single global fingerprint.

On top of that, the README says the package supports sklearn and keras models. That is the second half of the contract: maml does not ship its own regressor or neural network implementation, it hands your feature matrix to an existing estimator.

The application modules are where the package stops being generic. pes builds surrogate models of the potential energy surface and covers four potential types: Neural Network Potential (NNP), Gaussian approximation potential (GAP) with SOAP features, spectral neighbor analysis potential (SNAP), and Moment Tensor Potential (MTP). rfxas uses random forests to predict atomic local environments from X-ray absorption spectroscopy. bowsr performs rapid structural relaxation with Bayesian optimization over a surrogate energy model. Each of these maps to a separate publication listed in the README, which is a useful signal about how much of the code is research output rather than a settled API.

Installation Is a Package Manager Problem, Not a Python Problem

The base install is one line:

pip install maml

Everything past that is dependency assembly. For the potential energy surface work the README says LAMMPS is required, installable from source or from conda:

conda install -c conda-forge/label/cf202003 lammps

Note the channel label in that command. It pins you to a specific conda-forge build label rather than the default channel, which means the LAMMPS version you get is not necessarily the current one. The README states that the SNAP potential comes with this LAMMPS installation, and that GAP needs the GAP package, MTP needs the MLIP package, and NNP fitting needs n2p2. Those three are external projects with their own build requirements, and maml does not vendor them.

The repository also splits its Python dependencies across several files. The README shows requirements.txt on its own, and then a sequence that installs requirements-ci.txt, requirements-optional.txt, requirements-dl.txt and finally requirements.txt. The ordering in that snippet is worth reading carefully before you copy it, because it is not the order a resolver would pick on its own. Which file you need depends on whether you are running the deep learning models or only the classical estimators.

The Dependency Surface Is the Real Cost

The honest limitation is that maml's useful parts are only as installable as the least installable thing they wrap. A pip install of maml gives you the Python interfaces. It does not give you a working SNAP potential, a compiled MLIP binary or an n2p2 build. If your environment cannot produce those, the pes module is documentation you can read but not run.

This is a deliberate trade-off rather than an oversight. The README frames non-duplication as a goal, and the cost of that goal is that the user absorbs the integration work. The counter-argument is that the alternative, a package that reimplements LAMMPS potentials internally, would be far harder to keep correct.

There is a second limitation that follows from the repository shape. Jupyter Notebook is the primary language, and the README's usage section is essentially a pointer to notebooks and to the nanoHUB lecture rather than a written API walkthrough. The API documentation is generated and hosted separately. For a package whose behaviour depends heavily on which descriptor you choose and how you feed it to which estimator, that puts a lot of weight on the examples being current. The release cadence is uneven: v2023.9.9, then v2024.6.13, then v2025.4.1, with the last push to the default branch in July 2026. A user picking this up should check the notebook against the release they installed rather than assuming they match.

How It Compares to Writing the Pipeline Yourself

The realistic alternative is not another single package. It is assembling pymatgen for structure handling, matminer for featurisation, and scikit-learn or TensorFlow for the model, which is exactly the stack maml sits on. The difference in approach is that matminer exposes featurizers as a registry of named classes you compose yourself, while maml presents a smaller curated set of high-level interfaces aimed at specific materials tasks. Choosing maml means accepting its selection of descriptors and its task modules. Choosing the underlying libraries directly means more assembly code but no intermediate abstraction deciding what is exposed.

For the force field work specifically, the alternative is going straight to the potential implementations: LAMMPS with its SNAP pair style, the GAP package, MLIP, or n2p2, each driven by its own input files. maml's contribution there is the fitting and data preparation layer around them, not the potential evaluation itself. If you already have a working LAMMPS workflow and only need a potential file, maml adds a dependency without removing much work.

For the X-ray absorption spectroscopy case, the alternative is a plain scikit-learn random forest pipeline over your own spectral features. maml.rfxas is worth using only if its feature construction matches the spectra you have.

Licence and Long-Term Maintenance

maml is BSD-3-Clause. That is a permissive licence, and the practical consequence is that you can use it in a proprietary pipeline provided you keep the copyright notice and disclaimer intact. The BSD-3-Clause text also includes a clause restricting use of contributor names for endorsement, which matters if you plan to describe your product as built on this work. This is a description of the licence terms, not legal advice; read the LICENSE file in the repository and get your own counsel for anything that carries commercial weight.

The maintenance cost sits mostly outside the licence. Your upgrade path is bounded by LAMMPS, the GAP package, MLIP and n2p2, not by maml's own release tags. A maml version bump that changes a descriptor interface is a small edit; a LAMMPS rebuild that changes a potential's behaviour can invalidate fitted models. The README's citation list is a reasonable proxy for how the code is organised: the pes module, the bowsr module and the AtomSets model each correspond to a separate paper, so expect those three to move independently rather than as one coherent API surface.

Who Should Adopt maml and What to Check First

Adopt maml if you are already inside the pymatgen and matminer ecosystem, you need local environment descriptors for a supervised model, and you would rather import a prepared interface than write the featurisation plumbing. The sklearn and keras model support means you are not locked into a training framework, which keeps the decision reversible.

Do not adopt it if you need a single self-contained install, if your work depends on a potential type whose backend you cannot build, or if you are looking for a maintained API reference rather than notebooks. The README's usage section points at examples, and the repository's primary language is Jupyter Notebook, so plan to read code.

Before you commit, run the base install and then check which of requirements-ci.txt, requirements-optional.txt and requirements-dl.txt your target module actually needs, since the README's install sequence pulls all of them. If you intend to use pes, confirm that your conda LAMMPS build from the cf202003 label provides the SNAP potential, and confirm you have a working GAP, MLIP or n2p2 installation for whichever potential you plan to fit. If any of those three is missing, that part of the package is not available to you regardless of what pip reports.

Editorial conclusion

Adopt maml if your workflow already sits on pymatgen and matminer and you want one import surface for descriptors and sklearn or keras models. Do not adopt it if you expect a self-contained installer: the pes module needs LAMMPS, plus the GAP package for GAP, the MLIP package for MTP and n2p2 for NNP fitting. Before committing, verify that the conda LAMMPS build you install actually ships the SNAP potential the README says comes with it, and check which requirements file your target module pulls in.

Official sources

1. Issues
2. License: BSD-3-Clause
3. materialyzeai/maml on GitHub
4. README
5. Releases