Tensor Network Theory Library  Beta release 1.2.0
A library of routines for performing TNT-based operations
 All Data Structures Functions Variables Groups Pages
Algebra

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.

Functions

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.

Parameters
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.

Referenced by tntMpsCreateMpo(), tntMpsCreateSpinOp(), tntMpsCreateTwoSiteOp(), and tntMpsProcessExpecOptions().

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\).

contract.png
See Also
tntNodePrepContract() if the same contraction is being repeated multiple times.
Returns
The node that is the result of the contraction.
Parameters
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.
Examples:
create_nodes.c.

Definition at line 109 of file tntNodeAlgebra.c.

Referenced by tntDmrgLocalOps(), tntMpoMpoProduct(), tntMpoMpoTrace(), tntMpoPmpoProduct(), tntMpoPropSTscContract(), tntMpoTrace(), tntMpsCreateBosonOp(), tntMpsCreateMpo(), tntMpsCreateTwoSiteOp(), tntMpsMpoContract(), tntMpsMpoMpsPartProduct(), tntMpsMpsContract(), tntMpsPmpoProduct(), tntMpsProcessExpecOptions(), tntMpsPropSTscContract(), and tntMpsVarMinMpo2sSweep().

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.

If contraction of the group will result in all the legs of \(A, B, \dotsc\) being contracted, then a singleton leg with label "1" will be given to \(R\).

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

Definition at line 248 of file tntNodeAlgebra.c.

References tntIntArrayFree().

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.

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

Definition at line 522 of file tntNodeAlgebra.c.

References tntIntArrayFree(), and tntNodeCreateEyeLeg().

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.

Parameters
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 644 of file tntNodeAlgebra.c.

Referenced by tntMpsCreatePropArray().

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.

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

Definition at line 674 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\).
    Returns
    No return value.
Parameters
AThe first node to be contracted
BThe second node to be contracted

Definition at line 202 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.

Parameters
AThe node to scale
valThe value to scale it by

Definition at line 696 of file tntNodeAlgebra.c.

Referenced by tntMpsCreateMpo(), tntMpsCreateSpinOp(), tntMpsCreateTwoSiteOp(), and tntMpsProcessExpecOptions().

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.

Parameters
AThe node to scale
valThe value to scale it by

Definition at line 712 of file tntNodeAlgebra.c.

References tntComplex::im, and tntComplex::re.

Referenced by tntMpsCreateRandom(), tntMpsCreateSpinOp(), tntMpsCreateSymmRandom(), tntMpsOrthNorm(), and tntMpsProcessExpecOptions().

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

svd.png

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

svd_rename.png

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.

Note
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.
Returns
The node \(U\).
Parameters
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 769 of file tntNodeAlgebra.c.

Referenced by tntDmrgLocalOps(), tntMpoPropTwoSite(), tntMpsCreateRandom(), tntMpsMpoContract(), tntMpsPropTwoSite(), tntMpsTruncate(), and tntMpsVarMinMpo2sSweep().