Materials Graph Library <img src="https://github.com/materialyzeai/matgl/blob/main/assets/MatGL.png?raw=true" alt="matgl" width="30%" style="float: right">

Official Documentation

Introduction

MatGL (Materials Graph Library) is a graph deep learning library for materials science. Mathematical graphs are a natural representation for a collection of atoms. Graph deep learning models have been shown to consistently deliver exceptional performance as surrogate models for the prediction of materials properties. The goal is for MatGL to serve as an extensible platform to develop and share materials graph deep learning models.

This first version of MatGL is a collaboration between the [Materialyze.AI][materialyze] and Intel Labs.

MatGL is part of the MatML ecosystem, which includes the [MatGL] (Materials Graph Library) and [maml] (MAterials Machine Learning) packages, the [MatPES] (Materials Potential Energy Surface) dataset, and the [MatCalc] (Materials Calculator).

Status

Major milestones are summarized below. Please refer to the [changelog] for details.

v2.0.0 (Nov 13 2025): [QET] architecture added. PYG backend is now the default.
v1.3.0 (Aug 12 2025): Pretrained molecular potentials and PyG framework added.
v1.1.0 (May 7 2024): Implementation of [CHGNet] + pre-trained models.
v1.0.0 (Feb 14 2024): Implementation of [TensorNet] and [SO3Net].
v0.5.1 (Jun 9 2023): Model versioning implemented.
v0.5.0 (Jun 8 2023): Simplified saving and loading of models. Now models can be loaded with one line of code!
v0.4.0 (Jun 7 2023): Near feature parity with original TF implementations. Re-trained M3Gnet universal potential now available.
v0.1.0 (Feb 16 2023): Initial implementations of M3GNet and MEGNet architectures have been completed. Expect bugs!

Major update: v2.0.0 (Nov 12 2025)

We are in the process of moving away from the Deep Graph Library (DGL) framework to Pytorch Geometric (PyG) or even a pure PyTorch framework. This is motivated by the fact that DGL is no longer actively maintained. For now, both PYG and DGL models are available.

From v2.0.0, MatGL will default to a PyG backend, and DGL is no longer a required dependency. For now, only TensorNet has been re-implemented in PYG. To use the DGL-based models (which includes the new QET), you will need to install the DGL dependencies manually. This typically takes about 10 minutes, depending on the speed of downloading the required GPU packages.:

pip install "numpy<2"
pip install dgl==2.2.0
pip install torch==2.3.0
pip install "torchdata<=0.8.0"

and set the backend either via the environment variable MATGL_BACKEND=DGL or by using

import matgl
matgl.set_backend("DGL")

Current Architectures

<div style="float: left; padding: 10px; width: 200px"> <img src="https://github.com/materialyzeai/matgl/blob/main/assets/MxGNet.png?raw=true" alt="m3gnet_schematic"> <p>Figure: Schematic of M3GNet/MEGNet</p> </div>

Here, we summarize the currently implemented architectures in MatGL. It should be stressed that this is by no means an exhaustive list, and we expect new architectures to be added by the core MatGL team as well as other contributors in the future.

