Skip to content

Commit df19768

Browse files
yanghan234yanghan-microsoft
yanghan234
and
yanghan-microsoft
authored
Doc: Add Documentation and github actions to deploy to github pages (#6)
* add docs * add documentation * add github actions to deploy github pages * add missing package installation * add missing pandoc packge * add missing pandoc packge * manually install pandoc * give write permission * update docs config * update docs actions trigger --------- Co-authored-by: Han Yang <[email protected]>
1 parent 9d9528c commit df19768

12 files changed

+653
-0
lines changed

‎.github/workflows/gh-pages.yaml

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
pull_request:
9+
branches:
10+
- main
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
build:
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v3
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v4
25+
with:
26+
python-version: '3.9'
27+
28+
- name: Set up Pandoc
29+
run: |
30+
sudo apt-get update
31+
sudo apt-get install -y pandoc
32+
33+
- name: Install dependencies
34+
run: |
35+
pip install sphinx sphinx-autodoc-typehints sphinx_book_theme sphinx-copybutton
36+
pip install nbsphinx recommonmark Pygments
37+
pip install pandoc
38+
39+
- name: Build the docs
40+
run: |
41+
cd docs
42+
make html
43+
44+
- name: Deploy to GitHub Pages
45+
uses: peaceiris/actions-gh-pages@v3
46+
with:
47+
github_token: ${{ secrets.GITHUB_TOKEN }}
48+
publish_dir: ./docs/_build/html

‎.nojekyll

Whitespace-only changes.

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# MatterSim Documentations
2+
3+
## Prerequisite
4+
To compile the documentations on your local machine you will need to install
5+
the following dependency in your environment:
6+
```bash
7+
# sphinx
8+
pip install sphinx sphinx-autodoc-typehints sphinx_book_theme sphinx-copybutton
9+
10+
# enable Markdown documentation in sphinx
11+
pip install recommonmark
12+
13+
# enable python jupyter notebook in sphinx
14+
pip install nbsphinx nbconvert
15+
16+
# install pandoc
17+
conda install -c conda-forge pandoc
18+
```
19+
20+
## Compile the docs
21+
Under the root of this repo, execute the following commandline
22+
```bash
23+
sphinx-build -b html docs docs/_build
24+
```
25+
To browse the documentation on your local machine, you may start a minimal
26+
HTTP server with
27+
```bash
28+
python3 -m http.server --directory docs/_build 8000
29+
```
30+
In a web browser, e.g. Chrome or Edge, you can read the docs at [localhost at port 8000](http://localhost:8000).

‎docs/conf.py

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# -*- coding: utf-8 -*-
2+
import os
3+
import sys
4+
5+
from recommonmark.parser import CommonMarkParser # noqa: F401
6+
7+
sys.path.append(os.path.abspath("../src"))
8+
9+
# -- Project information -----------------------------------------------------
10+
project = "MatterSim"
11+
copyright = "2024"
12+
author = "Microsoft Corporation"
13+
release = "1.0.0"
14+
15+
# -- General configuration ---------------------------------------------------
16+
extensions = [
17+
"sphinx.ext.autodoc",
18+
"sphinx.ext.napoleon",
19+
"sphinx_autodoc_typehints",
20+
"sphinx.ext.mathjax",
21+
"sphinx_copybutton",
22+
"recommonmark",
23+
"nbsphinx",
24+
]
25+
26+
source_suffix = {
27+
".rst": "restructuredtext",
28+
".md": "markdown",
29+
}
30+
31+
templates_path = ["_templates"]
32+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
33+
html_theme = "sphinx_book_theme"
34+
html_theme_options = {
35+
"repository_url": "https://github.com/microsoft/mattersim",
36+
"repository_provider": "github",
37+
"use_repository_button": True,
38+
}
39+
40+
# colorful codes
41+
# pygments_style = 'sphinx' # or any other Pygments style you prefer
42+
# pygments_style = 'solarized-dark' # or any other Pygments style you prefer
43+
44+
html_static_path = ["_static"]
45+
46+
# -- Options for nbsphinx ----------------------------------------------------
47+
nbsphinx_allow_errors = True
48+
nbsphinx_execute = "never"

‎docs/examples/examples.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Examples
2+
========
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
:numbered:
7+
8+
relax_example
9+
phonon_example.ipynb

‎docs/examples/phonon_example.ipynb

+246
Large diffs are not rendered by default.

‎docs/examples/relax_example.rst

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
Structure Optimization
2+
======================
3+
4+
This is a simple example of how to perform a structure optimization using the MatterSim.
5+
6+
Import the necessary modules
7+
----------------------------
8+
9+
.. code-block:: python
10+
11+
import numpy as np
12+
from ase.build import bulk
13+
from mattersim.forcefield.potential import Potential
14+
from mattersim.forcefield.potential import DeepCalculator
15+
16+
Set up the structure to relax
17+
-----------------------------
18+
19+
.. code-block:: python
20+
21+
# initialize the structure of silicon
22+
si = bulk("Si", "diamond", a=5.43)
23+
24+
# perturb the structure
25+
si.positions += 0.1 * np.random.randn(len(si), 3)
26+
27+
# load the model
28+
potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
29+
30+
# create a calculator from the model
31+
calculator = DeepCalculator(potential=potential)
32+
33+
# attach the calculator to the atoms object
34+
si.calc = calculator
35+
36+
Create the optimizer
37+
--------------------
38+
39+
MatterSim implements a built-in relaxation class to support the relaxation of ase atoms.

‎docs/index.rst

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
.. mattersim documentation master file, created by
2+
sphinx-quickstart on Thu Aug 22 14:01:40 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to the MatterSim Documentation!
7+
=======================================
8+
9+
Overview
10+
--------
11+
12+
`MatterSim <https://arxiv.org/abs/2405.04967>`_ is an advanced deep learning model designed to simulate
13+
the properties of materials across a wide range of elements, temperatures, and pressures.
14+
The model leverages state-of-the-art deep learning techniques to deliver high accuracy and
15+
efficiency in atomistic simulations, making it a valuable tool for researchers
16+
in the field of materials science.
17+
18+
MatterSim is still in active development, and more checkpoints may be
19+
released in appropriate time, so please stay tuned for updates.
20+
21+
Pre-trained Models
22+
------------------
23+
24+
We currently offer two pre-trained versions of MatterSim with **M3GNet** architecture:
25+
26+
1. **mattersim-mini-v1.0.0**: A mini version of the model that is faster to run.
27+
2. **mattersim-medium-v1.0.0**: A medium version of the model that is more accurate.
28+
29+
These models have been trained using the data generated through the workflows
30+
introduced in the `MatterSim <https://arxiv.org/abs/2405.04967>`_ manuscript, which provides an in-depth
31+
explanation of the methodologies underlying the MatterSim model.
32+
33+
FAQ
34+
---
35+
36+
**Q1**: What is the difference between the mini and medium versions of MatterSim?
37+
38+
**A**: The mini version is a smaller model that is faster to run, while the medium version is more accurate.
39+
40+
**Q2**: Are you going to release the pre-trained models of MatterSim with transformer-based architectures?
41+
42+
**A**: The transformer-based MatterSim is still under development. Please contact us for more information.
43+
44+
Bibliography
45+
------------
46+
47+
.. note::
48+
49+
If you use MatterSim in your research, please cite the following paper:
50+
51+
.. code-block:: bibtex
52+
53+
@article{yang2024mattersim,
54+
title={
55+
Mattersim: A deep learning atomistic model across elements,
56+
temperatures and pressures
57+
},
58+
author={
59+
Yang, Han and Hu, Chenxi and Zhou, Yichi and Liu, Xixian
60+
and Shi, Yu and Li, Jielan and Li, Guanzhi and Chen, Zekun
61+
and Chen, Shuizhou and Zeni, Claudio and others
62+
},
63+
journal={arXiv preprint arXiv:2405.04967},
64+
year={2024}
65+
}
66+
67+
68+
69+
.. toctree::
70+
:maxdepth: 2
71+
:caption: User Guide:
72+
:hidden:
73+
74+
user_guide/installation
75+
user_guide/getting_started
76+
examples/examples

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/user_guide/getting_started.rst

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
Getting Started
2+
===============
3+
4+
A minimal example
5+
-----------------
6+
7+
The following example demonstrates how to load a pre-trained potential and make predictions for a single structure.
8+
9+
.. code-block:: python
10+
:linenos:
11+
12+
from ase.build import bulk
13+
from mattersim.forcefield.potential import Potential
14+
from mattersim.datasets.utils.build import build_dataloader
15+
16+
# set up the structure
17+
si = bulk("Si", "diamond", a=5.43)
18+
19+
# load the model
20+
potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
21+
22+
# build the dataloader that is compatible with MatterSim
23+
dataloader = build_dataloader([si], only_inference=True, model_type=model_name)
24+
25+
# make predictions
26+
predictions = potential.predict_properties(dataloader, include_forces=True, include_stresses=True)
27+
28+
# print the predictions
29+
print(f"Total energy in eV: {predictions[0]}")
30+
print(f"Forces in eV/Angstrom: {predictions[1]}")
31+
print(f"Stresses in GPa: {predictions[2]}")
32+
33+
34+
Interface to ASE
35+
----------------
36+
37+
MatterSim provides an interface to the Atomic Simulation Environment (ASE) to facilitate the use of MatterSim potentials in the popular ASE package.
38+
39+
.. code-block:: python
40+
:linenos:
41+
42+
from ase.build import bulk
43+
from mattersim.forcefield.potential import DeepCalculator
44+
45+
# same as before
46+
si = bulk("Si", "diamond", a=5.43)
47+
potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
48+
49+
# set up the calculator
50+
calculator = DeepCalculator(
51+
potential=potential,
52+
# important! convert GPa to eV/Angstrom^3
53+
stress_weight=1 / 160.21766208,
54+
)
55+
56+
si.calc = calculator
57+
# or
58+
si.set_calculator(calculator)
59+
60+
print(si.get_potential_energy())
61+
print(si.get_forces())
62+
print(si.get_stress(voigt=False))
63+
64+
65+
In the example above, the `DeepCalculator` class implements the ASE calculator interface. The **stress_weight** parameter is used to convert the stress tensor from GPa to :math:`\mathrm{eV}\cdot\mathrm{\mathring{A}}^{-3}`.
66+
67+
.. warning ::
68+
By default, the ASE package assumes :math:`\mathrm{eV}\cdot\mathrm{\mathring{A}}^{-3}` for the stress tensor. However, MatterSim uses GPa for the stress tensor. Therefore, the **stress_weight** parameter is necessary to convert the stress tensor from GPa to :math:`\mathrm{eV}\cdot\mathrm{\mathring{A}}^{-3}`.

0 commit comments

Comments
 (0)