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(const 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 and keys, which should not be released separately.

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

Parameters:

  • keys – pointer to labels containing the keys associated with each block. The new tensor map will increase the reference count of these labels

  • blocks – pointer to the first element of an array of blocks. The tensor map takes ownership of the 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.

const struct mts_labels_t *mts_tensormap_keys(const struct mts_tensormap_t *tensor)

Get the keys for the given tensor map.

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

Parameters:

  • tensor – pointer to an existing tensor map

Returns:

A pointer to the newly allocated labels containing the keys, 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_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.

struct mts_tensormap_t *mts_tensormap_keys_to_samples(const struct mts_tensormap_t *tensor, const struct mts_labels_t *keys_to_move, struct mts_array_t fill_value, 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

  • fill_value – an mts_array_t containing a single scalar of the same dtype as the data, used to fill missing entries when merging blocks. This function takes ownership of fill_value, and will free it when it’s not needed anymore.

  • 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, const struct mts_labels_t *keys_to_move, struct mts_array_t fill_value, 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

  • fill_value – an mts_array_t containing a single scalar of the same dtype as the data, used to fill missing entries when merging blocks. This function takes ownership of fill_value, and will free it when it’s not needed anymore.

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

mts_status_t mts_tensormap_set_info(struct mts_tensormap_t *tensor, const char *key, const char *value)

Set or update the info (i.e. global metadata) for key to value for this tensor map.

Parameters:

  • tensor – pointer to an existing tensor map

  • key – string key of the entry we are trying to set

  • value – content of the info field

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_get_info(const struct mts_tensormap_t *tensor, const char *key, const char **value)

Get the info (i.e. global metadata) value associated with key for this tensor map.

Parameters:

  • tensor – pointer to an existing tensor map

  • key – string key of the entry we are trying to access

  • value – will be set to content of the info field, or NULL if the key does not exist.

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_info_keys(const struct mts_tensormap_t *tensor, const char *const **keys, uintptr_t *keys_count)

Get the list of currently set info keys for this tensor map.

Parameters:

  • tensor – pointer to an existing tensor map

  • keys – will be set to point to an array of C strings

  • keys_count – the number of entries in the keys 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_tensormap_device(const struct mts_tensormap_t *tensor, DLDevice *device)

Get the device of this tensor map.

For an empty tensor map, the device is set to CPU.

Parameters:

  • tensor – pointer to an existing tensor map

  • device – pointer to a DLDevice that will be set to the tensor’s device

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_dtype(const struct mts_tensormap_t *tensor, DLDataType *dtype)

Get the data type of this tensor map.

For an empty tensor map (no blocks), the dtype is set to float64.

Parameters:

  • tensor – pointer to an existing tensor map

  • dtype – pointer to a DLDataType that will be set to the tensor’s dtype

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.