Skip to content

Commit dd70d04

Browse files
yanghan234yanghan-microsoft
yanghan234
and
yanghan-microsoft
authored
doc: update documentations (#41)
* change the phonon example to rst format * update the example page and link to new phonon example rst page * update relax example * add phonon plot * add python requirement * fix equations display in model card * try to fix inline formula * try to fix inline formula * try to fix inline formula --------- Co-authored-by: Han Yang <[email protected]>
1 parent e4ab7b9 commit dd70d04

7 files changed

+100
-247
lines changed

‎MODEL_CARD.md

+16-20
Original file line numberDiff line numberDiff line change
@@ -85,45 +85,41 @@ print(f"Stress: {atoms.get_stress(voigt=False)} eV/A^3, or {atoms.get_stress(voi
8585
#### Metrics
8686

8787
We evaluate the performance by computing the mean absolute errors (MAEs) of energy (E), forces (F) and stress (S) of each structures within the same dataset. The MAEs are defined as follows,
88-
89-
$$
90-
\mathrm{MAE}_E = \frac{1}{N}\sum_{i}^N \frac{1}{N_{at}^{(i)}}|E_i-\tilde{E}_i|,
91-
$$
92-
93-
$$
94-
\mathrm{MAE}_F = \frac{1}{N}\sum_i^N \frac{1}{N_{at}^{(i)}} \sum_{j}^{N^{(i)}_{at}} ||F_{ij}-\tilde{F}_{ij}||_2,
95-
$$
96-
and
97-
$$
98-
\mathrm{MAE}_S = \frac{1}{N}\sum_i^{N} ||S_{i}-\tilde{S}_{i}||_2,
99-
$$
100-
where $N$ is the number of structures in the same dataset, $N_{at}^{(i)}$ is the number of atoms in the $i$-th structure and $\tilde{E}$, $\tilde{F}$ and $\tilde{S}$ represent ground-truth energy, forces and stress, respectively.
88+
<p align="center">
89+
<img src="https://latex.codecogs.com/svg.latex?\mathrm{MAE}_E=\frac{1}{N}\sum_{i}^N\frac{1}{N_{at}^{(i)}}|E_i-\tilde{E}_i|" alt="MAE_E equation">
90+
</p>
91+
<p align="center">
92+
<img src="https://latex.codecogs.com/svg.latex?\mathrm{MAE}_F=\frac{1}{N}\sum_i^N\frac{1}{N_{at}^{(i)}}\sum_{j}^{N^{(i)}_{at}}||F_{ij}-\tilde{F}_{ij}||_2," alt="MAE_F equation">
93+
</p>
94+
<p align="center">
95+
<img src="https://latex.codecogs.com/svg.latex?\mathrm{MAE}_S=\frac{1}{N}\sum_i^{N}||S_{i}-\tilde{S}_{i}||_2," alt="MAE_S equation">
96+
</p>
97+
where N is the number of structures in the same dataset, <img src="https://latex.codecogs.com/svg.image?\inline&space;&space;N_{at}^{(i)}"> is the number of atoms in the i-th structure and E, F and S represent ground-truth energy, forces and stress, respectively.
10198

10299

103100
### Results
104101

105102
| Dataset | Dataset Size | MAE | mattersim-v1.0.0-1M | mattersim-v1.0.0-5M |
106103
| -------------------- | ------------ | ----------------- | ------------ | ------------ |
107104
| MPtrj-random-1k | 1000 | Energy [eV/atom] | 0.030 | 0.024 |
108-
| | | Forces [eV/$\AA$] | 0.149 | 0.109 |
105+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.149 | 0.109 |
109106
| | | Stress [GPa] | 0.241 | 0.186 |
110107
| MPtrj-high-stress-1k | 1000 | Energy [eV/atom] | 0.110 | 0.108 |
111-
| | | Forces [eV/$\AA$] | 0.417 | 0.361 |
108+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.417 | 0.361 |
112109
| | | Stress [GPa] | 6.230 | 6.003 |
113110
| Alexandria-1k | 1000 | Energy [eV/atom] | 0.058 | 0.016 |
114-
| | | Forces [eV/$\AA$] | 0.086 | 0.042 |
111+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.086 | 0.042 |
115112
| | | Stress [GPa] | 0.761 | 0.205 |
116113
| MPF-Alkali-TP | 460 | Energy [eV/atom] | 0.024 | 0.021 |
117-
| | | Forces [eV/$\AA$] | 0.331 | 0.293 |
114+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.331 | 0.293 |
118115
| | | Stress [GPa] | 0.845 | 0.714 |
119116
| MPF-TP | 1069 | Energy [eV/atom] | 0.029 | 0.026 |
120-
| | | Forces [eV/$\AA$] | 0.418 | 0.364 |
117+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.418 | 0.364 |
121118
| | | Stress [GPa] | 1.159 | 1.144 |
122119
| Random-TP | 693 | Energy [eV/atom] | 0.208 | 0.199 |
123-
| | | Forces [eV/$\AA$] | 0.933 | 0.824 |
120+
| | | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.933 | 0.824 |
124121
| | | Stress [GPa] | 2.065 | 1.999 |
125122

126-
127123
## Technical Specifications [optional]
128124

129125
### Model Architecture and Objective

‎README.md

+3
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ MatterSim is a deep learning atomistic model across elements, temperatures and p
2020
This README provides a quick start guide. For more comprehensive information, please refer to the [MatterSim documentation](https://microsoft.github.io/mattersim/).
2121

2222
## Installation
23+
### Prerequisite
24+
* Python==3.9
25+
2326
### Install from PyPI
2427
> [!TIP]
2528
> 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:

‎docs/_static/phonon_dispersion.png

81.4 KB
Loading

‎docs/examples/examples.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ Examples
66
:numbered:
77

88
relax_example
9-
phonon_example.ipynb
9+
phonon_example

‎docs/examples/phonon_example.ipynb

-226
This file was deleted.

‎docs/examples/phonon_example.rst

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
Phonon Dispersion
2+
=================
3+
4+
This is a simple example of how to compute the phonon dispersion using the MatterSim.
5+
6+
Import the necessary modules
7+
----------------------------
8+
9+
First we import the necessary modules. It is worth noting
10+
that we have a built-in workflow for phonon calculations using ``phonopy`` in MatterSim.
11+
12+
.. code-block:: python
13+
:linenos:
14+
15+
import numpy as np
16+
from ase.build import bulk
17+
from ase.units import GPa
18+
from ase.visualize import view
19+
from mattersim.forcefield.potential import MatterSimCalculator
20+
from mattersim.applications.phonon import PhononWorkflow
21+
22+
.. note ::
23+
The ``phonopy`` package is required to compute the phonon dispersion.
24+
You can install it by running the following command:
25+
26+
.. code-block:: console
27+
28+
conda install -c conda-forge phonopy==2.14.0
29+
30+
31+
Set up the MatterSim calculator
32+
-------------------------------
33+
34+
.. code-block:: python
35+
:linenos:
36+
37+
# initialize the structure of silicon
38+
si = bulk("Si")
39+
40+
# attach the calculator to the atoms object
41+
si.calc = MatterSimCalculator()
42+
43+
Set up the phonon workflow
44+
--------------------------
45+
46+
.. code-block:: python
47+
:linenos:
48+
49+
ph = PhononWorkflow(
50+
atoms=si,
51+
find_prim = False,
52+
work_dir = "/tmp/phonon_si_example",
53+
amplitude = 0.01,
54+
supercell_matrix = np.diag([4,4,4]),
55+
)
56+
57+
Compute the phonon dispersion
58+
-----------------------------
59+
60+
.. code-block:: python
61+
:linenos:
62+
63+
has_imag, phonons = ph.run()
64+
print(f"Has imaginary phonon: {has_imag}")
65+
print(f"Phonon frequencies: {phonons}")
66+
67+
Inspect the phonon dispersion
68+
-----------------------------
69+
70+
Once the calculation is done, you can find the phonon plot in the work directory.
71+
In this case, you find the plot in the directory ``/tmp/phonon_si_example``,
72+
and here is the phonon dispersion plot for the example above.
73+
74+
.. image:: /_static/phonon_dispersion.png
75+
:width: 400
76+
:align: center
77+
:alt: Phonon dispersion of silicon

‎docs/examples/relax_example.rst

+3
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Import the necessary modules
77
----------------------------
88

99
.. code-block:: python
10+
:linenos:
1011
1112
import numpy as np
1213
from ase.build import bulk
@@ -18,6 +19,7 @@ Set up the structure to relax
1819
-----------------------------
1920

2021
.. code-block:: python
22+
:linenos:
2123
2224
# initialize the structure of silicon
2325
si = bulk("Si", "diamond", a=5.43)
@@ -34,6 +36,7 @@ Run the relaxation
3436
MatterSim implements a built-in relaxation class to support the relaxation of ase atoms.
3537

3638
.. code-block:: python
39+
:linenos:
3740
3841
# initialize the relaxation object
3942
relaxer = Relaxer(

0 commit comments

Comments
 (0)