slice#

metatensor.slice(tensor: TensorMap, axis: str, labels: Labels) → TensorMap[source]#

Slice a TensorMap along either the “samples” or “properties” axis.

labels is a Labels objects that specifies the samples/properties (respectively) names and indices that should be sliced, i.e. kept in the output tensor. For axis, either “samples” or “properties” should be specified.

samples = Labels(
    names=["structure", "center"],
    values=np.array([[0, 1], [0, 6], [1, 6], [3, 16]]),  # must be a 2D-array
)
properties = Labels(
    names=["n"],  # radial channel
    values=np.array([[3], [4], [5]]),
)
sliced_tensor_samples = slice(
    tensor,
    axis="samples",
    labels=samples,
)
sliced_tensor_properties = slice(
    tensor,
    axis="properties",
    labels=properties,
)

Also note that this function will return a TensorMap whose blocks are of equal or smaller dimensions (due to slicing) than those of the input. However, the returned TensorMap will be returned with the same number of blocks and the corresponding keys as the input. If any block upon slicing is reduced to nothing, i.e. in the case that it has none of the specified labels along the “samples” or “properties” axis, an empty block will be returned but will still be accessible by its key. User warnings will be issued if any blocks are sliced to contain no values.

For the empty blocks that may be returned, although there will be no actual values in its TensorBlock.values array, the shape of this array will be non-zero in the dimensions that haven’t been sliced. This allows the slicing of dimensions to be tracked.

For example, if a TensorBlock of shape (52, 1, 5) is passed, and only some samples are specified to be sliced but none of these appear in the input TensorBlock, the returned block values array will be empty, but its shape will be (0, 1, 5) - i.e. the samples dimension has been sliced to zero but the components and properties dimensions remain in-tact. The same logic applies to any Gradient TensorBlocks the input TensorBlock may have associated with it.

See the documentation for the slice_block() function to see how an individual TensorBlock is sliced.

Parameters:

  • tensor (TensorMap) – the input TensorMap to be sliced.

  • axis (str) – a str indicating the axis along which slicing should occur. Should be either “samples” or “properties”.

  • labels (Labels) – a Labels object containing the names and indices of the “samples” or “properties” to keep in each of the sliced TensorBlock of the output TensorMap.

Returns:

a TensorMap that corresponds to the sliced input tensor.

Return type:

TensorMap

metatensor.slice_block(block: TensorBlock, axis: str, labels: Labels) → TensorBlock[source]#

Slices an input TensorBlock along either the “samples” or “properties” axis. labels is a Labels objects that specify the sample/property names and indices that should be sliced, i.e. kept in the output TensorBlock.

Example: take an input TensorBlock of shape (100, 1, 6), where there are 100 ‘samples’, 1 ‘components’, and 6 ‘properties’. Say we want to slice this tensor along the samples and properties dimensions. As in the code-block below, we can specify, for example, 4 samples and 3 properties indices to keep. The returned TensorBlock will have shape (4, 1, 3).

samples = Labels(
    names=["structure", "center"],
    values=np.array([[0, 1], [0, 6], [1, 6], [3, 16]]),  # must be a 2D-array
)
properties = Labels(
    names=["n"],  # radial channel
    values=np.array([[3], [4], [5]]),
)
sliced_block_samples = slice_block(
    block,
    axis="samples",
    labels=samples,
)
sliced_block_properties = slice_block(
    block,
    axis="properties",
    labels=properties,
)

For the empty blocks that may be returned, although there will be no actual values in its TensorBlock.values tensor, the shape of this tensor will be non-zero in the dimensions that haven’t been sliced. This is created by slicing the input TensorBlock, as opposed to just returning an artificially-created empty one (with no shape or dimensions), and is intentional. It allows the slicing of dimensions to be tracked.

For instance, if a TensorBlock of shape (52, 1, 5) is passed, and only some samples are specified to be sliced but none of these appear in the input TensorBlock, the returned TensorBlock values array will be empty, but its shape will be (0, 1, 5) - i.e. the samples dimension has been sliced to zero but the components and properties dimensions remain in-tact. The same logic applies to any Gradient TensorBlocks the input TensorBlock may have associated with it.

Parameters:

  • block (TensorBlock) – the input TensorBlock to be sliced.

  • axis (str) – a str indicating the axis along which slicing should occur. Should be either “samples” or “properties”.

  • labels (Labels) – a Labels object containing the names and indices of the “samples” or “properties” to keep in the sliced output TensorBlock.

Return new_block:

a TensorBlock that corresponds to the sliced input.

Return type:

TensorBlock