unique_metadata#

metatensor.unique_metadata(tensor: TensorMap, axis: str, names: List[str] | Tuple[str] | str, gradient: str | None = None) → Labels[source]#

Returns a Labels object containing the unique metadata across all blocks of the input TensorMap tensor. Unique Labels are returned for the specified axis (either "samples" or "properties") and metadata names.

Passing gradient as a str corresponding to a gradient parameter (for instance "cell" or "positions") returns the unique indices only for the gradient blocks. Note that gradient blocks by definition have the same properties metadata as their parent TensorBlock.

An empty Labels object is returned if there are no indices in the (gradient) blocks of tensor corresponding to the specified axis and names. This will have length zero but the names will be the same as passed in names.

For example, to find the unique "structure" indices in the "samples" metadata present in a given TensorMap:

import metatensor

unique_structures = metatensor.unique_metadata(
    tensor,
    axis="samples",
    names=["structure"],
)

Or, to find the unique "atom" indices in the "samples" metadata present in the "positions" gradient blocks of a given TensorMap:

unique_grad_atoms = metatensor.unique_metadata(
    tensor,
    axis="samples",
    names=["atom"],
    gradient="positions",
)

The unique indices can then be used to split the TensorMap into several smaller TensorMap objects. Say, for example, that the unique_structures from the example above are:

Labels(
    [(0,), (1,), (2,), (3,), (4,), (5,), (6,), (7,), (8,), (9,)],
    dtype=[("structure", "<i4")],
)

Then, the following code will split the TensorMap into 2 TensorMap objects, with first containing structure indices 0-3 and the second containing structure indices 4-9:

import metatensor

[tensor_1, tensor_2] = metatensor.split(
    tensor,
    axis="samples",
    grouped_labels=[unique_structures[:4], unique_structures[4:]],
)
Parameters:

  • tensor (TensorMap) – the TensorMap to find unique indices for.

  • axis (str) – a str, either "samples" or "properties", corresponding to the axis along which the named unique indices should be found.

  • names (List[str] | Tuple[str] | str) – a str, list of str, or tuple of str corresponding to the name(s) of the indices along the specified axis for which the unique values should be found.

  • gradient (str | None) – a str corresponding to the gradient parameter name for the gradient blocks to find the unique indices for. If None (default), the unique indices of the regular TensorBlock objects will be calculated.

Returns:

a sorted Labels object containing the unique metadata for the blocks of the input tensor or its gradient blocks for the specified parameter. Each element in the returned Labels object has len(names) entries.

Return type:

Labels

metatensor.unique_metadata_block(block: TensorBlock, axis: str, names: List[str] | Tuple[str] | str, gradient: str | None = None) → Labels[source]#

Returns a Labels object containing the unique metadata in the input TensorBlock block, for the specified axis (either "samples" or "properties") and metadata names.

Passing gradient as a str corresponding to a gradient parameter (for instance "cell" or "positions") returns the unique indices only for the gradient block associated with block. Note that gradient blocks by definition have the same properties metadata as their parent TensorBlock.

An empty Labels object is returned if there are no indices in the (gradient) blocks of tensor corresponding to the specified axis and names. This will have length zero but the names will be the same as passed in names.

For example, to find the unique "structure" indices in the "samples" metadata present in a given TensorBlock:

import metatensor

unique_samples = metatensor.unique_metadata_block(
    block,
    axis="samples",
    names=["structure"],
)

To find the unique "atom" indices along the "samples" axis present in the "positions" gradient block of a given TensorBlock:

unique_grad_samples = metatensor.unique_metadata_block(
    block,
    axis="samples",
    names=["atom"],
    gradient="positions",
)
Parameters:

  • block (TensorBlock) – the TensorBlock to find unique indices for.

  • axis (str) – a str, either "samples" or "properties", corresponding to the axis along which the named unique metadata should be found.

  • names (List[str] | Tuple[str] | str) – a str, list of str, or tuple of str corresponding to the name(s) of the metadata along the specified axis for which the unique indices should be found.

  • gradient (str | None) – a str corresponding to the gradient parameter name for the gradient blocks to find the unique metadata for. If None (default), the unique metadata of the regular TensorBlock objects will be calculated.

Returns:

a sorted Labels object containing the unique metadata for the input block or its gradient for the specified parameter. Each element in the returned Labels object has len(names) entries.

Return type:

Labels