> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/atomind-ai/mlip-arena/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first MLIP Arena benchmark in minutes.

## Available models

All integrated pretrained potentials are registered in `MLIPEnum`. After installation you can inspect which models were loaded successfully:

```python theme={null}
from mlip_arena.models import MLIPEnum

print(list(MLIPEnum.__members__.keys()))
# e.g. ['MACE-MP(M)', 'CHGNet', 'M3GNet', 'MatterSim', 'ORBv2', 'SevenNet',
#        'eqV2(OMat)', 'MACE-MPA', 'eSEN', 'MACE-OFF(M)', 'ANI2x', 'ALIGNN',
#        'DeepMD', 'ORB', ...]
```

***

## Run a single model

The helper `get_calculator` constructs an ASE-compatible calculator for any entry in `MLIPEnum`, with optional D3 dispersion correction via `torch_dftd`.

```python theme={null}
from ase.build import bulk
from ase import units

from mlip_arena.models import MLIPEnum
from mlip_arena.tasks import MD
from mlip_arena.tasks.utils import get_calculator

atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)

result = MD(
    atoms=atoms,
    calculator=get_calculator(
        MLIPEnum["MACE-MP(M)"],
        calculator_kwargs={},
        dispersion=True,
        dispersion_kwargs={
            "damping": "bj",
            "xc": "pbe",
            "cutoff": 40.0 * units.Bohr,
        },
    ),
    ensemble="nvt",          # "nve", "nvt", or "npt"
    dynamics="langevin",      # any ASE Dynamics class name
    total_time=1e3,           # ps — 1 ps = 1e3 fs
    time_step=2,              # fs
)
```

<Note>
  `get_calculator` also accepts a raw ASE `Calculator` instance or a class, so you are not limited to models registered in `MLIPEnum`.
</Note>

***

## Loop over all models

Iterate over `MLIPEnum` to run the same task against every installed model:

```python theme={null}
from mlip_arena.models import MLIPEnum
from mlip_arena.tasks import MD
from mlip_arena.tasks.utils import get_calculator
from ase.build import bulk

atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)

results = []
for model in MLIPEnum:
    result = MD(
        atoms=atoms,
        calculator=get_calculator(model, calculator_kwargs={}),
        ensemble="nvt",
        dynamics="langevin",
        total_time=1e3,
        time_step=2,
    )
    results.append(result)
```

***

## Parallelize with Prefect

All tasks in MLIP Arena are decorated with `@prefect.task`. Call `.submit()` instead of a direct invocation and wrap everything in a `@flow` to dispatch tasks concurrently to Prefect workers.

```python theme={null}
from prefect import flow
from ase.build import bulk
from mlip_arena.models import MLIPEnum
from mlip_arena.tasks import MD
from mlip_arena.tasks.utils import get_calculator

atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)

@flow
def benchmark_all_models():
    futures = []
    for model in MLIPEnum:
        future = MD.submit(
            atoms=atoms,
            calculator=get_calculator(model, calculator_kwargs={}),
            ensemble="nvt",
            dynamics="langevin",
            total_time=1e3,
            time_step=2,
        )
        futures.append(future)

    return [f.result(raise_on_failure=False) for f in futures]

if __name__ == "__main__":
    results = benchmark_all_models()
```

