# MatGL: a graph deep learning library for interatomic potentials and property prediction

> MatGL is a Python graph deep learning library for materials science, hosting M3GNet, MEGNet, TensorNet, SO3Net, CHGNet and the charge-equilibrated QET architectures with pre-trained weights served from Hugging Face. It suits a computational materials researcher who wants a maintained surrogate model rather than a from-scratch implementation, and it is PyTorch Geometric only since version 3.

**materialyzeai/matgl** — Graph deep learning library for materials

- Repository: https://github.com/materialyzeai/matgl
- Stars: 578 · Forks: 121
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/materialyzeai-matgl

## Why a graph is the right shape for a crystal

MatGL is a graph deep learning library for materials science, and the premise is that mathematical graphs are a natural representation for a collection of atoms.

That premise is doing real work in the library's design. A crystal is a periodic arrangement, so it is not naturally a flat list of atoms, and the graph representation has to carry both the connectivity and the cell. M3GNet adds the atom coordinates and the 3 by 3 lattice matrix to the crystal graph, and those extra terms are what make tensorial outputs such as forces and stresses reachable through auto-differentiation. Without the lattice in the input, a model can predict an energy but not the derivative of that energy with respect to position, which is the whole point of an interatomic potential.

The stated purpose of the project is to serve as an extensible platform to develop and share materials graph deep learning models. That phrasing is deliberate: the goal is not one model but a place where models live, which is why the README stresses that the architecture list is by no means exhaustive and that new architectures are expected from the core team and from contributors.

The first version was a collaboration between Materialyze.AI and Intel Labs, and the author list in the project metadata reflects that mix, with contributors from UC San Diego, Intel, Berkeley and the National University of Singapore. The library sits inside a wider set of packages: MatGL for the graph models, maml for materials machine learning, the MatPES dataset for potential energy surfaces, and MatCalc as a materials calculator.

The primary language is Python, the licence is BSD-3-Clause, and the current version in the project metadata is 4.1.0, with a release of the same number on 2026-09-30.

## The architectures, and what each one is for

The README documents the currently implemented architectures, and they differ in ways that matter for a research task rather than in ways that are easy to summarise.

QET, pronounced as ket, is a charge-equilibrated TensorNet architecture. It is an equivariant, charge-aware architecture that reaches linear scaling with system size through an analytically solvable charge-equilibration scheme. A pre-trained QET-MatQ FP is available, and it is described as matching state of the art FPs on standard materials property benchmarks while giving qualitatively different predictions in systems dominated by charge transfer, with NaCl-CaCl2 ionic liquid and reactive processes at the Li/Li6PS5Cl solid-electrolyte interface named as cases, and it supports simulations under applied electrochemical potentials.

TensorNet is an O(3)-equivariant message-passing neural network using Cartesian tensor representations, and it generalises SO3Net, which is a minimalist SO(3)-equivariant network. The README states that TensorNet has been shown to be much more data and parameter efficient than other equivariant architectures, and that it is the default architecture used in the Materials Virtual Lab.

CHGNet is a graph neural network machine learning interatomic potential that uses atom graphs to capture atom bond relations and a bond graph to capture angular information, specialising in capturing atomic charges by learning and predicting DFT atomic magnetic moments. M3GNet is an invariant graph neural network incorporating three-body interactions, and its key feature is a foundation potential trained on relaxations performed in the Materials Project that works across the entire periodic table of the elements. MEGNet, the Materials Graph Network, is listed alongside it.

The pattern across all of them is that equivariance is the organising idea. An equivariant architecture respects the symmetry of rotating a crystal, so a prediction cannot depend on how the input happened to be oriented. That is what lets these models generalise across chemical spaces rather than memorising a fixed set of reference structures.

## The v3.0.0 message-passing fix, and why old checkpoints are dead

The major update section is the most consequential thing in the README for anyone with an existing workflow, and it is a breaking change in both the API and the model weights.

DGL support was removed. matgl now targets PyTorch Geometric exclusively, and models that previously had only DGL implementations have either been ported to PyG or removed. The v2.0.0 milestone already made the PYG backend the default, so v3.0.0 finished a migration that had been running for a year.

