### Install MatterSim from Source with Mamba and UV

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/installation.md

For faster installation from source, use mamba or micromamba for environment creation and uv for package management.

```console
mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .
python setup.py build_ext --inplace
```

--------------------------------

### Install MatterSim from PyPI

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Installs the MatterSim package using pip. This is the recommended method for most users.

```bash
pip install mattersim
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/microsoft/mattersim/blob/main/docs/README.md

Starts a simple HTTP server to browse the compiled documentation on your local machine.

```bash
python3 -m http.server --directory docs/_build 8000
```

--------------------------------

### Install MatterSim from Source with Mamba

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Installs MatterSim from source code using Mamba for environment management and uv pip for editable installation. This method is recommended for development or when installing from source.

```bash
mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .
```

--------------------------------

### Minimal Finetune Example

Source: https://github.com/microsoft/mattersim/blob/main/README.md

A command-line example for finetuning the MatterSim model. It specifies the number of processes, the finetuning script, the path to the pre-trained model, and the custom training data.

```bash
torchrun --nproc_per_node=1 src/mattersim/training/finetune_mattersim.py --load_model_path mattersim-v1.0.0-1m --train_data_path tests/data/high_level_water.xyz
```

--------------------------------

### Install Latest MatterSim from GitHub

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Installs the latest version of MatterSim directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/microsoft/mattersim.git
```

--------------------------------

### Install MatterSim from Source with Conda

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/installation.md

Install MatterSim from source code using conda for environment and dependency management. This method may take longer due to dependency installation.

```console
conda env create -f environment.yaml
conda activate mattersim
pip install -e .
python setup.py build_ext --inplace
```

--------------------------------

### Install Sphinx Dependencies

Source: https://github.com/microsoft/mattersim/blob/main/docs/README.md

Installs necessary Python packages for Sphinx documentation generation, including themes and extensions.

```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
```

--------------------------------

### Minimal ASE Calculator Example

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/getting_started.md

Use `MatterSimCalculator` to interface MatterSim potentials with ASE for predicting properties of a single structure. Ensure PyTorch is installed and a compatible device (CPU or CUDA) is available.

```python
import torch
from ase.build import bulk
from ase.units import GPa
from mattersim.forcefield import MatterSimCalculator

device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Running MatterSim on {device}")

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}")
```

--------------------------------

### Import Necessary Modules for Phonon Calculations

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/phonon_example.md

Imports essential libraries for phonon calculations, including NumPy, ASE for atomic structures, and MatterSim's specific modules for calculators and workflows. Ensure these are installed before running.

```python
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
```

--------------------------------

### Run MatterSim LAMMPS Example Inside Docker

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Execute a LAMMPS simulation using the pre-built MatterSim Docker image. This example demonstrates exporting a model and running a simulation within the container.

```bash
docker run --gpus all -it mattersim-lammps

# Inside the container:
mkdir /tmp/example && cd /tmp/example

# Export the model and copy the example input (one-time):
python -c "
from mattersim.lammps.mliap_wrapper import MatterSimMLIAP
mliap = MatterSimMLIAP.from_checkpoint('mattersim-v1.0.0-5M')
mliap.save('model.pt')
import shutil, mattersim.lammps.examples as e, os
shutil.copy(os.path.join(os.path.dirname(e.__file__), 'cu_nve.in'), '.')
"

# Run (single GPU):
lmp -in cu_nve.in -k on g 1 -sf kk \
    -pk kokkos newton on neigh half \
    -var MODEL_PATH model.pt
```

--------------------------------

### Create TorchSim Wrapper from Model Identifier

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Use `get_torchsim_wrapper` with a model identifier to automatically download and load the checkpoint. Ensure PyTorch is installed and a CUDA-enabled device is available if possible.

```python
import torch
from mattersim.torchsim import get_torchsim_wrapper

device = "cuda" if torch.cuda.is_available() else "cpu"

# From a model identifier (downloads the checkpoint automatically)
wrapper = get_torchsim_wrapper(potential="mattersim-v1.0.0-1M", device=device)
```

--------------------------------

### NVT Molecular Dynamics Simulation

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Perform NVT molecular dynamics using the Langevin thermostat. This example initializes a system, runs integration for a specified number of steps at a target temperature, and converts the final state back to an ASE Atoms object.

