Calculators¶

class featomic.torch.CalculatorModule(name: str, parameters: str)¶

This is the base class for calculators in featomic-torch, providing the CalculatorModule.compute() function and integration with torch.nn.Module.

One can initialize a py:class:CalculatorModule in two ways: either directly with the registered name and JSON parameter string (which are documented in the Calculator reference); or through one of the child class documented below.

Parameters:

name – name used to register this calculator
parameters – JSON parameter string for the calculator

property name: str¶: name of this calculator

property c_name: str¶: name used to register & create this calculator

property parameters: str¶: parameters (formatted as JSON) used to create this calculator

property cutoffs: List[float]¶: all the radial cutoffs used by this calculator’s neighbors lists

Runs a calculation with this calculator on the given systems.

See also

featomic.calculators.CalculatorBase.compute() for more information on the different parameters of this function.

Parameters:

systems – single system or list of systems on which to run the calculation. If any of the systems’ positions or cell has requires_grad set to True, then the corresponding gradients are computed and registered as a custom node in the computational graph, to allow backward propagation of the gradients later.
gradients – List of forward gradients to keep in the output. If this is None or an empty list [], no gradients are kept in the output. Some gradients might still be computed at runtime to allow for backward propagation.
use_native_system – This can only be True, and is here for compatibility with the same parameter on featomic.calculators.CalculatorBase.compute().
selected_samples – Set of samples on which to run the calculation, with the same meaning as in featomic.calculators.CalculatorBase.compute().
selected_properties – Set of properties to compute, with the same meaning as in featomic.calculators.CalculatorBase.compute().
selected_keys – Selection for the keys to include in the output, with the same meaning as in featomic.calculators.CalculatorBase.compute().

forward(systems: List[System], gradients: List[str] | None = None, use_native_system: bool = True, selected_samples: Labels | TensorMap | None = None, selected_properties: Labels | TensorMap | None = None, selected_keys: Labels | None = None) → TensorMap¶: forward just calls CalculatorModule.compute()

featomic.torch.register_autograd(systems: List[System] | System, precomputed: TensorMap, forward_gradients: List[str] | None = None) → TensorMap¶

Register autograd nodes between system.positions and system.cell for each of the systems and the values in the precomputed metatensor.torch.TensorMap.

This is an advanced function must users should not need to use.

The autograd nodes backward function will use the gradients already stored in precomputed, meaning that if any of the system’s positions requires_grad, precomputed must contain "positions" gradients. Similarly, if any of the system’s cell requires_grad, precomputed must contain "cell" gradients.

Parameters:

systems – list of system used to compute precomputed
precomputed – precomputed metatensor.torch.TensorMap
forward_gradients – which gradients to keep in the output, defaults to None

class featomic.torch.AtomicComposition(*, per_system)¶

Bases: CalculatorModule

An atomic composition calculator for obtaining the stoichiometric information.

For per_system=False calculator has one property count that is 1 for all atoms, and has a sample index that indicates the central atom type.

For per_system=True a sum for each system is performed. The number of atoms per system is saved. The only sample left is named system.

class featomic.torch.NeighborList(*, cutoff, full_neighbor_list, self_pairs=False)¶

Bases: CalculatorModule

This calculator computes the neighbor list for a given spherical cutoff, and returns the list of distance vectors between all pairs of atoms strictly inside the cutoff.

Users can request either a “full” neighbor list (including an entry for both i - j pairs and j - i pairs) or save memory/computational by only working with “half” neighbor list (only including one entry for each i/j pair)

Pairs between an atom and it’s own periodic copy can appear when the cutoff is larger than the cell under periodic boundary conditions. Self pairs with a distance of 0 (i.e. self pairs inside the original unit cell) are only included when using self_pairs=True.

This calculator produces a single property ("distance") with three components ("pair_xyz") containing the x, y, and z component of the distance vector of the pair.

The samples contain the two atoms indexes, as well as the number of cell boundaries crossed to create this pair.

class featomic.torch.SortedDistances(*, cutoff, max_neighbors, separate_neighbor_types)¶

Bases: CalculatorModule

Sorted distances vector representation of an atomic environment.

Each atomic center is represented by a vector of distance to its neighbors within the spherical cutoff, sorted from smallest to largest. If there are less neighbors than max_neighbors, the remaining entries are filled with cutoff instead.

Separate atomic types for neighbors are represented separately, meaning that the max_neighbors parameter only apply to a single atomic type.

For a full description of the hyper-parameters, see the corresponding documentation.

class featomic.torch.SphericalExpansion(*, cutoff=None, density=None, basis=None, **kwargs)¶

Bases: CalculatorModule

Spherical expansion of Smooth Overlap of Atomic Positions (SOAP).

The spherical expansion is at the core of representations in the SOAP family of descriptors. The spherical expansion represent atomic density as a collection of Gaussian functions centered on each atom, and then represent the local density around each atom (up to a cutoff) on a basis of radial functions and spherical harmonics. This representation is not rotationally invariant, for that you should use the SoapPowerSpectrum class.

See this review article for more information on the SOAP representation, and this paper for information on how it is implemented in featomic.

For a full description of the hyper-parameters, see the corresponding documentation.

class featomic.torch.SphericalExpansionByPair(*, cutoff=None, density=None, basis=None, **kwargs)¶

Bases: CalculatorModule

Pair-by-pair version of the spherical expansion of Smooth Overlap of Atomic Positions (SOAP).

This is usually an intermediary step when computing the full SphericalExpansion, which most users do not need to care about. When computing SOAP, the density around the central atom \(i\) is a sum of pair contributions:

\[\rho_i(\mathbf{r}) = \sum_j g(\mathbf{r_{ji}} - \mathbf{r}).\]

The full spherical expansion is then computed as a sum over all pairs within the cutoff:

\[ \begin{align}\begin{aligned}\int Y^l_m(\mathbf{r})\ R_n(\mathbf{r}) \, \rho_i(\mathbf{r}) \mathrm{d}\mathbf{r} = \sum_j C^{ij}_{nlm}\\C^{ij}_{nlm} = \int Y^l_m(\mathbf{r}) \ R_n(\mathbf{r}) \, g(\mathbf{r_{ji}} - \mathbf{r}) \, \mathrm{d}\mathbf{r}\end{aligned}\end{align} \]

This calculators computes the individual \(C^{ij}_{nlm}\) terms, which can then be used to build multi-center representations such as the ones discussed in “Unified theory of atom-centered representations and message-passing machine-learning schemes”.

For a full description of the hyper-parameters, see the corresponding documentation.

class featomic.torch.SoapRadialSpectrum(*, cutoff=None, density=None, basis=None, **kwargs)¶

Bases: CalculatorModule

Radial spectrum of Smooth Overlap of Atomic Positions (SOAP).

The SOAP radial spectrum represent each atom by the radial average of the density of its neighbors. It is very similar to a radial distribution function g(r). It is a 2-body representation, only containing information about the distances between atoms.

See this review article for more information on the SOAP representation, and this paper for information on how it is implemented in featomic.

For a full description of the hyper-parameters, see the corresponding documentation.

class featomic.torch.SoapPowerSpectrum(*, cutoff=None, density=None, basis=None, **kwargs)¶

Bases: CalculatorModule

Power spectrum of Smooth Overlap of Atomic Positions (SOAP).

The SOAP power spectrum is the main member of the SOAP family of descriptors. The power spectrum is based on the SphericalExpansion coefficients, which are combined to create a rotationally invariant three-body descriptor.

See this review article for more information on the SOAP representation, and this paper for information on how it is implemented in featomic.

For a full description of the hyper-parameters, see the corresponding documentation.