join¶

metatensor.join(tensors: List[TensorMap], axis: str, different_keys: str = 'error', add_dimension: str | None = None) → TensorMap[source]¶

Join a sequence of TensorMap with similar keys along an axis.

The axis parameter specifies the type of joining: with axis='properties' the tensors will be joined along the properties and for axis='samples' they will be joined along the samples.

Parameters:

tensors (List[TensorMap]) – sequence of TensorMap to join
axis (str) – Along which axis the TensorMap`s should be joined. This can be either `’properties’`` or 'samples'.
different_keys (str) – Method to handle different keys between the tensors. For "error" keys in all tensors have to be the same. For "intersection" only blocks present in all tensors will be taken into account. For "union" missing keys will be treated like if they where associated with an empty block.
add_dimension (str | None) – Add an the extra dimension to the joined labels with the given name. See examples for the case where this is applicable. The dimension forms the last dimension of the joined labels.

Returns:

The joined TensorMap with more properties or samples than the inputs.

Return type:

TensorMap

Examples¶

The first use case for this function is when joining TensorMap with the same labels names (either along samples or properties):

>>> import numpy as np
>>> import metatensor as mts
>>> from metatensor import Labels, TensorBlock, TensorMap

>>> values = np.array([[1.1, 2.1, 3.1]])
>>> samples = Labels("sample", np.array([[0]]))

Define two disjoint set of Labels.

>>> properties_1 = Labels("n", np.array([[0], [2], [3]]))
>>> properties_2 = Labels("n", np.array([[1], [4], [5]]))

>>> block_1 = TensorBlock(
...     values=values,
...     samples=Labels.single(),
...     components=[],
...     properties=properties_1,
... )
>>> block_2 = TensorBlock(
...     values=values,
...     samples=Labels.single(),
...     components=[],
...     properties=properties_2,
... )

>>> tensor_1 = TensorMap(keys=Labels.single(), blocks=[block_1])
>>> tensor_2 = TensorMap(keys=Labels.single(), blocks=[block_2])

joining along the properties leads to

>>> joined_tensor = mts.join([tensor_1, tensor_2], axis="properties")
>>> joined_tensor[0].properties
Labels(
    n
    0
    2
    3
    1
    4
    5
)

Second, if the labels names are the same but the values are not unique, you can ask to add an extra dimension to the labels when joining with add_dimension, thus creating unique values

>>> properties_3 = Labels("n", np.array([[0], [2], [3]]))

properties_3 has the same name and also shares values with properties_1 as defined above.

>>> block_3 = TensorBlock(
...     values=values,
...     samples=Labels.single(),
...     components=[],
...     properties=properties_3,
... )
>>> tensor_3 = TensorMap(keys=Labels.single(), blocks=[block_3])

joining along properties leads to

>>> joined_tensor = mts.join(
...     [tensor_1, tensor_3], axis="properties", add_dimension="tensor"
... )
>>> joined_tensor[0].properties
Labels(
    n  tensor
    0    0
    2    0
    3    0
    0    1
    2    1
    3    1
)

Finally, when joining along properties, if different TensorMap have different property names, we’ll re-create new properties labels containing the original tensor index and the corresponding property index. This does not apply when joining along samples.

>>> properties_4 = Labels(["a", "b"], np.array([[0, 0], [1, 2], [1, 3]]))

properties_4 has the different names compared to properties_1 defined above.

>>> block_4 = TensorBlock(
...     values=values,
...     samples=Labels.single(),
...     components=[],
...     properties=properties_4,
... )
>>> tensor_4 = TensorMap(keys=Labels.single(), blocks=[block_4])

joining along properties leads to

>>> joined_tensor = mts.join([tensor_1, tensor_4], axis="properties")
>>> joined_tensor[0].properties
Labels(
    joined_index  property
         0           0
         0           1
         0           2
         1           0
         1           1
         1           2
)

metatensor.join_blocks(blocks: List[TensorBlock], axis: str, add_dimension: str | None = None) → TensorBlock[source]¶

Join a sequence of TensorBlock along an axis.

The axis parameter specifies the type of joining: with axis='properties' the blocks will be joined along the properties and for axis='samples' they will be joined along the samples.

Parameters:

tensors – sequence of TensorMap to join
axis (str) – Along which axis the blocks should be joined. This can be either 'properties' or 'samples'.
add_dimension (str | None) – Add an the extra dimension to the joined labels with the given name. The dimension forms the last dimension of the joined labels.
blocks (List[TensorBlock])

Returns:

The joined TensorBlock with more properties or samples than the inputs.

Return type:

TensorBlock