Data arrays¶

class DataArrayBase¶

DataArrayBase manages n-dimensional arrays used as data in a block or tensor map. The array itself if opaque to this library and can come from multiple sources: Rust program, a C/C++ program, a Fortran program, Python with numpy or torch. The data does not have to live on CPU, or even on the same machine where this code is executed.

WARNING: all function implementations MUST be thread-safe, and can be called from multiple threads at the same time. The DataArrayBase itself might be moved from one thread to another.

Subclassed by metatensor::EmptyDataArray, metatensor::SimpleDataArray< T, typename >, metatensor_torch::TorchDataArray

Public Functions

DataArrayBase(const DataArrayBase&) = default¶: DataArrayBase can be copy-constructed.

DataArrayBase &operator=(const DataArrayBase&) = default¶: DataArrayBase can be copy-assigned.

DataArrayBase(DataArrayBase&&) noexcept = default¶: DataArrayBase can be move-constructed.

DataArrayBase &operator=(DataArrayBase&&) noexcept = default¶: DataArrayBase can be move-assigned.

virtual mts_data_origin_t origin() const = 0¶

Get “data origin” for this array in.

Users of DataArrayBase should register a single data origin with mts_register_data_origin, and use it for all compatible arrays.

virtual DLDevice device() const = 0¶: Get the device where this array’s data resides.

virtual DLDataType dtype() const = 0¶: Get the data type of this array.

virtual DLManagedTensorVersioned *as_dlpack(DLDevice device, const int64_t *stream, DLPackVersion max_version) = 0¶

Get a DLPack representation of this array

The returned pointer is owned by the caller and should be freed using its deleter function when no longer needed.

See the documentation of mts_array_t::as_dlpack for more details about the parameters.

virtual std::unique_ptr<DataArrayBase> copy() const = 0¶: Make a copy of this DataArrayBase and return the new array. The new array is expected to have the same data origin and parameters (data type, data location, etc.)

virtual std::unique_ptr<DataArrayBase> create(std::vector<uintptr_t> shape, MtsArray fill_value) const = 0¶

Create a new array with the same options as the current one (data type, data location, etc.) and the requested shape.

The new array should be filled with the scalar value from fill_value, which must be an MtsArray containing a single element with the same dtype as this array.

virtual const std::vector<uintptr_t> &shape() const & = 0¶: Get the shape of this array.

virtual void reshape(const std::vector<uintptr_t> &shape) = 0¶: Set the shape of this array to the given shape

virtual void swap_axes(uintptr_t axis_1, uintptr_t axis_2) = 0¶: Swap the axes axis_1 and axis_2 in this array.

virtual void move_data(const DataArrayBase &input, std::vector<mts_data_movement_t> moves) = 0¶

Set entries in the current array taking data from the input array.

This array is guaranteed to be created by calling mts_array_t::create with one of the arrays in the same block or tensor map as the input.

The moves indicate where the data should be moved from input to the current DataArrayBase.

This function should copy data from input[move.sample_in, ..., move.properties_start_in + i] to array[move.sample_out, ..., move.properties_start_out + i] for each move in moves and i up to move.properties_length. All indexes are 0-based.

Public Static Functions

static inline MtsArray to_mts_array(std::unique_ptr<DataArrayBase> data)¶

Convert a concrete DataArrayBase to a C-compatible mts_array_t

The mts_array_t takes ownership of the data, which should be released with mts_array_t::destroy.

class MtsArray¶

RAII wrapper around mts_array_t that takes ownership of the underlying data and calls the appropriate destroy function when it goes out of scope.

This class also provides some convenience functions to call the function pointers in mts_array_t.

Public Functions

inline explicit MtsArray(mts_array_t array)¶: Create an MtsArray that takes ownership of the given mts_array_t.

inline MtsArray(const MtsArray &other)¶: MtsArray is copy-constructible.

inline MtsArray &operator=(const MtsArray &other)¶: MtsArray can be copy-assigned.

inline MtsArray(MtsArray &&other) noexcept¶: MtsArray is move-constructible.

inline MtsArray &operator=(MtsArray &&other) noexcept¶: MtsArray can be move-assigned.

inline mts_array_t release() &&¶: Release ownership of the mts_array_t and return it. After this call, the MtsArray is empty and does not own any data.

inline mts_array_t as_mts_array_t() const¶: Get a non-owning view of this MtsArray as an mts_array_t.

inline mts_data_origin_t origin() const¶: Get the data origin for this array.

inline DLDevice device() const¶: Get the device where this array’s data resides.

