Tensor Network Theory Library  Beta release 1.1.0
A library of routines for performing TNT-based operations

Detailed Description

These functions perform operations on the nodes that change their values, or create new nodes by factorising or multiplying the original nodes. These functions are built upon linear algebra routines, and so their speed will be determined by the performance of the libraries you are linking to.


void tntNodeAdd (tntNode A, tntNode B)
tntNode tntNodeContract (tntNode A, tntNode B, tntLegLabel legMapAC, tntLegLabel legMapBC)
tntNode tntNodeContractList (tntLegLabel remlegs, tntNode A, tntNode B, tntNode C...)
void tntNodeContractSelf (tntNode *Ap)
void tntNodeExp (tntNode A, tntComplex c, tntLegLabel rowlegs, tntLegLabel collegs)
void tntNodeInverseFact (tntNode A, tntLegLabel legA)
void tntNodePrepContract (tntNode A, tntNode B)
void tntNodeScaleComplex (tntNode A, tntComplex val)
void tntNodeScaleReal (tntNode A, double val)
tntNode tntNodeSVD (tntNode A, tntLegLabel Ulegs, tntLegLabel legUS, tntLegLabel legSU, tntLegLabel legSV, tntLegLabel legVS, int chi, double *err, tntLegLabel legmap)

Function Documentation

void tntNodeAdd ( tntNode  A,
tntNode  B 

Adds the elements of the node \(B\) to \(A\). The result is returned in \(A\), and \(B\) is unchanged. The connections of \(A\) and \(B\) are unchanged. This function will return an error if \(A\) and \(B\) do not have the same structure i.e. if the number of legs, dimensions of the legs, and the types of legs are not the same for the two nodes.

AThe first node to add and that will contain the result of the addition
Bthe tnode to be added to the node tnA. This is not changed function, unless it is of the functional type in which case function is evaluated)

Definition at line 37 of file tntNodeAlgebra.c.