```python
import torch
import torch_sim as ts
from ase.build import bulk
from mattersim.torchsim import get_torchsim_wrapper

device = "cuda" if torch.cuda.is_available() else "cpu"

# Create the wrapper
wrapper = get_torchsim_wrapper(potential="mattersim-v1.0.0-1M", device=device)

# Set up the structure
si = bulk("Si", "diamond", a=5.43)
state = ts.initialize_state([si], device=device)

# Run NVT MD at 300 K for 1000 steps
final_state = ts.integrate(
    system=state,
    model=wrapper,
    integrator=ts.Integrator.nvt_langevin,
    n_steps=1000,
    temperature=300.0,
    timestep=1e-3,
    pbar=True,
)

# Convert back to ASE Atoms
final_atoms = final_state.to_atoms()[0]
```

--------------------------------

### Import Libraries for MatterSim API Calls

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Import necessary Python packages for making API calls, handling data, and displaying results. Ensure these libraries are installed in your environment.

```python
import os
import urllib.request
import json
import base64
import time
from io import BytesIO
from IPython.display import Image, display
```

--------------------------------

### Minimal MatterSim Usage Test

Source: https://github.com/microsoft/mattersim/blob/main/README.md

A basic example demonstrating how to use MatterSimCalculator with ASE to calculate the energy, forces, and stress of a Silicon crystal. It automatically selects CUDA if available, otherwise uses CPU.

```python
import torch
from loguru import logger
from ase.build import bulk
from ase.units import GPa
from mattersim.forcefield import MatterSimCalculator

device = "cuda" if torch.cuda.is_available() else "cpu"
logger.info(f"Running MatterSim on {device}")

si = bulk("Si", "diamond", a=5.43)
si.calc = MatterSimCalculator(device=device)
logger.info(f"Energy (eV)                 = {si.get_potential_energy()}")
logger.info(f"Energy per atom (eV/atom)   = {si.get_potential_energy()/len(si)}")
logger.info(f"Forces of first atom (eV/A) = {si.get_forces()[0]}")
logger.info(f"Stress[0][0] (eV/A^3)       = {si.get_stress(voigt=False)[0][0]}")
logger.info(f"Stress[0][0] (GPa)          = {si.get_stress(voigt=False)[0][0] / GPa}")
```

--------------------------------

### Saving Trajectories with TrajectoryReporter

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Configure and use a `TrajectoryReporter` to save simulation trajectory frames to an HDF5 file. This example demonstrates saving velocities and forces every 100 steps during an NVT simulation.

```python
import torch
import torch_sim as ts
from ase.build import bulk
from mattersim.torchsim import get_torchsim_wrapper

device = "cuda" if torch.cuda.is_available() else "cpu"
wrapper = get_torchsim_wrapper(potential="mattersim-v1.0.0-1M", device=device)

si = bulk("Si", "diamond", a=5.43)
state = ts.initialize_state([si], device=device)

# Configure a trajectory reporter to save every 100 steps
reporter = ts.TrajectoryReporter(
    filenames=["md_trajectory.h5md"],
    state_frequency=100,
    state_kwargs=dict(save_velocities=True, save_forces=True),
)

final_state = ts.integrate(
    system=state,
    model=wrapper,
    integrator=ts.Integrator.nvt_langevin,
    n_steps=1000,
    temperature=300.0,
    timestep=1e-3,
    trajectory_reporter=reporter,
    pbar=True,
)
```

--------------------------------

### Set Up MatterSim Calculator

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/phonon_example.md

Initializes a silicon structure using ASE's bulk function and attaches the MatterSimCalculator to it. This calculator will be used for force field calculations.

```python
# initialize the structure of silicon
si = bulk("Si")

# attach the calculator to the atoms object
si.calc = MatterSimCalculator()
```

--------------------------------

### Set Up Structure for Relaxation

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/relax_example.md

Initialize a silicon structure using ASE's bulk function and perturb its positions. Attach the MatterSimCalculator to the structure.

```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)

# attach the calculator to the atoms object
si.calc = MatterSimCalculator()
```

--------------------------------

### Set Up Phonon Workflow

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/phonon_example.md

