Miscelaneous#

Error handling#

const char *mts_last_error(void)#

Get the last error message that was created on the current thread.

Returns:

the last error message, as a NULL-terminated string

typedef int32_t mts_status_t#

Status type returned by all functions in the C API.

The value 0 (MTS_SUCCESS) is used to indicate successful operations, positive values are used by this library to indicate errors, while negative values are reserved for users of this library to indicate their own errors in callbacks.

MTS_SUCCESS#

Status code used when a function succeeded

MTS_INVALID_PARAMETER_ERROR#

Status code used when a function got an invalid parameter

MTS_BUFFER_SIZE_ERROR#

Status code used when a memory buffer is too small to fit the requested data

MTS_INTERNAL_ERROR#

Status code used when there was an internal error, i.e. there is a bug inside metatensor itself

Serialization#

struct mts_tensormap_t *mts_tensormap_load(const char *path, mts_create_array_callback_t create_array)#

Load a tensor map from the file at the given path.

Arrays for the values and gradient data will be created with the given create_array callback, and filled by this function with the corresponding data.

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

TensorMap are serialized using numpy’s .npz format, i.e. a ZIP file without compression (storage method is STORED), where each file is stored as a .npy array. Both the ZIP and NPY format are well documented:

We add other restriction on top of these formats when saving/loading data. First, Labels instances are saved as structured array, see the labels module for more information. Only 32-bit integers are supported for Labels, and only 64-bit floats are supported for data (values and gradients).

Second, the path of the files in the archive also carry meaning. The keys of the TensorMap are stored in /keys.npy, and then different blocks are stored as

/  blocks / <block_id>  / values / samples.npy
                        / values / components  / 0.npy
                                               / <...>.npy
                                               / <n_components>.npy
                        / values / properties.npy
                        / values / data.npy

                        # optional sections for gradients, one by parameter
                        /   gradients / <parameter> / samples.npy
                                                    /   components  / 0.npy
                                                                    / <...>.npy
                                                                    / <n_components>.npy
                                                    /   data.npy
Parameters:

  • path – path to the file as a NULL-terminated UTF-8 string

  • create_array – callback function that will be used to create data arrays inside each block

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.

mts_status_t mts_tensormap_save(const char *path, const struct mts_tensormap_t *tensor)#

Save a tensor map to the file at the given path.

If the file already exists, it is overwritten.

Parameters:

  • path – path to the file as a NULL-terminated UTF-8 string

  • tensor – tensor map to save to the file

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_load_buffer(const uint8_t *buffer, uintptr_t buffer_count, mts_create_array_callback_t create_array)#

Load a tensor map from the given in-memory buffer.

Arrays for the values and gradient data will be created with the given create_array callback, and filled by this function with the corresponding data.

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

Parameters:

  • buffer – buffer containing a previously serialized mts_tensormap_t

  • buffer_count – number of elements in the buffer

  • create_array – callback function that will be used to create data arrays inside each block

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.

mts_status_t mts_tensormap_save_buffer(uint8_t **buffer, uintptr_t *buffer_count, void *realloc_user_data, uint8_t *(*realloc)(void *user_data, uint8_t *ptr, uintptr_t new_size), const struct mts_tensormap_t *tensor)#

Save a tensor map to an in-memory buffer.

The realloc callback should take an existing pointer and a new length, and grow the allocation. If the pointer is NULL, it should create a new allocation. If it is unable to allocate memory, it should return a NULL pointer. This follows the API of the standard C function realloc, with an additional parameter user_data that can be used to hold custom data.

On input, *buffer should contain the address of a starting buffer (which can be NULL) and *buffer_count should contain the size of the allocation.

On output, *buffer will contain the serialized data, and *buffer_count the total number of written bytes (which might be less than the allocation size).

Users of this function are responsible for freeing the *buffer when they are done with it, using the function matching the realloc callback.

Parameters:

  • buffer – pointer to the buffer the tensor will be stored to, which can change due to reallocations.

  • buffer_count – pointer to the buffer size on input, number of written bytes on output

  • realloc_user_data – Custom data for the realloc callback. This will be passed as the first argument to realloc as-is.

  • realloc – function that allows to grow the buffer allocation

  • tensor – tensor map that will saved to the buffer

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.

typedef mts_status_t (*mts_create_array_callback_t)(const uintptr_t *shape, uintptr_t shape_count, struct mts_array_t *array)#

Function pointer to create a new mts_array_t when de-serializing tensor maps.

This function gets the shape of the array (the shape contains shape_count elements) and should fill array with a new valid mts_array_t or return non-zero mts_status_t.

The newly created array should contains 64-bit floating points (double) data, and live on CPU, since metatensor will use mts_array_t.data to get the data pointer and write to it.