Data

Tools

Indexes

Applications

Experiments

Open Source Science

mattersim

MatterSim: A deep learning atomistic model across elements, temperatures and pressures.

https://github.com/microsoft/mattersim

Science Score: 46.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ✓
    Academic publication links
    Links to: arxiv.org
  • ✓
    Committers with academic emails
    1 of 16 committers (6.3%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (17.8%) to scientific vocabulary

Keywords

ai4materials ai4science computational-materials-science foundation-models machine-learning machine-learning-force-field materials-science mlff

Keywords from Contributors

standards mesh interactive
Last synced: 6 months ago · JSON representation

Repository

MatterSim: A deep learning atomistic model across elements, temperatures and pressures.

Basic Info
Statistics
  • Stars: 449
  • Watchers: 12
  • Forks: 58
  • Open Issues: 15
  • Releases: 18
Topics
ai4materials ai4science computational-materials-science foundation-models machine-learning machine-learning-force-field materials-science mlff
Created over 1 year ago · Last pushed 8 months ago
Metadata Files
Readme Contributing License Code of conduct Citation Security

README.md

MatterSim logo

[![arXiv](https://img.shields.io/badge/arXiv-2405.04967-blue?logo=arxiv&logoColor=white.svg)](https://arxiv.org/abs/2405.04967) [![Requires Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads) [![PyPI Downloads](https://static.pepy.tech/badge/mattersim)](https://pepy.tech/projects/mattersim)

MatterSim is a deep learning atomistic model across elements, temperatures and pressures.

Documentation

This README provides a quick start guide. For more comprehensive information, please refer to the MatterSim documentation.

Installation

Prerequisite

  • Python >= 3.10

Install from PyPI

[!TIP] While not mandatory, we recommend creating a clean conda environment before installing MatterSim to avoid potential package conflicts. You can create and activate a conda environment with the following commands:

```bash

create the environment

conda create -n mattersim python=3.10

activate the environment

conda activate mattersim ```

To install MatterSim, use the following command. Please note that downloading the dependencies may take some time: bash pip install mattersim

In case you want to install the package with the latest version, you can run the following command:

bash pip install git+https://github.com/microsoft/mattersim.git

Install from source code

  1. Download the source code of MatterSim and change to the directory

bash git clone git@github.com:microsoft/mattersim.git cd mattersim

  1. Install MatterSim

[!WARNING] We strongly recommend that users install MatterSim using mamba or micromamba, because conda can be significantly slower when resolving the dependencies in environment.yaml.

To install the package, run the following command under the root of the folder:

bash mamba env create -f environment.yaml mamba activate mattersim uv pip install -e .

Pre-trained Models

We currently offer two pre-trained MatterSim-v1 models based on the M3GNet architecture in the pretrained_models folder:

  1. MatterSim-v1.0.0-1M: A mini version of the model that is faster to run.
  2. MatterSim-v1.0.0-5M: A larger version of the model that is more accurate.

These models have been trained using the data generated through the workflows introduced in the MatterSim manuscript, which provides an in-depth explanation of the methodologies underlying the MatterSim model.

More advanced and fully-supported pretrained versions of MatterSim, and additional materials capabilities are available in Azure Quantum Elements.

Usage

[!TIP] Note for macOS Users: If you are using macOS with Apple Silicon, please be aware of potential numerical instability with the MPS backend. We recommend using the CPU device for MatterSim on Mac to avoid these issues.

A minimal test

```python import torch from loguru import logger from ase.build import bulk from ase.units import GPa from mattersim.forcefield import MatterSimCalculator

device = "cuda" if torch.cuda.is_available() else "cpu" logger.info(f"Running MatterSim on {device}")

si = bulk("Si", "diamond", a=5.43) si.calc = MatterSimCalculator(device=device) logger.info(f"Energy (eV) = {si.getpotentialenergy()}") logger.info(f"Energy per atom (eV/atom) = {si.getpotentialenergy()/len(si)}") logger.info(f"Forces of first atom (eV/A) = {si.getforces()[0]}") logger.info(f"Stress[0]0 = {si.getstress(voigt=False)[0][0]}") logger.info(f"Stress[0]0 = {si.get_stress(voigt=False)[0][0] / GPa}") ```

In this release, we provide two checkpoints: MatterSim-v1.0.0-1M.pth and MatterSim-v1.0.0-5M.pth. By default, the 1M version is loaded. To switch to the 5M version, manually set the load_path of MatterSimCalculator as shown below:

python MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device)

Finetune

[!TIP] MatterSim provides a finetune script to finetune the pre-trained MatterSim model on a custom dataset. Please refer to the MatterSim documentation for more details.

A minimal finetune example

bash torchrun --nproc_per_node=1 src/mattersim/training/finetune_mattersim.py --load_model_path mattersim-v1.0.0-1m --train_data_path tests/data/high_level_water.xyz

Reference

We kindly request that users of MatterSim version 1.0.0 cite our preprint available on arXiv: @article{yang2024mattersim, title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures}, author={Han Yang and Chenxi Hu and Yichi Zhou and Xixian Liu and Yu Shi and Jielan Li and Guanzhi Li and Zekun Chen and Shuizhou Chen and Claudio Zeni and Matthew Horton and Robert Pinsler and Andrew Fowler and Daniel Zgner and Tian Xie and Jake Smith and Lixin Sun and Qian Wang and Lingyu Kong and Chang Liu and Hongxia Hao and Ziheng Lu}, year={2024}, eprint={2405.04967}, archivePrefix={arXiv}, primaryClass={cond-mat.mtrl-sci}, url={https://arxiv.org/abs/2405.04967}, journal={arXiv preprint arXiv:2405.04967} }

[!IMPORTANT] We kindly ask users to explicitly specify the exact model version and checkpoint (e.g., MatterSim-v1.0.0-1M) when reporting results in academic papers or technical reports, rather than referring to the model generically as MatterSim. Precise versioning is crucial for ensuring reproducibility. For instance, the statement "This study was conducted using MatterSim-v1.0.0-1M" serves as a good example.

Limitations

MatterSim-v1 is designed specifically for atomistic simulations of bulk materials. Applications or interpretations beyond this scope should be approached with caution. For instance, when using the model for simulations involving surfaces, interfaces, or properties influenced by long-range interactions, the results may be qualitatively accurate but are not suitable for quantitative analysis. In such cases, we recommend fine-tuning the model to better align with the specific application.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Responsible AI Transparency Documentation

The responsible AI transparency documentation can be found here.

Researcher and Developers

MatterSim is actively under development, and we welcome community engagement. If you have research interests related to this model, ideas youd like to contribute, or issues to report, we encourage you to reach out to us at ai4s-materials@microsoft.com.

Owner

  • Name: Microsoft
  • Login: microsoft
  • Kind: organization
  • Email: opensource@microsoft.com
  • Location: Redmond, WA

Open source projects and samples from Microsoft

GitHub Events

Total
  • Fork event: 56
  • Create event: 53
  • Issues event: 40
  • Release event: 13
  • Watch event: 401
  • Delete event: 48
  • Member event: 4
  • Issue comment event: 66
  • Public event: 1
  • Push event: 132
  • Pull request review comment event: 9
  • Pull request review event: 48
  • Pull request event: 100
Last Year
  • Fork event: 56
  • Create event: 53
  • Issues event: 40
  • Release event: 13
  • Watch event: 401
  • Delete event: 48
  • Member event: 4
  • Issue comment event: 66
  • Public event: 1
  • Push event: 132
  • Pull request review comment event: 9
  • Pull request review event: 48
  • Pull request event: 100

Committers

Last synced: 9 months ago

All Time
  • Total Commits: 119
  • Total Committers: 16
  • Avg Commits per committer: 7.438
  • Development Distribution Score (DDS): 0.555
Past Year
  • Commits: 119
  • Committers: 16
  • Avg Commits per committer: 7.438
  • Development Distribution Score (DDS): 0.555
Top Committers
Name Email Commits
Han Yang y****4@o****m 53
Han Yang h****g@m****m 32
Xixian Liu 1****g 10
Claudio Zeni 3****i 4
Xixian v****u@m****m 4
bi-ran b****n@a****u 3
Ziheng LU z****h@g****m 2
Sebastian Ehlert 2****k 2
Janosh Riebesell j****l@g****m 2
microsoft-github-policy-service[bot] 7****] 1
dependabot[bot] 4****] 1
co63oc c****c 1
Songchen Xue 1****e 1
Mohammad Bagheri 7****0 1
Anyang Peng 1****l 1
Ran Bi b****n@m****m 1
Committer Domains (Top 20 + Academic)
microsoft.com: 3 alum.mit.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 31
  • Total pull requests: 97
  • Average time to close issues: 13 days
  • Average time to close pull requests: 3 days
  • Total issue authors: 25
  • Total pull request authors: 14
  • Average comments per issue: 1.1
  • Average comments per pull request: 0.31
  • Merged pull requests: 87
  • Bot issues: 2
  • Bot pull requests: 2
Past Year
  • Issues: 31
  • Pull requests: 97
  • Average time to close issues: 13 days
  • Average time to close pull requests: 3 days
  • Issue authors: 25
  • Pull request authors: 14
  • Average comments per issue: 1.1
  • Average comments per pull request: 0.31
  • Merged pull requests: 87
  • Bot issues: 2
  • Bot pull requests: 2
View more stats
Top Authors
Issue Authors
  • yuhao1982 (4)
  • microsoft-github-policy-service[bot] (2)
  • qchempku2017 (2)
  • ZeroKnighting (2)
  • dundarphys (2)
  • prometeios (1)
  • Dankomaister (1)
  • S1owFade (1)
  • mmamdouh4370 (1)
  • zdcao121 (1)
  • kyonofx (1)
  • sek1ro-yuzzz (1)
  • panmianzhi (1)
  • yanghan234 (1)
  • Liusiyuan2022 (1)
Pull Request Authors
  • yanghan234 (65)
  • ZeroKnighting (19)
  • ClaudioZeni (7)
  • bi-ran (5)
  • luzihen (4)
  • janosh (4)
  • ZeHeru (3)
  • awvwgk (3)
  • mbagheri20 (2)
  • co63oc (2)
  • anyangml (2)
  • microsoft-github-policy-service[bot] (1)
  • brian-xue (1)
  • CompRhys (1)
  • dependabot[bot] (1)
Top Labels
Issue Labels
bug (16) enhancement (1)
Pull Request Labels
enhancement (2) bug (2) dependencies (1) documentation (1)

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 293,443 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 12
  • Total maintainers: 1
pypi.org: mattersim

MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures.

  • Versions: 12
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 293,443 Last month
Rankings
Dependent packages count: 9.9%
Average: 32.9%
Dependent repos count: 56.0%
Maintainers (1)
hanyang_microsoft
Last synced: 6 months ago

Dependencies

.github/workflows/build.yaml actions
  • actions/checkout v3 composite
  • mamba-org/setup-micromamba v1 composite
.github/workflows/codeql.yaml actions
  • actions/checkout v4 composite
  • github/codeql-action/analyze v3 composite
  • github/codeql-action/init v3 composite
.github/workflows/gh-pages.yaml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • peaceiris/actions-gh-pages v3 composite
.github/workflows/python-publish.yaml actions
  • actions/checkout v4 composite
  • actions/download-artifact v4 composite
  • actions/setup-python v5 composite
  • actions/upload-artifact v4 composite
  • pypa/gh-action-pypi-publish release/v1 composite
pyproject.toml pypi
  • ase >=3.23.0
  • azure-identity *
  • azure-storage-blob *
  • deprecated *
  • e3nn ==0.5.0
  • emmet-core <0.84
  • loguru *
  • mp-api *
  • numpy <2
  • opt_einsum_fx *
  • pydantic ==2.9.2
  • pymatgen *
  • seekpath *
  • torch ==2.2.0
  • torch-ema ==0.3
  • torch_geometric ==2.5.3
  • torch_runstats ==0.2.0
  • torchaudio ==2.2.0
  • torchmetrics >=0.10.0
  • torchvision ==0.17.0
setup.py pypi
src/mattersim/datasets/utils/setup.py pypi
environment.yaml conda
  • ca-certificates
  • cython >=0.29.32
  • openssl
  • python 3.9.*
  • setuptools >=45
  • wheel