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.

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.