Labels

class Labels

A set of labels used to carry metadata associated with a tensor map.

This is similar to an array of named tuples, but stored as a 2D array of shape (count, size), with a set of names associated with the columns of this array (often called dimensions). Each row/entry in this array is unique, and they are often (but not always) sorted in lexicographic order.

Public Functions

inline Labels(const std::vector<std::string> &dimensions, MtsArray values)

Create Labels from the given dimension names and values.

The Labels take ownership of the values.

inline Labels(const std::vector<std::string> &dimensions, std::initializer_list<std::initializer_list<int32_t>> values)

Create a new set of Labels from the given names and values.

Each entry in the values must contain names.size() elements.

auto labels = Labels({"first", "second"}, {
   {0, 1},
   {1, 4},
   {2, 1},
   {2, 3},
});

inline Labels(const std::vector<std::string> &dimensions, MtsArray array, assume_unique)

Create Labels from the given dimension names and a backing mts_array_t, assuming uniqueness of entries (no uniqueness check is performed).

The Labels take ownership of the array.

inline explicit Labels(const std::vector<std::string> &dimensions)

Create an empty set of Labels with the given dimension names.

inline Labels(const std::vector<std::string> &dimensions, const int32_t *values, size_t count)

Create labels with the given dimensions and values. values must be an array with count x dimensions.size() elements.

inline Labels(const std::vector<std::string> &dimensions, const int32_t *values, size_t count, assume_unique)

Unchecked variant, caller promises the labels are unique. Calling with non-unique entries is invalid and can lead to crashes or infinite loops.

inline Labels(const Labels &other)

Labels is copy-constructible.

inline Labels &operator=(const Labels &other)

Labels can be copy-assigned.

inline Labels(Labels &&other) noexcept

Labels is move-constructible.

inline Labels &operator=(Labels &&other) noexcept

Labels can be move-assigned.

inline std::vector<const char*> names() const

Get the names of the dimensions used in these Labels.

inline DLDevice device() const

Get the device of the values for these Labels.

inline size_t count() const

Get the number of entries in this set of Labels.

inline size_t size() const

Get the number of dimensions in this set of Labels.

This is the same as shape()[1] for the corresponding values array

inline const mts_labels_t *as_mts_labels_t() const

Get the underlying mts_labels_t pointer.

inline std::optional<size_t> position(std::initializer_list<int32_t> entry) const

Get the position of the entry in this set of Labels, or std::nullopt if the entry is not part of these Labels.

template<size_t N>
inline std::optional<size_t> position(const std::array<int32_t, N> &entry) const

Variant of Labels::position taking a fixed-size array as input.

inline std::optional<size_t> position(const std::vector<int32_t> &entry) const

Variant of Labels::position taking a vector as input.

inline std::optional<size_t> position(const int32_t *entry, size_t length) const

Variant of Labels::position taking a pointer and length as input.

inline MtsArray mts_array() const

Get the array of values for these Labels as an mts_array_t.

inline DLPackArray<int32_t> values(DLDevice device = {kDLCPU, 0}, const int64_t *stream = nullptr) const

Get the array of values for these Labels as a DLPack array on the requested device.

Parameters:

• device – the DLPack device to request data on (default: CPU)

• stream – pointer to a device stream, or nullptr for default

inline NDArray<int32_t> values_cpu() const

Get the array of values for these Labels on CPU.

This can trigger a copy if the values are not already on CPU, but following calls to this function will then return a view without copying.

inline Labels set_union(const Labels &other, int64_t *first_mapping = nullptr, size_t first_mapping_count = 0, int64_t *second_mapping = nullptr, size_t second_mapping_count = 0) const

Take the union of these Labels with other.

If requested, this function can also give the positions in the union where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the union with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the union, this should be a pointer to an array containing this->count() elements, to be filled by this function. Otherwise it should be a nullptr.

• first_mapping_count – number of elements in first_mapping

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the union, this should be a pointer to an array containing other.count() elements, to be filled by this function. Otherwise it should be a nullptr.

• second_mapping_count – number of elements in second_mapping

inline Labels set_union(const Labels &other, std::vector<size_t> &first_mapping, std::vector<size_t> &second_mapping) const

Take the union of these Labels with other.

