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

Detailed Description

Routines that are used in the MPS library to build the main user functions.

Modules

 Time evolution
 
 Variational Minimisation
 

Functions

tntNetwork tntMpoHC (tntNetwork mpoO)
 
void tntMpoPmpoProduct (tntNetwork mpo, tntNodeArray *op, tntIntArray *sitenum)
 
tntNode tntMpoPropTwoSite (tntNode *Mlp, tntNode *Mrp, int chi, double *err)
 
tntNode tntMpsCreateTwoSiteOp (tntNodeArray *Lnodes, tntNodeArray *Rnodes, tntComplexArray *params)
 
void tntMpsMpoConnect (tntNetwork mps, tntNetwork mpo)
 
double tntMpsMpoContract (tntNetwork mpsmpo, int chi)
 
tntNetwork tntMpsMpoMpsConnect (tntNetwork mps, tntNetwork mpo)
 
tntComplex tntMpsMpoMpsContract (tntNetwork sandwich)
 
void tntMpsMpsConnect (tntNetwork mpsA, tntNetwork mpsB)
 
tntComplex tntMpsMpsContract (tntNetwork sandwich, int site_left, int site_right, tntNode beta, tntNode gamma)
 
tntIntArray tntMpsOpGetQN (tntNode op)
 
double tntMpsTruncate (tntNetwork mps, unsigned orth_centre, int chi)
 

Function Documentation

tntNetwork tntMpoHC ( tntNetwork  mpoO)

Returns the hermitian conjugate of an MPO, i.e. takes the complex conjugate, flips the physical legs (so takes the transpose) and switches the direction of the legs if they carry quantum number info. The input network is unchanged.

Returns
The hermitian conjugate of the input MPO.

Definition at line 161 of file tntMpoMpo.c.

References tntNetworkConjCopy(), tntNodeFindConn(), tntNodeFindFirst(), and tntNodeMapLegs().

void tntMpoPmpoProduct ( tntNetwork  mpo,
tntNodeArray *  op,
tntIntArray *  sitenum 
)

Applies on more single-site operators op[i] to the 'ket' (downward) physical legs of an MPO.

single_site_op.png

This set of single site operators represent a site-wide MPO formed from a tensor product of operators on every site, where the operator on any site not given is the identity operator. Site numbers count from 0. They do not need to be in a particular order, but they should be in the same order as op. Each of the specified operators is inserted on the relevant site, then contracted with the physical leg on the MPS. This function therefore represents an MPO-PMPO product.

mps_pmpo.png

This results in another MPO, which replaces the MPO network passed as an argument. The downwards physical legs of the MPO passed as an argument must be free, or an error will result.

Note that the single site operators applied can cause the dimension of the phsyical legs on the MPO to change, if the upwards and downwards facing legs have different dimensions.

Returns
No return value, but the input parameter mpo is altered by having its product taken with the PMPO.
Parameters
mpoThe network representing the MPS. Remains an MPS network, but with altered nodes, after the function is applied.
opArray giving the non-identity single-site operators which define the product MPO
sitenumArray giving the site numbers for each of the operators given in op

Definition at line 84 of file tntMpoPmpo.c.

References tntIntArrayAlloc(), tntIntArrayFree(), tntNodeContract(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), and tntNodeJoin().

Referenced by tntMpoPmpoTrace().

tntNode tntMpoPropTwoSite ( tntNode *  Mlp,
tntNode *  Mrp,
int  chi,
double *  err 
)

Contracts a two-site operator with a pair of MPS nodes which is already connected to the nodes, then performs an SVD. Returns the node S between the two nodes.

Parameters
MlpPoints to the left node of the pair
MrpPoints to the right node of the pair
chiThe maximum internal dimension for the SVD
errTotal truncation error

Definition at line 185 of file tntMpoST2sc.c.

References tntNodeFindConn(), tntNodeMapLegs(), and tntNodeSVD().

Referenced by tntMpoPropSTscContract().

tntNode tntMpsCreateTwoSiteOp ( tntNodeArray *  Lnodes,
tntNodeArray *  Rnodes,
tntComplexArray *  params 
)