tntNode tntNodeContract ( tntNode  A,
tntNode  B,
tntLegLabel  legMapAC,
tntLegLabel  legMapBC 

Contracts \(A\) with \(B\) on all connecting legs and returns the result in a new node \(C\). Nodes \(A\) with \(B\) are destroyed by the operation. Leg maps specify how the leg labels of the starting nodes relate to the leg labels of the final node - the final node should have no repeated labels. If none of the leg labels change then NULL can be used instead of passing a leg map, or both (but not one) of the final arguments can be left out. If \(A\) or \(B\) are required for later operations a copy should first be made using tntNodeCopy().

If \(A\) and \(B\) are not connected to one another it is assumed that there is a singleton leg connecting them. This means that the resulting node \(C\) will have all the legs of \(A\) and all the legs of \(B\).

See Also
tntNodePrepContract() if the same contraction is being repeated multiple times.
The node that is the result of the contraction.
AThe first node to be contracted
BThe second node to be contracted
legMapACHow the legs in node A map to the legs in node C.
legMapBCHow the legs in node B map to the legs in node C.

Definition at line 64 of file tntNodeAlgebra.c.

tntNode tntNodeContractList ( tntLegLabel  remlegs,
tntNode  A,
tntNode  B,
tntNode  C... 

Contracts a list of nodes \(A, B, \dotsc\) into a single resulting node \(R\), where the legs on the resulting node are labelled according to the string passed. The maximum number of nodes that can be passed in the list is 12 - any additional arguments will be ignored. The minimum number of nodes that can be passed in the list is 2. The nodes will be contracted in the order in which they are given - i.e. \(A\) will be contracted with \(B\) to make \(R\), \(R\) will be contracted with \(C\) to make \(R\), \(R\) will be contracted with \(D\) to make \(R\) etc - unless:

  • There are three or four nodes - in this case the optimal contraction order will be calculated and used
  • Any of the nodes have legs which connect to legs on the same node: these will be contracted first If after contracting none of the leg numbers will be changed, NULL can be used for the first argument instead.

The remaining legs will be labelled according to the values in the remleglabels array, in the order of the nodes, and then in the order of the legs of each node where ascending order is 0-9, A-Z, a-z.

The node that is the result of the contraction.
remlegsLabels for the contracted node
AFirst node to contract
BSecond node to contract
C...(optional) Third to twelfth nodes to contract

Definition at line 177 of file tntNodeAlgebra.c.

void tntNodeContractSelf ( tntNode *  Ap)

Contracts the legs of node \(A\) that are connected to other legs of \(A\). This is equivalent to taking the trace of the corresponding tensor over the indices that correspond to these legs.

If this will result in all the legs of \(A\) being contracted, then a singleton leg with label "1" will remain. In other cases the remaining legs will be unchanged, and no additional legs will be added. If there are no legs connected to each other, this function will have no effect.

No return value - the node passed as an argument is modified to contract the self-joined legs
ApPointer to node to contract

Definition at line 425 of file tntNodeAlgebra.c.

void tntNodeExp ( tntNode  A,
tntComplex  c,
tntLegLabel  rowlegs,
tntLegLabel  collegs 

Takes the matrix exponential of the node \(A\), where the node can first be scaled by the complex number \(c\). The legs that are assigned to each of the dimensions of the matrix are given as arguments, where the first leg corresponds to the fastest moving index. The resulting matrix must be square, and if it is not the function exits with an error. The input node is changed by the function (i.e. the result is placed in the original node), so a copy should be made first if it will be required later.

ANode to take the exponential of.
cNumber to scale node by before taking exponential.
rowlegsList of legs making up the rows of the matrix
collegsList of legs making up the columns of the matrix

Definition at line 545 of file tntNodeAlgebra.c.

void tntNodeInverseFact ( tntNode  A,
tntLegLabel  legA 

This `factorises' the node \(A\) into \(A\) connected to \(A^{-1}\), connected to \(A\). The original nodes is replaced by these three nodes, putting them in the network if \(A\) already has connections. This only makes sense for nodes with two legs - any other leg numbers will result in an error.

AThe node to find the inverse of.
legAThe leg of that node to connect the inverse and original nodes to.

Definition at line 572 of file tntNodeAlgebra.c.

void tntNodePrepContract ( tntNode  A,
tntNode  B 

This is a `mock' contract of node \(A\) and \(B\). It performs all the operations on \(A\) and \(B\) that are performed before a normal contraction but

  • does not contract the resulting nodes together
  • does not create a new node tnC
  • does not free \(A\) and \(B\). \(A\) and \(B\) can then be used again for the same contraction without these preparatory steps being required. This can significantly reduce the run time if the same contraction is repeated many times with one of the nodes \(A\) or \(B\).
    No return value.
AThe first node to be contracted
BThe second node to be contracted

Definition at line 141 of file tntNodeAlgebra.c.

void tntNodeScaleComplex ( tntNode  A,
tntComplex  val 

Scales a node by the complex value given. If the node was previously a functional node, it will now be a static node. The connections on the node are unchanged by the operation.

AThe node to scale
valThe value to scale it by

Definition at line 591 of file tntNodeAlgebra.c.

void tntNodeScaleReal ( tntNode  A,
double  val 

Scales a node by the real value given. If the node was previously a functional node, it will now be a static node. The connections on the node are unchanged by the operation.

AThe node to scale
valThe value to scale it by

Definition at line 604 of file tntNodeAlgebra.c.

tntNode tntNodeSVD ( tntNode  A,
tntLegLabel  Ulegs,
tntLegLabel  legUS,
tntLegLabel  legSU,
tntLegLabel  legSV,
tntLegLabel  legVS,
int  chi,
double *  err,
tntLegLabel  legmap 

Factorises the node \(A\) into three new nodes \(U\), \(S\), and \(V^{\dagger}\) using a singular value decomposition (SVD). The legs of \(A\) listed in the argument Ulegs are assigned to \(U\), and all remaining legs of \(A\) are assigned to \(V^{\dagger}\). The new internal legs i.e. the legs that connect to and from S, are given labels specified in the four arguments that follow this. If the legs should be relabelled after performing the SVD, use the optional final argument legmap. The map should have the format"abc=ABC" where 'a' should be relabelled as "A", 'b' as "B" and 'c' as "C". Any leg labels not listed keep their original values. E.g. to factorise the node A as shown below without renaming


If you wanted to perform exactly the same factorisation, but change the leg labels as shown then the final argument is required


If an exact SVD is performed, the dimension of the internal legs \(D_{\mathrm{exact}}\) will be the maximum of the combined dimension of the legs assigned to \(U\) and the combined dimension of the legs assigned to \(V^{\dagger}\). For this option set chi to be -1, or a value larger than \(D_{\mathrm{exact}}\).

Alternatively a truncated SVD can be performed in two ways:

  • By passing a value of chi that is less than \(D_{\mathrm{exact}}\);
  • By setting a truncation tolerance using tntSVDTruncTolSet() (which will apply for this SVD and all subsequent SVDs). If both of these are done, then the one which results in the smallest internal dimension will be used. In both cases the associated error will be assigned to the variable pointed to by err. The truncation error is calculated by taking the 2-norm of the discarded values by default, but to use a different function call the function tntTruncType() before calling this function. This changes the way the truncation error is calculated for all subsequent SVDs.

The function returns the node \(U\), and the remaining nodes \(S\) and \(V^{\dagger}\) are inserted in the network and can be identified by traversing the network using tntNodeFindConn().

The original node is \(A\) destroyed, so if it is required for further operations a copy should be made using tntNodeCopy() first.

By default this function optimises the SVD by making small values (below a certain tolerance) equal to zero, then splitting the SVD into blocks. The default tolerance is TNT_DEFAULT_TOL, so any values in \(A\) smaller than this will be set to zero. This can be changed by using tntSVDTolSet() - see the documentation for this function for more information.
The node \(U\).
AThe node that will be factorised.
UlegsThe legs that will be assigned to \(U\).
legUSThe leg that will connect \(U\) to \(S\).
legSUThe leg that will connect \(S\) to \(U\).
legSVThe leg that will connect \(S\) to \(V^{\dagger}\).
legVSThe leg that will connect \(V^{\dagger}\) to \(S\).
chiThe dimension of the leg connecting U to S and S to VH i.e. the number of singular vectors kept.
errPointer to the variable that will hold the truncation error. If the truncation error is not required, pass NULL.
legmapOptional argument: Map describing how the legs will be relabelled

Definition at line 658 of file tntNodeAlgebra.c.