If requested, this function can also give the positions in the union where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the union with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the union, this should be a vector containing this->count() elements, to be filled by this function. Otherwise it should be an empty vector.

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the union, this should be a vector containing other.count() elements, to be filled by this function. Otherwise it should be an empty vector.

inline Labels set_intersection(const Labels &other, int64_t *first_mapping = nullptr, size_t first_mapping_count = 0, int64_t *second_mapping = nullptr, size_t second_mapping_count = 0) const

Take the intersection of these Labels with other.

If requested, this function can also give the positions in the intersection where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the intersection with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the intersection, this should be a pointer to an array containing this->count() elements, to be filled by this function. Otherwise it should be a nullptr. If an entry in this is not used in the intersection, the mapping will be set to -1.

• first_mapping_count – number of elements in first_mapping

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the intersection, this should be a pointer to an array containing other.count() elements, to be filled by this function. Otherwise it should be a nullptr. If an entry in other is not used in the intersection, the mapping will be set to -1.

• second_mapping_count – number of elements in second_mapping

inline Labels set_intersection(const Labels &other, std::vector<std::optional<size_t>> &first_mapping, std::vector<std::optional<size_t>> &second_mapping) const

Take the intersection of this Labels with other.

If requested, this function can also give the positions in the intersection where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the intersection with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the intersection, this should be a vector containing this->count() elements, to be filled by this function. Otherwise it should be an empty vector. If an entry in this is not used in the intersection, the mapping will be set to std::nullopt.

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the intersection, this should be a vector containing other.count() elements, to be filled by this function. Otherwise it should be an empty vector. If an entry in other is not used in the intersection, the mapping will be set to std::nullopt.

inline Labels set_difference(const Labels &other, int64_t *first_mapping = nullptr, size_t first_mapping_count = 0) const

Take the difference of these Labels with other.

If requested, this function can also give the positions in the difference where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the difference with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the difference, this should be a pointer to an array containing this->count() elements, to be filled by this function. Otherwise it should be a nullptr. If an entry in this is not used in the difference, the mapping will be set to -1.

• first_mapping_count – number of elements in first_mapping

inline Labels set_difference(const Labels &other, std::vector<std::optional<size_t>> &first_mapping) const

Take the difference of this Labels with other.

If requested, this function can also give the positions in the difference where each entry of the input Labels ended up.

The output data will be on CPU, regardless of the device of the inputs.

Parameters:

• other – the Labels we want to take the difference with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the difference, this should be a vector containing this->count() elements, to be filled by this function. Otherwise it should be an empty vector. If an entry in this is not used in the difference, the mapping will be set to std::nullopt.

inline void select(const Labels &selection, int64_t *selected, size_t *selected_count) 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.

Parameters:

• selection – definition of the selection criteria. Multiple entries are interpreted as a logical or operation.

• selected – on input, a pointer to an array with space for *selected_count entries. On output, the first *selected_count values will contain the index in labels of selected entries.

• selected_count – on input, size of the selected array. On output, this will contain the number of selected entries.

inline std::vector<size_t> select(const Labels &selection) const

Select entries in these Labels that match the selection.

This function does the same thing as the one above, but allocates and return the list of selected indexes in a std::vector

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

Save Labels to the given path.

This is identical to metatensor::io::save(), and provided as a convenience API.

inline std::vector<uint8_t> save_buffer() const

Save Labels to an in-memory buffer.

This is identical to metatensor::io::save_buffer(), and provided as a convenience API.

template<typename Buffer>
inline Buffer save_buffer() const

Save Labels to an in-memory buffer.

This is identical to metatensor::io::save_buffer(), and provided as a convenience API.

Public Static Functions

static inline Labels load(const std::string &path)

Load previously saved Labels from the given path.

This is identical to metatensor::io::load_labels(), and provided as a convenience API.

static inline Labels load_buffer(const uint8_t *buffer, size_t buffer_count)

Load previously saved Labels from a in-memory buffer.

This is identical to metatensor::io::load_labels_buffer(), and provided as a convenience API.

template<typename Buffer>
static inline Labels load_buffer(const Buffer &buffer)

Load previously saved Labels from a in-memory buffer.

This is identical to metatensor::io::load_labels_buffer(), and provided as a convenience API.