Energy

The potential energy is associated with the "energy" or "energy/<variant>" name (see Variants), and must have the following metadata:

Metadata for "energy"

Metadata	Names	Description
keys	"_"	the keys must have a single dimension named "_", with a single entry set to 0. The "energy" quantity is always represented as a metatensor.torch.TensorMap with a single block.
samples	["system", "atom"] or ["system"]	the samples should be named ["system", "atom"] for per-atom quantities; or ["system"] for per-system quantities. "system" must range from 0 to the number of systems given as input to the model. "atom" must range between 0 and the number of atoms/particles in the corresponding system. If selected_atoms is provided, then only the selected atoms for each system should be part of the samples.
components		the "energy" quantity must not have any components
properties	"energy"	the "energy" quantity must have a single property dimension named "energy", with a single entry set at 0.

The following simulation engines can use the "energy" quantity as output:

ASE

eOn

GROMACS

i-PI

LAMMPS

TorchSim

Gradients of the "energy" quantity

Most of the time, when writing an atomistic model compatible with metatomic, gradients will be handled implicitly and computed by the simulation engine using a backward pass. Additionally, it is possible for the model to support explicit, forward mode gradients

The following gradients can be defined and requested with explicit_gradients:

• “positions” (\(r_j\)) gradients will contain the negative of the forces \(F_j\).

  \[\frac{\partial E}{\partial r_j} = -F_j\]

Metadata for positions gradients of the "energy"

Metadata	Names	Description
samples	["sample", "system", "atom"]	"sample" indicates which of the values samples we are taking the gradient of, and ("system", "atom") indicates which of the atom’s positions we are taking the gradients with respect to; i.e. \(j\) in the equation above.
components	"xyz"	there must be a single component named "xyz" with values 0, 1, 2; indicating the direction of the displacement of the atom in the gradient samples.

• “strain” (\(\epsilon\)) gradients will contain the stress \(\sigma\) acting on the system, multiplied by the volume \(V\) (sometimes also called the virial of this system)

  \[\frac{\partial E}{\partial \epsilon} = V \sigma\]

Metadata for strain gradients of the "energy"

Metadata	Names	Description
samples	"sample"	There is a single gradient sample dimension, "sample" indicating which of the values samples we are taking the gradient of.
components	["xyz_1", "xyz_2"]	Both "xyz_1" and "xyz_2" have values [0, 1, 2], and correspond to the two axes of the 3x3 strain matrix \(\epsilon\).

Energy ensemble

An ensemble of energies is associated with the "energy_ensemble" or "energy_ensemble/<variant>" name (see Variants). Such ensembles are sometimes used to perform uncertainty quantification, using multiple prediction to estimate an error on the mean prediction.

Energy ensembles must have the following metadata:

Metadata for "energy_ensemble"

Metadata	Names	Description
keys	same as Energy	same as Energy
samples	same as Energy	same as Energy
components	same as Energy	same as Energy
properties	"energy"	the "energy_ensemble" quantity must have a single property dimension named "energy", with entries ranging from 0 to the number of members of the ensemble minus one.

The following simulation engines can use the "energy_ensemble" quantity as output:

i-PI

Energy ensemble gradients

The gradient metadata for energy ensemble is the same as for the energy output (see Gradients of the "energy" quantity).

Energy uncertainty

The uncertainty on the "energy" quantity is associated with the "energy_uncertainty" or "energy_uncertainty/<variant>" name (see Variants). This corresponds to the expected standard deviation of the predictions when compared to the ground truth.

The "energy_uncertainty" quantity must have the following metadata:

Metadata for "energy_uncertainty"

Metadata	Names	Description
keys	same as Energy	same as Energy
samples	same as Energy	same as Energy
components	same as Energy	same as Energy
properties	same as Energy	same as Energy

The following simulation engines can use the "energy_uncertainty" quantity as output to automatically warn users about high-uncertainty predictions:

ASE

i-PI

eOn

LAMMPS