Data arrays

This part of metatensor contains advanced functionalities related to how data is stored inside metatensor.TensorBlock. Most users should not have to interact with this!

class metatensor.data.Array

An Array contains the actual data stored in a metatensor.TensorBlock.

This data is manipulated by metatensor in a completely opaque way: this library does not know what’s inside the arrays appart from a small set of constrains:

  • the array contains numeric data (metatensor.load() and metatensor.save() additionally requires contiguous arrays of 64-bit IEEE-754 floating points numbers);

  • they are stored as row-major, n-dimensional arrays with at least 2 dimensions;

  • it is possible to create new arrays and move data from one array to another.

The actual type of an Array depends on how the metatensor.TensorBlock was created. Currently, numpy.ndarray and torch.Tensor are supported.

alias of Union[ndarray, Tensor]

metatensor.data.register_external_data_wrapper(origin, klass)[source]

Register a non-Python data origin and the corresponding class wrapper.

The wrapper class constructor must take two arguments (raw mts_array and python parent object) and return a subclass of either numpy.ndarray or torch.Tensor, which keeps parent alive. The metatensor.data.ExternalCpuArray class should provide the right behavior for data living in CPU memory, and can serve as an example for more advanced custom arrays.

Parameters:

  • origin – data origin name as a string, corresponding to the output of mts_array_t.origin()

  • klass – wrapper class to use for this origin

class metatensor.data.ExternalCpuArray(mts_array: mts_array_t, parent: Any)[source]

Small wrapper class around np.ndarray, adding a reference to a parent Python object that actually owns the memory used inside the array. This prevents the parent from being garbage collected while the ndarray is still alive, thus preventing use-after-free.

This is intended to be used to wrap Rust-owned memory inside a numpy’s ndarray, while making sure the memory owner is kept around for long enough.

Parameters:

  • mts_array (mts_array_t) – raw array to wrap in a Python-compatible class

  • parent (Any) – owner of the raw array, we will keep a reference to this python object