Chgnet

<h1 align="center">CHGNet</h1> <h4 align="center">

</h4>

A pretrained universal neural network potential for charge-informed atomistic modeling (see publication) Crystal Hamiltonian Graph neural Network is pretrained on the GGA/GGA+U static and relaxation trajectories from Materials Project, a comprehensive dataset consisting of more than 1.5 Million structures from 146k compounds spanning the whole periodic table.

CHGNet highlights its ability to study electron interactions and charge distribution in atomistic modeling with near DFT accuracy. The charge inference is realized by regularizing the atom features with DFT magnetic moments, which carry rich information about both local ionic environments and charge distribution.

Pretrained CHGNet achieves excellent performance on materials stability prediction from unrelaxed structures according to Matbench Discovery [repo].

<slot name="metrics-table" />

Example notebooks

| Notebooks | Google Colab | Descriptions | | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CHGNet Basics | | Examples for loading pre-trained CHGNet, predicting energy, force, stress, magmom as well as running structure optimization and MD. | | Tuning CHGNet | | Examples of fine tuning the pretrained CHGNet to your system of interest. | | Visualize Relaxation | | Crystal Toolkit app that visualizes convergence of atom positions, energies and forces of a structure during CHGNet relaxation. | | Phonon DOS + Bands | | Use CHGNet with the atomate2 phonon workflow based on finite displacements as implemented in Phonopy to calculate phonon density of states and band structure for Si (mp-149). | | Elastic tensor + bulk/shear modulus | | Use CHGNet with the atomate2 elastic workflow based on a stress-strain approach to calculate elastic tensor and derived bulk and shear modulus for Si (mp-149). |

Installation

pip install chgnet

if PyPI installation fails or you need the latest main branch commits, you can install from source:

pip install git+https://github.com/CederGroupHub/chgnet

Tutorials and Docs

See the sciML webinar tutorial on 2023-11-02 and API docs.

Usage

Available Pretrained Models

CHGNet provides several pretrained models for different use cases:

from chgnet.model.model import CHGNet

# Load the latest CHGNet model (default: 0.3.0)
chgnet = CHGNet.load()
# Load specific CHGNet versions
chgnet = CHGNet.load(model_name='r2scan')

Model Details:

• '0.3.0' (default): MPtrj-pretrained CHGNet
• '0.2.0' : Deprecated MPtrj version for backward compatibility with NMI paper
• 'r2scan' : R2SCAN level model transfer learned from MP-R2SCAN dataset

Besides these checkpoints, we also have new CHGNet implementation and checkpoints based on the MatPES dataset available in the MatGL repo. The MatPES trained model are expected to be significantly better than MPtrj trained models in non-ground-state calculations like Molecular Dynamics.

Direct Inference (Static Calculation)

Pretrained CHGNet can predict the energy (eV/atom), force (eV/A), stress (GPa) and magmom ($\mu_B$) of a given structure.

from chgnet.model.model import CHGNet
from pymatgen.core import Structure

chgnet = CHGNet.load()
structure = Structure.from_file('examples/mp-18767-LiMnO2.cif')
prediction = chgnet.predict_structure(structure)

for key, unit in [
    ("energy", "eV/atom"),
    ("forces", "eV/A"),
    ("stress", "GPa"),
    ("magmom", "mu_B"),
]:
    print(f"CHGNet-predicted {key} ({unit}):\n{prediction[key[0]]}\n")

Molecular Dynamics

Charge-informed molecular dynamics can be simulated with pretrained CHGNet through ASE python interface (see below), or through LAMMPS.

from chgnet.model.model import CHGNet
from chgnet.model.dynamics import MolecularDynamics
from pymatgen.core import Structure
import warnings
warnings.filterwarnings("ignore", module="pymatgen")
warnings.filterwarnings("ignore", module="ase")

structure = Structure.from_file("examples/mp-18767-LiMnO2.cif")
chgnet = CHGNet.load()

md = MolecularDynamics(
    atoms=structure,
    model=chgnet,
    ensemble="nvt",
    temperature=1000,  # in K
    timestep=2,  # in femto-seconds
    trajectory="md_out.traj",
    logfile="md_out.log",