Systems#

class metatensor.torch.atomistic.System(species: Tensor, positions: Tensor, cell: Tensor)[source]#

A System contains all the information about an atomistic system; and should be used as the input of metatensor atomistic models.

You can create a System with species, positions and cell tensors, or convert data from other libraries.

Converting data to metatensor System

Some external packages provides ways to create System using data from other libraries:

rascaline has the rascaline.torch.systems_to_torch() function that can convert from ASE, chemfiles and PySCF.

Parameters:

species (Tensor) – 1D tensor of integer representing the particles identity. For atoms, this is typically their atomic numbers.
positions (Tensor) – 2D tensor of shape (len(species), 3) containing the Cartesian positions of all particles in the system.
cell (Tensor) – 2D tensor of shape (3, 3), describing the bounding box/unit cell of the system. Each row should be one of the bounding box vector; and columns should contain the x, y, and z components of these vectors (i.e. the cell should be given in row-major order). Systems are assumed to obey periodic boundary conditions, non-periodic systems should set the cell to 0.

property species: Tensor#: Tensor of 32-bit integers representing the particles identity

property positions: Tensor#: Tensor of floating point values containing the particles cartesian coordinates

property cell: Tensor#: Tensor of floating point values containing bounding box/cell of the system

property device: device#: get the device of all the arrays stored inside this System

property dtype: dtype#: get the dtype of all the arrays stored inside this System

Warning

Due to limitations in TorchScript C++ extensions, the dtype is returned as an integer, which can not be compared with torch.dtype instances. See TensorBlock.dtype() for more information.

to(dtype: dtype | None = None, device: device | None = None) → System[source]#

Move all the arrays in this system to the given dtype and device.

Parameters:

dtype (dtype | None) – new dtype to use for all arrays. The dtype stays the same if this is set to None.
device (device | None) – new device to use for all arrays. The device stays the same if this is set to None.

Return type:

System

add_neighbors_list(options: NeighborsListOptions, neighbors: TensorBlock)[source]#

Add a new neighbors list in this system corresponding to the given options.

The neighbors list should have the following samples: "first_atom", "second_atom", "cell_shift_a", "cell_shift_b", "cell_shift_c", containing the index of the first and second atoms (matching the “atom” sample in the positions); and the number of cell vector a/b/c to add to the positions difference to get the pair vector.

The neighbors should also have a single component "xyz" with values [0, 1, 2]; and a single property "distance" with value 0.

The neighbors values must contain the distance vector from the first to the second atom, i.e. positions[second_atom] - positions[first_atom] + cell_shift_a * cell_a + cell_shift_b * cell_b + cell_shift_c * cell_c.

Parameters:

options (NeighborsListOptions) – options of the neighbors list
neighbors (TensorBlock) – list of neighbors stored in a TensorBlock

get_neighbors_list(options: NeighborsListOptions) → TensorBlock[source]#

Retrieve a previously stored neighbors list with the given options, or throw an error if no such neighbors list exists.

Parameters:: options (NeighborsListOptions) – options of the neighbors list to retrieve
Return type:: TensorBlock

known_neighbors_lists() → List[NeighborsListOptions][source]#

Get all the neighbors lists options registered with this System

Return type:: List[NeighborsListOptions]

add_data(name: str, data: TensorBlock)[source]#

Add custom data to this system, stored as TensorBlock.

This is intended for experimentation with models that need more data as input, and moved into a field of System later.

Parameters:

name (str) – name of the custom data
data (TensorBlock) – values of the custom data

get_data(name: str) → TensorBlock[source]#

Retrieve custom data stored in this System with the given name, or throw an error if no data can be found.

Parameters:: name (str) – name of the custom data to retrieve
Return type:: TensorBlock

known_data() → List[str][source]#

Get the name of all the custom data registered with this System

Return type:: List[str]

class metatensor.torch.atomistic.NeighborsListOptions(model_cutoff: float, full_list: bool, requestor: str = '')[source]#

Options for the calculation of a neighbors list

Parameters:

model_cutoff (float) – spherical cutoff radius for the neighbors list, in the model units
full_list (bool) – should the list be a full or half neighbors list
requestor (str) – who requested this neighbors list, you can add additional requestors later using add_requestor()

property model_cutoff: float#: Spherical cutoff radius for this neighbors list in model units

property engine_cutoff: float#: Spherical cutoff radius for this neighbors list in engine units. This defaults to the same value as model_cutoff until set_engine_unit() is called.

set_engine_unit(conversion)[source]#: Set the conversion factor from the model units to the engine units

property full_list: bool#: Should the list be a full neighbors list (contains both the pair i->j and j->i) or a half neighbors list (contains only the pair i->j)

requestors() → List[str][source]#

Get the list of modules requesting this neighbors list

Return type:: List[str]

add_requestor(requestor: str)[source]#

Add another requestor to the list of modules requesting this neighbors list

Parameters:: requestor (str) –

__eq__(other: NeighborsListOptions) → bool[source]#

Return self==value.

Parameters:: other (NeighborsListOptions) –
Return type:: bool

__ne__(other: NeighborsListOptions) → bool[source]#

Return self!=value.

Parameters:: other (NeighborsListOptions) –
Return type:: bool