Create the silicon.data data file for a silicon system.

Running LAMMPS with KOKKOS and GPU support is similar to the CPU version, but you need to run the lmp binary with a few additional flags.

The lammps.in and silicon.data files remain the same.

To run the KOKKOS-enabled version of LAMMPS, you need to run

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 the simulation is parallelized over, so this number should be adjusted accordingly if you're running a large system on multiple GPUs.

• For CPU calculations, use a single MPI task unless simulating large systems (30+ A box size). Multi-threading can be enabled via:

  export OMP_NUM_THREADS=4

• For GPU calculations, use one MPI task per GPU.

UPET models can also be used to calculate the uncertainty of the energy prediction. This feature is particularly important if you are interested in probing the model on data that could be substantially different from the training data. Another important use case is propagation of uncertainties in the energy predictions to other observables, like phase transition temperatures, diffusion coefficients, etc.

To evaluate the uncertainty of energy predictions, or to get an ensemble of energy predictions, you can use the get_energy_uncertainty and get_energy_ensemble methods of the UPETCalculator class:

Please note that the uncertainty quantification and ensemble prediction accepts the per_atom flag, which indicates whether the uncertainty/ensemble should be computed per atom or for the whole system. More details on the LLPR uncertainty quantification and shallow ensemble methods can be found in this and this papers respectively.

By design, UPET models are not exactly equivariant w.r.t. rotations and inversions. Although the equivariance error is typically much smaller than the overall model error, in some cases (like geometry optimizations and phonon calculations of highly symmetrical structures) it may be beneficial to enforce additional rotational averaging to improve the symmetry of the predictions. This can be done by setting the rotational_average_order parameter when initializing the UPETCalculator class:

In this case, predictions will be averaged over a quadrature of the O(3) group based on a Lebedev grid of the specified order (here 3). Higher orders lead to more accurate equivariance, but also increase the computational cost.

By default, all the transformed structures are evaluated in a single batch, which may lead to high memory usage for large systems. If you want to reduce the memory usage, you can set the rotational_average_batch_size parameter to a smaller value (eg. 8), which will evaluate the transformed structures in smaller batches:

Finally, the rotational averaging error statistics are stored in the results dictionary of the calculator after the energy/forces/stresses are computed:

You can combine the UPET calculator with the torch-based implementation of the D3 dispersion correction of pfnet-research - torch-dftd:

Within the UPET environment you can install torch-dftd via:

Then you can use the D3Calculator class to combine the two calculators:

The UPET package also allows the use of the PET-MAD-DOS model to predict electronic density of states of materials, as well as their Fermi levels and bandgaps. The PET-MAD-DOS model is available from its ASE interface.

Predicting the densities of states for every atom in the crystal, or a list of atoms, is also possible:

Finally, you can use the calculate_bandgap and calculate_efermi methods to predict the bandgap and Fermi level for the crystal:

You can also re-use the DOS calculated earlier:

This option is also available for a list of ase.Atoms objects:

You can use the last-layer features of the PET-MAD model 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 to generate an interactive visualization.

UPET models can be fine-tuned using the Metatrain library. At the moment, we recommend fine-tuning from our OMat models, as they are pre-trained on a very large dataset and they come in all sizes (from XS to XL, allowing you to choose a good trade-off for your application).

It's important to note that by default the UPETCalculator class uses the energy and non-conservative forces/stresses heads provided with the pre-trained models. If you fine-tune the model and create a new head for your energy target, you should explicitly select the corresponding energy variant on runtime (same for non-conservative forces/stresses). Let's consider an example, where you fine-tune the energy head and call it "energy/finetune" in the options.yaml file, while running mtt train command.

In ASE, running the model with a variant selection can be done by loading your trained checkpoint and initializing the UPETCalculator class with the variants parameter:

Same applies to non-conservative forces and stresses, if you created new heads for them during fine-tuning.