Creates a single two-site operator represented by a ::tntNode type, using single site operators. The two-site operator is given as the sum of the tensor product of a number \(n_n\) of pairs (given in the arrays Lnodes and Rnodes) of two one-site operators \(\hat{o}^l_i\) and \(\hat{o}^r_i\). Each pair of operators can be scaled by a parameter \(\alpha_i\) (given in the array params). In summary the returned node is given by \( \hat{T} = \sum_i^{n_n}\alpha_{i}\hat{o}^l_i\otimes\hat{o}^r_i \) or:

twositeop_func.png

The operators have four physical legs, each physical leg having the same dimension as the original physical legs, which are labelled as follows:

two_site_gate.png

All nodes will be static nodes.

If there is a global physical symmetry specified, then symmetry information is applied to the legs. The upwards facing legs are set to be outgoing legs, and the downwards facing legs are set to be incoming legs. Note that if the two-site operators are not invariant under the symmetry type chosen, then some information will be discarded. A warning will be printed (by the core level function) if this is the case.

Returns
The node representing the two site gate.
Parameters
LnodesArray of operators for the left legs
RnodesArray of operators for the right legs that should correspond to those for the left operators
paramsParameters for each two-site term

Definition at line 39 of file tntMpsCreateTwoSiteOp.c.

References tntIntArrayFree(), tntNodeAdd(), tntNodeContract(), tntNodeCopy(), tntNodeFree(), tntNodeGetQN(), tntNodeScaleComplex(), tntNodeSetQN(), tntSymmTypeGet(), and tntSysBasisOpGet().

Referenced by tntMpsCreatePropArray().

void tntMpsMpoConnect ( tntNetwork  mps,
tntNetwork  mpo 
)

Creates a network that consists of an MPS connected to an MPO.

mps_mpo.png

As illustrated above, it connects up starting and ending singleton legs of the MPO with newly added singleton legs on the MPS.

If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the returned network represents \(\hat{O}|\psi\rangle \).

A copy of the MPO network is used, and it is connected to the original MPS network. Make a copy of your MPS network first if you require it to be unchanged.

Returns
No return value.
Parameters
mpsNetwork representing the MPS
mpoNetwork representing the MPO

Definition at line 30 of file tntMpsMpo.c.

References tntMpsLength(), tntNetworkCopy(), tntNetworkToNodeGroup(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), and tntNodeJoin().

Referenced by tntMpsMpoProduct().

double tntMpsMpoContract ( tntNetwork  mpsmpo,
int  chi 
)

Contracts an MPS-MPO network e.g. one generated using tntMpsMpoConnect() and at the same time zips through the network returning it to have a state with an orthogonality centre on the first site. The function also truncates during the zip procedure, setting the internal dimension to the parameter \(\chi\) passed in the arguments. If chi is set to -1 then no truncation is performed, other than discarding singular values that are smaller than the truncation tolerance, set through core library function tntSVDTruncTolSet().

The network passed as an argument must have the following form:

mps_mpo.png

First a left to right sweep is performed, contracting the MPO node \(\hat{O}\) with it's corresponding MPS node \(A\), and truncating to the truncation tolerance for singular values (use tntSVDTruncTolSet() to set this) rather than to \(\chi\). The network will now be in the MPS form. The routine then sweeps right to left, truncating to \(\chi\), using tntMpsTruncate().

Returns
Returns the sum of the truncation errors of all the SVDs.
Parameters
mpsmpoNetwork representing the MPS-MPO. Converted to an MPS network by the function.
chiMaximum internal dimension of the new MPS

Definition at line 91 of file tntMpsMpo.c.

