mlipx is a Python library designed for evaluating machine-learned interatomic potentials (MLIPs). It offers a growing set of evaluation methods alongside powerful visualization and comparison tools.

The goal of mlipx is to provide a common platform for MLIP evaluation and to facilitate sharing results among researchers. This allows you to determine the applicability of a specific MLIP to your research and compare it against others.

Installation

Install mlipx via pip:

pip install mlipx

[!NOTE] The mlipx package does not include the installation of any MLIP code, as we aim to keep the package as lightweight as possible. If you encounter any ImportError, you may need to install the additional dependencies manually.

Quickstart

This section provides a brief overview of the core features of mlipx. For more detailed instructions, visit the documentation.

Most recipes support different input formats, such as data file paths, SMILES strings, or Materials Project structure IDs.

[!NOTE] Because mlipx uses Git and DVC, you need to create a new project directory to run your experiments in. Here's how to set up your project:

mkdir exp
cd exp
git init && dvc init

If you want to use datafiles, it is recommend to track them with dvc add <file> instead of git add <file>.

cp /your/data/file.xyz .
dvc add file.xyz

Energy-Volume Curve

Compute an energy-volume curve using the mp-1143 structure from the Materials Project and MLIPs such as mace-mpa-0, sevennet, and orb-v2:

mlipx recipes ev --models mace-mpa-0,sevennet,orb-v2 --material-ids=mp-1143 --repro
mlipx compare --glob "*EnergyVolumeCurve"

[!NOTE] mlipx utilizes ASE, meaning any ASE-compatible calculator for your MLIP can be used. If we do not provide a preset for your model, you can either adapt the models.py file, raise an issue to request support, or submit a pull request to add your model directly.

Below is an example of the resulting comparison:

[!NOTE] Set your default visualizer path using: export ZNDRAW_URL=http://localhost:1234.

Structure Optimization

Compare the performance of different models in optimizing multiple molecular structures from SMILES representations:

mlipx recipes relax --models mace-mpa-0,sevennet,orb-v2 --smiles "CCO,C1=CC2=C(C=C1O)C(=CN2)CCN" --repro
mlipx compare --glob "*0_StructureOptimization"
mlipx compare --glob "*1_StructureOptimization"

Nudged Elastic Band (NEB)

Run and compare nudged elastic band (NEB) calculations for a given start and end structure:

mlipx recipes neb --models mace-mpa-0,sevennet,orb-v2 --datapath ../data/neb_end_p.xyz --repro
mlipx compare --glob "*NEBs"

Python API

You can also use all the recipes from the mlipx command-line interface programmatically in Python.

[!NOTE] Whether you use the CLI or the Python API, you must work within a GIT and DVC repository. This setup ensures reproducibility and enables automatic caching and other features from DVC and ZnTrack.

import mlipx

# Initialize the project
project = mlipx.Project()

# Define an MLIP
mace_mp = mlipx.GenericASECalculator(
    module="mace.calculators",
    class_name="mace_mp",
    device="auto",
    kwargs={
        "model": "medium",
    },
)

# Use the MLIP in a structure optimization
with project:
    data = mlipx.LoadDataFile(path="/your/data/file.xyz")
    relax = mlipx.StructureOptimization(
        data=data.frames,
        data_id=-1,
        model=mace_mp,
        fmax=0.1
    )

# Reproduce the project state
project.repro()

# Access the results
print(relax.frames)
# >>> [ase.Atoms(...), ...]