{"id":33861084,"url":"https://github.com/materialyzeai/m3gnet","last_synced_at":"2025-12-14T07:00:34.564Z","repository":{"id":37801345,"uuid":"449395509","full_name":"materialyzeai/m3gnet","owner":"materialyzeai","description":"Materials graph network with 3-body interactions featuring a DFT surrogate crystal relaxer and a state-of-the-art property predictor.","archived":true,"fork":false,"pushed_at":"2025-04-07T22:52:21.000Z","size":2336,"stargazers_count":306,"open_issues_count":15,"forks_count":72,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-12-07T16:41:06.467Z","etag":null,"topics":["deep-learning","graph","machine-learning","materials-science","neural-network"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/materialyzeai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-18T18:10:58.000Z","updated_at":"2025-11-22T13:25:14.000Z","dependencies_parsed_at":"2025-03-10T00:55:33.034Z","dependency_job_id":"4a64ffb8-b158-467b-b293-9edf6f03a382","html_url":"https://github.com/materialyzeai/m3gnet","commit_stats":{"total_commits":232,"total_committers":18,"mean_commits":12.88888888888889,"dds":0.7241379310344828,"last_synced_commit":"924a46f8b80801efcfe44e4d5fb0f78c562f6ba9"},"previous_names":["materialyzeai/m3gnet"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/materialyzeai/m3gnet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fm3gnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fm3gnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fm3gnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fm3gnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/materialyzeai","download_url":"https://codeload.github.com/materialyzeai/m3gnet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/materialyzeai%2Fm3gnet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27720787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","graph","machine-learning","materials-science","neural-network"],"created_at":"2025-12-09T07:00:47.137Z","updated_at":"2025-12-14T07:00:34.557Z","avatar_url":"https://github.com/materialyzeai.png","language":"Python","funding_links":[],"categories":["Universal Potentials"],"sub_categories":[],"readme":"[![GitHub license](https://img.shields.io/github/license/materialsvirtuallab/m3gnet)](https://github.com/materialsvirtuallab/m3gnet/blob/main/LICENSE)\n[![Linting](https://github.com/materialsvirtuallab/m3gnet/workflows/Linting/badge.svg)](https://github.com/materialsvirtuallab/m3gnet/workflows/Linting/badge.svg)\n[![Testing](https://github.com/materialsvirtuallab/m3gnet/workflows/Testing%20-%20main/badge.svg)](https://github.com/materialsvirtuallab/m3gnet/workflows/Testing/badge.svg)\n[![Downloads](https://pepy.tech/badge/m3gnet)](https://pepy.tech/project/m3gnet)\n\n\u003e **_NOTE:_**  A new implementation based on the Deep Graph Library and PyTorch called the\n\u003e [Materials Graph Library (MatGL)](https://github.com/materialsvirtuallab/matgl) has replaced this implementation.\n\u003e This repository has been archived and will no longer be maintained. It will be kept purely as a reference\n\u003e implementation. Users are recommended to use matgl instead.\n\n# M3GNet\n\n[M3GNet](https://www.nature.com/articles/s43588-022-00349-3) is a new materials graph neural network architecture that incorporates 3-body interactions. A key difference with prior materials graph implementations such as [MEGNet](https://github.com/materialsvirtuallab/megnet) 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.\n\nAs a framework, M3GNet has diverse applications, including:\n\n- **Interatomic potential development.** With the same training data, M3GNet performs similarly to state-of-the-art\n  machine learning interatomic potentials (ML-IAPs). However, a key feature of a graph representation is its\n  flexibility to scale to diverse chemical spaces. One of the key accomplishments of M3GNet is the development of a\n  *universal IAP* that can work across the entire periodic table of the elements by training on relaxations performed\n  in the [Materials Project](http://materialsproject.org).\n- **Surrogate models for property predictions.** Like the previous MEGNet architecture, M3GNet can be used to develop\n  surrogate models for property predictions, achieving in many cases accuracies that better or similar to other\n  state-of-the-art ML models.\n\nFor detailed performance benchmarks, please refer to the publication in the [References](#references) section. The\nAPI documentation is available via the [Github Page](http://materialsvirtuallab.github.io/m3gnet).\n\n# Table of Contents\n\n- [System requirements](#system-requirements)\n- [Installation](#installation)\n- [Change Log](#change-log)\n- [Usage](#usage)\n- [Model training](#model-training)\n- [Matterverse](#matterverse)\n- [API docs](#api-docs)\n- [Datasets](#datasets)\n- [References](#reference)\n\n# System requirements\n\nInferences using the pre-trained models can be ran on any standard computer. For model training, the GPU memory needs\nto be \u003e 18 Gb for a batch size of 32 using the crystal training data. In our work, we used a single RTX 3090\nGPU for model training.\n\n# Installation\n\nM3GNet can be installed via pip:\n\n```\npip install m3gnet\n```\n\nYou can also directly download the source from Github and install from source.\n\n## Apple Silicon Installation\n\nApple Silicon (M1, M1 Pro, M1 Max, M1 Ultra) has extremely powerful ML capabilities, but special steps are needed for\nthe installation of tensorflow and other dependencies. Here are the recommended installation steps.\n\n1. Ensure that you already have XCode and CLI installed.\n2. Install Miniconda or Anaconda.\n3. Create a Python 3.9 environment.\n\n    ```bash\n    conda create --name m3gnet python=3.9\n    conda activate m3gnet\n    ```\n\n4. First install tensorflow and its dependencies for Apple Silicon.\n\n    ```bash\n    conda install -c apple tensorflow-deps\n    pip install tensorflow-macos\n    ```\n\n5. If you wish, you can install `tensorflow-metal`, which helps speed up training. If you encounter strange tensorflow\n   errors, you should uninstall `tensorflow-metal` and see if it fixes the errors first.\n\n    ```bash\n    pip install tensorflow-metal\n    ```\n\n6. Install m3gnet but ignore dependencies (otherwise, pip will look for tensorflow).\n\n    ```bash\n    pip install --no-deps m3gnet\n    ```\n\n7. Install other dependencies like pymatgen, etc. manually.\n\n    ```bash\n    pip install protobuf==3.20.0 pymatgen ase cython\n    ```\n\n8. Once you are done, you can try running `pytest m3gnet` to see if all tests pass.\n\n# Change Log\n\nSee [change log](CHANGES.md)\n\n# Usage\n\n## Structure relaxation\n\nA M3Gnet universal potential for the periodic table has been developed using data from Materials Project relaxations\nsince 2012. This universal potential can be used to perform structural relaxation of any arbitrary crystal as follows.\n\n```python\nimport warnings\n\nfrom m3gnet.models import Relaxer\nfrom pymatgen.core import Lattice, Structure\n\nfor category in (UserWarning, DeprecationWarning):\n    warnings.filterwarnings(\"ignore\", category=category, module=\"tensorflow\")\n\n# Init a Mo structure with stretched lattice (DFT lattice constant ~ 3.168)\nmo = Structure(Lattice.cubic(3.3), [\"Mo\", \"Mo\"], [[0., 0., 0.], [0.5, 0.5, 0.5]])\n\nrelaxer = Relaxer()  # This loads the default pre-trained model\n\nrelax_results = relaxer.relax(mo, verbose=True)\n\nfinal_structure = relax_results['final_structure']\nfinal_energy_per_atom = float(relax_results['trajectory'].energies[-1] / len(mo))\n\nprint(f\"Relaxed lattice parameter is {final_structure.lattice.abc[0]:.3f} Å\")\nprint(f\"Final energy is {final_energy_per_atom:.3f} eV/atom\")\n```\n\nThe output is as follows:\n\n```txt\nRelaxed lattice parameter is  3.169 Å\nFinal energy is -10.859 eV/atom\n```\n\nThe initial lattice parameter of 3.3 Å was successfully relaxed to 3.169 Å, close to the DFT value of 3.168 Å. The\nfinal energy -10.859 eV/atom is also close to Materials Project DFT value of\n[-10.8456 eV/atom](http://materialsproject.org/materials/mp-129/).\n\nThe relaxation takes less than 20 seconds on a single laptop.\n\nThe table below provides more comprehensive benchmarks for cubic crystals based on\n[exp data on Wikipedia](http://en.wikipedia.org/wiki/Lattice_constant) and MP DFT data. The\n[Jupyter notebook](/examples/Cubic%20Crystal%20Test.ipynb) is in the [examples](/examples) folder. This benchmark is\nlimited to cubic crystals for ease of comparison since there is only one lattice parameter. Of course, M3GNet is not\nlimited to cubic systems (see [LiFePO4 example](/examples/Relaxation%20of%20LiFePO4.ipynb)).\n\n| Material    | Crystal structure |   a (Å) | MP a (Å) | M3GNet a (Å) | % error vs Expt | % error vs MP |\n| :---------- | :---------------- | ------: | -------: | -----------: | :-------------- | :------------ |\n| Ac          | FCC               |    5.31 |  5.66226 |       5.6646 | 6.68%           | 0.04%         |\n| Ag          | FCC               |   4.079 |  4.16055 |      4.16702 | 2.16%           | 0.16%         |\n| Al          | FCC               |   4.046 |  4.03893 |      4.04108 | -0.12%          | 0.05%         |\n| AlAs        | Zinc blende (FCC) |  5.6605 |  5.73376 |      5.73027 | 1.23%           | -0.06%        |\n| AlP         | Zinc blende (FCC) |   5.451 |  5.50711 |      5.50346 | 0.96%           | -0.07%        |\n| AlSb        | Zinc blende (FCC) |  6.1355 |  6.23376 |      6.22817 | 1.51%           | -0.09%        |\n| Ar          | FCC               |    5.26 |  5.64077 |      5.62745 | 6.99%           | -0.24%        |\n| Au          | FCC               |   4.065 |  4.17129 |      4.17431 | 2.69%           | 0.07%         |\n| BN          | Zinc blende (FCC) |   3.615 |    3.626 |      3.62485 | 0.27%           | -0.03%        |\n| BP          | Zinc blende (FCC) |   4.538 |  4.54682 |      4.54711 | 0.20%           | 0.01%         |\n| Ba          | BCC               |    5.02 |   5.0303 |      5.03454 | 0.29%           | 0.08%         |\n| C (diamond) | Diamond (FCC)     |   3.567 |  3.57371 |       3.5718 | 0.13%           | -0.05%        |\n| Ca          | FCC               |    5.58 |  5.50737 |      5.52597 | -0.97%          | 0.34%         |\n| CaVO3       | Cubic perovskite  |   3.767 |  3.83041 |      3.83451 | 1.79%           | 0.11%         |\n| CdS         | Zinc blende (FCC) |   5.832 |  5.94083 |       5.9419 | 1.88%           | 0.02%         |\n| CdSe        | Zinc blende (FCC) |    6.05 |  6.21283 |      6.20987 | 2.64%           | -0.05%        |\n| CdTe        | Zinc blende (FCC) |   6.482 |  6.62905 |      6.62619 | 2.22%           | -0.04%        |\n| Ce          | FCC               |    5.16 |  4.72044 |      4.71921 | -8.54%          | -0.03%        |\n| Cr          | BCC               |    2.88 |  2.87403 |      2.84993 | -1.04%          | -0.84%        |\n| CrN         | Halite            |   4.149 |        - |      4.16068 | 0.28%           | -             |\n| Cs          | BCC               |    6.05 |  6.11004 |      5.27123 | -12.87%         | -13.73%       |\n| CsCl        | Caesium chloride  |   4.123 |  4.20906 |      4.20308 | 1.94%           | -0.14%        |\n| CsF         | Halite            |    6.02 |  6.11801 |       6.1265 | 1.77%           | 0.14%         |\n| CsI         | Caesium chloride  |   4.567 |  4.66521 |      4.90767 | 7.46%           | 5.20%         |\n| Cu          | FCC               |   3.597 |  3.62126 |      3.61199 | 0.42%           | -0.26%        |\n| Eu          | BCC               |    4.61 |  4.63903 |      4.34783 | -5.69%          | -6.28%        |\n| EuTiO3      | Cubic perovskite  |    7.81 |  3.96119 |      3.92943 | -49.69%         | -0.80%        |\n| Fe          | BCC               |   2.856 |  2.84005 |      2.85237 | -0.13%          | 0.43%         |\n| GaAs        | Zinc blende (FCC) |   5.653 |  5.75018 |      5.75055 | 1.73%           | 0.01%         |\n| GaP         | Zinc blende (FCC) |  5.4505 |   5.5063 |       5.5054 | 1.01%           | -0.02%        |\n| GaSb        | Zinc blende (FCC) |  6.0959 |  6.21906 |      6.21939 | 2.03%           | 0.01%         |\n| Ge          | Diamond (FCC)     |   5.658 |  5.76286 |       5.7698 | 1.98%           | 0.12%         |\n| HfC0.99     | Halite            |    4.64 |  4.65131 |      4.65023 | 0.22%           | -0.02%        |\n| HfN         | Halite            |   4.392 |  4.53774 |      4.53838 | 3.33%           | 0.01%         |\n| InAs        | Zinc blende (FCC) |  6.0583 |  6.18148 |      6.25374 | 3.23%           | 1.17%         |\n| InP         | Zinc blende (FCC) |   5.869 |  5.95673 |       5.9679 | 1.69%           | 0.19%         |\n| InSb        | Zinc blende (FCC) |   6.479 |  6.63322 |      6.63863 | 2.46%           | 0.08%         |\n| Ir          | FCC               |    3.84 |  3.87573 |      3.87716 | 0.97%           | 0.04%         |\n| K           | BCC               |    5.23 |  5.26212 |       5.4993 | 5.15%           | 4.51%         |\n| KBr         | Halite            |     6.6 |  6.70308 |      6.70797 | 1.64%           | 0.07%         |\n| KCl         | Halite            |    6.29 |  6.38359 |      6.39634 | 1.69%           | 0.20%         |\n| KF          | Halite            |    5.34 |  5.42398 |      5.41971 | 1.49%           | -0.08%        |\n| KI          | Halite            |    7.07 |  7.18534 |      7.18309 | 1.60%           | -0.03%        |\n| KTaO3       | Cubic perovskite  |  3.9885 |  4.03084 |      4.03265 | 1.11%           | 0.05%         |\n| Kr          | FCC               |    5.72 |  6.49646 |      6.25924 | 9.43%           | -3.65%        |\n| Li          | BCC               |    3.49 |  3.42682 |      3.41891 | -2.04%          | -0.23%        |\n| LiBr        | Halite            |     5.5 |  5.51343 |      5.51076 | 0.20%           | -0.05%        |\n| LiCl        | Halite            |    5.14 |  5.15275 |      5.14745 | 0.15%           | -0.10%        |\n| LiF         | Halite            |    4.03 |  4.08343 |      4.08531 | 1.37%           | 0.05%         |\n| LiI         | Halite            |    6.01 |   6.0257 |      6.02709 | 0.28%           | 0.02%         |\n| MgO         | Halite (FCC)      |   4.212 |  4.25648 |       4.2567 | 1.06%           | 0.01%         |\n| Mo          | BCC               |   3.142 |  3.16762 |      3.16937 | 0.87%           | 0.06%         |\n| Na          | BCC               |    4.23 |  4.17262 |      4.19684 | -0.78%          | 0.58%         |\n| NaBr        | Halite            |    5.97 |   6.0276 |      6.01922 | 0.82%           | -0.14%        |\n| NaCl        | Halite            |    5.64 |  5.69169 |      5.69497 | 0.97%           | 0.06%         |\n| NaF         | Halite            |    4.63 |  4.69625 |      4.69553 | 1.42%           | -0.02%        |\n| NaI         | Halite            |    6.47 |    6.532 |      6.52739 | 0.89%           | -0.07%        |\n| Nb          | BCC               |  3.3008 |  3.32052 |      3.32221 | 0.65%           | 0.05%         |\n| NbN         | Halite            |   4.392 |  4.45247 |      4.45474 | 1.43%           | 0.05%         |\n| Ne          | FCC               |    4.43 |  4.30383 |      6.95744 | 57.05%          | 61.66%        |\n| Ni          | FCC               |   3.499 |   3.5058 |       3.5086 | 0.27%           | 0.08%         |\n| Pb          | FCC               |    4.92 |  5.05053 |      5.02849 | 2.21%           | -0.44%        |\n| PbS         | Halite (FCC)      |  5.9362 |  6.00645 |      6.01752 | 1.37%           | 0.18%         |\n| PbTe        | Halite (FCC)      |   6.462 |  6.56567 |      6.56111 | 1.53%           | -0.07%        |\n| Pd          | FCC               |   3.859 |  3.95707 |      3.95466 | 2.48%           | -0.06%        |\n| Pt          | FCC               |   3.912 |  3.97677 |      3.97714 | 1.67%           | 0.01%         |\n| Rb          | BCC               |    5.59 |  5.64416 |      5.63235 | 0.76%           | -0.21%        |\n| RbBr        | Halite            |    6.89 |  7.02793 |      6.98219 | 1.34%           | -0.65%        |\n| RbCl        | Halite            |    6.59 |  6.69873 |      6.67994 | 1.36%           | -0.28%        |\n| RbF         | Halite            |    5.65 |  5.73892 |      5.76843 | 2.10%           | 0.51%         |\n| RbI         | Halite            |    7.35 |  7.48785 |      7.61756 | 3.64%           | 1.73%         |\n| Rh          | FCC               |     3.8 |   3.8439 |      3.84935 | 1.30%           | 0.14%         |\n| ScN         | Halite            |    4.52 |  4.51831 |      4.51797 | -0.04%          | -0.01%        |\n| Si          | Diamond (FCC)     | 5.43102 |  5.46873 |      5.45002 | 0.35%           | -0.34%        |\n| Sr          | FCC               |    6.08 |  6.02253 |      6.04449 | -0.58%          | 0.36%         |\n| SrTiO3      | Cubic perovskite  | 3.98805 |  3.94513 |      3.94481 | -1.08%          | -0.01%        |\n| SrVO3       | Cubic perovskite  |   3.838 |  3.90089 |      3.90604 | 1.77%           | 0.13%         |\n| Ta          | BCC               |  3.3058 |  3.32229 |      3.31741 | 0.35%           | -0.15%        |\n| TaC0.99     | Halite            |   4.456 |  4.48208 |      4.48225 | 0.59%           | 0.00%         |\n| Th          | FCC               |    5.08 |  5.04122 |      5.04483 | -0.69%          | 0.07%         |\n| TiC         | Halite            |   4.328 |  4.33565 |      4.33493 | 0.16%           | -0.02%        |\n| TiN         | Halite            |   4.249 |  4.25353 |      4.25254 | 0.08%           | -0.02%        |\n| V           | BCC               |  3.0399 |  2.99254 |      2.99346 | -1.53%          | 0.03%         |\n| VC0.97      | Halite            |   4.166 |  4.16195 |      4.16476 | -0.03%          | 0.07%         |\n| VN          | Halite            |   4.136 |  4.12493 |       4.1281 | -0.19%          | 0.08%         |\n| W           | BCC               |   3.155 |  3.18741 |      3.18826 | 1.05%           | 0.03%         |\n| Xe          | FCC               |     6.2 |  6.66148 |      7.06991 | 14.03%          | 6.13%         |\n| Yb          | FCC               |    5.49 |  5.44925 |      5.45807 | -0.58%          | 0.16%         |\n| ZnO         | Halite (FCC)      |    4.58 |  4.33888 |      4.33424 | -5.37%          | -0.11%        |\n| ZnS         | Zinc blende (FCC) |    5.42 |  5.45027 |      5.45297 | 0.61%           | 0.05%         |\n| ZrC0.97     | Halite            |   4.698 |  4.72434 |      4.72451 | 0.56%           | 0.00%         |\n| ZrN         | Halite            |   4.577 |  4.61762 |      4.61602 | 0.85%           | -0.03%        |\n\nFrom the table, it can be observed that almost all M3GNet-relaxed cubic lattice constants are within 1% of the DFT\nvalues. The only major errors are with EuTiO3, iodides (RbI and CsI) and the noble gases. It is quite likely the\nWikipedia value for EuTiO3 is wrong by a factor of  2 and the lower than expected accuracy on iodides and noble gases\nmay be due to the paucity of data in these chemical systems. It should be noted that M3GNet is expected to reproduce\nthe MP DFT value and not the experimental values, which are only provided as an additional point of reference.\n\nAll relaxations take less than 1s on a M1 Max Mac.\n\n### CLI tool\n\nA simple CLI tool has been written. Right now, it supports just doing structure relaxations with M3GNet, which is\nimmediately useful for quick testing of the capabilities of M3GNet itself. More features will be developed in future if\nthere is user interest. Examples below.\n\n```bash\nm3g relax --infile Li2O.cif  # Outputs to stdout the relaxed structure.\nm3g relax --infile Li2O.cif --outfile Li2O_relaxed.cif  # Outputs to a file the relaxed structure.\n```\n\n## Molecular dynamics\n\nSimilarly, the universal IAP can be used to perform molecular dynamics (MD) simulations as well.\n\n```python\nfrom pymatgen.core import Structure, Lattice\nfrom m3gnet.models import MolecularDynamics\n\n# Init a Mo structure with stretched lattice (DFT lattice constant ~ 3.168)\nmo = Structure(Lattice.cubic(3.3),\n               [\"Mo\", \"Mo\"], [[0., 0., 0.], [0.5, 0.5, 0.5]])\n\nmd = MolecularDynamics(\n    atoms=mo,\n    temperature=1000,  # 1000 K\n    ensemble='nvt',  # NVT ensemble\n    timestep=1, # 1fs,\n    trajectory=\"mo.traj\",  # save trajectory to mo.traj\n    logfile=\"mo.log\",  # log file for MD\n    loginterval=100,  # interval for record the log\n)\n\nmd.run(steps=1000)\n```\n\nAfter the run, `mo.log` contains thermodynamic information similar to the following:\n\n```bash\nTime[ps]      Etot[eV]     Epot[eV]     Ekin[eV]    T[K]\n0.0000         -21.3307     -21.3307       0.0000     0.0\n0.1000         -21.3307     -21.3307       0.0000     0.0\n0.2000         -21.2441     -21.3087       0.0645   249.7\n0.3000         -21.0466     -21.2358       0.1891   731.6\n0.4000         -20.9702     -21.1149       0.1447   559.6\n0.5000         -20.9380     -21.1093       0.1713   662.6\n0.6000         -20.9176     -21.1376       0.2200   850.9\n0.7000         -20.9016     -21.1789       0.2773  1072.8\n0.8000         -20.8804     -21.1638       0.2835  1096.4\n0.9000         -20.8770     -21.0695       0.1925   744.5\n1.0000         -20.8908     -21.0772       0.1864   721.2\n```\n\nThe MD run takes less than 1 minute.\n\n# Model training\n\nYou can also train your own IAP using the `PotentialTrainer` in `m3gnet.trainers`. The training dataset can include:\n\n- structures, a list of pymatgen Structures\n- energies, a list of energy floats with unit eV.\n- forces, a list of nx3 force matrix with unit eV/Å, where n is the number of atom in\n  each structure. n does not need to be the same for all structures.\n- stresses, a list of 3x3 stress matrices with unit GPa (optional)\n\nFor stresses, we use the convention that compressive stress gives negative values. Stresses obtained from\nVASP calculations (default unit is kBar) should be multiplied by -0.1 to work directly with the model.\n\nWe use validation dataset to select the stopping epoch number. The dataset has similar format as the training dataset.\n\nIf you want to use the offical MPF dataset shared above, here are some code examples that you can follow to load the dataset smoothly and train your own model.\n\nFirst, load the MPF dataset consisting of block_0 and block_1\n\n```python\nimport pickle as pk\nimport pandas as pd\nimport pymatgen\n\nprint('loading the MPF dataset 2021')\nwith open('/yourpath/block_0.p', 'rb') as f:\n    data = pk.load(f)\n\nwith open('/yourpath/block_1.p', 'rb') as f:\n    data2 = pk.load(f)\nprint('MPF dataset 2021 loaded')\ndata.update(data2)\ndf = pd.DataFrame.from_dict(data)\n```\n\nThen, split the data based on material id and map the energy to formation energy with unit eV/atom\n\n```python\nid_train, id_val, id_test = get_id_train_val_test(\n    total_size=len(data),\n    split_seed=42,\n    train_ratio=0.90,\n    val_ratio=0.05,\n    test_ratio=0.05,\n    keep_data_order=False,\n)\n\ncnt = 0\nfor idx, item in df.items():\n    # import pdb; pdb.set_trace()\n    if cnt in id_train:\n        for iid in range(len(item['energy'])):\n            dataset_train.append({\"atoms\":item['structure'][iid], \"energy\":item['energy'][iid] / len(item['force'][iid]), \"force\": np.array(item['force'][iid])})\n    elif cnt in id_val:\n        for iid in range(len(item['energy'])):\n            dataset_val.append({\"atoms\":item['structure'][iid], \"energy\":item['energy'][iid] / len(item['force'][iid]), \"force\": np.array(item['force'][iid])})\n    elif cnt in id_test:\n        for iid in range(len(item['energy'])):\n            dataset_test.append({\"atoms\":item['structure'][iid], \"energy\":item['energy'][iid] / len(item['force'][iid]), \"force\": np.array(item['force'][iid])})\n    cnt += 1\n\nprint('using %d samples to train, %d samples to evaluate, and %d samples to test'%(len(dataset_train), len(dataset_val), len(dataset_test)))\n```\nAfter this, you can use the dataset_train to train, dataset_val to evaluate, and dataset_test to test.\n\nA minimal example of model training is shown below.\n\n```python\nfrom m3gnet.models import M3GNet, Potential\nfrom m3gnet.trainers import PotentialTrainer\n\nimport tensorflow as tf\n\nm3gnet = M3GNet(is_intensive=False)\npotential = Potential(model=m3gnet)\n\ntrainer = PotentialTrainer(\n    potential=potential, optimizer=tf.keras.optimizers.Adam(1e-3)\n)\n\ntrainer.train(\n    structures,\n    energies,\n    forces,\n    stresses,\n    validation_graphs_or_structures=val_structures,\n    val_energies=val_energies,\n    val_forces=val_forces,\n    val_stresses=val_stresses,\n    epochs=100,\n    fit_per_element_offset=True,\n    save_checkpoint=False,\n)\n```\n\n# Matterverse\n\nAs an example of the power of M3GNet for materials discovery, we have created a database of yet-to-be-synthesized\nmaterials called [matterverse.ai](https://matterverse.ai). At the time of writing, matterverse.ai has 31 million\nstructures, of which more than 1 million are predicted to be potentially stable. The initial candidate list was\ngenerated via combinatorial isovalent ionic substitutions based on the common oxidation states of non-noble-gas elements\non 5,283 binary, ternary and quaternary structural prototypes in the 2019 version of the ICSD database.\n\n# API docs\n\nThe API docs are available [here](https://materialsvirtuallab.github.io/m3gnet/modules).\n\n# Datasets\n\nThe training data used to develop the universal M3GNet IAP is `MPF.2021.2.8` and is hosted on\n[figshare](https://figshare.com/articles/dataset/MPF_2021_2_8/19470599) with DOI `10.6084/m9.figshare.19470599`.\n\n# Reference\n\nPlease cite the following work:\n\n\u003e Chen, C., Ong, S.P. A universal graph deep learning interatomic potential for the periodic table. Nat Comput Sci 2, 718–728 (2022). https://doi.org/10.1038/s43588-022-00349-3.\n\n# Acknowledgements\n\nThis work was primarily supported by the Materials Project, funded by the U.S. Department of Energy, Office of Science,\nOffice of Basic Energy Sciences, Materials Sciences and Engineering Division under contract no.\nDE-AC02-05-CH11231: Materials Project program KC23MP. This work used the Expanse supercomputing cluster at the Extreme\nScience and Engineering Discovery Environment (XSEDE), which is supported by National Science Foundation grant number\nACI-1548562.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialyzeai%2Fm3gnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterialyzeai%2Fm3gnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterialyzeai%2Fm3gnet/lists"}