Machine learning models

This section contains recipes that concern the training of machine-learning models, or the pre-processing of data to optimize the model architecture or data.

A ML model for the electron density of states
This tutorial would go through the entire machine learning framework for the electronic density of states (DOS). It will cover the construction of the DOS and SOAP descriptors from ase Atoms and eigenenergy results. A simple neural network will then be constructed and the model parameters, along with the energy reference will be optimized during training. A total of three energy reference will be used, the average Hartree potential, the Fermi level, and an optimized energy reference starting from the Fermi level energy reference. The performance of each model is then compared.
A ML model for the electron density of states
Long-distance Equivariants: a tutorial
This tutorial explains how Long range equivariant descriptors can be constructed using featomic and the resulting descriptors be used to construct a linear model with equisolve
Long-distance Equivariants: a tutorial
Sample and Feature Selection with FPS and CUR
In this tutorial we generate descriptors using featomic, then select a subset of structures using both the farthest-point sampling (FPS) and CUR algorithms implemented in scikit-matter. Finally, we also generate a selection of the most important features using the same techniques.
Sample and Feature Selection with FPS and CUR
Periodic Hamiltonian learning
This tutorial explains how to train a machine learning model for the electronic Hamiltonian of a periodic system. Even though we focus on periodic systems, the code and techniques presented here can be directly transferred to molecules.
Periodic Hamiltonian learning
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
Mendeleev clusters
This example demonstrates how to stress test universal machine learning potentials by simulating a complex nanoparticle containing all the elements that are supported by the target model. We will use the version 1.5.0 of the PET-MAD universal potential, which covers 102 elements, using ASE, and i-PI.
Mendeleev clusters
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
Phonon dispersions with unconstrained models and uncertainty quantification
Phonon dispersion curves are important experimental probes of the lattice dynamics of a material, and are commonly used to validate MLIPs. They are also crucial for computing temperature-dependent properties such as free energies and thermal conductivity.
Phonon dispersions with unconstrained models and uncertainty quantification
ML/MM Simulations with GROMACS and Metatomic
In this tutorial we simulate and analyse an alanine dipeptide in water using a machine learning potential for the solute while the solvent is treated with a classical force field. This setup is commonly referred to as an ML/MM simulation and follows very similar ideas to QM/MM.
ML/MM Simulations with GROMACS and Metatomic
Thermal conductivity from the Boltzmann transport equation
This recipe shows how to compute lattice thermal conductivity \kappa by solving the phonon Boltzmann transport equation (BTE) with kALDo and the PET-MAD universal machine-learning potential via the UPET calculator.
Thermal conductivity from the Boltzmann transport equation
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
Foundational (or universal) machine-learning interatomic potentials are trained once on broad, chemically diverse datasets, with the goal of describing essentially any system without specific re-parameterization. This recipe illustrates the concept: we take a single foundational model, PET-MAD-XS (which spans 102 elements of the periodic table), and use it, unchanged, to run molecular dynamics on four qualitatively different aqueous systems:
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