Configures the PhononWorkflow with the atomic structure, specifies the working directory, and sets parameters like the supercell matrix and displacement amplitude. The `find_prim` parameter is set to False, indicating that the primitive cell is not automatically determined.

```python
ph = PhononWorkflow(
    atoms=si,
    find_prim = False,
    work_dir = "/tmp/phonon_si_example",
    amplitude = 0.01,
    supercell_matrix = np.diag([4,4,4]),
)
```

--------------------------------

### Set Up MatterSim Batch Relaxer

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/batch_relaxation_example.md

Initialize the MatterSim Potential and the BatchRelaxer with specified parameters for cell relaxation and optimization.

```python
# initialize the default MatterSim Potential
potential = Potential.from_checkpoint()

# initialize the batch relaxer with a EXPCELLFILTER for cell relaxation and a FIRE optimizer
relaxer = BatchRelaxer(potential, fmax=0.01, filter="EXPCELLFILTER", optimizer="FIRE")
```

--------------------------------

### Load and Access Test Datasets

Source: https://github.com/microsoft/mattersim/blob/main/MODEL_CARD.md

This snippet demonstrates how to load test datasets (e.g., MPtrj-random-1k, Alexandria-1k) using pickle and access atomic properties like energy, forces, and stress. Ensure the path to the dataset file is correct.

```python
import pickle
from ase.units import GPa

atoms_list = pickle.load(open("/path/to/datasets.pkl", "rb"))
atoms = atoms_list[0]

print(f"Energy: {atoms.get_potential_energy()} eV")
print(f"Forces: {atoms.get_forces()} eV/A")
print(f"Stress: {atoms.get_stress(voigt=False)} eV/A^3, or {atoms.get_stress(voigt=False)/GPa}")
```

--------------------------------

### Import Necessary Modules

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/relax_example.md

Import required libraries from NumPy, ASE, and MatterSim for structure optimization.

```python
import numpy as np
from ase.build import bulk
from ase.units import GPa
from mattersim.forcefield.potential import MatterSimCalculator
from mattersim.applications.relax import Relaxer
```

--------------------------------

### Run LAMMPS Simulation (Single GPU)

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Execute a LAMMPS simulation using the ML-IAP pair style with Kokkos and GPU support. Ensure the correct flags for Kokkos and neighbor lists are set.

```bash
lmp -in input.in -k on g 1 -sf kk -pk kokkos newton on neigh half
```

--------------------------------

### Compile Sphinx Documentation

Source: https://github.com/microsoft/mattersim/blob/main/docs/README.md

Builds the HTML version of the documentation from the Sphinx source files.

```bash
sphinx-build -b html docs docs/_build
```

--------------------------------

### Import Necessary Modules

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/batch_relaxation_example.md

Import the required modules from ASE and MatterSim for batch relaxation.

```python
from ase.build import bulk
from mattersim.applications.batch_relax import BatchRelaxer
from mattersim.forcefield.potential import Potential
```

--------------------------------

### Run Batch Relaxation

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/batch_relaxation_example.md

Execute the batch relaxation process on the prepared list of structures using the configured relaxer.

```python
# Run the relaxation
relaxation_trajectories = relaxer.relax(atoms)
```

--------------------------------

### Direct TorchSim Wrapper Construction

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Construct a `TorchSimWrapper` directly for full control over initialization. Requires explicit loading of the `Potential` object.

```python
from mattersim.torchsim import TorchSimWrapper
from mattersim.forcefield import Potential

# Assuming 'device' is already defined (e.g., "cuda" or "cpu")
potential = Potential.from_checkpoint(device=device)
wrapper = TorchSimWrapper(model=potential, device=device)
```

--------------------------------

### Switch to 5M Pre-trained Model

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Demonstrates how to explicitly load the larger 'MatterSim-v1.0.0-5M.pth' model by setting the 'load_path' argument in MatterSimCalculator.

```python
MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device)
```

--------------------------------

### Run Structure Relaxation

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/relax_example.md

Initialize and run the relaxation process using MatterSim's Relaxer class with specified optimizer and cell filter.

```python
# initialize the relaxation object
relaxer = Relaxer(
    optimizer="BFGS", # the optimization method
    filter="ExpCellFilter", # filter to apply to the cell
    constrain_symmetry=True, # whether to constrain the symmetry
)

relaxed_structure = relaxer.relax(si, steps=500)
```

