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, 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 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) 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 zeros.

virtual double *data() & = 0

Get a pointer to the underlying data storage.

This function is allowed to fail if the data is not accessible in RAM, not stored as 64-bit floating point values, or not stored as a C-contiguous array.

virtual const std::vector<uintptr_t> &shape() const & = 0

Get the shape of this array.

virtual void reshape(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_samples_from(const DataArrayBase &input, std::vector<mts_sample_mapping_t> samples, uintptr_t property_start, uintptr_t property_end) = 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 samples indicate where the data should be moved from input to the current DataArrayBase.

This function should copy data from input[samples[i].input, ..., :] to array[samples[i].output, ..., property_start:property_end] for i up to samples_count. All indexes are 0-based.

Public Static Functions

static inline mts_array_t to_mts_array_t(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 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, double value = 0.0)

Create a SimpleDataArray with the given shape, and all elements set to value

inline SimpleDataArray(std::vector<uintptr_t> shape, std::vector<double> 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<double> view() const

Get a const view of the data managed by this SimpleDataArray.

inline NDArray<double> view()

Get a mutable view of the data managed by this SimpleDataArray.

Public Static Functions

static inline SimpleDataArray &from_mts_array(mts_array_t &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 mts_array_t &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.