7.3. Changing labels

We can set and change the labels of the Bonds in a UniTensor as desired. This is particularly helpful for contractions with cytnx.Contract() and cytnx.Contracts(). As will be explained in Contract(s), these functions contract bonds with the same name on different UniTensors. Therefore, we might need to change the labels for some bond(s) to initiate the correct tensor contraction.

To change the label associated to a certain leg of a UniTensor, one can use:

UniTensor.relabel_(index, new_label)
Parameters:

  • index ([int]) – the index (order) of the bond in the UniTensor

  • new_label ([string]) – the new label that you want to change to

Alternatively, if we don’t know the index of the target bond in the current order, we can also specify the old label:

UniTensor.relabel_(old_label, new_label)
Parameters:

  • old_label ([string]) – the current label of the bond

  • new_label ([string]) – the new label that you want to change to

If we wish to change the labels of all legs, we can use:

UniTensor.relabels_(new_labels)
Parameters:

new_labels (List[string]) – a list of new labels

or

UniTensor.relabels_(old_labels, new_labels)
Parameters:

  • old_labels (List[string]) – a list of current labels

  • new_labels (List[string]) – a list of the corresponding new labels

For example:

  • In Python:

1T = cytnx.arange(2*3*4).reshape(2,3,4)
2uT = cytnx.UniTensor(T)
3
4uT.relabel_(1,"xx")
5uT.print_diagram()
6
7uT.relabels_(["a","b","c"])
8uT.print_diagram()

Output >>

-----------------------
tensor Name :
tensor Rank : 3
block_form  : False
is_diag     : False
on device   : cytnx device: CPU
          ---------
         /         \
   0 ____| 2     3 |____ xx
         |         |
         |       4 |____ 2
         \         /
          ---------
-----------------------
tensor Name :
tensor Rank : 3
block_form  : False
is_diag     : False
on device   : cytnx device: CPU
          ---------
         /         \
   a ____| 2     3 |____ b
         |         |
         |       4 |____ c
         \         /
          ---------

Note

One cannot have duplicate labels within the same UniTensor!

Warning

The previously provided method set_label(s) is deprecated and should be replaced by relabel(s)_.

7.3.1. Creating UniTensors with different labels that share data

In some scenarios, especially in contractions with cytnx.Contract() and cytnx.Contracts(), we want to create a UniTensor with changed labels. However, we might not want to modify the original tensor. Creating a copy of the tensor data is also not desired, since it would double the memory usage. In such a case one can use the function relabel(s) without underscore. This returns a new UniTensor with different meta (in this case only the labels are changed), but the actual memory block(s) are still referring to the old ones. The arguments of relabel(s) are similar to relabel(s)_, see above. For example:

  • In Python:

1uT_new = uT.relabel(old_label="a", new_label="xx")
2uT.print_diagram()
3uT_new.print_diagram()
4
5print(uT_new.same_data(uT))

Output >>

-----------------------
tensor Name :
tensor Rank : 3
block_form  : False
is_diag     : False
on device   : cytnx device: CPU
          ---------
         /         \
   a ____| 2     3 |____ b
         |         |
         |       4 |____ c
         \         /
          ---------
-----------------------
tensor Name :
tensor Rank : 3
block_form  : False
is_diag     : False
on device   : cytnx device: CPU
           ---------
          /         \
   xx ____| 2     3 |____ b
          |         |
          |       4 |____ c
          \         /
           ---------
True