--------------------------------

### Structure Relaxation with FIRE Optimizer

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Perform structure relaxation using TorchSim's `optimize` function with the FIRE optimizer. Requires setting up the system, initializing a TorchSim state, and converting the relaxed state back to an ASE Atoms object.

```python
import numpy as np
import torch
import torch_sim as ts
from ase.build import bulk
from mattersim.torchsim import get_torchsim_wrapper

device = "cuda" if torch.cuda.is_available() else "cpu"

# Create the wrapper
wrapper = get_torchsim_wrapper(potential="mattersim-v1.0.0-1M", device=device)

# Set up the structure
si = bulk("Si", "diamond", a=5.43)
si.positions += 0.1 * np.random.randn(len(si), 3)

# Initialize a TorchSim state from the ASE Atoms object
state = ts.initialize_state([si], device=device)

# Run relaxation with the FIRE optimizer
relaxed_state = ts.optimize(
    system=state,
    model=wrapper,
    optimizer=ts.Optimizer.fire,
    max_steps=500,
    pbar=True,
)

# Convert back to ASE Atoms
relaxed_atoms = relaxed_state.to_atoms()[0]
print(f"Relaxed energy: {relaxed_state.energy[0].item():.4f} eV")
```

--------------------------------

### Create TorchSim Wrapper from Potential Object

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Instantiate a `TorchSimWrapper` using an already loaded `Potential` object. This method is useful when the potential is managed elsewhere or pre-loaded.

```python
from mattersim.torchsim import get_torchsim_wrapper
from mattersim.forcefield import Potential

# Assuming 'device' is already defined (e.g., "cuda" or "cpu")
potential = Potential.from_checkpoint(device=device)
wrapper = get_torchsim_wrapper(potential=potential, device=device)
```

--------------------------------

### Generate and Perturb Structures for Relaxation

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/batch_relaxation_example.md

Create a list of ASE Atoms objects, perturb them using rattle for non-trivial relaxation, and prepare them for the batch relaxation process.

```python
# Here, we generate a list of ASE Atoms objects we want to relax
atoms = [bulk("C"), bulk("Mg"), bulk("Si"), bulk("Ni")]

# And then perturb them a bit so that relaxation is not trivial
for atom in atoms:
    atom.rattle(stdev=0.1)
```

--------------------------------

### Inspect Relaxed Structures and Energies

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/batch_relaxation_example.md

Extract and compare the initial and final structures and their total energies from the relaxation trajectories to verify energy decrease.

```python
# Extract the relaxed structures and corresponding energies
relaxed_structures = [traj[-1] for traj in relaxation_trajectories.values()]
relaxed_energies = [structure.info['total_energy'] for structure in relaxed_structures]

# Do the same with the initial structures and energies
initial_structures = [traj[0] for traj in relaxation_trajectories.values()]
initial_energies = [structure.info['total_energy'] for structure in initial_structures]

# verify by inspection that total energy has decreased in all instances
for initial_energy, relaxed_energy in zip(initial_energies, relaxed_energies):
    print(f"Initial energy: {initial_energy} eV, relaxed energy: {relaxed_energy} eV")
```

--------------------------------

### Finetune MatterSim Model

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/finetune.md

Use this command to finetune the MatterSim model with your custom dataset. Replace data paths and adjust parameters like batch size, learning rate, and epochs as needed. The script supports including stresses and forces in the training process.

```bash
torchrun --nproc_per_node=1 src/mattersim/training/finetune_mattersim.py \
                            --load_model_path mattersim-v1.0.0-1m \
                            --train_data_path xyz_files/train.xyz \
                            --valid_data_path xyz_files/valid.xyz \
                            --batch_size 16 \
                            --lr 2e-4 \
                            --step_size 20 \
                            --epochs 200 \
                            --save_path ./finetune_result \
                            --save_checkpoint \
                            --ckpt_interval 20 \
                            --include_stresses \
                            --include_forces
```

--------------------------------

### Run Custom Simulations in MatterSim LAMMPS Docker

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Run your own LAMMPS simulations using the MatterSim Docker image by mounting your input files and specifying the model path. Supports both single-GPU and multi-GPU configurations.

