Miscellaneous

Version number

The same functions and macros as the C API are available in C++.

Error handling

class Error : public runtime_error

Exception class used for all errors in metatensor.

Public Functions

inline Error(const std::string &message)

Create a new Error with the given message

N-dimensional arrays

template<typename T>
class NDArray

Simple N-dimensional array interface

This class can either be a non-owning view inside some existing memory (for example memory allocated by Rust); or own its memory (in the form of an std::vector<double>). If the array does not own its memory, accessing it is only valid for as long as the memory is kept alive.

The API of this class is very intentionally minimal to keep metatensor as simple as possible. Feel free to wrap the corresponding data inside types with richer API such as Eigen, Boost, etc.

Public Functions

inline NDArray()

Create a new empty NDArray, with shape [0, 0].

inline NDArray(const T *data, std::vector<size_t> shape)

Create a new NDArray using a non-owning view in const memory with the given shape.

data must point to contiguous memory containing the right number of elements as described by the shape, which will be interpreted as an N-dimensional array in row-major order. The resulting NDArray is only valid for as long as data is.

inline NDArray(T *data, std::vector<size_t> shape)

Create a new NDArray using a non-owning view in non-const memory with the given shape.

data must point to contiguous memory containing the right number of elements as described by the shape, which will be interpreted as an N-dimensional array in row-major order. The resulting NDArray is only valid for as long as data is.

inline NDArray(std::vector<T> data, std::vector<size_t> shape)

Create a new NDArray owning its data with the given shape.

NDArray(const NDArray&) = delete

NDArray is not copy-constructible.

NDArray &operator=(const NDArray &other) = delete

NDArray can not be copy-assigned.

inline NDArray(NDArray &&other) noexcept

NDArray is move-constructible.

inline NDArray &operator=(NDArray &&other) noexcept

NDArray can be move-assigned.

inline bool is_view() const

Is this NDArray a view into external data?

template<typename ...Args>
inline T operator()(Args... args) const &

Get the value inside this NDArray at the given index

auto array = NDArray(...);

double value = array(2, 3, 1);

template<typename ...Args>
inline T &operator()(Args... args) &

Get a reference to the value inside this NDArray at the given index

auto array = NDArray(...);

array(2, 3, 1) = 5.2;

inline const T *data() const &

Get the data pointer for this array, i.e. the pointer to the first element.

inline T *data() &

Get the data pointer for this array, i.e. the pointer to the first element.

inline const std::vector<size_t> &shape() const &

Get the shape of this array.

inline bool is_empty() const

Check if this array is empty, i.e. if at least one of the shape element is 0.

TensorMap serialization

inline void metatensor::io::save(const std::string &path, const TensorMap &tensor)

Save a TensorMap to the file at path.

If the file exists, it will be overwritten.

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. See the C API documentation for more information on the format.

template<typename Buffer = std::vector<uint8_t>>
Buffer metatensor::io::save_buffer(const TensorMap &tensor)

Save a TensorMap to an in-memory buffer.

The Buffer template parameter can be set to any type that can be constructed from a pair of iterator over std::vector<uint8_t>.

inline TensorMap metatensor::io::load(const std::string &path, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from the given path.

create_array will be used to create new arrays when constructing the blocks and gradients, the default version will create data using SimpleDataArray. See mts_create_array_callback_t() for more information.

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. See the C API documentation for more information on the format.

inline TensorMap metatensor::io::load_buffer(const uint8_t *buffer, size_t buffer_count, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from the given buffer, containing buffer_count elements.

create_array will be used to create new arrays when constructing the blocks and gradients, the default version will create data using SimpleDataArray. See mts_create_array_callback_t() for more information.

template<typename Buffer>
TensorMap metatensor::io::load_buffer(const Buffer &buffer, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorMap from the given buffer.

The Buffer template parameter would typically be a std::vector<uint8_t> or a std::string, but any container with contiguous data and an item_type with the same size as a uint8_t can work.

inline mts_status_t metatensor::details::default_create_array(const uintptr_t *shape_ptr, uintptr_t shape_count, mts_array_t *array)

Default callback for data array creating in TensorMap::load, which will create a SimpleDataArray.

TensorBlock serialization

inline void metatensor::io::save(const std::string &path, const TensorBlock &block)

Save a TensorBlock to the file at path.

If the file exists, it will be overwritten.

template<typename Buffer = std::vector<uint8_t>>
Buffer metatensor::io::save_buffer(const TensorBlock &block)

Save a TensorBlock to an in-memory buffer.

The Buffer template parameter can be set to any type that can be constructed from a pair of iterator over std::vector<uint8_t>.

inline TensorBlock metatensor::io::load_block(const std::string &path, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorBlock from the given path.

create_array will be used to create new arrays when constructing the blocks and gradients, the default version will create data using SimpleDataArray. See mts_create_array_callback_t() for more information.

inline TensorBlock metatensor::io::load_block_buffer(const uint8_t *buffer, size_t buffer_count, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorBlock from the given buffer, containing buffer_count elements.

create_array will be used to create new arrays when constructing the blocks and gradients, the default version will create data using SimpleDataArray. See mts_create_array_callback_t() for more information.

template<typename Buffer>
TensorBlock metatensor::io::load_block_buffer(const Buffer &buffer, mts_create_array_callback_t create_array = details::default_create_array)

Load a previously saved TensorBlock from the given buffer.

The Buffer template parameter would typically be a std::vector<uint8_t> or a std::string, but any container with contiguous data and an item_type with the same size as a uint8_t can work.

Labels serialization

inline void metatensor::io::save(const std::string &path, const Labels &labels)

Save Labels to the file at path.

If the file exists, it will be overwritten.

template<typename Buffer = std::vector<uint8_t>>
Buffer metatensor::io::save_buffer(const Labels &labels)

Save Labels to an in-memory buffer.

The Buffer template parameter can be set to any type that can be constructed from a pair of iterator over std::vector<uint8_t>.

inline Labels metatensor::io::load_labels(const std::string &path)

Load previously saved Labels from the given path.

inline Labels metatensor::io::load_labels_buffer(const uint8_t *buffer, size_t buffer_count)

Load previously saved Labels from the given buffer, containing buffer_count elements.

template<typename Buffer>
Labels metatensor::io::load_labels_buffer(const Buffer &buffer)

Load a previously saved Labels from the given buffer.

The Buffer template parameter would typically be a std::vector<uint8_t> or a std::string, but any container with contiguous data and an item_type with the same size as a uint8_t can work.