deploy: 88180f5

_sources/examples/relax_example.rst

@@ -11,8 +11,7 @@ Import the necessary modules
     import numpy as np
     from ase.build import bulk
     from ase.units import GPa
-    from mattersim.forcefield.potential import Potential
-    from mattersim.forcefield.potential import DeepCalculator
+    from mattersim.forcefield.potential import MatterSimCalculator
     from mattersim.applications.relax import Relaxer
 
 Set up the structure to relax
@@ -26,14 +25,8 @@ Set up the structure to relax
     # 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
-    calc = DeepCalculator(potential=potential, stress_weight=GPa)
-
     # attach the calculator to the atoms object
-    si.calc = calc
+    si.calc = MatterSimCalculator()
 
 Run the relaxation
 --------------------
@@ -49,5 +42,4 @@ MatterSim implements a built-in relaxation class to support the relaxation of as
         constrain_symmetry=True, # whether to constrain the symmetry
     )
 
-    relaxed_structure = relaxer.run(si, steps=500)
-
+    relaxed_structure = relaxer.relax(si, steps=500)

_sources/index.rst

@@ -9,25 +9,25 @@ 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 
+`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.
+MatterSim is still in active development, and newer models may be released
+in appropriate time. Please stay tuned for updates.
 
 Pre-trained Models
 ------------------
 
-We currently offer two pre-trained versions of MatterSim with **M3GNet** architecture:
+We currently offer two pre-trained **MatterSim-v1** models based on the **M3GNet** architecture
 
-1. **MatterSim-v1.0.0-1M**: A mini version of the model that is faster to run. 
+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 <https://arxiv.org/abs/2405.04967>`_ manuscript, which provides an in-depth 
+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.
 
 Bibliography
@@ -40,7 +40,7 @@ Bibliography
    .. code-block:: bibtex
 
       @article{yang2024mattersim,
-         title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures}, 
+         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 Zügner 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},
@@ -67,7 +67,7 @@ Frequently Asked Questions
    **A**: Yes, we are actively working on developing more pre-trained models for MatterSim. Please stay tuned for updates.
 
 **Q4**: How can I contribute to the development of MatterSim?
-   
+
    **A**: We warmly welcome contributions! Please help improve MatterSim by reporting bugs, suggesting features, or submitting pull requests to our GitHub repository: https://github.com/microsoft/mattersim/pulls.
 
 

_sources/user_guide/getting_started.rst

@@ -1,69 +1,76 @@
 Getting Started
 ===============
 
-A minimal example
------------------
+A minimal example using ASE calculator
+--------------------------------------
 
-The following example demonstrates how to load a pre-trained potential and make predictions for a single structure.
+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:
 
+    import torch
     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")
+    from ase.units import GPa
+    from mattersim.forcefield import MatterSimCalculator
 
-    # build the dataloader that is compatible with MatterSim
-    dataloader = build_dataloader([si], only_inference=True, model_type=model_name)
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"Running MatterSim on {device}")
 
-    # make predictions
-    predictions = potential.predict_properties(dataloader, include_forces=True, include_stresses=True)
+    si = bulk("Si", "diamond", a=5.43)
+    si.calc = MatterSimCalculator(device=device)
+    print(f"Energy (eV)                 = {si.get_potential_energy()}")
+    print(f"Energy per atom (eV/atom)   = {si.get_potential_energy()/len(si)}")
+    print(f"Forces of first atom (eV/A) = {si.get_forces()[0]}")
+    print(f"Stress[0][0] (eV/A^3)       = {si.get_stress(voigt=False)[0][0]}")
+    print(f"Stress[0][0] (GPa)          = {si.get_stress(voigt=False)[0][0] / GPa}")
 
-    # 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]}")
 
+In the example above, the ``MatterSimCalculator`` class implements the ASE calculator interface.
+However, with ``MatterSimCalculator``, one can only predict the properties of a single structure at a time,
+which is not efficient for large-scale calculations to effectively utilize the GPU.
+Thus, we also provide a more efficient way to predict the properties of multiple structures using the ``Potential`` class.
 
-Interface to ASE
-----------------
+Batch prediction using the ``Potential`` class
+----------------------------------------------
 
-MatterSim provides an interface to the Atomic Simulation Environment (ASE) to facilitate the use of MatterSim potentials in the popular ASE package.
+The ``Potential`` class provides a more efficient way to predict the properties of
+multiple structures using the ``predict_properties`` method.
+In the following example, we demonstrate how to predict the properties of
+a list of structures using the ``Potential`` class.
 
 .. code-block:: python
     :linenos:
 
+    import numpy as np
     from ase.build import bulk
     from ase.units import GPa
-    from mattersim.forcefield.potential import DeepCalculator
+    from mattersim.forcefield.potential import Potential
+    from mattersim.datasets.utils.build import build_dataloader
 
-    # same as before
+    # set up the structure
     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=GPa,
-    )
+    # replicate the structures to form a list
+    structures = [si] * 10
 
-    si.calc = calculator
-    # or
-    si.set_calculator(calculator)
+    # load the model
+    potential = Potential.load(load_path="/path/to/checkpoint", device="cuda:0")
 
-    print(si.get_potential_energy())
-    print(si.get_forces())
-    print(si.get_stress(voigt=False))
+    # build the dataloader that is compatible with MatterSim
+    dataloader = build_dataloader(structures, only_inference=True)
 
+    # make predictions
+    predictions = potential.predict_properties(dataloader, include_forces=True, include_stresses=True)
 
-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}`.
+    # 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]}")
+    print(f"Stresses in eV/A^3: {np.array(predictions[2])*GPa}")
 
 .. 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}`.
+    By default, MatterSim ``potential.predict_properties`` predicts stress tensors in GPa.
+    To convert the stress tensor to :math:`\mathrm{eV}\cdot\mathrm{\mathring{A}}^{-3}`,
+    multiply the stress tensor by the conversion factor ``GPa``.

_sources/user_guide/installation.rst

@@ -29,6 +29,19 @@ To install the package, run the following command under the root of the folder:
     conda env create -f environment.yaml
     conda activate mattersim
     pip install -e .
+    python setup.py build_ext --inplace
+
+
+Please note that the installation process may take a while due to the installation of the dependencies.
+For faster installation, we recommend the users to install with [mamba or micromamba](https://mamba.readthedocs.io/en/latest/index.html),
+and the [uv](https://docs.astral.sh/uv/) package manager.
+
+.. code-block:: console
+
+    mamba env create -f environment.yaml
+    mamba activate mattersim
+    uv pip install -e .
+    python setup.py build_ext --inplace
 
 Model checkpoints
 ----------------------------