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 <hanyang@microsoft.com>
microsoft · Dec 3, 2024 · dd70d04 · dd70d04
1 parent e4ab7b9
commit dd70d04
Show file tree

Hide file tree

Showing 7 changed files with 100 additions and 247 deletions.
diff --git a/MODEL_CARD.md b/MODEL_CARD.md
@@ -85,45 +85,41 @@ print(f"Stress: {atoms.get_stress(voigt=False)} eV/A^3, or {atoms.get_stress(voi
 #### Metrics
 
 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,
-
-$$
-\mathrm{MAE}_E = \frac{1}{N}\sum_{i}^N \frac{1}{N_{at}^{(i)}}|E_i-\tilde{E}_i|,
-$$
-
-$$
-\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,
-$$
-and
-$$
-\mathrm{MAE}_S = \frac{1}{N}\sum_i^{N}  ||S_{i}-\tilde{S}_{i}||_2,
-$$
-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.
+<p align="center">
+      <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">
+</p>
+<p align="center">
+      <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">
+</p>
+<p align="center">
+      <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">
+</p>
+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.
 
 
 ### Results
 
 | Dataset              | Dataset Size | MAE               | mattersim-v1.0.0-1M | mattersim-v1.0.0-5M |
 | -------------------- | ------------ | ----------------- | ------------ | ------------ |
 | MPtrj-random-1k      | 1000         | Energy [eV/atom]  | 0.030        | 0.024        |
-|                      |              | Forces [eV/$\AA$] | 0.149        | 0.109        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.149        | 0.109        |
 |                      |              | Stress [GPa]      | 0.241        | 0.186        |
 | MPtrj-high-stress-1k | 1000         | Energy [eV/atom]  | 0.110        | 0.108        |
-|                      |              | Forces [eV/$\AA$] | 0.417        | 0.361        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.417        | 0.361        |
 |                      |              | Stress [GPa]      | 6.230        | 6.003        |
 | Alexandria-1k        | 1000         | Energy [eV/atom]  | 0.058        | 0.016        |
-|                      |              | Forces [eV/$\AA$] | 0.086        | 0.042        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.086        | 0.042        |
 |                      |              | Stress [GPa]      | 0.761        | 0.205        |
 | MPF-Alkali-TP        | 460          | Energy [eV/atom]  | 0.024        | 0.021        |
-|                      |              | Forces [eV/$\AA$] | 0.331        | 0.293        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.331        | 0.293        |
 |                      |              | Stress [GPa]      | 0.845        | 0.714        |
 | MPF-TP               | 1069         | Energy [eV/atom]  | 0.029        | 0.026        |
-|                      |              | Forces [eV/$\AA$] | 0.418        | 0.364        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.418        | 0.364        |
 |                      |              | Stress [GPa]      | 1.159        | 1.144        |
 | Random-TP            | 693          | Energy [eV/atom]  | 0.208        | 0.199        |
-|                      |              | Forces [eV/$\AA$] | 0.933        | 0.824        |
+|                      |              | Forces [eV/<img src="https://latex.codecogs.com/svg.latex?\AA" alt="\AA">] | 0.933        | 0.824        |
 |                      |              | Stress [GPa]      | 2.065        | 1.999        |
 
-
 ## Technical Specifications [optional]
 
 ### Model Architecture and Objective

diff --git a/README.md b/README.md
@@ -20,6 +20,9 @@ MatterSim is a deep learning atomistic model across elements, temperatures and p
 This README provides a quick start guide. For more comprehensive information, please refer to the [MatterSim documentation](https://microsoft.github.io/mattersim/).
 
 ## Installation
+### Prerequisite
+* Python==3.9
+
 ### 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:

diff --git a/docs/_static/phonon_dispersion.png b/docs/_static/phonon_dispersion.png
diff --git a/docs/examples/examples.rst b/docs/examples/examples.rst
@@ -6,4 +6,4 @@ Examples
    :numbered:
 
    relax_example
-   phonon_example.ipynb
+   phonon_example
diff --git a/docs/examples/phonon_example.ipynb b/docs/examples/phonon_example.ipynb
diff --git a/docs/examples/phonon_example.rst b/docs/examples/phonon_example.rst
@@ -0,0 +1,77 @@
+Phonon Dispersion
+=================
+
+This is a simple example of how to compute the phonon dispersion using the MatterSim.
+
+Import the necessary modules
+----------------------------
+
+First we import the necessary modules. It is worth noting
+that we have a built-in workflow for phonon calculations using ``phonopy`` in MatterSim.
+
+.. code-block:: python
+    :linenos:
+
+    import numpy as np
+    from ase.build import bulk
+    from ase.units import GPa
+    from ase.visualize import view
+    from mattersim.forcefield.potential import MatterSimCalculator
+    from mattersim.applications.phonon import PhononWorkflow
+
+.. note ::
+    The ``phonopy`` package is required to compute the phonon dispersion.
+    You can install it by running the following command:
+
+    .. code-block:: console
+
+        conda install -c conda-forge phonopy==2.14.0
+
+
+Set up the MatterSim calculator
+-------------------------------
+
+.. code-block:: python
+    :linenos:
+
+    # initialize the structure of silicon
+    si = bulk("Si")
+
+    # attach the calculator to the atoms object
+    si.calc = MatterSimCalculator()
+
+Set up the phonon workflow
+--------------------------
+
+.. code-block:: python
+    :linenos:
+
+    ph = PhononWorkflow(
+        atoms=si,
+        find_prim = False,
+        work_dir = "/tmp/phonon_si_example",
+        amplitude = 0.01,
+        supercell_matrix = np.diag([4,4,4]),
+    )
+
+Compute the phonon dispersion
+-----------------------------
+
+.. code-block:: python
+    :linenos:
+
+    has_imag, phonons = ph.run()
+    print(f"Has imaginary phonon: {has_imag}")
+    print(f"Phonon frequencies: {phonons}")
+
+Inspect the phonon dispersion
+-----------------------------
+
+Once the calculation is done, you can find the phonon plot in the work directory.
+In this case, you find the plot in the directory ``/tmp/phonon_si_example``,
+and here is the phonon dispersion plot for the example above.
+
+.. image:: /_static/phonon_dispersion.png
+    :width: 400
+    :align: center
+    :alt: Phonon dispersion of silicon
diff --git a/docs/examples/relax_example.rst b/docs/examples/relax_example.rst
@@ -7,6 +7,7 @@ Import the necessary modules
 ----------------------------
 
 .. code-block:: python
+    :linenos:
 
     import numpy as np
     from ase.build import bulk
@@ -18,6 +19,7 @@ Set up the structure to relax
 -----------------------------
 
 .. code-block:: python
+    :linenos:
 
     # initialize the structure of silicon
     si = bulk("Si", "diamond", a=5.43)
@@ -34,6 +36,7 @@ Run the relaxation
 MatterSim implements a built-in relaxation class to support the relaxation of ase atoms.
 
 .. code-block:: python
+    :linenos:
 
     # initialize the relaxation object
     relaxer = Relaxer(