References tntMpsLength(), tntMpsTruncate(), tntNodeContract(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFuse(), tntNodeGroupFree(), tntNodeInsertAtStart(), tntNodeJoin(), tntNodeMapLegs(), tntNodeSplit(), and tntNodeSVD().

Referenced by tntMpsMpoProduct().

tntNetwork tntMpsMpoMpsConnect ( tntNetwork  mps,
tntNetwork  mpo 
)

Returns a network that consists of an MPS and its flipped counterpart with an MPO inserted between them i.e.

mps_mpo_mps.png

If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the returned network represents \(\langle\psi|\hat{O}|\psi\rangle \).

Copies of the original networks are used, and the original networks are unchanged.

Returns
The MPS-MPO-MPS network illustrated above.
Parameters
mpsNetwork representing the MPS
mpoNetwork representing the MPO

Definition at line 25 of file tntMpsMpoMps.c.

References tntMpsLength(), tntMpsMpsConnect(), tntNetworkCopy(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeInsert(), and tntNodeJoin().

Referenced by tntMpsMpoMpsInit(), tntMpsMpoMpsInitOrth(), and tntMpsMpoMpsProduct().

tntComplex tntMpsMpoMpsContract ( tntNetwork  sandwich)

Contracts an MPS-MPO-MPS network sandwich e.g. one generated using tntMpsMpoMpsConnect() to return a scalar complex value.

The sandwich network passed as an argument must have the following form:

mps_mpo_mps.png

There is no requirement for the MPS networks forming the top and bottom of the network to be the same, or any requirement on the dimensions in the network. The network is destroyed by the function, so a copy should be made first if it will be required later.

Returns
A complex scalar value that is the result of the network contraction.
Parameters
sandwichNetwork representing the MPS-MPO-MPS sandwich. Destroyed by the function.

Definition at line 94 of file tntMpsMpoMps.c.

References tntMpsLength(), tntNetworkFree(), tntNodeFindConn(), tntNodeFindFirst(), and tntNodeGetFirstEl().

Referenced by tntMpsMpoMpsProduct().

void tntMpsMpsConnect ( tntNetwork  mpsA,
tntNetwork  mpsB 
)

Flips an MPS mpsB and joins it to the original MPS mpsA along the physical legs. The flipping operation involves:

  • renumbering the downwards facing physical leg as an upwards facing physical leg
  • taking the complex conjugate of the tensor elements in each node
  • if symmetry information is defined, turning the physical leg from an incoming leg to an outgoing leg.

If the original MPSs mpsA, mpsB represent a wave functions \(|\psi_\mathrm{A}\rangle\), \(|\psi_\mathrm{B}\rangle\) then the new MPS network is \(\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle\).

If any of the physical legs are already connected to something, this function will result in an error.

The function copies, node by node, each MPS node in mpsB and connects the flipped version to the network mpsA. Once the function is complete, the network mpsA will look like the following:

mpsA_mpsB.png

The network mpsB will be unchanged as a copy is used. Note that passing the same network for both arguments is permitted, although in this case mpsB is changed in the same way as mpsA since they are the same network.

Returns
No return value.
Parameters
mpsAThe MPS network to join the flipped network to. On entry: An MPS network with all physical legs unconnected. On exit: An MPS network with all physical legs connected to the flipped MPS network for mpsB.
mpsBThe MPS network to flip and connect to mpsA. Unchanged by the function.

Definition at line 38 of file tntMpsMps.c.

References tntMpsLength(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeJoin(), and tntNodeMapLegs().

Referenced by tntMpsMpoMpsConnect(), tntMpsMpsProduct(), tntMpsPmpoMpsProduct(), tntMpsSelfInit(), and tntMpsSelfProduct().

tntComplex tntMpsMpsContract ( tntNetwork  sandwich,
int  site_left,
int  site_right,
tntNode  beta,
tntNode  gamma 
)

Calculates the inner product of two MPSs joined to form a network as follows:

mpsA_mpsB.png

Note the MPSs forming the top and bottom parts of the sandwich do not have to be the same. If the original MPSs mpsA, mpsB represent a wave functions \(|\psi_\mathrm{A}\rangle\), \(|\psi_\mathrm{B}\rangle\) then this represents the inner product \(|\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle|^2\).

This network can be created using function tntMpsMpsConnect(), where the MPSs forming the top or bottom of the network can be the same MPS of different MPSs.

The function can be made more efficient by make use of orthogonality centres of the MPS.

This can then reduce the number of contractions required to find the expectation value. If either site_left or site_right is -1, then a full contraction is performed.

Note that after a left to right TEBD or DMRG sweep, the orthogonality centre will be the last site, and after a right to left sweep, the orthonormality centre will be the first site.

Returns
The complex value of the inner product of the MPS-MPS network, equivalent to \(|\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle|^2\) if the MPSs represent wave functions.

Calculates the inner product of two MPSs joined to form a network as follows:

mpsA_mpsB.png

Note the MPSs forming the top and bottom parts of the sandwich do not have to be the same. If the original MPSs mpsA, mpsB represent a wave functions \(|\psi_\mathrm{A}\rangle\), \(|\psi_\mathrm{B}\rangle\) then this represents the inner product \(|\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle|^2\).

This network can be created using function tntMpsMpsConnect(), where the MPSs forming the top or bottom of the network can be the same MPS of different MPSs.

This function takes as optional additional arguments pre-contracted segments for the left and right parts of the network. If either or both of these are NULL, and the respective site_left and site_right are not -1, then the respective orthonormalisation condition is used i.e. all sites to the right of site_right should obey the right orthonormalisation condition:

right_orth.png

All sites to the left of site_left should obey the left orthonormalisation condition:

left_orth.png

If site_left and site_right are not -1, and precontracted parts of the network are provided, then the pre-contracted network is inserted instead of the identity.

Returns
The complex value of the inner product of the MPS-MPS network, equivalent to \(|\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle|^2\) if the MPSs represent wave functions.
Parameters
sandwichThe network representing the MPS-MPS sandwich. Destroyed by the function.
site_leftAll sites to the left of this obey the left orthonormalisation condition. Use -1 for full contraction.
site_rightAll sites to the right of this obey the right orthonormalisation condition. Use -1 for full contraction.
betaNode formed from contracting all nodes to the left of site_left. Unchanged by function. Send NULL if the identity should be used instead.
gammaNode formed from contract all nodes to the right of site_right. Unchanged by function. Send NULL if the identity should be used instead

Definition at line 150 of file tntMpsMps.c.

References tntMpsLength(), tntNetworkFree(), tntNetworkSplit(), tntNodeContract(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeGetFirstEl(), and tntNodeJoin().

Referenced by tntMpsMpsProduct(), tntMpsPmpoMpsProduct(), and tntMpsSelfProduct().

tntIntArray tntMpsOpGetQN ( tntNode  op)

Determines the overall QN of a single site operator i.e. an operator with two physical legs labels "D" (rows) and "U" (columns).

Returns
An array giving the quantum number of the oeprator.

Definition at line 51 of file tntMpsUtil.c.

References tntIntArrayAlloc(), tntIntArrayFree(), tntNodeAddLeg(), tntNodeCopy(), tntNodeFree(), tntNodeGetQN(), tntNodeIsCovariant(), tntNodeMakeCovariantQN(), tntNodeSetQN(), tntSymmNumGet(), and tntSysBasisOpGet().

Referenced by tntMpsCreateMpo().

double tntMpsTruncate ( tntNetwork  mps,
unsigned  orth_centre,
int  chi 
)

Sweeps through the MPS performing a sequence of truncated SVDs and contractions, to leave the every node apart from the orthogonality centre either left or right orthonormalised.

It does not assume anything about the initial orthonormality properties of the MPS. It simply starts from the left-most site performing truncated SVDs until the orthogonality centre is reached (obviously this has no effect if the orthogonality centre is the first site). It then starts from the right-most site performing truncated SVDs until the orthogonality centre is reached (obviously this has no effect if the orthogonality centre is the last site).

After applying the routine, every node to the left of the orthogonality centre will obey the left orthonormalisation condition:

left_orth.png

and every node to the right of the orthogonality centre will obey the right orthonormalisation condition:

right_orth.png

To internal dimension will be set by the minimum of the dimension \(\chi\) given as an argument or the one that results from the global truncation tolerance (set using tntSVDTruncTolSet()). To truncate to the global truncation tolerance only, set the argument chi to -1.

Returns
The sum of the truncation errors of all the SVDs.
See Also
Use tntMpsOrth() for a routine that orthogonalises the MPS without any truncation (i.e. with the truncation tolerance turned off).
Parameters
mpsThe MPS network to truncate
orth_centreThe required orthogonality centre of the MPS.
chiMaximum internal dimension of the new MPS. Use -1 to truncate to the truncation tolerance only.

Definition at line 44 of file tntMpsTruncate.c.

References tntMpsLength(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), and tntNodeSVD().

Referenced by tntMpsMpoContract(), and tntMpsOrth().