<Tip>
  For HPC usage see the [MD stability benchmark notebook](https://github.com/atomind-ai/mlip-arena/blob/main/benchmarks/stability/temperature.ipynb) for an end-to-end Prefect + Dask example on a SLURM cluster.
</Tip>

***

## Available tasks

All tasks live under `mlip_arena.tasks` and are importable directly:

```python theme={null}
from mlip_arena.tasks import OPT, EOS, MD, PHONON, NEB, NEB_FROM_ENDPOINTS, ELASTICITY
```

<Note>
  `PHONON` requires [phonopy](https://phonopy.github.io/phonopy/install.html) to be installed. If phonopy is missing the wildcard import `from mlip_arena.tasks import *` will log a warning but the other tasks will still load.
</Note>

### OPT — Structure optimization

Relax atomic positions and/or unit cell using any ASE `Optimizer` and `Filter`:

```python theme={null}
from ase.build import bulk
from mlip_arena.tasks import OPT
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

atoms = bulk("Fe", "bcc", a=2.87)

result = OPT(
    atoms=atoms,
    calculator=get_calculator(MLIPEnum["MACE-MP(M)"], calculator_kwargs={}),
    optimizer="BFGSLineSearch",  # any ASE Optimizer name
    filter="FrechetCell",        # relax cell shape and volume
    criterion={"fmax": 0.01},    # convergence threshold in eV/Å
)
# result["atoms"] — relaxed Atoms; result["converged"] — bool; result["steps"] — int
```

### EOS — Equation of state

Compute the energy–volume curve and fit a Birch–Murnaghan EOS to extract bulk modulus and equilibrium volume:

```python theme={null}
from ase.build import bulk
from mlip_arena.tasks import EOS
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

atoms = bulk("Si", "diamond", a=5.43)

result = EOS(
    atoms=atoms,
    calculator=get_calculator(MLIPEnum["CHGNet"], calculator_kwargs={}),
    max_abs_strain=0.1,  # ±10 % volume range
    npoints=11,          # number of EV sample points
)
# result["K"] — bulk modulus (GPa); result["v0"] — eq. volume (ų); result["e0"] — eq. energy (eV)
```

### MD — Molecular dynamics

Flexible NVE / NVT / NPT simulation with temperature and pressure scheduling:

```python theme={null}
from ase.build import bulk
from mlip_arena.tasks import MD
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

atoms = bulk("Cu", "fcc", a=3.6) * (4, 4, 4)

result = MD(
    atoms=atoms,
    calculator=get_calculator(MLIPEnum["MACE-MP(M)"], calculator_kwargs={}),
    ensemble="nvt",
    dynamics="langevin",
    total_time=10_000,  # fs — 10 ps
    time_step=2,        # fs
    temperature=600,    # K  (scalar or array for annealing)
    traj_file="cu_nvt.traj",
    traj_interval=10,
)
# result["atoms"], result["n_steps"], result["runtime"]
```

### PHONON — Phonon calculation

Finite-displacement phonon calculation powered by [phonopy](https://phonopy.github.io/phonopy/):

```python theme={null}
from ase.build import bulk
from mlip_arena.tasks import PHONON
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

atoms = bulk("Al", "fcc", a=4.05)

result = PHONON(
    atoms=atoms,
    calculator=get_calculator(MLIPEnum["M3GNet"], calculator_kwargs={}),
    supercell_matrix=[2, 2, 2],
    t_min=0,
    t_max=1000,
    t_step=10,
)
# result["phonon"]  — a phonopy.Phonopy object
```

### NEB — Nudged elastic band

Minimum energy path calculation from a list of pre-built images:

```python theme={null}
from ase.build import bulk, make_supercell
from mlip_arena.tasks import NEB
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

# Provide start, intermediate (empty), and end images
images = [initial_atoms] + [initial_atoms.copy() for _ in range(5)] + [final_atoms]

result = NEB(
    images=images,
    calculator=get_calculator(MLIPEnum["SevenNet"], calculator_kwargs={}),
    optimizer="MDMin",
    climb=True,           # climbing-image NEB
    interpolation="idpp", # or "linear"
    criterion={"fmax": 0.05},
)
# result["barrier"], result["images"], result["forcefit"]
```

### NEB\_FROM\_ENDPOINTS — NEB with automatic interpolation

Convenience wrapper that handles image interpolation from just two endpoint structures:

```python theme={null}
from mlip_arena.tasks import NEB_FROM_ENDPOINTS
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum

result = NEB_FROM_ENDPOINTS(
    start=initial_atoms,
    end=final_atoms,
    n_images=7,
    calculator=get_calculator(MLIPEnum["SevenNet"], calculator_kwargs={}),
    relax_end_points=True,  # relax start/end before NEB
    interpolation="idpp",
    climb=True,
    criterion={"fmax": 0.05},
)
```

### ELASTICITY — Elastic tensor

Compute the full elastic tensor by applying symmetry-adapted normal and shear strains:

```python theme={null}
from ase.build import bulk
from mlip_arena.tasks import ELASTICITY
from mlip_arena.tasks.utils import get_calculator
from mlip_arena.models import MLIPEnum
import numpy as np

atoms = bulk("W", "bcc", a=3.16)

result = ELASTICITY(
    atoms=atoms,
    calculator=get_calculator(MLIPEnum["MACE-MP(M)"], calculator_kwargs={}),
    filter="FrechetCell",
    normal_strains=np.linspace(-0.01, 0.01, 4),
    shear_strains=np.linspace(-0.06, 0.06, 4),
)
# result contains the elastic tensor and derived moduli
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Benchmarks" icon="chart-bar" href="https://huggingface.co/spaces/atomind/mlip-arena">
    View live benchmark results on the MLIP Arena leaderboard.
  </Card>

  <Card title="Contributing models" icon="plus" href="https://github.com/atomind-ai/mlip-arena/blob/main/mlip_arena/models/README.md">
    Add your own pretrained potential as an external ASE calculator or a HuggingFace model.
  </Card>

  <Card title="Prefect docs" icon="bolt" href="https://docs.prefect.io/v3/develop/write-tasks">
    Learn how to write Prefect tasks and flows to orchestrate large-scale benchmarks.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/atomind-ai/mlip-arena">
    Source code, issue tracker, and contribution guidelines.
  </Card>
</CardGroup>