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 "strain" 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 "system" indices in the "samples" metadata present in a given TensorMap:

>>> import numpy as np
>>> from metatensor import Labels, TensorBlock, TensorMap
>>> import metatensor
>>> block = TensorBlock(
...     values=np.random.rand(5, 3),
...     samples=Labels(
...         names=["system", "atom"],
...         values=np.array([[0, 0], [0, 1], [1, 0], [1, 1], [2, 3]]),
...     ),
...     components=[],
...     properties=Labels.range("properties", 3),
... )
>>> keys = Labels(names=["key"], values=np.array([[0]]))
>>> tensor = TensorMap(keys, [block.copy()])
>>> unique_systems = metatensor.unique_metadata(
...     tensor,
...     axis="samples",
...     names=["system"],
... )
>>> unique_systems
Labels(
    system
      0
      1
      2
)

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

>>> gradient = TensorBlock(
...     values=np.random.rand(4, 3, 3),
...     samples=Labels(
...         names=["sample", "system", "atom"],
...         values=np.array([[0, 0, 0], [1, 0, 0], [2, 1, 4], [3, 2, 5]]),
...     ),
...     components=[Labels.range("xyz", 3)],
...     properties=Labels.range("properties", 3),
... )
>>> block.add_gradient("positions", gradient)
>>> tensor = TensorMap(keys, [block])
>>> metatensor.unique_metadata(
...     tensor,
...     axis="samples",
...     names=["system", "atom"],
...     gradient="positions",
... )
Labels(
    system  atom
      0      0
      1      4
      2      5
)
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 TensorBlock containing the values 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 "strain" 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.

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