The second half is harder to absorb. A bug in the message-passing convention of TensorNet, M3GNet and QET was corrected: edge messages are now aggregated onto the source, or center, node, so each atom correctly collects information from its neighbors. Pre-trained weights generated under the old convention are no longer numerically valid.

That is a hard break, not a deprecation. A checkpoint from before May 2026 will produce wrong numbers rather than an error, which is the worst kind of failure in a surrogate model, because the output still looks plausible. The release notes state that new weights, including TensorNet-PES-MatPES-PBE-2025.2 and the PyG M3GNet and QET potentials, have been retrained against the corrected convention and uploaded to the materialyze Hugging Face org, which is now the canonical and only source for matgl pre-trained models. The legacy GitHub pretrained_models/ download fallback, with RemoteFile and PRETRAINED_MODELS_BASE_URL, was removed in this release.

So there is no migration path for old weights. The download fallback that used to smooth over the missing Hugging Face integration is gone, and the model host has changed in the same release.

## Installing MatGL, and the dependency surface it drags in

The package builds as a standard Python distribution and is published on PyPI under the name matgl, with the project metadata declaring Python 3.11 or later and the build backend as setuptools.

```toml
[project]
name = "matgl"
```

The runtime dependencies tell you what a graph deep learning stack for materials actually requires, and it is a long list. The project metadata lists ase for atomic simulation environment, torch, torchdata, lightning at 2.6.6 or later, pydantic, boto3, numpy, torch-geometric, pymatgen-core at 2026.5.18 or later, and huggingface_hub at 0.24 or later.

Three of those deserve attention. torch-geometric is the graph framework the whole library now rests on, so the DGL removal moved that dependency out of the optional column and into the mandatory one. pymatgen-core is the materials data layer, providing structures, lattices and the chemical space that the graphs are built from. And boto3 alongside huggingface_hub is the model distribution story: the weights come from Hugging Face, and the S3 client is there for the data path.

The build system pins the oldest-supported-numpy as the NumPy version used during the build, with setuptools 58.0.3 or later, which is a common way to avoid a NumPy 2 build failure on an older toolchain.

The project also installs a console entry point, which the metadata defines as mgl pointing at matgl.cli:main. That gives you a command line tool alongside the library, and it is worth knowing it exists before you write a script that duplicates it.

The examples directory is where the workflow shows up. The notebooks cover benchmarking M3GNet predictions of cubic lattice parameters, running relaxations and simulations with the M3GNet universal potential, combining the M3GNet universal potential with property prediction models, fine-tuning a potential on a customised dataset with DIRECT sampling, training with PyTorch Lightning for formation energy, band gap and multi-fidelity models, training a QET potential, and using LAMMPS with MatGL.

## The repo layout, and the development tooling around it

The repository is a src layout Python project with a task runner rather than a bare package.

The top-level entries include src/ for the package, tests/, docs/, examples/, assets/ for images such as the MatGL logo and the MxGNet schematic, dev/, scripts/, and a tasks.py file, which indicates an invoke-style task runner. There is also a pyproject.toml, a uv.lock, a .python-version file, a pylintrc, a .pre-commit-config.yaml and a .codespellrc, so the project pins its tooling rather than leaving each contributor to choose.

The .pre-commit-config.yaml, the pylintrc and the codespell configuration together describe a project that treats code review and lint as part of the build. The README carries three separate badges for this: a Lint badge for the lint workflow, a Test badge for the test workflow, and a codecov badge for coverage on the main branch. There is a CITATION.cff file, which means the project supports formal citation of its code, the normal expectation for a research library that papers depend on.

Two directories outside the package are worth calling out. lammps/ holds the LAMMPS integration, and examples/ includes an NVT molecular dynamics notebook with TensorNet and the nvalchemi toolkit, alongside a dedicated notebook on using LAMMPS with MatGL. The LAMMPS coupling is the point where the library stops being a standalone predictor and becomes a potential inside an existing simulation stack, which is how these models are used for relaxation and molecular dynamics in practice.

