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.

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.