Struct metatensor::TensorMap

pub struct TensorMap { /* private fields */ }

TensorMap is the main user-facing struct of this library, and can store any kind of data used in atomistic machine learning.

A tensor map contains a list of TensorBlocks, each one associated with a key in the form of a single Labels entry.

It provides functions to merge blocks together by moving some of these keys to the samples or properties labels of the blocks, transforming the sparse representation of the data to a dense one.

Implementations

impl TensorMap

pub fn new(keys: Labels, blocks: Vec<TensorBlock>) -> Result<TensorMap, Error>

Create a new TensorMap with the given keys and blocks.

The number of keys must match the number of blocks, and all the blocks must contain the same kind of data (same labels names, same gradients defined on all blocks).

pub unsafe fn from_raw(ptr: *mut mts_tensormap_t) -> TensorMap

Create a new TensorMap from a raw pointer.

This function takes ownership of the pointer, and will call mts_tensormap_free on it when the TensorMap goes out of scope.

Safety

The pointer must be non-null and created by mts_tensormap or TensorMap::into_raw.

pub fn into_raw(map: TensorMap) -> *mut mts_tensormap_t

Extract the underlying raw pointer.

The pointer should be passed back to TensorMap::from_raw or mts_tensormap_free to release the memory corresponding to this TensorMap.

pub fn try_clone(&self) -> Result<TensorMap, Error>

Clone this TensorMap, cloning all the data and metadata contained inside.

This can fail if the external data held inside an mts_array_t can not be cloned.

pub fn keys(&self) -> &Labels

Get the keys defined in this TensorMap

pub fn block_by_id(&self, index: usize) -> TensorBlockRef<'_>

Get a reference to the block at the given index in this TensorMap

Panics

If the index is out of bounds

pub fn block_mut_by_id(&mut self, index: usize) -> TensorBlockRefMut<'_>

Get a mutable reference to the block at the given index in this TensorMap

Panics

If the index is out of bounds

pub fn blocks_matching(&self, selection: &Labels) -> Result<Vec<usize>, Error>

Get the index of blocks matching the given selection.

The selection must contains a single entry, defining the requested key or keys. If the selection contains only a subset of the dimensions of the keys, there can be multiple matching blocks.

pub fn block_matching(&self, selection: &Labels) -> Result<usize, Error>

Get the index of the single block matching the given selection.

This function is similar to TensorMap::blocks_matching, but also returns an error if more than one block matches the selection.

pub fn block(&self, selection: &Labels) -> Result<TensorBlockRef<'_>, Error>

Get a reference to the block matching the given selection.

This function uses TensorMap::blocks_matching under the hood to find the matching block.

pub fn blocks(&self) -> Vec<TensorBlockRef<'_>>

Get a reference to every blocks in this TensorMap

pub fn blocks_mut(&mut self) -> Vec<TensorBlockRefMut<'_>>

Get a mutable reference to every blocks in this TensorMap

pub fn keys_to_samples( &self, keys_to_move: &Labels, sort_samples: bool ) -> Result<TensorMap, Error>

Merge blocks with the same value for selected keys dimensions along the samples axis.

The dimensions (names) of keys_to_move will be moved from the keys to the sample labels, and blocks with the same remaining keys dimensions will be merged together along the sample axis.

keys_to_move must be empty (keys_to_move.count() == 0), and the new sample labels will contain entries corresponding to the merged blocks’ keys.

The new sample labels will contains all of the merged blocks sample labels. The order of the samples is controlled by sort_samples. If sort_samples is true, samples are re-ordered to keep them lexicographically sorted. Otherwise they are kept in the order in which they appear in the blocks.

This function is only implemented if all merged block have the same property labels.

pub fn keys_to_properties( &self, keys_to_move: &Labels, sort_samples: bool ) -> Result<TensorMap, Error>

Merge blocks with the same value for selected keys dimensions along the property axis.

The dimensions (names) of keys_to_move will be moved from the keys to the property labels, and blocks with the same remaining keys dimensions will be merged together along the property axis.

If keys_to_move does not contains any entries (keys_to_move.count() == 0), then the new property labels will contain entries corresponding to the merged blocks only. For example, merging a block with key a=0 and properties p=1, 2 with a block with key a=2 and properties p=1, 3 will produce a block with properties a, p = (0, 1), (0, 2), (2, 1), (2, 3).

If keys_to_move contains entries, then the property labels must be the same for all the merged blocks. In that case, the merged property labels will contains each of the entries of keys_to_move and then the current property labels. For example, using a=2, 3 in keys_to_move, and blocks with properties p=1, 2 will result in a, p = (2, 1), (2, 2), (3, 1), (3, 2).

The new sample labels will contains all of the merged blocks sample labels. The order of the samples is controlled by sort_samples. If sort_samples is true, samples are re-ordered to keep them lexicographically sorted. Otherwise they are kept in the order in which they appear in the blocks.

pub fn components_to_properties( &self, dimensions: &[&str] ) -> Result<TensorMap, Error>

Move the given dimensions from the component labels to the property labels for each block in this TensorMap.

pub fn iter(&self) -> TensorMapIter<'_>

Get an iterator over the keys and associated blocks

pub fn iter_mut(&mut self) -> TensorMapIterMut<'_>

Get an iterator over the keys and associated blocks, with read-write access to the blocks

Trait Implementations

impl Debug for TensorMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for TensorMap

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> IntoIterator for &'a TensorMap

type Item = (&'a [LabelValue], TensorBlockRef<'a>)

The type of the elements being iterated over.

type IntoIter = TensorMapIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut TensorMap

type Item = (&'a [LabelValue], TensorBlockRefMut<'a>)

The type of the elements being iterated over.

type IntoIter = TensorMapIterMut<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Send for TensorMap

impl Sync for TensorMap