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, torch::Tensor pbc)

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

• pbc – 1D tensor of 3 boolean values, indicating if the system is periodic along the directions defined by cell axes a, b and c, respectively.

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::Tensor pbc() const

Periodic boundary conditions for the system.

void set_pbc(torch::Tensor pbc)

Set periodic boundary conditions 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_neighbor_list(NeighborListOptions options, TorchTensorBlock neighbors)

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

The neighbor 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_neighbor_list(NeighborListOptions options) const

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

std::vector<NeighborListOptions> known_neighbor_lists() const

Get the options for all neighbor lists registered with this System

void add_data(std::string name, TorchTensorMap tensor, 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

• tensor – the data to store

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

TorchTensorMap 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::NeighborListOptions = torch::intrusive_ptr<NeighborListOptionsHolder>

TorchScript will always manipulate NeighborListOptions through a torch::intrusive_ptr

class NeighborListOptionsHolder : public CustomClassHolder

Options for the calculation of a neighbor list.

Public Functions

NeighborListOptionsHolder(double cutoff, bool full_list, bool strict, std::string requestor = "")

Create NeighborListOptions with the given cutoff value, and the flags full_list and strict.

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

inline double cutoff() const

Spherical cutoff radius for this neighbor 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 neighbor list, in the units of the engine.

inline bool full_list() const

Should the list be a full neighbor list (contains both the pair i->j and j->i) or a half neighbor list (contains only the pair i->j)

inline bool strict() const

Should the list guarantee that only atoms within the cutoff are.

inline std::vector<std::string> requestors() const

Get the list of strings describing who requested this neighbor list.

void add_requestor(std::string requestor)

Add a new requestor to the list of who requested this neighbor 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 NeighborListOptions to a JSON string.

Public Static Functions

static NeighborListOptions from_json(const std::string &json)

Load a serialized NeighborListOptions from a JSON string.