TensorBlock

typedef struct mts_block_t mts_block_t

Basic building block for tensor map. A single block contains a n-dimensional mts_array_t, and n sets of mts_labels_t (one for each dimension).

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 sample and component labels but share the property labels with the values.

The following functions operate on mts_block_t:

struct mts_block_t *mts_block(struct mts_array_t data, struct mts_labels_t samples, const struct mts_labels_t *components, uintptr_t components_count, struct mts_labels_t properties)

Create a new mts_block_t with the given data and samples, components and properties labels.

The memory allocated by this function and the blocks should be released using mts_block_free, or moved into a tensor map using mts_tensormap.

Parameters:

  • data – array handle containing the data for this block. The block takes ownership of the array, and will release it with array.destroy(array.ptr) when it no longer needs it.

  • samples – sample labels corresponding to the first dimension of the data

  • components – array of component labels corresponding to intermediary dimensions of the data

  • components_count – number of entries in the components array

  • properties – property labels corresponding to the last dimension of the data

Returns:

A pointer to the newly allocated block, or a NULL pointer in case of error. In case of error, you can use mts_last_error() to get the error message.

struct mts_block_t *mts_block_copy(const struct mts_block_t *block)

Make a copy of an mts_block_t.

The memory allocated by this function and the blocks should be released using mts_block_free, or moved into a tensor map using mts_tensormap.

Parameters:

  • block – existing block to copy

Returns:

A pointer to the newly allocated block, or a NULL pointer in case of error. In case of error, you can use mts_last_error() to get the error message.

mts_status_t mts_block_free(struct mts_block_t *block)

Free the memory associated with a block previously created with mts_block.

If block is NULL, this function does nothing.

Parameters:

  • block – pointer to an existing block, or NULL

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_block_labels(const struct mts_block_t *block, uintptr_t axis, struct mts_labels_t *labels)

Get the set of labels from this block.

This function allocates memory for labels which must be released mts_labels_free when you don’t need it anymore.

Parameters:

  • block – pointer to an existing block

  • axis – axis/dimension of the data array for which you need the labels

  • labels – pointer to an empty mts_labels_t that will be set to the block’s labels

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_block_data(struct mts_block_t *block, struct mts_array_t *data)

Get the array handle for the values in this block.

Parameters:

  • block – pointer to an existing block

  • data – pointer to an empty mts_array_t that will be set to the requested array

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_block_gradient(struct mts_block_t *block, const char *parameter, struct mts_block_t **gradient)

Get one of the gradients in this block.

The gradient memory is still managed by the block, the returned mts_block_t* should not be freed. The gradient pointer is invalidated if more gradients are added to the parent block, or if the parent block is freed with mts_block_free.

Parameters:

  • block – pointer to an existing block

  • parameter – the name of the gradient to be extracted

  • gradient – pointer to an empty mts_block_t pointer that will be overwritten to the requested gradient

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_block_add_gradient(struct mts_block_t *block, const char *parameter, struct mts_block_t *gradient)

Add a new gradient to this block with the given name.

The block takes ownership of the gradient, which should not be released separately.

Parameters:

  • block – pointer to an existing block

  • parameter – name of the gradient as a NULL-terminated UTF-8 string. This is usually the parameter used when taking derivatives (e.g. "positions", "cell", etc.)

  • gradient – a block whose values contain the gradients with respect to the parameter. The labels of the gradient should be organized as follows: its samples must contain "sample" as the first label, which establishes a correspondence with the samples of the original block; 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 block.

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_block_gradients_list(const struct mts_block_t *block, const char *const **parameters, uintptr_t *parameters_count)

Get a list of all gradients defined in this block in the parameters array.

Parameters:

  • block – pointer to an existing block

  • parameters – will be set to the first element of an array of NULL-terminated UTF-8 strings containing all the parameters for which a gradient exists in the block

  • parameters_count – will be set to the number of elements in parameters

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.