<div align="center" width="600">
<picture>
<source srcset="https://github.com/lab-cosmo/pet-mad/raw/refs/heads/main/docs/static/pet-mad-logo-with-text-dark.svg" media="(prefers-color-scheme: dark)">
<img src="https://github.com/lab-cosmo/pet-mad/raw/refs/heads/main/docs/static/pet-mad-logo-with-text.svg" alt="Figure">
</picture>
</div>
# PET-MAD: A Universal Interatomic Potential for Advanced Materials Modeling
This repository contains **PET-MAD** - a universal interatomic potential for
advanced materials modeling across the periodic table. This model is based on
the **Point Edge Transformer (PET)** model trained on the **Massive Atomic
Diversity (MAD) Dataset** and is capable of predicting energies and forces in
complex atomistic simulations.
## Key Features
- **Universality**: PET-MAD is a generally-applicable model that can be used for
a wide range of materials and molecules.
- **Accuracy**: PET-MAD achieves high accuracy in various types of atomistic
simulations of organic and inorganic systems, comparable with system-specific
models, while being fast and efficient.
- **Efficiency**: PET-MAD achieves high computational efficiency and low memory
usage, making it suitable for large-scale simulations.
- **Infrastructure**: Various MD engines are available for diverse research and
application needs.
- **HPC Compatibility**: Efficient in HPC environments for extensive simulations.
## Table of Contents
1. [Installation](#installation)
2. [Pre-trained Models](#pre-trained-models)
3. [Interfaces for Atomistic Simulations](#interfaces-for-atomistic-simulations)
4. [Usage](#usage)
- [ASE Interface](#ase-interface)
- [Basic usage](#basic-usage)
- [Non-conservative (direct) forces and stresses prediction](#non-conservative-direct-forces-and-stresses-prediction)
- [Evaluating PET-MAD on a dataset](#evaluating-pet-mad-on-a-dataset)
- [Running PET-MAD with LAMMPS](#running-pet-mad-with-lammps)
- [Running PET-MAD with empirical dispersion corrections](#running-pet-mad-with-empirical-dispersion-corrections)
- [Dataset visualization with the PET-MAD featurizer](#dataset-visualization-with-the-pet-mad-featurizer)
5. [Examples](#examples)
6. [Fine-tuning](#fine-tuning)
7. [Documentation](#documentation)
8. [Citing PET-MAD](#citing-pet-mad)
## Installation
You can install PET-MAD using pip:
```bash
pip install pet-mad
```
Or directly from the GitHub repository:
```bash
pip install git+https://github.com/lab-cosmo/pet-mad.git
```
Alternatively, you can install PET-MAD using `conda` package manager, which is
especially important for running PET-MAD with **LAMMPS**.
> [!WARNING]
> We strongly recommend installing PET-MAD using
> [`Miniforge`](https://github.com/conda-forge/miniforge) as a base `conda`
> provider, because other `conda` providers (such as `Anaconda`) may yield
> undesired behavior when resolving dependencies and are usually slower than
> `Miniforge`. Smooth installation and use of PET-MAD is not guaranteed with
> other `conda` providers.
To install Miniforge on unix-like systems, run:
```bash
wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
```
Once Miniforge is installed, create a new conda environment and install PET-MAD
with:
```bash
conda create -n pet-mad
conda activate pet-mad
conda install -c metatensor -c conda-forge pet-mad
```
## Pre-trained Models
Currently, we provide the following pre-trained models:
- **`v1.1.0`** or **`latest`**: The updated PET-MAD model with an ability to run
simulations using the non-conservative forces and stresses.
- **`v1.0.1`**: The updated PET-MAD model with a new, pure PyTorch backend and
slightly improved performance.
- **`v1.0.0`**: PET-MAD model trained on the MAD dataset, which contains 95,595
structures, including 3D and 2D inorganic crystals, surfaces, molecular
crystals, nanoclusters, and molecules.
## Interfaces for Atomistic Simulations
PET-MAD integrates with the following atomistic simulation engines:
- **Atomic Simulation Environment (ASE)**
- **LAMMPS** (including the KOKKOS support)
- **i-PI**
- **OpenMM** (coming soon)
- **GROMACS** (coming soon)
## Usage
### ASE Interface
#### Basic usage
You can use the PET-MAD calculator, which is compatible with the Atomic
Simulation Environment (ASE):
```python
from pet_mad.calculator import PETMADCalculator
from ase.build import bulk
atoms = bulk("Si", cubic=True, a=5.43, crystalstructure="diamond")
pet_mad_calculator = PETMADCalculator(version="latest", device="cpu")
atoms.calc = pet_mad_calculator
energy = atoms.get_potential_energy()
forces = atoms.get_forces()
```
These ASE methods are ideal for single-structure evaluations, but they are
inefficient for the evaluation on a large number of pre-defined structures. To
perform efficient evaluation in that case, read [here](docs/README_BATCHED.md).
#### Non-conservative (direct) forces and stresses prediction
PET-MAD also supports the direct prediction of forces and stresses. In that case,
the forces and stresses are predicted as separate targets along with the energy
target, i.e. not computed as derivatives of the energy using the PyTorch
automatic differentiation. This approach typically leads to 2-3x speedup in the
evaluation time, since backward pass is disabled. However, as discussed in [this
preprint](https://arxiv.org/abs/2412.11569) it requires additional care to avoid
instabilities during the molecular dynamics simulations.
To use the non-conservative forces and stresses, you need to set the `non_conservative` parameter to `True` when initializing the `PETMADCalculator` class.
```python
from pet_mad.calculator import PETMADCalculator
from ase.build import bulk
atoms = bulk("Si", cubic=True, a=5.43, crystalstructure="diamond")
pet_mad_calculator = PETMADCalculator(version="latest", device="cpu", non_conservative=True)
atoms.calc = pet_mad_calculator
energy = atoms.get_potential_energy() # energy is computed as usual
forces = atoms.get_forces() # forces now are predicted as a separate target
stresses = atoms.get_stress() # stresses now are predicted as a separate target
```
More details on how to make the direct forces MD simulations reliable are provided
in the [Atomistic Cookbook](https://atomistic-cookbook.org/examples/pet-mad-nc/pet-mad-nc.html).
### Evaluating PET-MAD on a dataset
Efficient evaluation of PET-MAD on a desired dataset is also available from the
command line via [`metatrain`](https://github.com/metatensor/metatrain), which
is installed as a dependency of PET-MAD. To evaluate the model, you first need
to fetch the PET-MAD model from the HuggingFace repository:
```bash
mtt export https://huggingface.co/lab-cosmo/pet-mad/resolve/main/models/pet-mad-latest.ckpt
```
Alternatively, you can also download the model from Python:
```py
import pet_mad
pet_mad.save_pet_mad(version="latest", output="pet-mad-latest.pt")
# you can also get a metatomic AtomisticModel for advance usage
model = pet_mad.get_pet_mad(version="latest")
```
This command will download the model and convert it to TorchScript format. Then
you need to create the `options.yaml` file and specify the dataset you want to
evaluate the model on (where the dataset is stored in `extxyz` format):
```yaml
systems: your-test-dataset.xyz
targets:
energy:
key: "energy"
unit: "eV"
```
Then, you can use the `mtt eval` command to evaluate the model on a dataset:
```bash
mtt eval pet-mad-latest.pt options.yaml --batch-size=16 --extensions-dir=extensions --output=predictions.xyz
```
This will create a file called `predictions.xyz` with the predicted energies and
forces for each structure in the dataset. More details on how to use `metatrain`
can be found in the [Metatrain documentation](https://metatensor.github.io/metatrain/latest/getting-started/usage.html#evaluation).
## Running PET-MAD with LAMMPS
### 1. Install LAMMPS with metatomic support
To use PET-MAD with LAMMPS, you need to first install PET-MAD from `conda` (see
the installation instructions above). Then, follow the instructions
[here](https://docs.metatensor.org/metatomic/latest/engines/lammps.html#how-to-install-the-code) to install lammps-metatomic. We recomend you also use conda to install lammps.
### 2. Run LAMMPS with PET-MAD
#### 2.1. CPU version
Fetch the PET-MAD checkpoint from the HuggingFace repository:
```bash
mtt export https://huggingface.co/lab-cosmo/pet-mad/resolve/v1.1.0/models/pet-mad-v1.1.0.ckpt
```
This will download the model and convert it to TorchScript format compatible
with LAMMPS, using the `metatomic` and `metatrain` libraries, which PET-MAD is
based on.
Prepare a lammps input file using `pair_style metatomic` and defining the
mapping from LAMMPS types in the data file to elements PET-MAD can handle using
`pair_coeff` syntax. Here we indicate that lammps atom type 1 is Silicon (atomic
number 14).
```
units metal
atom_style atomic
read_data silicon.data
pair_style metatomic pet-mad-v1.1.0.pt device cpu # Change device to 'cuda' evaluate PET-MAD on GPU
pair_coeff * * 14
neighbor 2.0 bin
timestep 0.001
dump myDump all xyz 10 trajectory.xyz
dump_modify myDump element Si
thermo_style multi
thermo 1
velocity all create 300 87287 mom yes rot yes
fix 1 all nvt temp 300 300 0.10
run 100
```
Create the **`silicon.data`** data file for a silicon system.
```
# LAMMPS data file for Silicon unit cell
8 atoms
1 atom types
0.0 5.43 xlo xhi
0.0 5.43 ylo yhi
0.0 5.43 zlo zhi
Masses
1 28.084999992775295 # Si
Atoms # atomic
1 1 0 0 0
2 1 1.3575 1.3575 1.3575
3 1 0 2.715 2.715
4 1 1.3575 4.0725 4.0725
5 1 2.715 0 2.715
6 1 4.0725 1.3575 4.0725
7 1 2.715 2.715 0
8 1 4.0725 4.0725 1.3575
```
```bash
lmp -in lammps.in # For serial version
mpirun -np 1 lmp -in lammps.in # For MPI version
```
#### 2.2. KOKKOS-enabled GPU version
Running LAMMPS with KOKKOS and GPU support is similar to the CPU version, but
you need to change the `lammps.in` slightly and run `lmp` binary with a few
additional flags.
The updated `lammps.in` file looks like this:
```
package kokkos newton on neigh half
units metal
atom_style atomic/kk
read_data silicon.data
pair_style metatensor/kk pet-mad-v1.1.0.pt # This will use the same device as the kokkos simulation
pair_coeff * * 14
neighbor 2.0 bin
timestep 0.001
dump myDump all xyz 10 trajectory.xyz
dump_modify myDump element Si
thermo_style multi
thermo 1
velocity all create 300 87287 mom yes rot yes
fix 1 all nvt temp 300 300 0.10
run_style verlet/kk
run 100
```
The **silicon.data** file remains the same.
To run the KOKKOS-enabled version of LAMMPS, you need to run
```bash
lmp -in lammps.in -k on g 1 -sf kk # For serial version
mpirun -np 1 lmp -in lammps.in -k on g 1 -sf kk # For MPI version
```
Here, the `-k on g 1 -sf kk` flags are used to activate the KOKKOS
subroutines. Specifically `g 1` is used to specify, how many GPUs are the
simulation is parallelized over, so if running the large systems on two or more
GPUs, this number should be adjusted accordingly.
### 3. Important Notes
- For **CPU calculations**, use a single MPI task unless simulating large
systems (30+ Å box size). Multi-threading can be enabled via:
```bash
export OMP_NUM_THREADS=4
```
- For **GPU calculations**, use **one MPI task per GPU**.
## Running PET-MAD with empirical dispersion corrections
### In **ASE**:
You can combine the PET-MAD calculator with the torch based implementation of
the D3 dispersion correction of `pfnet-research` - `torch-dftd`:
Within the PET-MAD environment you can install `torch-dftd` via:
```bash
pip install torch-dftd
```
Then you can use the `D3Calculator` class to combine the two calculators:
```python
from torch_dftd.torch_dftd3_calculator import TorchDFTD3Calculator
from pet_mad.calculator import PETMADCalculator
from ase.calculators.mixing import SumCalculator
device = "cuda" if torch.cuda.is_available() else "cpu"
calc_MAD = PETMADCalculator(version="latest", device=device)
dft_d3 = TorchDFTD3Calculator(device=device, xc="pbesol", damping="bj")
combined_calc = SumCalculator([calc_MAD, dft_d3])
# assign the calculator to the atoms object
atoms.calc = combined_calc
```
## Dataset visualization with the PET-MAD featurizer
You can use PET-MAD last-layer features together with a pre-trained
sketch-map dimensionality reduction to obtain 2D and 3D representations
of a dataset, e.g. to identify structural or chemical motifs.
This can be used as a stand-alone feature builder, or combined with
the [chemiscope viewer](https://chemiscope.org) to generate an
interactive visualization.
```python
import ase.io
import chemiscope
from pet_mad.explore import PETMADFeaturizer
featurizer = PETMADFeaturizer(version="latest")
# Load structures
frames = ase.io.read("dataset.xyz", ":")
# You can just compute features
features = featurizer(frames, None)
# Or create an interactive visualization in a Jupyter notebook
chemiscope.explore(
frames,
featurize=featurizer
)
```
## Examples
More examples for **ASE, i-PI, and LAMMPS** are available in the [Atomistic
Cookbook](https://atomistic-cookbook.org/examples/pet-mad/pet-mad.html).
## Fine-tuning
PET-MAD can be fine-tuned using the
[Metatrain](https://metatensor.github.io/metatrain/latest/advanced-concepts/fine-tuning.html)
library.
## Documentation
Additional documentation can be found in the
[metatensor](https://docs.metatensor.org),
[metatomic](https://docs.metatensor.org/metatomic) and
[metatrain](https://metatensor.github.io/metatrain/) repositories.
- [Training a model](https://metatensor.github.io/metatrain/latest/getting-started/usage.html#training)
- [Fine-tuning](https://metatensor.github.io/metatrain/latest/advanced-concepts/fine-tuning.html)
- [LAMMPS interface](https://docs.metatensor.org/metatomic/latest/engines/lammps.html)
- [i-PI interface](https://docs.metatensor.org/metatomic/latest/engines/ipi.html)
## Citing PET-MAD
If you use PET-MAD in your research, please cite:
```bibtex
@misc{PET-MAD-2025,
title={PET-MAD, a universal interatomic potential for advanced materials modeling},
author={Arslan Mazitov and Filippo Bigi and Matthias Kellner and Paolo Pegolo and Davide Tisi and Guillaume Fraux and Sergey Pozdnyakov and Philip Loche and Michele Ceriotti},
year={2025},
eprint={2503.14118},
archivePrefix={arXiv},
primaryClass={cond-mat.mtrl-sci},
url={https://arxiv.org/abs/2503.14118}
}
Raw data
{
"_id": null,
"home_page": null,
"name": "pet-mad",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Arslan Mazitov <arslan.mazitov@epfl.ch>",
"keywords": "machine learning, molecular modeling",
"author": "Filippo Bigi, Matthias Kellner, Paolo Pegolo, Davide Tisi, Guillaume Fraux, Sergey Pozdnyakov, Philip Loche",
"author_email": "Arslan Mazitov <arslan.mazitov@epfl.ch>, Michele Ceriotti <michele.ceriotti@epfl.ch>",
"download_url": "https://files.pythonhosted.org/packages/f3/24/ef0f66e4e8ca7869679ecd9f9a1248503c33a9115c2ff3db3853992e497a/pet_mad-1.3.1.tar.gz",
"platform": null,
"description": "<div align=\"center\" width=\"600\">\n <picture>\n <source srcset=\"https://github.com/lab-cosmo/pet-mad/raw/refs/heads/main/docs/static/pet-mad-logo-with-text-dark.svg\" media=\"(prefers-color-scheme: dark)\">\n <img src=\"https://github.com/lab-cosmo/pet-mad/raw/refs/heads/main/docs/static/pet-mad-logo-with-text.svg\" alt=\"Figure\">\n </picture>\n</div>\n\n# PET-MAD: A Universal Interatomic Potential for Advanced Materials Modeling\n\nThis repository contains **PET-MAD** - a universal interatomic potential for\nadvanced materials modeling across the periodic table. This model is based on\nthe **Point Edge Transformer (PET)** model trained on the **Massive Atomic\nDiversity (MAD) Dataset** and is capable of predicting energies and forces in\ncomplex atomistic simulations.\n\n## Key Features\n\n- **Universality**: PET-MAD is a generally-applicable model that can be used for\n a wide range of materials and molecules.\n- **Accuracy**: PET-MAD achieves high accuracy in various types of atomistic\n simulations of organic and inorganic systems, comparable with system-specific\n models, while being fast and efficient.\n- **Efficiency**: PET-MAD achieves high computational efficiency and low memory\n usage, making it suitable for large-scale simulations.\n- **Infrastructure**: Various MD engines are available for diverse research and\n application needs.\n- **HPC Compatibility**: Efficient in HPC environments for extensive simulations.\n\n## Table of Contents\n1. [Installation](#installation)\n2. [Pre-trained Models](#pre-trained-models)\n3. [Interfaces for Atomistic Simulations](#interfaces-for-atomistic-simulations)\n4. [Usage](#usage)\n - [ASE Interface](#ase-interface)\n - [Basic usage](#basic-usage)\n - [Non-conservative (direct) forces and stresses prediction](#non-conservative-direct-forces-and-stresses-prediction)\n - [Evaluating PET-MAD on a dataset](#evaluating-pet-mad-on-a-dataset)\n - [Running PET-MAD with LAMMPS](#running-pet-mad-with-lammps)\n - [Running PET-MAD with empirical dispersion corrections](#running-pet-mad-with-empirical-dispersion-corrections)\n - [Dataset visualization with the PET-MAD featurizer](#dataset-visualization-with-the-pet-mad-featurizer)\n5. [Examples](#examples)\n6. [Fine-tuning](#fine-tuning)\n7. [Documentation](#documentation)\n8. [Citing PET-MAD](#citing-pet-mad)\n\n## Installation\n\nYou can install PET-MAD using pip:\n\n```bash\npip install pet-mad\n```\n\nOr directly from the GitHub repository:\n\n```bash\npip install git+https://github.com/lab-cosmo/pet-mad.git\n```\n\nAlternatively, you can install PET-MAD using `conda` package manager, which is\nespecially important for running PET-MAD with **LAMMPS**.\n\n> [!WARNING]\n> We strongly recommend installing PET-MAD using\n> [`Miniforge`](https://github.com/conda-forge/miniforge) as a base `conda`\n> provider, because other `conda` providers (such as `Anaconda`) may yield\n> undesired behavior when resolving dependencies and are usually slower than\n> `Miniforge`. Smooth installation and use of PET-MAD is not guaranteed with\n> other `conda` providers.\n\nTo install Miniforge on unix-like systems, run:\n\n```bash\nwget \"https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh\"\nbash Miniforge3-$(uname)-$(uname -m).sh\n```\n\nOnce Miniforge is installed, create a new conda environment and install PET-MAD\nwith:\n\n```bash\nconda create -n pet-mad\nconda activate pet-mad\nconda install -c metatensor -c conda-forge pet-mad\n```\n\n## Pre-trained Models\n\nCurrently, we provide the following pre-trained models:\n\n- **`v1.1.0`** or **`latest`**: The updated PET-MAD model with an ability to run\n simulations using the non-conservative forces and stresses.\n- **`v1.0.1`**: The updated PET-MAD model with a new, pure PyTorch backend and\n slightly improved performance.\n- **`v1.0.0`**: PET-MAD model trained on the MAD dataset, which contains 95,595\n structures, including 3D and 2D inorganic crystals, surfaces, molecular\n crystals, nanoclusters, and molecules.\n\n## Interfaces for Atomistic Simulations\n\nPET-MAD integrates with the following atomistic simulation engines:\n\n- **Atomic Simulation Environment (ASE)**\n- **LAMMPS** (including the KOKKOS support)\n- **i-PI**\n- **OpenMM** (coming soon)\n- **GROMACS** (coming soon)\n\n## Usage\n\n### ASE Interface\n\n#### Basic usage\n\nYou can use the PET-MAD calculator, which is compatible with the Atomic\nSimulation Environment (ASE):\n\n```python\nfrom pet_mad.calculator import PETMADCalculator\nfrom ase.build import bulk\n\natoms = bulk(\"Si\", cubic=True, a=5.43, crystalstructure=\"diamond\")\npet_mad_calculator = PETMADCalculator(version=\"latest\", device=\"cpu\")\natoms.calc = pet_mad_calculator\nenergy = atoms.get_potential_energy()\nforces = atoms.get_forces()\n```\n\nThese ASE methods are ideal for single-structure evaluations, but they are\ninefficient for the evaluation on a large number of pre-defined structures. To\nperform efficient evaluation in that case, read [here](docs/README_BATCHED.md).\n\n#### Non-conservative (direct) forces and stresses prediction\n\nPET-MAD also supports the direct prediction of forces and stresses. In that case,\nthe forces and stresses are predicted as separate targets along with the energy\ntarget, i.e. not computed as derivatives of the energy using the PyTorch\nautomatic differentiation. This approach typically leads to 2-3x speedup in the\nevaluation time, since backward pass is disabled. However, as discussed in [this\npreprint](https://arxiv.org/abs/2412.11569) it requires additional care to avoid\ninstabilities during the molecular dynamics simulations.\n\nTo use the non-conservative forces and stresses, you need to set the `non_conservative` parameter to `True` when initializing the `PETMADCalculator` class.\n\n```python\nfrom pet_mad.calculator import PETMADCalculator\nfrom ase.build import bulk\n\natoms = bulk(\"Si\", cubic=True, a=5.43, crystalstructure=\"diamond\")\npet_mad_calculator = PETMADCalculator(version=\"latest\", device=\"cpu\", non_conservative=True)\natoms.calc = pet_mad_calculator\nenergy = atoms.get_potential_energy() # energy is computed as usual\nforces = atoms.get_forces() # forces now are predicted as a separate target\nstresses = atoms.get_stress() # stresses now are predicted as a separate target\n```\n\nMore details on how to make the direct forces MD simulations reliable are provided \nin the [Atomistic Cookbook](https://atomistic-cookbook.org/examples/pet-mad-nc/pet-mad-nc.html).\n\n### Evaluating PET-MAD on a dataset\n\nEfficient evaluation of PET-MAD on a desired dataset is also available from the\ncommand line via [`metatrain`](https://github.com/metatensor/metatrain), which\nis installed as a dependency of PET-MAD. To evaluate the model, you first need\nto fetch the PET-MAD model from the HuggingFace repository:\n\n```bash\nmtt export https://huggingface.co/lab-cosmo/pet-mad/resolve/main/models/pet-mad-latest.ckpt\n```\n\nAlternatively, you can also download the model from Python:\n\n```py\nimport pet_mad\n\npet_mad.save_pet_mad(version=\"latest\", output=\"pet-mad-latest.pt\")\n\n# you can also get a metatomic AtomisticModel for advance usage\nmodel = pet_mad.get_pet_mad(version=\"latest\")\n```\n\nThis command will download the model and convert it to TorchScript format. Then\nyou need to create the `options.yaml` file and specify the dataset you want to\nevaluate the model on (where the dataset is stored in `extxyz` format):\n\n```yaml\nsystems: your-test-dataset.xyz\ntargets:\n energy:\n key: \"energy\"\n unit: \"eV\"\n```\n\nThen, you can use the `mtt eval` command to evaluate the model on a dataset:\n\n```bash\nmtt eval pet-mad-latest.pt options.yaml --batch-size=16 --extensions-dir=extensions --output=predictions.xyz\n```\n\nThis will create a file called `predictions.xyz` with the predicted energies and\nforces for each structure in the dataset. More details on how to use `metatrain`\ncan be found in the [Metatrain documentation](https://metatensor.github.io/metatrain/latest/getting-started/usage.html#evaluation).\n\n## Running PET-MAD with LAMMPS\n\n### 1. Install LAMMPS with metatomic support\n\nTo use PET-MAD with LAMMPS, you need to first install PET-MAD from `conda` (see\nthe installation instructions above). Then, follow the instructions\n[here](https://docs.metatensor.org/metatomic/latest/engines/lammps.html#how-to-install-the-code) to install lammps-metatomic. We recomend you also use conda to install lammps.\n\n### 2. Run LAMMPS with PET-MAD\n\n#### 2.1. CPU version\n\nFetch the PET-MAD checkpoint from the HuggingFace repository:\n\n```bash\nmtt export https://huggingface.co/lab-cosmo/pet-mad/resolve/v1.1.0/models/pet-mad-v1.1.0.ckpt\n```\n\nThis will download the model and convert it to TorchScript format compatible\nwith LAMMPS, using the `metatomic` and `metatrain` libraries, which PET-MAD is\nbased on.\n\nPrepare a lammps input file using `pair_style metatomic` and defining the\nmapping from LAMMPS types in the data file to elements PET-MAD can handle using\n`pair_coeff` syntax. Here we indicate that lammps atom type 1 is Silicon (atomic\nnumber 14).\n\n```\nunits metal\natom_style atomic\n\nread_data silicon.data\n\npair_style metatomic pet-mad-v1.1.0.pt device cpu # Change device to 'cuda' evaluate PET-MAD on GPU\npair_coeff * * 14\n\nneighbor 2.0 bin\ntimestep 0.001\n\ndump myDump all xyz 10 trajectory.xyz\ndump_modify myDump element Si\n\nthermo_style multi\nthermo 1\n\nvelocity all create 300 87287 mom yes rot yes\n\nfix 1 all nvt temp 300 300 0.10\n\nrun 100\n```\n\nCreate the **`silicon.data`** data file for a silicon system.\n\n```\n# LAMMPS data file for Silicon unit cell\n8 atoms\n1 atom types\n\n0.0 5.43 xlo xhi\n0.0 5.43 ylo yhi\n0.0 5.43 zlo zhi\n\nMasses\n\n1 28.084999992775295 # Si\n\nAtoms # atomic\n\n1 1 0 0 0\n2 1 1.3575 1.3575 1.3575\n3 1 0 2.715 2.715\n4 1 1.3575 4.0725 4.0725\n5 1 2.715 0 2.715\n6 1 4.0725 1.3575 4.0725\n7 1 2.715 2.715 0\n8 1 4.0725 4.0725 1.3575\n```\n\n```bash\nlmp -in lammps.in # For serial version\nmpirun -np 1 lmp -in lammps.in # For MPI version\n```\n\n#### 2.2. KOKKOS-enabled GPU version\n\nRunning LAMMPS with KOKKOS and GPU support is similar to the CPU version, but\nyou need to change the `lammps.in` slightly and run `lmp` binary with a few\nadditional flags.\n\nThe updated `lammps.in` file looks like this:\n\n```\npackage kokkos newton on neigh half\n\nunits metal\natom_style atomic/kk\n\nread_data silicon.data\n\npair_style metatensor/kk pet-mad-v1.1.0.pt # This will use the same device as the kokkos simulation\npair_coeff * * 14\n\nneighbor 2.0 bin\ntimestep 0.001\n\ndump myDump all xyz 10 trajectory.xyz\ndump_modify myDump element Si\n\nthermo_style multi\nthermo 1\n\nvelocity all create 300 87287 mom yes rot yes\n\nfix 1 all nvt temp 300 300 0.10\n\nrun_style verlet/kk\nrun 100\n```\n\nThe **silicon.data** file remains the same.\n\nTo run the KOKKOS-enabled version of LAMMPS, you need to run\n\n```bash\nlmp -in lammps.in -k on g 1 -sf kk # For serial version\nmpirun -np 1 lmp -in lammps.in -k on g 1 -sf kk # For MPI version\n```\n\nHere, the `-k on g 1 -sf kk` flags are used to activate the KOKKOS\nsubroutines. Specifically `g 1` is used to specify, how many GPUs are the\nsimulation is parallelized over, so if running the large systems on two or more\nGPUs, this number should be adjusted accordingly.\n\n\n### 3. Important Notes\n\n- For **CPU calculations**, use a single MPI task unless simulating large\n systems (30+ \u00c5 box size). Multi-threading can be enabled via:\n\n ```bash\n export OMP_NUM_THREADS=4\n ```\n\n- For **GPU calculations**, use **one MPI task per GPU**.\n\n## Running PET-MAD with empirical dispersion corrections\n\n### In **ASE**:\n\nYou can combine the PET-MAD calculator with the torch based implementation of\nthe D3 dispersion correction of `pfnet-research` - `torch-dftd`:\n\nWithin the PET-MAD environment you can install `torch-dftd` via:\n\n```bash\npip install torch-dftd\n```\n\nThen you can use the `D3Calculator` class to combine the two calculators:\n\n```python\nfrom torch_dftd.torch_dftd3_calculator import TorchDFTD3Calculator\nfrom pet_mad.calculator import PETMADCalculator\nfrom ase.calculators.mixing import SumCalculator\n\ndevice = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n\ncalc_MAD = PETMADCalculator(version=\"latest\", device=device)\ndft_d3 = TorchDFTD3Calculator(device=device, xc=\"pbesol\", damping=\"bj\")\n\ncombined_calc = SumCalculator([calc_MAD, dft_d3])\n\n# assign the calculator to the atoms object\natoms.calc = combined_calc\n\n```\n\n## Dataset visualization with the PET-MAD featurizer\n \nYou can use PET-MAD last-layer features together with a pre-trained \nsketch-map dimensionality reduction to obtain 2D and 3D representations\nof a dataset, e.g. to identify structural or chemical motifs.\nThis can be used as a stand-alone feature builder, or combined with\nthe [chemiscope viewer](https://chemiscope.org) to generate an \ninteractive visualization. \n\n```python\nimport ase.io\nimport chemiscope\nfrom pet_mad.explore import PETMADFeaturizer\n\nfeaturizer = PETMADFeaturizer(version=\"latest\")\n\n# Load structures\nframes = ase.io.read(\"dataset.xyz\", \":\")\n\n# You can just compute features\nfeatures = featurizer(frames, None)\n\n# Or create an interactive visualization in a Jupyter notebook\nchemiscope.explore(\n frames,\n featurize=featurizer\n)\n```\n\n## Examples\n\nMore examples for **ASE, i-PI, and LAMMPS** are available in the [Atomistic\nCookbook](https://atomistic-cookbook.org/examples/pet-mad/pet-mad.html).\n\n## Fine-tuning\n\nPET-MAD can be fine-tuned using the\n[Metatrain](https://metatensor.github.io/metatrain/latest/advanced-concepts/fine-tuning.html)\nlibrary.\n\n## Documentation\n\nAdditional documentation can be found in the\n[metatensor](https://docs.metatensor.org),\n[metatomic](https://docs.metatensor.org/metatomic) and\n[metatrain](https://metatensor.github.io/metatrain/) repositories.\n\n- [Training a model](https://metatensor.github.io/metatrain/latest/getting-started/usage.html#training)\n- [Fine-tuning](https://metatensor.github.io/metatrain/latest/advanced-concepts/fine-tuning.html)\n- [LAMMPS interface](https://docs.metatensor.org/metatomic/latest/engines/lammps.html)\n- [i-PI interface](https://docs.metatensor.org/metatomic/latest/engines/ipi.html)\n\n## Citing PET-MAD\n\nIf you use PET-MAD in your research, please cite:\n\n```bibtex\n@misc{PET-MAD-2025,\n title={PET-MAD, a universal interatomic potential for advanced materials modeling},\n author={Arslan Mazitov and Filippo Bigi and Matthias Kellner and Paolo Pegolo and Davide Tisi and Guillaume Fraux and Sergey Pozdnyakov and Philip Loche and Michele Ceriotti},\n year={2025},\n eprint={2503.14118},\n archivePrefix={arXiv},\n primaryClass={cond-mat.mtrl-sci},\n url={https://arxiv.org/abs/2503.14118}\n}\n",
"bugtrack_url": null,
"license": null,
"summary": "A universal interatomic potential for advanced materials modeling",
"version": "1.3.1",
"project_urls": {
"repository": "https://github.com/lab-cosmo/pet-mad"
},
"split_keywords": [
"machine learning",
" molecular modeling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0e15164eda7d6e38bbd09cf35e41ce4dc5c39052c51922b1e43bb15cbe3afbba",
"md5": "6633d77afa5b7515d236682d537b978a",
"sha256": "1dd89b9f5fbd42c29bce43d27dd0057145021e5f40d77e8228e4a7f25d5dd166"
},
"downloads": -1,
"filename": "pet_mad-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6633d77afa5b7515d236682d537b978a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16526,
"upload_time": "2025-07-18T15:33:18",
"upload_time_iso_8601": "2025-07-18T15:33:18.305084Z",
"url": "https://files.pythonhosted.org/packages/0e/15/164eda7d6e38bbd09cf35e41ce4dc5c39052c51922b1e43bb15cbe3afbba/pet_mad-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f324ef0f66e4e8ca7869679ecd9f9a1248503c33a9115c2ff3db3853992e497a",
"md5": "9cc20fa00bee0788e1f1c9dedc15aa88",
"sha256": "be3661bb606e88239e957a7b7d8d776af7c8cd087b2c025b8254c7361cfc2368"
},
"downloads": -1,
"filename": "pet_mad-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "9cc20fa00bee0788e1f1c9dedc15aa88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20177,
"upload_time": "2025-07-18T15:33:19",
"upload_time_iso_8601": "2025-07-18T15:33:19.439149Z",
"url": "https://files.pythonhosted.org/packages/f3/24/ef0f66e4e8ca7869679ecd9f9a1248503c33a9115c2ff3db3853992e497a/pet_mad-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 15:33:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lab-cosmo",
"github_project": "pet-mad",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pet-mad"
}
JSON
