TensorMap

class TensorMap

A TensorMap is the main user-facing class of this library, and can store any kind of data used in atomistic machine learning.

A tensor map contains a list of TensorBlock, each one associated with a key. Users can access the blocks either one by one with the block_by_id() function.

A tensor map provides functions to move some of these keys to the samples or properties labels of the blocks, moving from a sparse representation of the data to a dense one.

Public Functions

inline TensorMap(Labels keys, std::vector<TensorBlock> blocks)

Create a new TensorMap with the given keys and blocks

TensorMap(const TensorMap&) = delete

TensorMap can NOT be copy constructed, use TensorMap::clone instead.

TensorMap &operator=(const TensorMap&) = delete

TensorMap can not be copy assigned, use TensorMap::clone instead.

inline TensorMap(TensorMap &&other) noexcept

TensorMap can be move constructed.

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

TensorMap can be move assigned.

inline TensorMap clone() const

Make a copy of this TensorMap, including all the data contained inside.

inline TensorMap clone_metadata_only() const

Get a copy of the metadata in this TensorMap (i.e. keys, samples, components, and properties), ignoring the data itself.

The resulting blocks values will be an EmptyDataArray instance, which does not contain any data.

inline Labels keys() const

Get the set of keys labeling the blocks in this tensor map.

inline std::vector<uintptr_t> blocks_matching(const Labels &selection) const

Get a (possibly empty) list of block indexes matching the selection

inline TensorBlock block_by_id(uintptr_t index) &

Get a block inside this TensorMap by it’s index/the index of the corresponding key.

The returned TensorBlock is a view inside memory owned by this TensorMap, and is only valid as long as the TensorMap is kept alive.

inline TensorMap keys_to_properties(const Labels &keys_to_move, bool sort_samples = true) const

Merge blocks with the same value for selected keys dimensions along the property axis.

The dimensions (names) of keys_to_move will be moved from the keys to the property labels, and blocks with the same remaining keys dimensions will be merged together along the property axis.

If keys_to_move does not contains any entries (i.e. keys_to_move.count() == 0), then the new property labels will contain entries corresponding to the merged blocks only. For example, merging a block with key a=0 and properties p=1, 2 with a block with key a=2 and properties p=1, 3 will produce a block with properties a, p = (0, 1), (0, 2), (2, 1), (2, 3).

If keys_to_move contains entries, then the property labels must be the same for all the merged blocks. In that case, the merged property labels will contains each of the entries of keys_to_move and then the current property labels. For example, using a=2, 3 in keys_to_move, and blocks with properties p=1, 2 will result in a, p = (2, 1), (2, 2), (3, 1), (3, 2).

The new sample labels will contains all of the merged blocks sample labels. The order of the samples is controlled by sort_samples. If sort_samples is true, samples are re-ordered to keep them lexicographically sorted. Otherwise they are kept in the order in which they appear in the blocks.

Parameters:

• keys_to_move – description of the keys to move

• sort_samples – whether to sort the merged samples or keep them in the order in which they appear in the original blocks

inline TensorMap keys_to_properties(const std::vector<std::string> &keys_to_move, bool sort_samples = true) const

This function calls keys_to_properties with an empty set of Labels with the dimensions defined in keys_to_move

inline TensorMap keys_to_properties(const std::string &key_to_move, bool sort_samples = true) const

This function calls keys_to_properties with an empty set of Labels with a single dimension: key_to_move

inline TensorMap keys_to_samples(const Labels &keys_to_move, bool sort_samples = true) const

Merge blocks with the same value for selected keys dimensions along the samples axis.

The dimensions (names) of keys_to_move will be moved from the keys to the sample labels, and blocks with the same remaining keys dimensions will be merged together along the sample axis.

If keys_to_move must be an empty set of Labels (keys_to_move.count() == 0). The new sample labels will contain entries corresponding to the merged blocks’ keys.

The order of the samples is controlled by sort_samples. If sort_samples is true, samples are re-ordered to keep them lexicographically sorted. Otherwise they are kept in the order in which they appear in the blocks.

This function is only implemented if all merged block have the same property labels.

Parameters:

• keys_to_move – description of the keys to move

• sort_samples – whether to sort the merged samples or keep them in the order in which they appear in the original blocks

inline TensorMap keys_to_samples(const std::vector<std::string> &keys_to_move, bool sort_samples = true) const

This function calls keys_to_samples with an empty set of Labels with the dimensions defined in keys_to_move

inline TensorMap keys_to_samples(const std::string &key_to_move, bool sort_samples = true) const

This function calls keys_to_samples with an empty set of Labels with a single dimension: key_to_move

inline TensorMap components_to_properties(const std::vector<std::string> &dimensions) const

Move the given dimensions from the component labels to the property labels for each block.

Parameters:

dimensions – name of the component dimensions to move to the properties

inline TensorMap components_to_properties(const std::string &dimension) const

Call components_to_properties with a single dimension.

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

Save a TensorMap 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 a TensorMap 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 a TensorMap to an in-memory buffer.

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

inline mts_tensormap_t *as_mts_tensormap_t() &

Get the mts_tensormap_t pointer corresponding to this TensorMap.

The tensor map pointer is still managed by the current TensorMap

inline const mts_tensormap_t *as_mts_tensormap_t() const &

Get the const mts_tensormap_t pointer corresponding to this TensorMap.

The tensor map pointer is still managed by the current TensorMap

inline explicit TensorMap(mts_tensormap_t *tensor)

Create a C++ TensorMap from a C mts_tensormap_t pointer. The C++ tensor map takes ownership of the C pointer.

Public Static Functions

static inline TensorMap load(const std::string &path, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from the given path.

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

static inline TensorMap load_buffer(const uint8_t *buffer, size_t buffer_count, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from a in-memory buffer.

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

template<typename Buffer>
static inline TensorMap load_buffer(const Buffer &buffer, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from a in-memory buffer.

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