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

TorchLabels to(torch::IValue 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.

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

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