[](https://github.com/materialsvirtuallab/matgl/blob/main/LICENSE)
[](https://github.com/materialsvirtuallab/matgl/workflows/Linting/badge.svg)
[](https://github.com/materialsvirtuallab/matgl/actions/workflows/testing.yml)
[](https://pepy.tech/project/matgl)
[](https://codecov.io/gh/materialsvirtuallab/matgl)
[](https://pypi.org/project/matgl?logo=pypi&logoColor=white)
# Materials Graph Library <img src="https://github.com/materialsvirtuallab/matgl/blob/main/assets/MatGL.png?raw=true" alt="matgl" width="30%" style="float: right">
## Official Documentation
<https://matgl.ai>
## 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.
MatGL is built on the [Deep Graph Library (DGL)][dgl] and PyTorch, with suitable adaptations for materials-specific
applications. The goal is for MatGL to serve as an extensible platform to develop and share materials graph deep
learning models, including the [MatErials 3-body Graph Network (M3GNet)][m3gnet] and its predecessor, [MEGNet].
This effort is a collaboration between the [Materials Virtual Lab][mavrl] and Intel Labs (Santiago Miret, Marcel
Nassar, Carmelo Gonzales).
## Status
Major milestones are summarized below. Please refer to the [changelog] for details.
- 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!
## Current Architectures
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 future.
<div style="float: left; padding: 10px; width: 300px">
<img src="https://github.com/materialsvirtuallab/matgl/blob/main/assets/MxGNet.png?raw=true" alt="m3gnet_schematic">
<p>Figure: Schematic of M3GNet/MEGNet</p>
</div>
### M3GNet
[Materials 3-body Graph Network (M3GNet)][m3gnet] is a new materials graph neural network architecture that
incorporates 3-body interactions in MEGNet. 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
[*universal IP*][m3gnet] that can work across the entire periodic table of the elements by training on relaxations
performed in the [Materials Project][mp].
- **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 are better or similar to other
state-of-the-art ML models.
For detailed performance benchmarks, please refer to the publications in the [References](#references) section.
MatGL reimplemennts M3GNet using DGL and Pytorch. Compared to the original Tensorflow implementation, some key
improvements over the TF implementations are:
- A more intuitive API and class structure based on DGL.
- Multi-GPU support via PyTorch Lightning.
### MEGNet
[MatErials Graph Network (MEGNet)][megnet] 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.
### Other models
We have implemented other models in matgl as well. A non-exhaustive list is given below.
- [TensorNet], an O(3)-equivariant message-passing neural network architecture that
leverages Cartesian tensor representations.
- [SO3Net], a minimalist SO(3)-equivariant neural network.
## Installation
Matgl can be installed via pip for the latest stable version:
```bash
pip install matgl
```
For the latest dev version, please clone this repo and install using:
```bash
pip install -e .
```
### 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](https://pytorch.org/get-started/locally/) and [DGL docs](https://www.dgl.ai/pages/start.html) if you
run into any problems.
```shell
pip install torch==2.2.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install dgl -f https://data.dgl.ai/wheels/cu118/repo.html
pip install dglgo -f https://data.dgl.ai/wheels-test/repo.html
```
## 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:
1. To perform a relaxation,
```bash
mgl relax --infile Li2O.cif --outfile Li2O_relax.cif
```
2. To use one of the pre-trained property models,
```bash
mgl predict --model M3GNet-MP-2018.6.1-Eform --infile Li2O.cif
```
3. To clear the cache,
```bash
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.
```python
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,
```python
import matgl
print(matgl.get_available_pretrained_models())
```
## Pytorch Hub
The pre-trained models are also available on Pytorch hub. To use these models, simply install matgl and use the
following commands:
```python
import torch
# To obtain a listing of models
torch.hub.list("materialsvirtuallab/matgl", force_reload=True)
# To load a model
model = torch.hub.load("materialsvirtuallab/matgl", 'm3gnet_universal_potential')
```
## Model Training
In the PES training, the unit of energies, forces and stresses (optional) in the training, validation and test sets is extremely important to be consistent with the unit used in MatGL.
- energies: a list of energies 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)
Note: 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.
## Tutorials
We wrote [tutorials] on how to use MatGL. These were generated from [Jupyter notebooks]
[jupyternb], which can be directly run on [Google Colab].
## Resources
- [API docs][apidocs] for all classes and methods.
- [Developer Guide](developer.md) outlines the key design elements of `matgl`, especially for developers wishing to
train and contribute matgl models.
- AdvancedSoft has implemented a [LAMMPS interface](https://github.com/advancesoftcorp/lammps/tree/based-on-lammps_2Jun2022/src/ML-M3GNET)
to both the TF and MatGL version of M3Gnet.
## References
A MatGL publication is currently being written. For now, pls refer to the CITATION.cff file for the citation
information. If you are using any of the pretrained models, please cite the relevant works below:
> **MEGNet**
>
> Chen, C.; Ye, W.; Zuo, Y.; Zheng, C.; Ong, S. P. *Graph Networks as a Universal Machine Learning Framework for
> Molecules and Crystals.* Chem. Mater. 2019, 31 (9), 3564–3572. DOI: [10.1021/acs.chemmater.9b01294][megnet].
> **Multi-fidelity MEGNet**
>
> Chen, C.; Zuo, Y.; Ye, W.; Li, X.; Ong, S. P. *Learning Properties of Ordered and Disordered Materials from
> Multi-Fidelity Data.* Nature Computational Science, 2021, 1, 46–53. DOI: [10.1038/s43588-020-00002-x][mfimegnet].
> **M3GNet**
>
> Chen, C., Ong, S.P. *A universal graph deep learning interatomic potential for the periodic table.* Nature
> Computational Science, 2023, 2, 718–728. DOI: [10.1038/s43588-022-00349-3][m3gnet].
## FAQs
1. **The `M3GNet-MP-2021.2.8-PES` differs from the original TensorFlow (TF) implementation!**
*Answer:* `M3GNet-MP-2021.2.8-PES` is a refitted model with some data improvements and minor architectural changes.
Porting over the weights from the TF version to DGL/PyTorch is non-trivial. We have performed reasonable benchmarking
to ensure that the new implementation reproduces the broad error characteristics of the original TF implementation
(see [examples][jupyternb]). However, it is not expected to reproduce the TF version exactly. This refitted model
serves as a baseline for future model improvements. We do not believe there is value in expending the resources
to reproduce the TF version exactly.
2. **I am getting errors with `matgl.load_model()`!**
*Answer:* The most likely reason is that you have a cached older version of the model. We often refactor models to
ensure the best implementation. This can usually be solved by updating your `matgl` to the latest version
and clearing your cache using the following command `mgl clear`. On the next run, the latest model will be
downloaded. With effect from v0.5.2, we have implemented a model versioning scheme that will detect code vs model
version conflicts and alert the user of such problems.
3. **What pre-trained models should I be using?**
*Answer:* There is no one definitive answer. In general, the newer the architecture and dataset, the more likely
the model performs better. However, it should also be noted that a model operating on a more diverse dataset may
compromise on performance on a specific system. The best way is to look at the READMEs included with each model
and do some tests on the systems you are interested in.
4. **How do I contribute to matgl?**
*Answer:* For code contributions, please fork and submit pull requests. You should read the
[developer guide](developer.md) to understand the general design guidelines. We welcome pre-trained model
contributions as well, which should also be submitted via PRs. Please follow the folder structure of the
pretrained models. In particular, we expect all models to come with a `README.md` and notebook
documenting its use and its key performance metrics. Also, we expect contributions to be on new properties
or systems or to significantly outperform the existing models. We will develop an alternative means for model
sharing in the future.
5. **None of your models do what I need. Where can I get help?**
*Answer:* Please contact [Prof Ong][ongemail] with a brief description of your needs. For simple problems, we are
glad to advise and point you in the right direction. For more complicated problems, we are always open to
academic collaborations or projects. We also offer [consulting services][mqm] for companies with unique needs,
including but not limited to custom data generation, model development and materials design.
## Acknowledgments
This work was primarily supported by the [Materials Project][mp], 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.
[m3gnetrepo]: https://github.com/materialsvirtuallab/m3gnet "M3GNet repo"
[megnetrepo]: https://github.com/materialsvirtuallab/megnet "MEGNet repo"
[dgl]: https://www.dgl.ai "DGL website"
[mavrl]: http://materialsvirtuallab.org "MAVRL website"
[changelog]: https://matgl.ai/changes "Changelog"
[graphnetwork]: https://arxiv.org/abs/1806.01261 "Deepmind's paper"
[megnet]: https://pubs.acs.org/doi/10.1021/acs.chemmater.9b01294 "MEGNet paper"
[mfimegnet]: https://nature.com/articles/s43588-020-00002-x "mfi MEGNet paper"
[m3gnet]: https://nature.com/articles/s43588-022-00349-3 "M3GNet paper"
[mp]: http://materialsproject.org "Materials Project"
[apidocs]: https://matgl.ai/matgl.html "MatGL API docs"
[doc]: https://matgl.ai "MatGL Documentation"
[google colab]: https://colab.research.google.com/ "Google Colab"
[jupyternb]: https://github.com/materialsvirtuallab/matgl/tree/main/examples
[ongemail]: mailto:ongsp@ucsd.edu "Email"
[mqm]: https://materialsqm.com "MaterialsQM"
[tutorials]: https://matgl.ai/tutorials "Tutorials"
[tensornet]: https://arxiv.org/abs/2306.06482 "TensorNet"
[so3net]: https://pubs.aip.org/aip/jcp/article-abstract/158/14/144801/2877924/SchNetPack-2-0-A-neural-network-toolbox-for "SO3Net"
Raw data
{
"_id": null,
"home_page": null,
"name": "matgl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "materials, interatomic potential, force field, science, property prediction, AI, machine learning, graph, deep learning",
"author": null,
"author_email": "Tsz Wai Ko <t1ko@ucsd.edu>, Marcel Nassar <marcel.nassar@intel.com>, Ji Qi <j1qi@ucsd.edu>, Santiago Miret <santiago.miret@intel.com>, Eliott Liu <elliottliu17@gmail.com>, Bowen Deng <bowendeng@berkeley.edu>, Luis Barroso-Luque <lbluque@berkeley.edu>, Shyue Ping Ong <ongsp@ucsd.edu>",
"download_url": "https://files.pythonhosted.org/packages/64/d6/0ad42a2efe7bc799df0bf4805cc90866f35aba2bc366de7372c2202d8e37/matgl-1.1.3.tar.gz",
"platform": null,
"description": "[](https://github.com/materialsvirtuallab/matgl/blob/main/LICENSE)\n[](https://github.com/materialsvirtuallab/matgl/workflows/Linting/badge.svg)\n[](https://github.com/materialsvirtuallab/matgl/actions/workflows/testing.yml)\n[](https://pepy.tech/project/matgl)\n[](https://codecov.io/gh/materialsvirtuallab/matgl)\n[](https://pypi.org/project/matgl?logo=pypi&logoColor=white)\n\n# Materials Graph Library <img src=\"https://github.com/materialsvirtuallab/matgl/blob/main/assets/MatGL.png?raw=true\" alt=\"matgl\" width=\"30%\" style=\"float: right\">\n\n## Official Documentation\n\n<https://matgl.ai>\n\n## Introduction\n\nMatGL (Materials Graph Library) is a graph deep learning library for materials science. Mathematical graphs are a\nnatural representation for a collection of atoms. Graph deep learning models have been shown to consistently deliver\nexceptional performance as surrogate models for the prediction of materials properties.\n\nMatGL is built on the [Deep Graph Library (DGL)][dgl] and PyTorch, with suitable adaptations for materials-specific\napplications. The goal is for MatGL to serve as an extensible platform to develop and share materials graph deep\nlearning models, including the [MatErials 3-body Graph Network (M3GNet)][m3gnet] and its predecessor, [MEGNet].\n\nThis effort is a collaboration between the [Materials Virtual Lab][mavrl] and Intel Labs (Santiago Miret, Marcel\nNassar, Carmelo Gonzales).\n\n## Status\n\nMajor milestones are summarized below. Please refer to the [changelog] for details.\n\n- v1.0.0 (Feb 14 2024): Implementation of [TensorNet] and [SO3Net].\n- v0.5.1 (Jun 9 2023): Model versioning implemented.\n- v0.5.0 (Jun 8 2023): Simplified saving and loading of models. Now models can be loaded with one line of code!\n- v0.4.0 (Jun 7 2023): Near feature parity with original TF implementations. Re-trained M3Gnet universal potential now\n available.\n- v0.1.0 (Feb 16 2023): Initial implementations of M3GNet and MEGNet architectures have been completed. Expect\n bugs!\n\n## Current Architectures\n\nHere, we summarize the currently implemented architectures in MatGL. It should be stressed that this is by no means\nan exhaustive list, and we expect new architectures to be added by the core MatGL team as well as other contributors\nin future.\n\n<div style=\"float: left; padding: 10px; width: 300px\">\n<img src=\"https://github.com/materialsvirtuallab/matgl/blob/main/assets/MxGNet.png?raw=true\" alt=\"m3gnet_schematic\">\n<p>Figure: Schematic of M3GNet/MEGNet</p>\n</div>\n\n### M3GNet\n\n[Materials 3-body Graph Network (M3GNet)][m3gnet] is a new materials graph neural network architecture that\nincorporates 3-body interactions in MEGNet. An additional difference is the addition of the coordinates for atoms and\nthe 3\u00d73 lattice matrix in crystals, which are necessary for obtaining tensorial quantities such as forces and\nstresses via auto-differentiation. As 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 (MLIPs). 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 IP*][m3gnet] that can work across the entire periodic table of the elements by training on relaxations\n performed in the [Materials Project][mp].\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 are better or similar to other\n state-of-the-art ML models.\n\nFor detailed performance benchmarks, please refer to the publications in the [References](#references) section.\n\nMatGL reimplemennts M3GNet using DGL and Pytorch. Compared to the original Tensorflow implementation, some key\nimprovements over the TF implementations are:\n\n- A more intuitive API and class structure based on DGL.\n- Multi-GPU support via PyTorch Lightning.\n\n### MEGNet\n\n[MatErials Graph Network (MEGNet)][megnet] is an implementation of DeepMind's [graph networks][graphnetwork] for\nmachine learning in materials science. We have demonstrated its success in achieving low prediction errors in a broad\narray of properties in both [molecules and crystals][megnet]. New releases have included our recent work on\n[multi-fidelity materials property modeling][mfimegnet]. Figure 1 shows the sequential update steps of the graph\nnetwork, whereby bonds, atoms, and global state attributes are updated using information from each other, generating an\noutput graph.\n\n### Other models\n\nWe have implemented other models in matgl as well. A non-exhaustive list is given below.\n\n- [TensorNet], an O(3)-equivariant message-passing neural network architecture that\n leverages Cartesian tensor representations.\n- [SO3Net], a minimalist SO(3)-equivariant neural network.\n\n## Installation\n\nMatgl can be installed via pip for the latest stable version:\n\n```bash\npip install matgl\n```\n\nFor the latest dev version, please clone this repo and install using:\n\n```bash\npip install -e .\n```\n\n### CUDA (GPU) installation\n\nIf you intend to use CUDA (GPU) to speed up training, it is important to install the appropriate versions of PyTorch\nand DGL. The basic instructions are given below, but it is recommended that you consult the\n[PyTorch docs](https://pytorch.org/get-started/locally/) and [DGL docs](https://www.dgl.ai/pages/start.html) if you\nrun into any problems.\n\n```shell\npip install torch==2.2.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\npip install dgl -f https://data.dgl.ai/wheels/cu118/repo.html\npip install dglgo -f https://data.dgl.ai/wheels-test/repo.html\n```\n\n## Usage\n\nPre-trained M3GNet universal potential and MEGNet models for the Materials Project formation energy and\nmulti-fidelity band gap are now available.\n\n### Command line (from v0.6.2)\n\nA CLI tool now provides the capability to perform quick relaxations or predictions using pre-trained models, as well\nas other simple administrative tasks (e.g., clearing the cache). Some simple examples:\n\n1. To perform a relaxation,\n\n ```bash\n mgl relax --infile Li2O.cif --outfile Li2O_relax.cif\n ```\n\n2. To use one of the pre-trained property models,\n\n ```bash\n mgl predict --model M3GNet-MP-2018.6.1-Eform --infile Li2O.cif\n ```\n\n3. To clear the cache,\n\n ```bash\n mgl clear\n ```\n\nFor a full range of options, use `mgl -h`.\n\n### Code\n\nUsers who just want to use the models out of the box should use the newly implemented `matgl.load_model` convenience\nmethod. The following is an example of a prediction of the formation energy for CsCl.\n\n```python\nfrom pymatgen.core import Lattice, Structure\nimport matgl\n\nmodel = matgl.load_model(\"MEGNet-MP-2018.6.1-Eform\")\n\n# This is the structure obtained from the Materials Project.\nstruct = Structure.from_spacegroup(\"Pm-3m\", Lattice.cubic(4.1437), [\"Cs\", \"Cl\"], [[0, 0, 0], [0.5, 0.5, 0.5]])\neform = model.predict_structure(struct)\nprint(f\"The predicted formation energy for CsCl is {float(eform.numpy()):.3f} eV/atom.\")\n```\n\nTo obtain a listing of available pre-trained models,\n\n```python\nimport matgl\nprint(matgl.get_available_pretrained_models())\n```\n\n## Pytorch Hub\n\nThe pre-trained models are also available on Pytorch hub. To use these models, simply install matgl and use the\nfollowing commands:\n\n```python\nimport torch\n\n# To obtain a listing of models\ntorch.hub.list(\"materialsvirtuallab/matgl\", force_reload=True)\n\n# To load a model\nmodel = torch.hub.load(\"materialsvirtuallab/matgl\", 'm3gnet_universal_potential')\n```\n## Model Training\n\nIn the PES training, the unit of energies, forces and stresses (optional) in the training, validation and test sets is extremely important to be consistent with the unit used in MatGL.\n\n- energies: a list of energies with unit eV.\n- forces: a list of nx3 force matrix with unit eV/\u00c5, where n is the number of atom in 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\nNote: 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.\n\n## Tutorials\n\nWe wrote [tutorials] on how to use MatGL. These were generated from [Jupyter notebooks]\n[jupyternb], which can be directly run on [Google Colab].\n\n## Resources\n\n- [API docs][apidocs] for all classes and methods.\n- [Developer Guide](developer.md) outlines the key design elements of `matgl`, especially for developers wishing to\n train and contribute matgl models.\n- AdvancedSoft has implemented a [LAMMPS interface](https://github.com/advancesoftcorp/lammps/tree/based-on-lammps_2Jun2022/src/ML-M3GNET)\n to both the TF and MatGL version of M3Gnet.\n\n## References\n\nA MatGL publication is currently being written. For now, pls refer to the CITATION.cff file for the citation\ninformation. If you are using any of the pretrained models, please cite the relevant works below:\n\n> **MEGNet**\n>\n> Chen, C.; Ye, W.; Zuo, Y.; Zheng, C.; Ong, S. P. *Graph Networks as a Universal Machine Learning Framework for\n> Molecules and Crystals.* Chem. Mater. 2019, 31 (9), 3564\u20133572. DOI: [10.1021/acs.chemmater.9b01294][megnet].\n\n> **Multi-fidelity MEGNet**\n>\n> Chen, C.; Zuo, Y.; Ye, W.; Li, X.; Ong, S. P. *Learning Properties of Ordered and Disordered Materials from\n> Multi-Fidelity Data.* Nature Computational Science, 2021, 1, 46\u201353. DOI: [10.1038/s43588-020-00002-x][mfimegnet].\n\n> **M3GNet**\n>\n> Chen, C., Ong, S.P. *A universal graph deep learning interatomic potential for the periodic table.* Nature\n> Computational Science, 2023, 2, 718\u2013728. DOI: [10.1038/s43588-022-00349-3][m3gnet].\n\n## FAQs\n\n1. **The `M3GNet-MP-2021.2.8-PES` differs from the original TensorFlow (TF) implementation!**\n\n *Answer:* `M3GNet-MP-2021.2.8-PES` is a refitted model with some data improvements and minor architectural changes.\n Porting over the weights from the TF version to DGL/PyTorch is non-trivial. We have performed reasonable benchmarking\n to ensure that the new implementation reproduces the broad error characteristics of the original TF implementation\n (see [examples][jupyternb]). However, it is not expected to reproduce the TF version exactly. This refitted model\n serves as a baseline for future model improvements. We do not believe there is value in expending the resources\n to reproduce the TF version exactly.\n\n2. **I am getting errors with `matgl.load_model()`!**\n\n *Answer:* The most likely reason is that you have a cached older version of the model. We often refactor models to\n ensure the best implementation. This can usually be solved by updating your `matgl` to the latest version\n and clearing your cache using the following command `mgl clear`. On the next run, the latest model will be\n downloaded. With effect from v0.5.2, we have implemented a model versioning scheme that will detect code vs model\n version conflicts and alert the user of such problems.\n\n3. **What pre-trained models should I be using?**\n\n *Answer:* There is no one definitive answer. In general, the newer the architecture and dataset, the more likely\n the model performs better. However, it should also be noted that a model operating on a more diverse dataset may\n compromise on performance on a specific system. The best way is to look at the READMEs included with each model\n and do some tests on the systems you are interested in.\n\n4. **How do I contribute to matgl?**\n\n *Answer:* For code contributions, please fork and submit pull requests. You should read the\n [developer guide](developer.md) to understand the general design guidelines. We welcome pre-trained model\n contributions as well, which should also be submitted via PRs. Please follow the folder structure of the\n pretrained models. In particular, we expect all models to come with a `README.md` and notebook\n documenting its use and its key performance metrics. Also, we expect contributions to be on new properties\n or systems or to significantly outperform the existing models. We will develop an alternative means for model\n sharing in the future.\n\n5. **None of your models do what I need. Where can I get help?**\n\n *Answer:* Please contact [Prof Ong][ongemail] with a brief description of your needs. For simple problems, we are\n glad to advise and point you in the right direction. For more complicated problems, we are always open to\n academic collaborations or projects. We also offer [consulting services][mqm] for companies with unique needs,\n including but not limited to custom data generation, model development and materials design.\n\n## Acknowledgments\n\nThis work was primarily supported by the [Materials Project][mp], funded by the U.S. Department of Energy, Office of\nScience, Office 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\n[m3gnetrepo]: https://github.com/materialsvirtuallab/m3gnet \"M3GNet repo\"\n[megnetrepo]: https://github.com/materialsvirtuallab/megnet \"MEGNet repo\"\n[dgl]: https://www.dgl.ai \"DGL website\"\n[mavrl]: http://materialsvirtuallab.org \"MAVRL website\"\n[changelog]: https://matgl.ai/changes \"Changelog\"\n[graphnetwork]: https://arxiv.org/abs/1806.01261 \"Deepmind's paper\"\n[megnet]: https://pubs.acs.org/doi/10.1021/acs.chemmater.9b01294 \"MEGNet paper\"\n[mfimegnet]: https://nature.com/articles/s43588-020-00002-x \"mfi MEGNet paper\"\n[m3gnet]: https://nature.com/articles/s43588-022-00349-3 \"M3GNet paper\"\n[mp]: http://materialsproject.org \"Materials Project\"\n[apidocs]: https://matgl.ai/matgl.html \"MatGL API docs\"\n[doc]: https://matgl.ai \"MatGL Documentation\"\n[google colab]: https://colab.research.google.com/ \"Google Colab\"\n[jupyternb]: https://github.com/materialsvirtuallab/matgl/tree/main/examples\n[ongemail]: mailto:ongsp@ucsd.edu \"Email\"\n[mqm]: https://materialsqm.com \"MaterialsQM\"\n[tutorials]: https://matgl.ai/tutorials \"Tutorials\"\n[tensornet]: https://arxiv.org/abs/2306.06482 \"TensorNet\"\n[so3net]: https://pubs.aip.org/aip/jcp/article-abstract/158/14/144801/2877924/SchNetPack-2-0-A-neural-network-toolbox-for \"SO3Net\"\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "MatGL is a framework for graph deep learning for materials science.",
"version": "1.1.3",
"project_urls": null,
"split_keywords": [
"materials",
" interatomic potential",
" force field",
" science",
" property prediction",
" ai",
" machine learning",
" graph",
" deep learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b94833e646984c473c168528ab34af957f8346b47dfc5edb539210bacbcc31a4",
"md5": "a6ee273865056aadd740f66b8c032c01",
"sha256": "edd966d8bc2fe3b78ea920aee80b33eeb4799bda4631068396c73490cf370ba9"
},
"downloads": -1,
"filename": "matgl-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6ee273865056aadd740f66b8c032c01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 223267,
"upload_time": "2024-08-07T12:39:57",
"upload_time_iso_8601": "2024-08-07T12:39:57.343690Z",
"url": "https://files.pythonhosted.org/packages/b9/48/33e646984c473c168528ab34af957f8346b47dfc5edb539210bacbcc31a4/matgl-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64d60ad42a2efe7bc799df0bf4805cc90866f35aba2bc366de7372c2202d8e37",
"md5": "23096108517672b512ff3665d10c6377",
"sha256": "6b09b3a7a68a1f6fe47bed8c7408540353e46371e32c1a1ac2bde347a6885a14"
},
"downloads": -1,
"filename": "matgl-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "23096108517672b512ff3665d10c6377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 215012,
"upload_time": "2024-08-07T12:39:58",
"upload_time_iso_8601": "2024-08-07T12:39:58.714003Z",
"url": "https://files.pythonhosted.org/packages/64/d6/0ad42a2efe7bc799df0bf4805cc90866f35aba2bc366de7372c2202d8e37/matgl-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-07 12:39:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "matgl"
}
JSON