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 <hanyang@microsoft.com>

.github/workflows/gh-pages.yaml

@@ -0,0 +1,48 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Set up Pandoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc
+
+    - name: Install dependencies
+      run: |
+        pip install sphinx sphinx-autodoc-typehints sphinx_book_theme sphinx-copybutton
+        pip install nbsphinx recommonmark Pygments
+        pip install pandoc
+
+    - name: Build the docs
+      run: |
+        cd docs
+        make html
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,30 @@
+# MatterSim Documentations
+
+## Prerequisite
+To compile the documentations on your local machine you will need to install
+the following dependency in your environment:
+```bash
+# sphinx
+pip install sphinx sphinx-autodoc-typehints sphinx_book_theme sphinx-copybutton
+
+# enable Markdown documentation in sphinx
+pip install recommonmark
+
+# enable python jupyter notebook in sphinx
+pip install nbsphinx nbconvert
+
+# install pandoc
+conda install -c conda-forge pandoc
+```
+
+## Compile the docs
+Under the root of this repo, execute the following commandline
+```bash
+sphinx-build -b html docs docs/_build
+```
+To browse the documentation on your local machine, you may start a minimal
+HTTP server with
+```bash
+python3 -m http.server --directory docs/_build 8000
+```
+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

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+import os
+import sys
+
+from recommonmark.parser import CommonMarkParser  # noqa: F401
+
+sys.path.append(os.path.abspath("../src"))
+
+# -- Project information -----------------------------------------------------
+project = "MatterSim"
+copyright = "2024"
+author = "Microsoft Corporation"
+release = "1.0.0"
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+    "recommonmark",
+    "nbsphinx",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "repository_url": "https://github.com/microsoft/mattersim",
+    "repository_provider": "github",
+    "use_repository_button": True,
+}
+
+# colorful codes
+# pygments_style = 'sphinx'  # or any other Pygments style you prefer
+# pygments_style = 'solarized-dark'  # or any other Pygments style you prefer
+
+html_static_path = ["_static"]
+
+# -- Options for nbsphinx ----------------------------------------------------
+nbsphinx_allow_errors = True
+nbsphinx_execute = "never"

docs/examples/examples.rst

@@ -0,0 +1,9 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   relax_example
+   phonon_example.ipynb

docs/examples/relax_example.rst

@@ -0,0 +1,39 @@
+Structure Optimization
+======================
+
+This is a simple example of how to perform a structure optimization using the MatterSim.
+
+Import the necessary modules
+----------------------------
+
+.. code-block:: python
+
+    import numpy as np
+    from ase.build import bulk
+    from mattersim.forcefield.potential import Potential
+    from mattersim.forcefield.potential import DeepCalculator
+
+Set up the structure to relax
+-----------------------------
+
+.. code-block:: python
+
+    # initialize the structure of silicon
+    si = bulk("Si", "diamond", a=5.43)
+
+    # perturb the structure
+    si.positions += 0.1 * np.random.randn(len(si), 3)
+
+    # load the model
+    potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
+
+    # create a calculator from the model
+    calculator = DeepCalculator(potential=potential)
+
+    # attach the calculator to the atoms object
+    si.calc = calculator
+
+Create the optimizer
+--------------------
+
+MatterSim implements a built-in relaxation class to support the relaxation of ase atoms.

docs/index.rst

@@ -0,0 +1,76 @@
+.. mattersim documentation master file, created by
+   sphinx-quickstart on Thu Aug 22 14:01:40 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the MatterSim Documentation!
+=======================================
+
+Overview
+--------
+
+`MatterSim <https://arxiv.org/abs/2405.04967>`_ is an advanced deep learning model designed to simulate 
+the properties of materials across a wide range of elements, temperatures, and pressures. 
+The model leverages state-of-the-art deep learning techniques to deliver high accuracy and 
+efficiency in atomistic simulations, making it a valuable tool for researchers 
+in the field of materials science.
+
+MatterSim is still in active development, and more checkpoints may be
+released in appropriate time, so please stay tuned for updates.
+
+Pre-trained Models
+------------------
+
+We currently offer two pre-trained versions of MatterSim with **M3GNet** architecture:
+
+1. **mattersim-mini-v1.0.0**: A mini version of the model that is faster to run. 
+2. **mattersim-medium-v1.0.0**: A medium version of the model that is more accurate.
+
+These models have been trained using the data generated through the workflows 
+introduced in the `MatterSim <https://arxiv.org/abs/2405.04967>`_ manuscript, which provides an in-depth 
+explanation of the methodologies underlying the MatterSim model.
+
+FAQ
+---
+
+**Q1**: What is the difference between the mini and medium versions of MatterSim?
+
+   **A**: The mini version is a smaller model that is faster to run, while the medium version is more accurate.
+
+**Q2**: Are you going to release the pre-trained models of MatterSim with transformer-based architectures?
+
+   **A**: The transformer-based MatterSim is still under development. Please contact us for more information.
+
+Bibliography
+------------
+
+.. note::
+
+   If you use MatterSim in your research, please cite the following paper:
+
+   .. code-block:: bibtex
+
+      @article{yang2024mattersim,
+         title={
+            Mattersim: A deep learning atomistic model across elements,
+            temperatures and pressures
+         },
+         author={
+            Yang, Han and Hu, Chenxi and Zhou, Yichi and Liu, Xixian
+            and Shi, Yu and Li, Jielan and Li, Guanzhi and Chen, Zekun
+            and Chen, Shuizhou and Zeni, Claudio and others
+         },
+         journal={arXiv preprint arXiv:2405.04967},
+         year={2024}
+      }
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide:
+   :hidden:
+
+   user_guide/installation
+   user_guide/getting_started
+   examples/examples

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/user_guide/getting_started.rst

@@ -0,0 +1,68 @@
+Getting Started
+===============
+
+A minimal example
+-----------------
+
+The following example demonstrates how to load a pre-trained potential and make predictions for a single structure.
+
+.. code-block:: python
+    :linenos:
+
+    from ase.build import bulk
+    from mattersim.forcefield.potential import Potential
+    from mattersim.datasets.utils.build import build_dataloader
+
+    # set up the structure
+    si = bulk("Si", "diamond", a=5.43)
+
+    # load the model
+    potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
+
+    # build the dataloader that is compatible with MatterSim
+    dataloader = build_dataloader([si], only_inference=True, model_type=model_name)
+
+    # make predictions
+    predictions = potential.predict_properties(dataloader, include_forces=True, include_stresses=True)
+
+    # print the predictions
+    print(f"Total energy in eV: {predictions[0]}")
+    print(f"Forces in eV/Angstrom: {predictions[1]}")
+    print(f"Stresses in GPa: {predictions[2]}")
+
+
+Interface to ASE
+----------------
+
+MatterSim provides an interface to the Atomic Simulation Environment (ASE) to facilitate the use of MatterSim potentials in the popular ASE package.
+
+.. code-block:: python
+    :linenos:
+
+    from ase.build import bulk
+    from mattersim.forcefield.potential import DeepCalculator
+
+    # same as before
+    si = bulk("Si", "diamond", a=5.43)
+    potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
+
+    # set up the calculator
+    calculator = DeepCalculator(
+        potential=potential,
+        # important! convert GPa to eV/Angstrom^3
+        stress_weight=1 / 160.21766208,
+    )
+
+    si.calc = calculator
+    # or
+    si.set_calculator(calculator)
+
+    print(si.get_potential_energy())
+    print(si.get_forces())
+    print(si.get_stress(voigt=False))
+
+
+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}`.
+
+.. warning ::
+    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}`.