TensorMap

typedef struct mts_tensormap_t mts_tensormap_t

Opaque type representing a TensorMap.

The following functions operate on mts_tensormap_t:

struct mts_tensormap_t *mts_tensormap(struct mts_labels_t keys, struct mts_block_t **blocks, uintptr_t blocks_count)

Create a new mts_tensormap_t with the given keys and blocks. blocks_count must be set to the number of entries in the blocks array.

The new tensor map takes ownership of the blocks, which should not be released separately.

The memory allocated by this function and the blocks should be released using mts_tensormap_free.

Parameters:

  • keys – labels containing the keys associated with each block

  • blocks – pointer to the first element of an array of blocks

  • blocks_count – number of elements in the blocks array

Returns:

A pointer to the newly allocated tensor map, 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_tensormap_t *mts_tensormap_copy(const struct mts_tensormap_t *tensor)

Make a copy of an mts_tensormap_t.

The memory allocated by this function and the blocks should be released using mts_tensormap_free.

Parameters:

  • tensor – existing tensor to copy

Returns:

A pointer to the newly allocated tensor, 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_tensormap_free(struct mts_tensormap_t *tensor)

Free the memory associated with a tensor previously created with mts_tensormap.

If tensor is NULL, this function does nothing.

Parameters:

  • tensor – pointer to an existing tensor map, 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_tensormap_keys(const struct mts_tensormap_t *tensor, struct mts_labels_t *keys)

Get the keys for the given tensor map.

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

Parameters:

  • tensor – pointer to an existing tensor map

  • keys – pointer to be filled with the keys of the tensor map

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_tensormap_block_by_id(struct mts_tensormap_t *tensor, struct mts_block_t **block, uintptr_t index)

Get a pointer to the index-th block in this tensor map.

The block memory is still managed by the tensor map, this block should not be freed. The block is invalidated when the tensor map is freed with mts_tensormap_free or the set of keys is modified by calling one of the mts_tensormap_keys_to_XXX function.

Parameters:

  • tensor – pointer to an existing tensor map

  • block – pointer to be filled with a block

  • index – index of the block to get

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_tensormap_blocks_matching(const struct mts_tensormap_t *tensor, uintptr_t *block_indexes, uintptr_t *count, struct mts_labels_t selection)

Get indices of the blocks in this tensor corresponding to the given selection. The selection should have a subset of the names/dimensions of the keys for this tensor map, and only one entry, describing the requested blocks.

When calling this function, *count should contain the number of entries in block_indexes. When the function returns successfully, *count will contain the number of blocks matching the selection, i.e. how many values were written to block_indexes.

Parameters:

  • tensor – pointer to an existing tensor map

  • block_indexes – array to be filled with indexes of blocks in the tensor map matching the selection

  • count – number of entries in block_indexes

  • selection – labels with a single entry describing which blocks are requested

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.

struct mts_tensormap_t *mts_tensormap_keys_to_samples(const struct mts_tensormap_t *tensor, struct mts_labels_t keys_to_move, bool sort_samples)

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.

keys_to_move must be empty (keys_to_move.count == 0), and the new sample labels will contain entries corresponding to the merged blocks’ keys.

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.

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

Parameters:

  • tensor – pointer to an existing tensor map

  • keys_to_move – description of the keys to move

  • sort_samples – whether to sort the samples lexicographically after merging blocks or not

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.

struct mts_tensormap_t *mts_tensormap_keys_to_properties(const struct mts_tensormap_t *tensor, struct mts_labels_t keys_to_move, bool sort_samples)

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

The result is a new tensor map, which should be freed with mts_tensormap_free.

Parameters:

  • tensor – pointer to an existing tensor map

  • keys_to_move – description of the keys to move

  • sort_samples – whether to sort the samples lexicographically after merging blocks

Returns:

A pointer to the newly allocated tensor map, 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_tensormap_t *mts_tensormap_components_to_properties(struct mts_tensormap_t *tensor, const char *const *dimensions, uintptr_t dimensions_count)

Move the given dimensions from the component labels to the property labels for each block in this tensor map.

dimensions must be an array of dimensions_count NULL-terminated strings, encoded as UTF-8.

Parameters:

  • tensor – pointer to an existing tensor map

  • dimensions – names of the key dimensions to move to the properties

  • dimensions_count – number of entries in the dimensions 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.