metatensor

Metatensor is a library providing a cross-platform data interchange API for atomistic simulation and beyond. It also powers metatomic – an API to define atomistic models that can be used to run simulations using several different atomistic simulation packages and metatrain a set of tools to facilitate training and evaluating ML models.

Atomistic Water Model for Molecular Dynamics
In this example, we demonstrate how to construct a metatomic model for flexible three and four-point water model, with parameters optimized for use together with quantum-nuclear-effects-aware path integral simulations (cf. Habershon et al., JCP (2009)). The model also demonstrates the use of torch-pme, a Torch library for long-range interactions, and uses the resulting model to perform demonstrative molecular dynamics simulations.
Atomistic Water Model for Molecular Dynamics
Equivariant linear model for polarizability
In this example, we demonstrate how to construct a metatensor atomistic model for the polarizability tensor of molecular systems. This example uses the featomic library to compute equivariant descriptors, and scikit-learn to train a linear regression model. The model can then be used in an ASE calculator. You could also have a look at this recipe based on scalar/tensorial models, which provides an alternative approach for equivariant learning of tensors.
Equivariant linear model for polarizability
Equivariant model for tensorial properties based on scalar features
In this example, we demonstrate how to train a metatensor atomistic model on dipole moments and polarizabilities of small molecular systems, using a model that combines scalar descriptors with equivariant tensorial components that depend in a simple way from the molecular geometry. You may also want to read this recipe for a linear polarizability model, which provides an alternative approach for tensorial learning. The model is trained with metatrain and can then be used in an ASE calculator.
Equivariant model for tensorial properties based on scalar features
The PET-MAD universal potential
This example demonstrates how to use the PET-MAD model with ASE, i-PI and LAMMPS. PET-MAD is a "universal" machine-learning forcefield trained on a dataset that aims to incorporate a very high degree of structural diversity.
The PET-MAD universal potential
MD using direct-force predictions with PET-MAD
Evaluating forces as a direct output of a ML model accelerates their evaluation, by up to a factor of 3 in comparison to the traditional approach that evaluates them as derivatives of the interatomic potential. Unfortunately, as discussed e.g. in this paper, doing so means that forces are not conservative, leading to instabilities and artefacts in many modeling tasks, such as constant-energy molecular dynamics. Here we demonstrate the issues associated with direct force predictions, and ways to mitigate them, using the generally-applicable PET-MAD potential. See also this recipe for examples of using PET-MAD for basic tasks such as geometry optimization and conservative MD, and this for an example of how to use direct forces to accelerate training.
MD using direct-force predictions with PET-MAD
Fine-tuning the PET-MAD universal potential
This example demonstrates how to fine-tune the PET-MAD universal ML potential on a new dataset using metatrain. This allows adapting the model to a specialized task by retraining it on a more focused, domain-specific dataset.
Fine-tuning the PET-MAD universal potential
Conservative fine-tuning for a PET model
This example demonstrates a "conservative fine-tuning" (or equivalently, "non-conservative pre-training") strategy. This consists in training a model using (faster) direct, non-conservative force predictions, and then fine-tuning it with backpropagated forces to achieve an accurate conservative model.
Conservative fine-tuning for a PET model
Long-stride trajectories with a universal FlashMD model
For a quickstart on how to use FlashMD with ASE, you can go here.
Long-stride trajectories with a universal FlashMD model
Computing NMR shielding tensors using ShiftML
This example shows how to compute NMR shielding tensors using a point-edge transformer model trained on the ShiftML dataset.
Computing NMR shielding tensors using ShiftML
NMR-shielding-driven structure determination with ShiftML3
This recipe shows how to use a fast machine-learning surrogate for ab initio NMR chemical-shielding calculations -- ShiftML3 -- to pick out an experimentally observed crystal structure from a pool of candidate polymorphs. In a nutshell, the NMR-shielding-driven structure determination protocol, also sometimes referred to as NMR crystallography or NMR crystal-structure prediction (NMR-CSP), aims to enhance the confidence in a classical crystal structure prediction (CSP) workflow by anchoring the final structure selection step to experimental solid-state NMR data. This method is particularly useful to determine the structure of organic solids, for which it is difficult to obtain single crystals suitable for X-ray diffraction, or to unambiguously determine protonation states who cannot be resolved by XRD.
NMR-shielding-driven structure determination with ShiftML3
Hamiltonian Learning for Molecules with Indirect Targets
This tutorial introduces a machine learning (ML) framework that predicts Hamiltonians for molecular systems. Another one of our cookbook examples demonstrates an ML model that predicts real-space Hamiltonians for periodic systems. While we use the same model here to predict a molecular Hamiltonians, we further finetune these models to optimise predictions of different quantum mechanical (QM) properties of interest, thereby treating the Hamiltonian predictions as an intermediate component of the ML framework. More details on this hybrid or indirect learning framework can be found in ACS Cent. Sci. 2024, 10, 637−648. and our preprint arXiv:2504.01187.
Hamiltonian Learning for Molecules with Indirect Targets
ML collective variables in PLUMED with metatomic
This example shows how to build a metatomic model that computes order parameters for a Lennard-Jones cluster, and how to use it with the PLUMED package to run a metadynamics simulation.
ML collective variables in PLUMED with metatomic
Geometry relaxation with unconstrained MLIPs
This recipe shows how to perform geometry optimization with unconstrained machine-learning interatomic potentials (MLIPs), and what tools are available to control symmetry during relaxation.
Geometry relaxation with unconstrained MLIPs
ML surrogate for the electron density and derived properties
ML surrogate for the electron density and derived properties
Introduction to foundational models for molecular dynamics
Introduction to foundational models for molecular dynamics
Machine-learned dipoles and infrared spectroscopy of liquid water
Machine-learned dipoles and infrared spectroscopy of liquid water