[QET] (DGL only, PYG coming soon), pronounced as "ket", is a charge-equilibrated TensorNet architecture. It is an equivariant, charge-aware architecture that attains linear scaling with system size via an analytically solvable charge-equilibration scheme. A pre-trained QET-MatQ FP is available, which matches state-of-the-art FPs on standard materials property benchmarks but delivers qualitatively different predictions in systems dominated by charge transfer, e.g., NaCl–\ce{CaCl2} ionic liquid, reactive processes at the Li/\ce{Li6PS5Cl} solid-electrolyte interface, and supports simulations under applied electrochemical potentials.
[TensorNet] (PYG and DGL) is an O(3)-equivariant message-passing neural network architecture that leverages Cartesian tensor representations. It is a generalization of the [SO3Net] architecture, which is a minimalist SO(3)-equivariant neural network. In general, TensorNet has been shown to be much more data and parameter efficient than other equivariant architectures. It is currently the default architecture used in the [Materials Virtual Lab].
[Crystal Hamiltonian Graph Network (CHGNet)][chgnet] (DGL only) is a graph neural network based MLIP. CHGNet involves atom graphs to capture atom bond relations and bond graph to capture angular information. It specializes in capturing the atomic charges through learning and predicting DFT atomic magnetic moments. See [original implementation][chgnetrepo]
[Materials 3-body Graph Network (M3GNet)][m3gnet] is an invariant graph neural network architecture that incorporates 3-body interactions. An additional difference is the addition of the coordinates for atoms and the 3×3 lattice matrix in crystals, which are necessary for obtaining tensorial quantities such as forces and stresses via auto-differentiation. As a framework, M3GNet has diverse applications, including Interatomic potential development. With the same training data, M3GNet performs similarly to state-of-the-art machine learning interatomic potentials (MLIPs). However, a key feature of a graph representation is its flexibility to scale to diverse chemical spaces. One of the key accomplishments of M3GNet is the development of a [foundation potential][m3gnet] that can work across the entire periodic table of the elements by training on relaxations performed in the [Materials Project][mp]. Like the previous MEGNet architecture, M3GNet can be used to develop surrogate models for property predictions, achieving in many cases accuracies that are better or similar to other state-of-the-art ML models.
[MatErials Graph Network (MEGNet)][megnet] (DGL only) is an implementation of DeepMind's [graph networks][graphnetwork] for machine learning in materials science. We have demonstrated its success in achieving low prediction errors in a broad array of properties in both [molecules and crystals][megnet]. New releases have included our recent work on [multi-fidelity materials property modeling][mfimegnet]. Figure 1 shows the sequential update steps of the graph network, whereby bonds, atoms, and global state attributes are updated using information from each other, generating an output graph.

For detailed performance benchmarks, please refer to the publications in the References section.

Installation

Matgl can be installed via pip:

pip install matgl

If you need to use DGL, it is recommended you install the latest version of DGL before installing matgl.

pip install dgl -f https://data.dgl.ai/wheels/torch-2.4/repo.html

CUDA (GPU) installation

If you intend to use CUDA (GPU) to speed up training, it is important to install the appropriate versions of PyTorch and DGL. The basic instructions are given below, but it is recommended that you consult the PyTorch docs and DGL docs if you run into any problems.

pip install torch==2.2.0 --index-url https://download.pytorch.org/whl/cu121
pip install dgl -f https://data.dgl.ai/wheels/cu121/repo.html
pip install dglgo -f https://data.dgl.ai/wheels-test/repo.html

Docker images

Docker images have now been built for matgl, together with LAMMPS support. They are available at the [Materials Virtual Lab Docker Repository]. If you wish to use MatGL with LAMMPS, this is probably the easiest option.

Usage

Pre-trained M3GNet universal potential and MEGNet models for the Materials Project formation energy and multi-fidelity band gap are now available.

Command line (from v0.6.2)

A CLI tool now provides the capability to perform quick relaxations or predictions using pre-trained models, as well as other simple administrative tasks (e.g., clearing the cache). Some simple examples:

To perform a relaxation,

mgl relax --infile Li2O.cif --outfile Li2O_relax.cif

To use one of the pre-trained property models,

mgl predict --model M3GNet-MP-2018.6.1-Eform --infile Li2O.cif

To clear the cache,
```
mgl clear
```

For a full range of options, use mgl -h.

Code

Users who just want to use the models out of the box should use the newly implemented matgl.load_model convenience method. The following is an example of a prediction of the formation energy for CsCl.

from pymatgen.core import Lattice, Structure
import matgl

model = matgl.load_model("MEGNet-MP-2018.6.1-Eform")

# This is the structure obtained from the Materials Project.
struct = Structure.from_spacegroup("Pm-3m", Lattice.cubic(4.1437), ["Cs", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]])
eform = model.predict_structure(struct)
print(f"The predicted formation energy for CsCl is {float(eform.numpy()):.3f} eV/atom.")

To obtain a listing of available pre-trained models,

import matgl
print(matgl.get_available_pretrained_models())

Matgl

Install / Use

README