Reduction over properties

These functions allow to reduce over the properties of TensorMap or TensorBlock objects. The values sharing the same values for the indicated property_names will be combined in a single entry. One way to see these operations is that the property indices describe the non-zero entries in a sparse array, and the reduction acts much like numpy.sum(), where property_names plays the same role as the axis argument. Whenever gradients are present, the reduction is performed also on the gradients.

TensorMap operations

metatensor.sum_over_properties(tensor: TensorMap, property_names: List[str] | str) → TensorMap[source]

Sum a TensorMap, combining the properties according to property_names.

This function creates a new TensorMap with the same keys as as the input tensor. Each TensorBlock is obtained summing the corresponding input TensorBlock over the property_names indices, essentially calling sum_over_properties_block() over each block in tensor.

property_names indicates over which dimensions in the properties the sum is performed. It accept either a single string or a list of the string with the property names corresponding to the directions along which the sum is performed. A single string is equivalent to a list with a single element: property_names = "atom" is the same as property_names = ["atom"].

Parameters:
Returns:

a TensorMap containing the reduced values and property labels

Return type:

TensorMap

>>> from metatensor import Labels, TensorBlock, TensorMap
>>> block = TensorBlock(
...     values=np.array(
...         [
...             [1, 3, 7, 10],
...             [2, 5, 8, 11],
...             [4, 6, 9, 12],
...         ]
...     ),
...     samples=Labels(
...         ["system", "atom"],
...         np.array(
...             [
...                 [0, 0],
...                 [0, 1],
...                 [1, 0],
...             ]
...         ),
...     ),
...     components=[],
...     properties=Labels(
...         ["i", "j"],
...         np.array(
...             [
...                 [0, 0],
...                 [0, 1],
...                 [1, 0],
...                 [1, 1],
...             ]
...         ),
...     ),
... )
>>> keys = Labels(names=["key"], values=np.array([[0]]))
>>> tensor = TensorMap(keys, [block])
>>> tensor_sum = sum_over_properties(tensor, property_names="j")
>>> # only 'i' is left as a property
>>> print(tensor_sum.block(0))
TensorBlock
    samples (3): ['system', 'atom']
    components (): []
    properties (2): ['i']
    gradients: None
>>> print(tensor_sum.block(0).properties)
Labels(
    i
    0
    1
)
>>> print(tensor_sum.block(0).values)
[[ 4 17]
 [ 7 19]
 [10 21]]
metatensor.mean_over_properties(tensor: TensorMap, property_names: str | List[str]) → TensorMap[source]

Compute the mean of a TensorMap, combining the properties according to property_names.

This function creates a new TensorMap with the same keys as the input tensor, and each TensorBlock is obtained averaging the corresponding input TensorBlock over the property_names indices.

property_names indicates over which dimensions in the properties the mean is performed. It accept either a single string or a list of the string with the property names corresponding to the directions along which the mean is performed. A single string is equivalent to a list with a single element: property_names = "atom" is the same as property_names = ["atom"].

For a general discussion of reduction operations and a usage example see the doc for sum_over_properties().

Parameters:
Return type:

TensorMap

metatensor.var_over_properties(tensor: TensorMap, property_names: str | List[str]) → TensorMap[source]

Compute the variance of a TensorMap, combining the properties according to property_names.

This function creates a new TensorMap with the same keys as as the input tensor, and each TensorBlock is obtained performing the variance of the corresponding input TensorBlock over the property_names indices.

property_names indicates over which dimensions in the properties the mean is performed. It accept either a single string or a list of the string with the property names corresponding to the directions along which the mean is performed. A single string is equivalent to a list with a single element: property_names = "i" is the same as property_names = ["i"].

For a general discussion of reduction operations and a usage example see the doc for sum_over_properties().

The gradient is implemented as follow:

\[\nabla[Var(X)] = 2(E[X \nabla X] - E[X]E[\nabla X])\]
Parameters:
Return type:

TensorMap

metatensor.std_over_properties(tensor: TensorMap, property_names: str | List[str]) → TensorMap[source]

Compute the standard deviation of a TensorMap, combining the properties according to property_names.

This function creates a new TensorMap with the same keys as as the input tensor, and each TensorBlock is obtained performing the std deviation of the corresponding input TensorBlock over the property_names indices.

property_names indicates over which dimensions in the properties the mean is performed. It accept either a single string or a list of the string with the property names corresponding to the directions along which the mean is performed. A single string is equivalent to a list with a single element: property_names = "i" is the same as property_names = ["i"].

For a general discussion of reduction operations and a usage example see the doc for sum_over_properties().

The gradient is implemented as follows:

\[\nabla[Std(X)] = 0.5(\nabla[Var(X)])/Std(X) = (E[X \nabla X] - E[X]E[\nabla X])/Std(X)\]
Parameters:
Return type:

TensorMap

TensorBlock operations

metatensor.sum_over_properties_block(block: TensorBlock, property_names: List[str] | str) → TensorBlock[source]

Sum a TensorBlock, combining the properties according to property_names.

This function creates a new TensorBlock in which each property is obtained summing over the property_names indices, so that the resulting TensorBlock does not have those indices.

property_names indicates over which dimensions in the properties the sum is performed. It accept either a single string or a list of the string with the property names corresponding to the directions along which the sum is performed. A single string is equivalent to a list with a single element: property_names = "i" is the same as property_names = ["i"].

Parameters:
Returns:

a TensorBlock containing the reduced values and property labels

Return type:

TensorBlock

>>> from metatensor import Labels, TensorBlock, TensorMap
>>> block = TensorBlock(
...     values=np.array(
...         [
...             [1, 3, 7, 10],
...             [2, 5, 8, 11],
...             [4, 6, 9, 12],
...         ]
...     ),
...     samples=Labels(
...         ["system", "atom"],
...         np.array(
...             [
...                 [0, 0],
...                 [0, 1],
...                 [1, 0],
...             ]
...         ),
...     ),
...     components=[],
...     properties=Labels(
...         ["i", "j"],
...         np.array(
...             [
...                 [0, 0],
...                 [0, 1],
...                 [1, 0],
...                 [1, 1],
...             ]
...         ),
...     ),
... )
>>> block_sum = sum_over_properties_block(block, property_names="j")
>>> print(block_sum.properties)
Labels(
    i
    0
    1
)
>>> print(block_sum.values)
[[ 4 17]
 [ 7 19]
 [10 21]]
metatensor.mean_over_properties_block(block: TensorBlock, property_names: List[str] | str) → TensorBlock[source]

Averages a TensorBlock, combining the properties according to property_names.

See also sum_over_properties_block() and mean_over_properties()

Parameters:
Returns:

a TensorBlock containing the reduced values and property labels

Return type:

TensorBlock

metatensor.var_over_properties_block(block: TensorBlock, property_names: List[str] | str) → TensorBlock[source]

Computes the variance for a TensorBlock, combining the properties according to property_names.

See also sum_over_properties_block() and std_over_properties()

Parameters:
Returns:

a TensorBlock containing the reduced values and property labels

Return type:

TensorBlock

metatensor.std_over_properties_block(block: TensorBlock, property_names: List[str] | str) → TensorBlock[source]

Computes the standard deviation for a TensorBlock, combining the properties according to property_names.

See also sum_over_properties_block() and std_over_properties()

Parameters:
Returns:

a TensorBlock containing the reduced values and property labels

Return type:

TensorBlock