```bash
docker run --gpus all -it -v $(pwd):/work -w /work mattersim-lammps

# Single GPU:
lmp -in input.in -k on g 1 -sf kk \
    -pk kokkos newton on neigh half \
    -var MODEL_PATH /path/to/mattersim-v1.0.0-5M-mliap.pt

# Multi-GPU (4 GPUs):
mpirun -np 4 --mca pml ucx --mca osc ucx \
    lmp -in input.in \
    -k on g 4 -sf kk \
    -pk kokkos newton on neigh half gpu/aware on \
    comm/pair/forward device comm/pair/reverse device \
    -var MODEL_PATH /path/to/mattersim-v1.0.0-5M-mliap.pt
```

--------------------------------

### Clone MatterSim Repository

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Clones the MatterSim source code from GitHub and navigates into the project directory.

```bash
git clone git@github.com:microsoft/mattersim.git
cd mattersim
```

--------------------------------

### Structure Relaxation with Custom Convergence

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/torchsim.md

Customize structure relaxation convergence criteria using `ts.generate_force_convergence_fn`. This allows setting a specific force tolerance for stopping the optimization.

```python
convergence_fn = ts.generate_force_convergence_fn(force_tol=0.01)

# Assuming 'state', 'wrapper' are already defined
relaxed_state = ts.optimize(
    system=state,
    model=wrapper,
    optimizer=ts.Optimizer.fire,
    max_steps=500,
    convergence_fn=convergence_fn,
    pbar=True,
)
```

--------------------------------

### Build MatterSim LAMMPS Docker Image

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Build a Docker image for LAMMPS with Kokkos GPU support, CUDA-aware MPI, and MatterSim pre-installed. Specify the KOKKOS_ARCH argument to match your GPU architecture.

```bash
docker build -t mattersim-lammps \
    --build-arg KOKKOS_ARCH=AMPERE80 \
    -f dockerfiles/lammps.Dockerfile .
```

--------------------------------

### Compute and Print Phonon Dispersion Results

Source: https://github.com/microsoft/mattersim/blob/main/docs/examples/phonon_example.md

Executes the phonon dispersion calculation using the configured workflow and prints whether imaginary phonons were found, along with the calculated phonon frequencies. The results are stored in the `phonons` variable.

```python
has_imag, phonons = ph.run()
print(f"Has imaginary phonon: {has_imag}")
print(f"Phonon frequencies: {phonons}")
```

--------------------------------

### Display Phonon Density-of-States Plot

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Decodes a base64-encoded PNG image of the phonon density-of-states (DOS) from the API results and displays it using the Image class. Adjust width and height as needed.

```python
decoded_png = base64.b64decode(silicon_result["phonon_dos_plot"])
image = Image(data=decoded_png, width=600, height=400)  # Adjust width and height as needed
display(image)
```

--------------------------------

### Configure LAMMPS Input for ML-IAP

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Set up the LAMMPS input script to use the exported MatterSim model via the ML-IAP pair style. Specify the model file and the element type.

```lammps
pair_style      mliap unified mattersim-v1.0.0-1M-mliap.pt
pair_coeff      * * Cu
```

--------------------------------

### Validate LAMMPS Output with Python

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Run a LAMMPS simulation with a specific input file and model path, then use a Python script to validate the output against a Python recomputation. This helps verify the accuracy of the ML-IAP integration.

```bash
cd src/mattersim/lammps/examples
lmp -in cu_nve.in -var MODEL_PATH /path/to/mattersim_mliap.pt \
    -k on g 1 -sf kk -pk kokkos newton on neigh half
python validate.py --version mattersim-v1.0.0-1M --plot
```

--------------------------------

### Inspect API Results

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Prints the number of results obtained from the API and lists the available properties for the first result. Useful for understanding the structure of the returned data.

```python
print(f"Number of results: {len(results)}")
print(f"The available properties: {results[0].keys()}")
```

--------------------------------

### Batch Prediction with Potential Class

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/getting_started.md

Utilize the `Potential` class for efficient batch prediction of properties across multiple structures. This method is optimized for GPU usage and requires setting up a dataloader compatible with MatterSim. Note that stress tensors are predicted in GPa by default.

