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

create_array will be used to create new arrays when constructing the blocks and gradients, the default version will create data using SimpleDataArray. See mts_create_array_callback_t() for more information.

TensorMap are serialized using numpy’s .npz format, i.e. a ZIP file without compression (storage method is STORED), where each file is stored as a .npy array. See the C API documentation for more information on the format.

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 the given buffer, containing buffer_count elements.

static inline TensorMap load_buffer(const std::string &buffer, mts_create_array_callback_t create_array = details::default_create_array)#

Load a previously saved TensorMap from the given buffer

static inline TensorMap load_buffer(const std::vector<uint8_t> &buffer, mts_create_array_callback_t create_array = details::default_create_array)#

Load a previously saved TensorMap from the given buffer

static inline void save(const std::string &path, const TensorMap &tensor)#

Save the given TensorMap to a file at path.

static inline std::vector<uint8_t> save_buffer(const TensorMap &tensor)#: Save a tensor map to an in-memory buffer.

static inline std::string save_string_buffer(const TensorMap &tensor)#: Similar to TensorMap::save_buffer, but return the result as a std::string.