Labels

using metatensor_torch::TorchLabels = torch::intrusive_ptr<LabelsHolder>

TorchScript will always manipulate LabelsHolder through a torch::intrusive_ptr

class LabelsHolder : public CustomClassHolder

Wrapper around metatensor::Labels for integration with TorchScript

Python/TorchScript code will typically manipulate torch::intrusive_ptr<LabelsHolder> (i.e. TorchLabels) instead of instances of LabelsHolder.

The main difference with metatensor::Labels is that the values of the labels entries are stored twice: once inside the Rust side labels, and once in a torch::Tensor. The data inside the tensor can be moved to different devices if needed.

Public Functions

LabelsHolder(torch::IValue names, torch::Tensor values)

Construct LabelsHolder from a set of names and the corresponding values

The names should be either a single string or a list/tuple of strings; and the values should be a 2D tensor of integers.

explicit LabelsHolder(metatensor::Labels labels)

Create a LabelsHolder from a pre-existing metatensor::Labels

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

Get the names of the dimensions/columns of these Labels.

inline torch::Tensor values() const

Get the values of these labels as a torch Tensor.

TorchLabels append(std::string name, torch::Tensor values) const

Create new Labels with a new dimension with the given name and values added to the end of the dimensions list.

TorchLabels insert(int64_t index, std::string name, torch::Tensor values) const

Create new Labels with a new dimension with the given name and values before index.

TorchLabels permute(std::vector<int64_t> dimensions_indexes) const

Create new Labels with permuted dimensions.

TorchLabels remove(std::string name) const

Create new Labels with name removed from the dimensions list.

TorchLabels rename(std::string old_name, std::string new_name) const

Create new Labels with old_name renamed to new_name in the dimensions list

inline torch::Device device() const

Get the current device for these Labels

TorchLabels to(torch::IValue device) const

Move the values for these Labels to the given device

TorchLabels to(torch::Device device) const

Move the values for these Labels to the given device

torch::Tensor column(std::string dimension)

Get the values associated with a single dimension (i.e. a single column of values()) in these labels.

inline int64_t count() const

Get the number of entries in this set of Labels.

This is the same as values().size(0)

inline int64_t size() const

Get the number of dimensions in this set of Labels.

This is the same as values().size(1)

torch::optional<int64_t> position(torch::IValue entry) const

Get the position of the given entry in this set of Labels, or None if the entry is not part of these labels.

Parameters:

entry – one of:

• a LabelsEntry

• a 1-D torch::Tensor containing integers;

• a list of integers;

• a tuple of integers;

std::string print(int64_t max_entries, int64_t indent) const

Print the names and values of these Labels to a string, including at most max_entries entries (set this to -1 to print all entries), and indenting all lines after the first with indent spaces.

std::string str() const

Implementation of __str__ for Python.

std::string repr() const

Implementation of __repr__ for Python.

const metatensor::Labels &as_metatensor() const

Get the underlying metatensor::Labels.

inline bool is_view() const

Is this a view inside existing Labels or an owned Labels?

TorchLabels to_owned() const

Transform a view of Labels into owned Labels, which can be further given to metatensor functions. This does nothing if the Labels are already owned.

TorchLabels set_union(const TorchLabels &other) const

Get the union of this and other

std::tuple<TorchLabels, torch::Tensor, torch::Tensor> union_and_mapping(const TorchLabels &other) const

Get the union of this and other, as well as the mapping from positions of entries in the input to the position of entries in the output.

TorchLabels set_intersection(const TorchLabels &other) const

Get the intersection of this and other

std::tuple<TorchLabels, torch::Tensor, torch::Tensor> intersection_and_mapping(const TorchLabels &other) const

Get the intersection of this and other, as well as the mapping from positions of entries in the input to the position of entries in the output.

torch::Tensor select(const TorchLabels &selection) const

Select entries in these Labels that match the selection.

The selection’s names must be a subset of the names of these labels.

All entries in these Labels that match one of the entry in the selection for all the selection’s dimension will be picked. Any entry in the selection but not in these Labels will be ignored.

void save(const std::string &path) const

Serialize and save Labels to the given path.

torch::Tensor save_buffer() const

Serialize and save Labels to an in-memory buffer (represented as a torch::Tensor of bytes)

Public Static Functions

static TorchLabels create(std::vector<std::string> names, const std::vector<std::initializer_list<int32_t>> &values)

Convenience constructor for building LabelsHolder in C++, similar to metatensor::Labels.

static TorchLabels view(const TorchLabels &labels, std::vector<std::string> names)

Get a view of labels corresponding to only the given columns names.

static TorchLabels single()

Create Labels with a single entry, and a single dimension named "_"

static TorchLabels empty(torch::IValue names)

Create Labels with the given dimension names and zero entries.

static TorchLabels range(std::string name, int64_t end)

Create Labels with a single dimension with the given name and values in the [0, stop) range

static TorchLabels load(const std::string &path)

Load serialized Labels from the given path.

static TorchLabels load_buffer(torch::Tensor buffer)

Load serialized Labels from an in-memory buffer (represented as a torch::Tensor of bytes)

using metatensor_torch::TorchLabelsEntry = torch::intrusive_ptr<LabelsEntryHolder>

TorchScript will always manipulate LabelsEntryHolder through a torch::intrusive_ptr

class LabelsEntryHolder : public CustomClassHolder

A single entry inside a TorchLabels

Public Functions

LabelsEntryHolder(TorchLabels labels, int64_t index)

Create a new LabelsEntryHolder corresponding to the entry at the given index in the given labels

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

Get the names of the dimensions/columns of these Labels.

inline torch::Tensor values() const

Get the values of these labels as a torch Tensor.

inline torch::Device device() const

Get the current device for this LabelsEntry

inline int64_t size() const

Get the number of dimensions in this LabelsEntry.

This is the same as values().size(0)

inline int32_t operator[](int64_t index) const

Get the value at index in this LabelsEntry

int32_t operator[](const std::string &name) const

Get the value for the name dimension in this LabelsEntry

int64_t getitem(torch::IValue index) const

implementation of getitem, forwarding to one of the operator[]

std::string print() const

Print this entry as a named tuple (i.e. (key=value, key=value)).

std::string repr() const

Implementation of repr for Python.