```python
import torch
import numpy as np
from ase.build import bulk
from ase.units import GPa
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)

# replicate the structures to form a list
structures = [si] * 10

# load the model
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Running MatterSim on {device}")
potential = Potential.from_checkpoint(device=device)

# 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)

# 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}")
```

--------------------------------

### Run Multi-GPU LAMMPS Simulation

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Execute a LAMMPS simulation across multiple GPUs using MPI domain decomposition. This requires a CUDA-aware MPI stack and specific LAMMPS flags for GPU-aware communication.

```bash
mpirun -np 4 lmp -in input.in \
    -k on g 4 -sf kk \
    -pk kokkos newton on neigh half gpu/aware on \
    comm/pair/forward device comm/pair/reverse device
```

--------------------------------

### Send Payload to MatterSim API

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Prepares and sends a JSON payload containing structural data and workflow type to the AI Foundry endpoint. Requires FOUNDRY_URL and FOUNDRY_TOKEN environment variables. Handles potential HTTP errors during the request.

```python
# Prepare the input data and choose the workflow
payload = json.dumps({
    "input_data":{
      "data": json.dumps({
       "workflow": "phonon",
       "structure_data": [structure,]
      })
    }
})

# Call the Azure Foundry endpoint
url = os.environ["FOUNDRY_URL"] # e.g. https://<subdomain>.ml.azure.com/score
api_key = os.environ["FOUNDRY_TOKEN"]

headers = {
    'Content-Type':'application/json',
    'Authorization':('Bearer '+ api_key),
  }
body = payload.encode()
t0 = time.time()
print("Sending request...")
req = urllib.request.Request(url, body, headers)

# Read the response
try:
    response = urllib.request.urlopen(req)
    results = json.loads(response.read().decode())
except urllib.error.HTTPError as error:
    print(f"The request failed with status code: {error.code}")
    print(error.info())
    print(error.read().decode("utf8", 'ignore'))
print("Response received!")
print(f"Time taken: {time.time()-t0:.2f}s")
```

--------------------------------

### Check Material Dynamical Stability

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Extracts the first result and checks the 'has_imaginary' property to determine if the material is dynamically stable. Prints a message indicating stability if no imaginary frequencies are found.

```python
silicon_result = results[0]
print(f"Does this material has an imaginary frequency? {silicon_result['has_imaginary']}")
if not silicon_result['has_imaginary']:
    print("The material has no imaginary frequency, so it is dynamically stable.")
```

--------------------------------

### Define Silicon Structure in CIF Format

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Define the crystal structure of silicon using the Crystallographic Information File (CIF) format. This structure will be used as input for the MatterSim API.

```python
# Define the structure...
structure = """

```

--------------------------------

### Display Phonon Band Plot

Source: https://github.com/microsoft/mattersim/blob/main/notebooks/foundry-mattersim-phonon.ipynb

Decodes a base64-encoded PNG image of the phonon band structure from the API results and displays it using the Image class. Adjust width and height as needed.

```python
decoded_png = base64.b64decode(silicon_result["phonon_band_plot"])
image = Image(data=decoded_png, width=600, height=400)  # Adjust width and height as needed
display(image)
```

--------------------------------

### Export MatterSim Model for LAMMPS

Source: https://github.com/microsoft/mattersim/blob/main/docs/user_guide/lammps.md

Export a MatterSim model to a file that can be used by LAMMPS ML-IAP interface. Ensure the model checkpoint is specified correctly.

```python
from mattersim.lammps.mliap_wrapper import MatterSimMLIAP

# Choose your model: "mattersim-v1.0.0-1M" or "mattersim-v1.0.0-5M"
mliap = MatterSimMLIAP.from_checkpoint("mattersim-v1.0.0-1M", device="cpu")
mliap.save("mattersim-v1.0.0-1M-mliap.pt")
```

--------------------------------

### MatterSim Citation

Source: https://github.com/microsoft/mattersim/blob/main/README.md

Cite this preprint when using MatterSim version 1.0.0. Ensure to specify the exact model version and checkpoint in academic reporting for reproducibility.

```bibtex
@article{yang2024mattersim,
      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},
      archivePrefix={arXiv},
      primaryClass={cond-mat.mtrl-sci},
      url={https://arxiv.org/abs/2405.04967},
      journal={arXiv preprint arXiv:2405.04967}
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.