Package: m3gnet
M3GNetM3GNet is a new materials graph neural network architecture that incorporates 3-body interactions. A key difference
with prior materials graph implementations such asMEGNetis 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 (ML-IAPs). 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 auniversal IAPthat can work across the entire periodic table of the elements by training on relaxations performed
in theMaterials Project.Surrogate models for property predictions.Like the previous MEGNet architecture, M3GNet can be used to develop
surrogate models for property predictions, achieving in many cases accuracies that better or similar to other
state-of-the-art ML models.For detailed performance benchmarks, please refer to the publication in theReferencessection. The
API documentation is available via theGithub Page.Table of ContentsSystem requirementsInstallationChange LogUsageModel trainingMatterverseAPI docsDatasetsReferencesSystem requirementsInferences using the pre-trained models can be ran on any standard computer. For model training, the GPU memory needs
to be > 18 Gb for a batch size of 32 using the crystal training data. In our work, we used a single RTX 3090
GPU for model training.InstallationM3GNet can be installed via pip:pip install m3gnetYou can also directly download the source from Github and install from source.Apple Silicon InstallationApple Silicon (M1, M1 Pro, M1 Max, M1 Ultra) has extremely powerful ML capabilities, but special steps are needed for
the installation of tensorflow and other dependencies. Here are the recommended installation steps.Ensure that you already have XCode and CLI installed.Install Miniconda or Anaconda.Create a Python 3.9 environment.condacreate--namem3gnetpython=3.9
condaactivatem3gnetFirst install tensorflow and its dependencies for Apple Silicon.condainstall-cappletensorflow-deps
pipinstalltensorflow-macosIf you wish, you can installtensorflow-metal, which helps speed up training. If you encounter strange tensorflow
errors, you should uninstalltensorflow-metaland see if it fixes the errors first.pipinstalltensorflow-metalInstall m3gnet but ignore dependencies (otherwise, pip will look for tensorflow).pipinstall--no-depsm3gnetInstall other dependencies like pymatgen, etc. manually.pipinstallprotobuf==3.20.0pymatgenasecythonOnce you are done, you can try runningpytest m3gnetto see if all tests pass.Change LogSeechange logUsageStructure relaxationA M3Gnet universal potential for the periodic table has been developed using data from Materials Project relaxations
since 2012. This universal potential can be used to perform structural relaxation of any arbitrary crystal as follows.importwarningsfromm3gnet.modelsimportRelaxerfrompymatgen.coreimportLattice,Structureforcategoryin(UserWarning,DeprecationWarning):warnings.filterwarnings("ignore",category=category,module="tensorflow")# Init a Mo structure with stretched lattice (DFT lattice constant ~ 3.168)mo=Structure(Lattice.cubic(3.3),["Mo","Mo"],[[0.,0.,0.],[0.5,0.5,0.5]])relaxer=Relaxer()# This loads the default pre-trained modelrelax_results=relaxer.relax(mo,verbose=True)final_structure=relax_results['final_structure']final_energy_per_atom=float(relax_results['trajectory'].energies[-1]/len(mo))print(f"Relaxed lattice parameter is{final_structure.lattice.abc[0]:.3f}Å")print(f"Final energy is{final_energy_per_atom:.3f}eV/atom")The output is as follows:Relaxed lattice parameter is  3.169 Å
Final energy is -10.859 eV/atomThe initial lattice parameter of 3.3 Å was successfully relaxed to 3.169 Å, close to the DFT value of 3.168 Å. The
final energy -10.859 eV/atom is also close to Materials Project DFT value of-10.8456 eV/atom.The relaxation takes less than 20 seconds on a single laptop.The table below provides more comprehensive benchmarks for cubic crystals based onexp data on Wikipediaand MP DFT data. TheJupyter notebookis in theexamplesfolder. This benchmark is
limited to cubic crystals for ease of comparison since there is only one lattice parameter. Of course, M3GNet is not
limited to cubic systems (seeLiFePO4 example).MaterialCrystal structurea (Å)MP a (Å)M3GNet a (Å)% error vs Expt% error vs MPAcFCC5.315.662265.66466.68%0.04%AgFCC4.0794.160554.167022.16%0.16%AlFCC4.0464.038934.04108-0.12%0.05%AlAsZinc blende (FCC)5.66055.733765.730271.23%-0.06%AlPZinc blende (FCC)5.4515.507115.503460.96%-0.07%AlSbZinc blende (FCC)6.13556.233766.228171.51%-0.09%ArFCC5.265.640775.627456.99%-0.24%AuFCC4.0654.171294.174312.69%0.07%BNZinc blende (FCC)3.6153.6263.624850.27%-0.03%BPZinc blende (FCC)4.5384.546824.547110.20%0.01%BaBCC5.025.03035.034540.29%0.08%C (diamond)Diamond (FCC)3.5673.573713.57180.13%-0.05%CaFCC5.585.507375.52597-0.97%0.34%CaVO3Cubic perovskite3.7673.830413.834511.79%0.11%CdSZinc blende (FCC)5.8325.940835.94191.88%0.02%CdSeZinc blende (FCC)6.056.212836.209872.64%-0.05%CdTeZinc blende (FCC)6.4826.629056.626192.22%-0.04%CeFCC5.164.720444.71921-8.54%-0.03%CrBCC2.882.874032.84993-1.04%-0.84%CrNHalite4.149-4.160680.28%-CsBCC6.056.110045.27123-12.87%-13.73%CsClCaesium chloride4.1234.209064.203081.94%-0.14%CsFHalite6.026.118016.12651.77%0.14%CsICaesium chloride4.5674.665214.907677.46%5.20%CuFCC3.5973.621263.611990.42%-0.26%EuBCC4.614.639034.34783-5.69%-6.28%EuTiO3Cubic perovskite7.813.961193.92943-49.69%-0.80%FeBCC2.8562.840052.85237-0.13%0.43%GaAsZinc blende (FCC)5.6535.750185.750551.73%0.01%GaPZinc blende (FCC)5.45055.50635.50541.01%-0.02%GaSbZinc blende (FCC)6.09596.219066.219392.03%0.01%GeDiamond (FCC)5.6585.762865.76981.98%0.12%HfC0.99Halite4.644.651314.650230.22%-0.02%HfNHalite4.3924.537744.538383.33%0.01%InAsZinc blende (FCC)6.05836.181486.253743.23%1.17%InPZinc blende (FCC)5.8695.956735.96791.69%0.19%InSbZinc blende (FCC)6.4796.633226.638632.46%0.08%IrFCC3.843.875733.877160.97%0.04%KBCC5.235.262125.49935.15%4.51%KBrHalite6.66.703086.707971.64%0.07%KClHalite6.296.383596.396341.69%0.20%KFHalite5.345.423985.419711.49%-0.08%KIHalite7.077.185347.183091.60%-0.03%KTaO3Cubic perovskite3.98854.030844.032651.11%0.05%KrFCC5.726.496466.259249.43%-3.65%LiBCC3.493.426823.41891-2.04%-0.23%LiBrHalite5.55.513435.510760.20%-0.05%LiClHalite5.145.152755.147450.15%-0.10%LiFHalite4.034.083434.085311.37%0.05%LiIHalite6.016.02576.027090.28%0.02%MgOHalite (FCC)4.2124.256484.25671.06%0.01%MoBCC3.1423.167623.169370.87%0.06%NaBCC4.234.172624.19684-0.78%0.58%NaBrHalite5.976.02766.019220.82%-0.14%NaClHalite5.645.691695.694970.97%0.06%NaFHalite4.634.696254.695531.42%-0.02%NaIHalite6.476.5326.527390.89%-0.07%NbBCC3.30083.320523.322210.65%0.05%NbNHalite4.3924.452474.454741.43%0.05%NeFCC4.434.303836.9574457.05%61.66%NiFCC3.4993.50583.50860.27%0.08%PbFCC4.925.050535.028492.21%-0.44%PbSHalite (FCC)5.93626.006456.017521.37%0.18%PbTeHalite (FCC)6.4626.565676.561111.53%-0.07%PdFCC3.8593.957073.954662.48%-0.06%PtFCC3.9123.976773.977141.67%0.01%RbBCC5.595.644165.632350.76%-0.21%RbBrHalite6.897.027936.982191.34%-0.65%RbClHalite6.596.698736.679941.36%-0.28%RbFHalite5.655.738925.768432.10%0.51%RbIHalite7.357.487857.617563.64%1.73%RhFCC3.83.84393.849351.30%0.14%ScNHalite4.524.518314.51797-0.04%-0.01%SiDiamond (FCC)5.431025.468735.450020.35%-0.34%SrFCC6.086.022536.04449-0.58%0.36%SrTiO3Cubic perovskite3.988053.945133.94481-1.08%-0.01%SrVO3Cubic perovskite3.8383.900893.906041.77%0.13%TaBCC3.30583.322293.317410.35%-0.15%TaC0.99Halite4.4564.482084.482250.59%0.00%ThFCC5.085.041225.04483-0.69%0.07%TiCHalite4.3284.335654.334930.16%-0.02%TiNHalite4.2494.253534.252540.08%-0.02%VBCC3.03992.992542.99346-1.53%0.03%VC0.97Halite4.1664.161954.16476-0.03%0.07%VNHalite4.1364.124934.1281-0.19%0.08%WBCC3.1553.187413.188261.05%0.03%XeFCC6.26.661487.0699114.03%6.13%YbFCC5.495.449255.45807-0.58%0.16%ZnOHalite (FCC)4.584.338884.33424-5.37%-0.11%ZnSZinc blende (FCC)5.425.450275.452970.61%0.05%ZrC0.97Halite4.6984.724344.724510.56%0.00%ZrNHalite4.5774.617624.616020.85%-0.03%From the table, it can be observed that almost all M3GNet-relaxed cubic lattice constants are within 1% of the DFT
values. The only major errors are with EuTiO3, iodides (RbI and CsI) and the noble gases. It is quite likely the
Wikipedia value for EuTiO3 is wrong by a factor of  2 and the lower than expected accuracy on iodides and noble gases
may be due to the paucity of data in these chemical systems. It should be noted that M3GNet is expected to reproduce
the MP DFT value and not the experimental values, which are only provided as an additional point of reference.All relaxations take less than 1s on a M1 Max Mac.CLI toolA simple CLI tool has been written. Right now, it supports just doing structure relaxations with M3GNet, which is
immediately useful for quick testing of the capabilities of M3GNet itself. More features will be developed in future if
there is user interest. Examples below.m3grelax--infileLi2O.cif# Outputs to stdout the relaxed structure.m3grelax--infileLi2O.cif--outfileLi2O_relaxed.cif# Outputs to a file the relaxed structure.Molecular dynamicsSimilarly, the universal IAP can be used to perform molecular dynamics (MD) simulations as well.frompymatgen.coreimportStructure,Latticefromm3gnet.modelsimportMolecularDynamics# Init a Mo structure with stretched lattice (DFT lattice constant ~ 3.168)mo=Structure(Lattice.cubic(3.3),["Mo","Mo"],[[0.,0.,0.],[0.5,0.5,0.5]])md=MolecularDynamics(atoms=mo,temperature=1000,# 1000 Kensemble='nvt',# NVT ensembletimestep=1,# 1fs,trajectory="mo.traj",# save trajectory to mo.trajlogfile="mo.log",# log file for MDloginterval=100,# interval for record the log)md.run(steps=1000)After the run,mo.logcontains thermodynamic information similar to the following:Time[ps]Etot[eV]Epot[eV]Ekin[eV]T[K]0.0000-21.3307-21.33070.00000.00.1000-21.3307-21.33070.00000.00.2000-21.2441-21.30870.0645249.70.3000-21.0466-21.23580.1891731.60.4000-20.9702-21.11490.1447559.60.5000-20.9380-21.10930.1713662.60.6000-20.9176-21.13760.2200850.90.7000-20.9016-21.17890.27731072.80.8000-20.8804-21.16380.28351096.40.9000-20.8770-21.06950.1925744.51.0000-20.8908-21.07720.1864721.2The MD run takes less than 1 minute.Model trainingYou can also train your own IAP using thePotentialTrainerinm3gnet.trainers. The training dataset can include:structures, a list of pymatgen Structuresenergies, a list of energy floats with unit eV.forces, a list of nx3 force matrix with unit eV/Å, where n is the number of atom in
each structure. n does not need to be the same for all structures.stresses, a list of 3x3 stress matrices with unit GPa (optional)For stresses, we use the convention that compressive stress gives negative values. Stresses obtained from
VASP calculations (default unit is kBar) should be multiplied by -0.1 to work directly with the model.We use validation dataset to select the stopping epoch number. The dataset has similar format as the training dataset.A minimal example of model training is shown below.fromm3gnet.modelsimportM3GNet,Potentialfromm3gnet.trainersimportPotentialTrainerimporttensorflowastfm3gnet=M3GNet(is_intensive=False)potential=Potential(model=m3gnet)trainer=PotentialTrainer(potential=potential,optimizer=tf.keras.optimizers.Adam(1e-3))trainer.train(structures,energies,forces,stresses,validation_graphs_or_structures=val_structures,val_energies=val_energies,val_forces=val_forces,val_stresses=val_stresses,epochs=100,fit_per_element_offset=True,save_checkpoint=False,)MatterverseAs an example of the power of M3GNet for materials discovery, we have created a database of yet-to-be-synthesized
materials calledmatterverse.ai. At the time of writing, matterverse.ai has 31 million
structures, of which more than 1 million are predicted to be potentially stable. The initial candidate list was
generated via combinatorial isovalent ionic substitutions based on the common oxidation states of non-noble-gas elements
on 5,283 binary, ternary and quaternary structural prototypes in the 2019 version of the ICSD database.API docsThe API docs are availablehere.DatasetsThe training data used to develop the universal M3GNet IAP isMPF.2021.2.8and is hosted onfigsharewith DOI10.6084/m9.figshare.19470599.ReferencePlease cite the following work:Chi Chen, and Shyue Ping Ong. "A Universal Graph Deep Learning Interatomic Potential for the Periodic Table."
arXiv preprint [arXiv:2202.02450](https://arxiv.org/abs/2202.02450) (2022).AcknowledgementsThis work was primarily supported by the Materials Project, funded by the U.S. Department of Energy, Office of Science,
Office of Basic Energy Sciences, Materials Sciences and Engineering Division under contract no.
DE-AC02-05-CH11231: Materials Project program KC23MP. This work used the Expanse supercomputing cluster at the Extreme
Science and Engineering Discovery Environment (XSEDE), which is supported by National Science Foundation grant number
ACI-1548562.