inline DLDataType dtype() const¶: Get the data type of this array.

inline DLManagedTensorVersioned *as_dlpack(DLDevice device, const int64_t *stream, DLPackVersion max_version)¶

Get a DLPack representation of this array

The returned pointer is owned by the caller and should be freed using its deleter function when no longer needed.

See the documentation of mts_array_t::as_dlpack for more details about the parameters.

template<typename T> inline DLPackArray<T> as_dlpack_array(DLDevice device, const int64_t *stream, DLPackVersion max_version)¶

Get a DLPackArray corresponding to this array

See the documentation of mts_array_t::as_dlpack for more details about the parameters.

inline MtsArray create(const std::vector<uintptr_t> &shape, MtsArray fill_value) const¶

Create a new array with the same options as the current one (data type, data location, etc.) and the requested shape.

The new array should be filled with the scalar value from fill_value, which must be an mts_array_t with shape (1,) and the same dtype as this array. This function should call fill_value.destroy if the function pointer is not null when fill_value is no longer needed.

inline std::vector<uintptr_t> shape() const¶: Get the shape of this array.

inline void reshape(const std::vector<uintptr_t> &shape)¶: Set the shape of this array to the given shape

inline void swap_axes(uintptr_t axis_1, uintptr_t axis_2)¶: Swap the axes axis_1 and axis_2 in this array.

inline void move_data(const MtsArray &input, std::vector<mts_data_movement_t> moves)¶

Set entries in the current array taking data from the input array.

This array is guaranteed to be created by calling mts_array_t::create with one of the arrays in the same block or tensor map as the input.

The moves indicate where the data should be moved from input to the current DataArrayBase.

This function copy data from input[move.sample_in, ..., move.properties_start_in + i] to array[move.sample_out, ..., move.properties_start_out + i] for each move in moves and i up to move.properties_length. All indexes are 0-based.

template<typename T, typename = std::enable_if_t<std::is_arithmetic_v<T>>> class SimpleDataArray : public metatensor::DataArrayBase ¶

Very basic implementation of DataArrayBase in C++.

This is included as an example implementation of DataArrayBase, and to make metatensor usable without additional dependencies. For other uses cases, it might be better to implement DataArrayBase on your data, using functionalities from Eigen, Boost.Array, etc.

Public Functions

inline SimpleDataArray(std::vector<uintptr_t> shape, T value = T{})¶: Create a SimpleDataArray with the given shape, and all elements set to value

inline SimpleDataArray(std::vector<uintptr_t> shape, std::vector<T> data)¶

Create a SimpleDataArray with the given shape and data.

The data is interpreted as a row-major n-dimensional array.

SimpleDataArray(const SimpleDataArray&) = default¶: SimpleDataArray can be copy-constructed.

SimpleDataArray &operator=(const SimpleDataArray&) = default¶: SimpleDataArray can be copy-assigned.

SimpleDataArray(SimpleDataArray&&) noexcept = default¶: SimpleDataArray can be move-constructed.

SimpleDataArray &operator=(SimpleDataArray&&) noexcept = default¶: SimpleDataArray can be move-assigned.

inline NDArray<T> view() const¶: Get a const view of the data managed by this SimpleDataArray.

inline NDArray<T> view()¶: Get a mutable view of the data managed by this SimpleDataArray.

Public Static Functions

static inline SimpleDataArray &from_mts_array(MtsArray &array)¶

Extract a reference to SimpleDataArray out of an mts_array_t.

This function fails if the mts_array_t does not contain a SimpleDataArray.

static inline const SimpleDataArray &from_mts_array(const MtsArray &array)¶

Extract a const reference to SimpleDataArray out of an mts_array_t.

This function fails if the mts_array_t does not contain a SimpleDataArray.

class EmptyDataArray : public metatensor::DataArrayBase ¶

An implementation of DataArrayBase containing no data.

This class only tracks it’s shape, and can be used when only the metadata of a TensorBlock is important, leaving the data unspecified.

Public Functions

inline EmptyDataArray(std::vector<uintptr_t> shape)¶: Create ae EmptyDataArray with the given shape

EmptyDataArray(const EmptyDataArray&) = default¶: EmptyDataArray can be copy-constructed.

EmptyDataArray &operator=(const EmptyDataArray&) = default¶: EmptyDataArray can be copy-assigned.

EmptyDataArray(EmptyDataArray&&) noexcept = default¶: EmptyDataArray can be move-constructed.

EmptyDataArray &operator=(EmptyDataArray&&) noexcept = default¶: EmptyDataArray can be move-assigned.