Systems#

using metatensor_torch::System = torch::intrusive_ptr<SystemHolder>#: TorchScript will always manipulate SystemHolder through a torch::intrusive_ptr

class SystemHolder : public CustomClassHolder#

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

Public Functions

SystemHolder(torch::Tensor types, torch::Tensor positions, torch::Tensor cell)#

Create a SystemHolder with the given types, positions and cell.

Parameters:

types – 1D tensor of 32-bit integer representing the particles identity. For atoms, this is typically their atomic numbers.
positions – 2D tensor of shape (len(types), 3) containing the Cartesian positions of all particles in the system.
cell – 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.

inline torch::Tensor types() const#: Get the particle types for all particles in the system.

void set_types(torch::Tensor types)#: Set types for all particles in the system.

inline torch::Tensor positions() const#: Get the positions for the atoms in the system.

void set_positions(torch::Tensor positions)#: Set positions for all particles in the system.

inline torch::Tensor cell() const#: Unit cell/bounding box of the system.

void set_cell(torch::Tensor cell)#: Set cell for the system.

inline torch::Device device() const#: Get the device used by all the data in this System

inline torch::Dtype scalar_type() const#: Get the dtype used by all the floating point data in this System

System to(torch::optional<torch::Dtype> dtype = torch::nullopt, torch::optional<torch::Device> device = torch::nullopt) const#: Move all the data in this System to the given dtype and device.

System to_positional(torch::IValue positional_1, torch::IValue positional_2, torch::optional<torch::Dtype> dtype, torch::optional<torch::Device> device) const#: Wrapper of the to function to enable using it with positional parameters from Python; for example to(dtype), to(device), to(dtype, device=device), to(dtype, device), to(device, dtype), etc.

inline int64_t size() const#: Get the number of particles in this system.

void add_neighbors_list(NeighborsListOptions options, TorchTensorBlock neighbors)#

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 atom 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.

TorchTensorBlock get_neighbors_list(NeighborsListOptions options) const#: Retrieve a previously stored neighbors list with the given options, or throw an error if no such neighbors list exists.

std::vector<NeighborsListOptions> known_neighbors_lists() const#: Get the list of neighbors lists registered with this System

void add_data(std::string name, TorchTensorBlock values, bool override = false)#

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 SystemHolder later.

Parameters:

name – name of the data
values – values of the data
override – if true, allow this function to override existing data with the same name

TorchTensorBlock get_data(std::string name) const#: Retrieve custom data stored in this System, or throw an error.

std::vector<std::string> known_data() const#: Get the list of data registered with this System

std::string str() const#: Implementation of __str__ and __repr__ for Python.

using metatensor_torch::NeighborsListOptions = torch::intrusive_ptr<NeighborsListOptionsHolder>#: TorchScript will always manipulate NeighborsListOptions through a torch::intrusive_ptr

class NeighborsListOptionsHolder : public CustomClassHolder#

Options for the calculation of a neighbors list.

Public Functions

NeighborsListOptionsHolder(double cutoff, bool full_list, std::string requestor = "")#

Create NeighborsListOptions with the given cutoff and full_list.

requestor can be used to store information about who requested the neighbors list.

inline double cutoff() const#: Spherical cutoff radius for this neighbors list, in the units of the model.

inline const std::string &length_unit() const#: Get the length unit of the model, this will be used in engine_cutoff.

void set_length_unit(std::string length_unit)#

Set the length unit to a new value.

This is typically called by MetatensorAtomisticModel, and should not need to be set by users directly.

double engine_cutoff(const std::string &engine_length_unit) const#: Spherical cutoff radius for this neighbors list, in the units of the engine.

inline bool full_list() const#: 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)

inline std::vector<std::string> requestors() const#: Get the list of strings describing who requested this neighbors list.

void add_requestor(std::string requestor)#: Add a new requestor to the list of who requested this neighbors list.

std::string repr() const#: Implementation of Python’s __repr__

std::string str() const#: Implementation of Python’s __str__

std::string to_json() const#: Serialize a NeighborsListOptions to a JSON string.

Public Static Functions

static NeighborsListOptions from_json(const std::string &json)#: Load a serialized NeighborsListOptions from a JSON string.