The development documentation is split across developer.md and CLAUDE.md, and the CONTRIBUTING-style guidance for external contributors is not part of the README. The last push was on 2026-10-20, two days before the version of this material, and the release cadence of v4.0.2, v4.0.3 and v4.1.0 across June, July and September 2026 shows a project moving quickly.

## MatGL against training your own graph potential

The alternative is to write the model yourself, and in a field where architectures appear regularly, that is a real option rather than a straw man.

The difference in approach is about what you inherit. Training your own means you choose the message-passing scheme, the atom featurisation, the readout, the loss, the dataset split and the training schedule, and you own every one of those decisions along with the debugging. MatGL hands you a set of architectures that have already been trained, retrained after the v3.0.0 correction, and validated against standard benchmarks, plus the data plumbing around them.

What you give up with that shortcut is control over the physics and the training. The README is direct that the architecture list is not exhaustive and that contributions are expected, which is a good sign for the codebase, but a contributed model still has to fit the framework's conventions rather than your own. And the pre-trained weights constrain where you can start: the M3GNet foundation potential works across the periodic table, which is exactly what you want for exploration and exactly what you do not want if your target property is off-distribution.

The other alternative is to use one of the original implementations directly, and for CHGNet the README links the original implementation, which is the reference code for that specific architecture. The difference there is maintenance and packaging: the original is a standalone project with its own dependencies and its own release cadence, while the MatGL port gives you a consistent interface across architectures and a single model host. The trade is real for reproduction, where matching the exact published implementation matters more than having a uniform API.

The honest framing of the library's own ambition is the extensible platform. If your goal is to publish a new materials graph model, MatGL gives you the data structures, the training conventions and a distribution channel for weights. If your goal is to run one model on one dataset, it may be more machinery than you need, and the older original implementations are often lighter.

## Conclusion

MatGL fits a computational materials scientist who wants a maintained implementation of an interatomic potential or a property surrogate with pre-trained weights, and it does not fit someone whose pipeline is built on the DGL backend, since support was removed in v3.0.0 and models that had only DGL implementations were ported or dropped. Before adopting a checkpoint, check its release: the v3.0.0 correction to the message-passing convention invalidated the older pre-trained weights, so anything downloaded before that release has to be replaced with the retrained models on the materialyze Hugging Face organisation.

## FAQ

### What is MatGL and which model architectures does it include?

MatGL is a graph deep learning library for materials science. The documented architectures are QET, a charge-equilibrated and charge-aware equivariant network, TensorNet and its generalisation of SO3Net, CHGNet for interatomic potentials with atomic charges, and M3GNet and MEGNet for property prediction.

### Where do I download MatGL pre-trained models?

The materialyze organisation on Hugging Face is now the canonical and only source for matgl pre-trained models. The legacy GitHub pretrained_models/ download fallback, with RemoteFile and PRETRAINED_MODELS_BASE_URL, was removed in the v3.0.0 release.

### Does MatGL still support DGL?

No. The v3.0.0 release removed DGL support and matgl now targets PyTorch Geometric exclusively. Models that previously had only DGL implementations have either been ported to PyG or removed, and the PYG backend had already become the default in v2.0.0.

### What Python version and dependencies does MatGL need?

The project metadata requires Python 3.11 or later, and lists ase, torch, torchdata, lightning 2.6.6 or later, pydantic, boto3, numpy, torch-geometric, pymatgen-core 2026.5.18 or later, and huggingface_hub 0.24 or later as runtime dependencies.

### Which MatGL release fixed the message-passing convention?

Version 3.0.0, released in May 2026, corrected the convention so edge messages are aggregated onto the source node. Weights trained under the old convention are no longer numerically valid, so checkpoints from before that release must be replaced with the retrained models.

## Sources

- [Issues](https://github.com/materialyzeai/matgl/issues)
- [License: BSD-3-Clause](https://github.com/materialyzeai/matgl/blob/main/LICENSE)
- [materialyzeai/matgl on GitHub](https://github.com/materialyzeai/matgl)
- [README](https://github.com/materialyzeai/matgl/blob/main/README.md)
- [Releases](https://github.com/materialyzeai/matgl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/materialyzeai-matgl