M3GNet

Overview

M3GNet provides a materials graph neural network architecture and an implementation for interatomic potentials and property-prediction surrogate models. Its graph representation includes three-body interactions, atomic coordinates and the crystal lattice matrix, enabling forces and stresses to be obtained through automatic differentiation. The repository supplies a pretrained potential developed using Materials Project relaxation data, alongside tools for applying and training models.

In a computational materials workflow, the pretrained potential can support crystal structure relaxation and molecular dynamics. The documented relaxation example accepts a pymatgen Structure and returns a final structure plus a trajectory containing energies. A separate command-line interface reads a crystal structure file and writes the relaxed structure to standard output or a file. Molecular dynamics examples save trajectories and thermodynamic logs. For custom potential training, PotentialTrainer accepts structures, energies, per-atom forces and optional stress matrices, with validation data used to select the stopping epoch.

This repository is archived and no longer maintained; its README identifies MatGL, based on the Deep Graph Library and PyTorch, as the replacement. It is therefore most relevant as a reference implementation or for examining existing M3GNet workflows. The pretrained potential is intended to reproduce Materials Project DFT results rather than experimental measurements. The supplied cubic-crystal comparisons show material-dependent discrepancies, including for some iodides and noble gases, so broad elemental coverage should not be treated as uniform accuracy. The README also reports substantial GPU-memory requirements for its illustrated training configuration; these are source-described requirements, not independently tested compatibility.

Key Features

• Materials graph architecture incorporating three-body interactions, atomic coordinates and a 3×3 crystal lattice matrix for differentiable force and stress calculations.
• Default pretrained interatomic potential trained on Materials Project relaxation data and accessible through Relaxer.
• Structure relaxation returning a final structure and energy trajectory, with a CLI supporting structure-file input and relaxed-structure output.
• MolecularDynamics workflow with configurable temperature, ensemble and timestep, plus trajectory and thermodynamic-log output.
• Custom interatomic-potential training through PotentialTrainer using structures, energies, forces and optional stresses, with validation inputs.
• Architecture intended for developing surrogate models for materials-property prediction as well as interatomic potentials.

Use Cases

• Intended evaluation: assess pretrained crystal relaxation on representative materials by comparing final structures and energies with appropriate DFT references.
• Intended evaluation: explore molecular dynamics on a selected crystal, inspecting the saved trajectory and thermodynamic log before using results scientifically.
• Intended evaluation: train a domain-specific interatomic potential from structures, energies, forces and optional stresses, then assess it on held-out materials.
• Use the archived implementation as a reference when examining legacy M3GNet workflows or planning a transition to MatGL.

How to Use

1. Read the repository README, especially its archive notice. Decide whether this reference implementation is needed or whether the recommended MatGL replacement better fits the project.
2. Consult the README installation and system-requirement sections. Follow its documented package-installation route and any relevant platform-specific instructions; do not assume the archived dependencies have current compatibility.
3. Prepare a pymatgen Structure and follow the documented Relaxer example. Inspect the returned final_structure and trajectory energies. The README also describes file-based relaxation through the CLI.
4. For dynamics, follow the MolecularDynamics example and choose temperature, ensemble, timestep and recording settings. Inspect both trajectory and thermodynamic-log outputs as part of an intended evaluation.
5. For custom training, prepare energies in eV, forces in eV/Å and optional stresses in GPa, checking the documented stress sign convention. Use validation inputs and consult the API documentation. The source identifies MPF.2021.2.8 as the pretrained potential's training dataset.