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 species, torch::Tensor positions, torch::Tensor cell)#

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

Parameters:

  • species – 1D tensor of 32-bit integer representing the particles identity. For atoms, this is typically their atomic numbers.

  • positions – 2D tensor of shape (len(species), 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 species() const#

Get the species for all particles in the system.

void set_species(torch::Tensor species)#

Set species 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

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)#

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

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 model_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 model_cutoff() const#

Spherical cutoff radius for this neighbors list, in the units of the model.

inline double engine_cutoff() const#

Spherical cutoff radius for this neighbors list, in the units of the engine.

inline void set_engine_unit(double conversion)#

Set the conversion factor from the model units to the engine units.

This should be called before engine_cutoff().

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.