Manipulating TensorMap dimensions

Functions for manipulating dimensions of an metatensor.TensorMap (i.e. changing the columns of the metatensor.Labels within).

metatensor.append_dimension(tensor: TensorMap, axis: str, name: str, values: ndarray | Tensor | int) → TensorMap[source]

Append a metatensor.Labels dimension along the given axis.

For axis=="samples" the new dimension is not appended to gradients.

Parameters:

  • tensor (TensorMap) – the input TensorMap.

  • axis (str) – axis for which the name should be appended. Allowed are "keys", "properties" or "samples".

  • name (str) – name of the dimension be appended

  • values (ndarray | Tensor | int) – values of the dimension to be appended (np.array or torch.Tensor according to whether metatensor or metatensor.torch is being used); or an integer. In the latter case, the new dimension will have the given integer value for all entries in the labels

Raises:

ValueError – if axis is a not valid value

Returns:

a new metatensor.TensorMap with appended labels dimension.

Return type:

TensorMap

Examples

>>> import numpy as np
>>> import metatensor
>>> values = np.array([[1, 2], [3, 4]])
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["foo"], np.array([[0]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block])
>>> tensor
TensorMap with 1 blocks
keys: foo
       0
>>> metatensor.append_dimension(
...     tensor,
...     axis="keys",
...     name="bar",
...     values=np.array([1]),
... )
TensorMap with 1 blocks
keys: foo  bar
       0    1
metatensor.insert_dimension(tensor: TensorMap, axis: str, index: int, name: str, values: ndarray | Tensor | int) → TensorMap[source]

Insert a metatensor.Labels dimension along the given axis before the given index.

For axis=="samples" a new dimension is not appended to gradients.

Parameters:

  • tensor (TensorMap) – the input TensorMap.

  • axis (str) – axis for which the name should be inserted. Allowed are "keys", "properties" or "samples".

  • index (int) – index before the new dimension is inserted.

  • name (str) – the name to be inserted

  • values (ndarray | Tensor | int) – values to be inserted. This can be an array (np.array or torch.Tensor according to whether metatensor or metatensor.torch is being used); or an integer. In the latter case, the new dimension will have the given integer value for all entries in the labels

Raises:

ValueError – if axis is a not valid value

Returns:

a new metatensor.TensorMap with inserted labels dimension.

Return type:

TensorMap

Examples

>>> import numpy as np
>>> import metatensor
>>> values = np.array([[1, 2], [3, 4]])
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["foo"], np.array([[0]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block])
>>> tensor
TensorMap with 1 blocks
keys: foo
       0
>>> metatensor.insert_dimension(
...     tensor,
...     axis="keys",
...     index=0,
...     name="bar",
...     values=np.array([1]),
... )
TensorMap with 1 blocks
keys: bar  foo
       1    0
metatensor.permute_dimensions(tensor: TensorMap, axis: str, dimensions_indexes: List[int]) → TensorMap[source]

Permute dimensions of a Labels of the given axis according to a list of indexes.

Values of dimensions_indexes have to be same as the indexes of Labels but can be in a different order.

For axis=="samples" gradients samples dimensions are not permuted.

Parameters:

  • tensor (TensorMap) – the input TensorMap.

  • axis (str) – axis for which the name should be inserted. Allowed are "keys", "properties" or "samples".

  • dimensions_indexes (List[int]) – desired ordering of the dimensions

Raises:

ValueError – if axis is a not valid value

Returns:

a new metatensor.TensorMap with the labels dimension permuted

Return type:

TensorMap

Examples

>>> import numpy as np
>>> import metatensor
>>> values = np.array([[1, 2], [3, 4]])
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["foo", "bar", "baz"], np.array([[42, 10, 3]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block])
>>> tensor
TensorMap with 1 blocks
keys: foo  bar  baz
      42   10    3

Move the last (second) dimension to the first position.

>>> metatensor.permute_dimensions(tensor, axis="keys", dimensions_indexes=[2, 0, 1])
TensorMap with 1 blocks
keys: baz  foo  bar
       3   42   10
metatensor.remove_dimension(tensor: TensorMap, axis: str, name: str) → TensorMap[source]

Remove a metatensor.Labels dimension along the given axis.

Removal can only be performed if the resulting metatensor.Labels instance will be unique.

For axis=="samples" the dimension is not removed from gradients.

Parameters:
Raises:
Returns:

a new metatensor.TensorMap with removed labels dimension.

Return type:

TensorMap

Examples

>>> import numpy as np
>>> import metatensor
>>> values = np.array([[1, 2], [3, 4]])
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["key", "extra"], np.array([[0, 0]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block])
>>> tensor
TensorMap with 1 blocks
keys: key  extra
       0     0
>>> metatensor.remove_dimension(tensor, axis="keys", name="extra")
TensorMap with 1 blocks
keys: key
       0

Removing a dimension can only be performed if the resulting Labels will contain unique entries.

>>> from metatensor import MetatensorError
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["key", "extra"], np.array([[0, 0], [0, 1]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block.copy(), block.copy()])
>>> tensor
TensorMap with 2 blocks
keys: key  extra
       0     0
       0     1
>>> try:
...     metatensor.remove_dimension(tensor, axis="keys", name="extra")
... except MetatensorError as e:
...     print(e)
...
invalid parameter: can not have the same label value multiple time: [0] is already present at position 0
metatensor.rename_dimension(tensor: TensorMap, axis: str, old: str, new: str) → TensorMap[source]

Rename a metatensor.Labels dimension name for a given axis.

Parameters:

  • tensor (TensorMap) – the input TensorMap.

  • axis (str) – axis for which the names should be appended. Allowed are "keys", "properties" or "samples".

  • old (str) – name to be replaced

  • new (str) – name after the replacement

Raises:

ValueError – if axis is a not valid value

Returns:

a new metatensor.TensorMap with renamed labels dimension.

Return type:

TensorMap

Examples

>>> import numpy as np
>>> import metatensor
>>> values = np.array([[1, 2], [3, 4]])
>>> block = metatensor.block_from_array(values)
>>> keys = metatensor.Labels(["foo"], np.array([[0]]))
>>> tensor = metatensor.TensorMap(keys=keys, blocks=[block])
>>> tensor
TensorMap with 1 blocks
keys: foo
       0
>>> metatensor.rename_dimension(tensor, axis="keys", old="foo", new="bar")
TensorMap with 1 blocks
keys: bar
       0