TensorBlock

class TensorBlock

Basic building block for a tensor map.

A single block contains a n-dimensional mts_array_t (or DataArrayBase), and n sets of Labels (one for each dimension). The first dimension is the samples dimension, the last dimension is the properties dimension. Any intermediate dimension is called a component dimension.

Samples should be used to describe what we are representing, while properties should contain information about how we are representing it. Finally, components should be used to describe vectorial or tensorial components of the data.

A block can also contain gradients of the values with respect to a variety of parameters. In this case, each gradient has a separate set of samples, and possibly components but share the same property labels as the values.

Public Functions

inline TensorBlock(std::unique_ptr<DataArrayBase> values, const Labels &samples, const std::vector<Labels> &components, const Labels &properties)

Create a new TensorBlock containing the given values array.

The different dimensions of the values are described by samples, components and properties Labels

TensorBlock(const TensorBlock&) = delete

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

TensorBlock &operator=(const TensorBlock &other) = delete

TensorBlock can NOT be copy assigned, use TensorBlock::clone instead.

inline TensorBlock(TensorBlock &&other) noexcept

TensorBlock can be move constructed.

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

TensorBlock can be moved assigned.

inline TensorBlock clone() const

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

inline TensorBlock clone_metadata_only() const

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

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

inline NDArray<double> values() &

Get a view in the values in this block.

inline Labels samples() const

Access the sample Labels for this block.

The entries in these labels describe the first dimension of the values() array.

inline std::vector<Labels> components() const

Access the component Labels for this block.

The entries in these labels describe intermediate dimensions of the values() array.

inline Labels properties() const

Access the property Labels for this block.

The entries in these labels describe the last dimension of the values() array. The properties are guaranteed to be the same for a block and all of its gradients.

inline void add_gradient(const std::string &parameter, TensorBlock gradient)

Add a set of gradients with respect to parameters in this block.

Parameters:

• parameter – add gradients with respect to this parameter (e.g. "positions", "cell", …)

• gradient – a TensorBlock whose values contain the gradients with respect to the parameter. The labels of the gradient TensorBlock should be organized as follows: its samples must contain "sample" as the first label, which establishes a correspondence with the samples of the original TensorBlock; its components must contain at least the same components as the original TensorBlock, with any additional component coming before those; its properties must match those of the original TensorBlock.

inline std::vector<std::string> gradients_list() const

Get a list of all gradients defined in this block.

inline TensorBlock gradient(const std::string &parameter) const

Get the gradient in this block with respect to the given parameter. The gradient is returned as a TensorBlock itself.

Parameters:

parameter – check for gradients with respect to this parameter (e.g. "positions", "cell", …)

inline mts_block_t *as_mts_block_t() &

Get the mts_block_t pointer corresponding to this block.

The block pointer is still managed by the current TensorBlock

inline const mts_block_t *as_mts_block_t() const &

const version of as_mts_block_t

inline mts_array_t mts_array()

Get a raw mts_array_t corresponding to the values in this block.

inline Labels labels(uintptr_t axis) const

Get the labels in this block associated with the given axis.

inline std::vector<uintptr_t> values_shape() const

Get the shape of the value array for this block.

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

Save this TensorBlock 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 this TensorBlock 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 this TensorBlock to an in-memory buffer.

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

Public Static Functions

static inline TensorBlock unsafe_from_ptr(mts_block_t *ptr)

Create a new TensorBlock taking ownership of a raw mts_block_t pointer.

static inline TensorBlock unsafe_view_from_ptr(mts_block_t *ptr)

Create a new TensorBlock which is a view corresponding to a raw mts_block_t pointer.

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

Load a previously saved TensorBlock from the given path.

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

static inline TensorBlock 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 TensorBlock from a in-memory buffer.

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

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

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

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