Similarly to ASE calculator, you can select the new head for evaluation with metatrain while running mtt eval command by specifying the head in the options.yaml file:

In LAMMPS, you can select the new head by specifying the variant/energy parameter in the pair_style metatomic command:

More examples for ASE, i-PI, and LAMMPS are available in the Atomistic Cookbook.

Additional documentation can be found in the metatensor, metatomic and metatrain repositories.

• Training a model
• Fine-tuning
• LAMMPS interface
• i-PI interface

In general, if you see that something doens't work as you expect, please update to the latest version of the UPET package (and simulation engines like lammps-metatomic), before spending hours on debugging or reporting the issue immediately. Our codebase evolves quickly, and chances are your issue has been already fixed in a recent update. If you still see the issue after updating, please follow the FAQs below, and open an issue or a discussion in case you didn't find the answer.

What model should I use for my application?

• For molecular dynamics simulations, we recommend using the PET-MAD v1.5.0 models.
• For materials discovery tasks (convex hull energies, geometry optimization, phonons, etc), we recommend using the PET-OAM models.
• For accurate and fast simulations of biomolecules, we recommend using the PET-SPICE models.
• If you want to fine-tune your own model, we recommend starting from the PET-OMat checkpoints, and select an appropriate size (from XS to XL) for your needs.
• In any case, we recommend starting from the smaller models (XS or S) to benchmark your application, and then scaling up to larger models if you need more accuracy.

The model is slow for my application. What should I do?

• Make sure you run it on a GPU
• Use an S or XS model
• Simulate with LAMMPS (Kokkos-GPU version)
• Use non-conservative forces and stresses, preferably with multiple time stepping. Check out this example for details.
• Still too slow? Check out FlashMD for a further 30x boost.

My MD ran out of memory. How do I fix that?

• Reduce the model size (XS models are the least memory-intensive)
• Reduce the structure size
• Try to use LAMMPS (Kokkos-GPU version) and run with multiple MPI tasks to enable domain decomposition
• As a last resort, use non-conservative forces and stresses
• If you hit a weird bug when running more than 65535 atoms on GPU, this is not an out-of-memory bug, but a pytorch bug. You can fix it by adding torch.backends.cuda.enable_mem_efficient_sdp(False) (after importing torch) near the top of your file.

The model is not fully equivariant. Should I worry?

Although our models are unconstrained, they are explicitly trained for equivariance, and the equivariance error is, in the vast majority of cases, one to two orders of magnitude smaller than the machine-learning error with respect to the target electronic structure method. Hence:

• Read this paper which shows that the impact of non-equivariance on observables is often negligible. Proceed to the next two points only if you believe that you're seeing effects due to non-equivariance.
• For MD, activate random frame averaging (we are working on a tutorial)
• For geometry optimization, use a symmetrized calculator (see rotational_average_order parameter in the ASE calculator)

The XL models are huge!

There are two aspects to this:

• The number of parameters is large, but these parameters are used in a very sparse way and the evaluation cost is comparable to, and often lower than, that of other large models in the field.
• The listed cutoff radius may be large, but the cutoff strategy is adaptive, meaning that the model prunes the neighbor list internally. The effective cutoff for the vast majority of atomic environments in materials ends up being between 4 and 7 A in practice.

If you are fine-tuning our models, please also see the metatrain FAQs

Simulation blows up with lammps-metatomic 2025.9.10.mta2

While running upet models with the version above, we observe that simulations blow up. This is most likely a bug introduced in a recent PR in lammps-metatomic. Please update to the latest version of lammps-metatomic, 2025.9.10.mta3 or later, to fix this issue.

If you found our models useful, you can cite the corresponding articles.

PET-MAD-1.5:

Current UPET architecture, PET-OAM, PET-OMat, PET-OMAD, PET-OMATPES, PET-SPICE:

PET-MAD:

PET-MAD-DOS:

For a general citation for the PET architecture, you can use