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 Library

Detailed Description

This library can be used in addition to the core library (libtnt.a), and contains network functions for matrix product states (MPS) in systems with open boundary conditions. The functions in this library are available by linking to the static library libtntMps.a.

These functions assume an MPS network of the following form:

mps.png

where the diamonds represent the network start and end, and the dashed lines represent singleton legs. The left internal leg is labelled with constant "L", the right internal leg is labelled with "R", and the physical leg is labelled with "D".

The functions also currently accept three types of operators:

Matrix product operators (MPOs)

An MPO network is a site-wide operator, formed from nodes having two physical legs (labelled "L" and "R") and two internal legs (labelled "U" and "D").

When joined along the internal legs to form a network, they can represent a site-wide operator that does not necessarily have to be able to be expressed as a product of single-site operators.

mpo_op_nw.png

Although these types of MPOs are not restricted to this, the library functions are currently able to build site-wide operators formed from a sum of nearest neighbour and on-site terms. The internal dimension (i.e. the size of the left and right legs) will be equal to the number of nearest-neighbour terms + 2.

To build an MPO, either use the function tntMpsProcessInitOptions() to create the system (including an MPO) from parameters specified on the command line, or prepare an MPO using single site operators (see below) within your function using tntMpsCreateMpo().

Single site operators or produt MPOs

These should have two physical legs, labelled as shown below.

single_site_op.png

They can be thought of as a subset of the MPOs described above, with an internal dimension of 1, so that the legs do not have to be specified.

To create the most common operators within your code use tntMpsCreateBosonOp() and tntMpsCreateSpinOp().

To create these operators in a MATLAB initialisation script you can use the function tntMatCreateOpArray() and then use tntNodesLoad() or tntNodeArraysLoad() to load these nodes from your .mat file as usual.

Two-site gates or propagators

These should have four physical legs, labelled "U" and "V" for the left and right upwards facing legs and "D" and "E" for the left and right downwards facing legs.

The can be created from single site operators using the library functions tntMpsCreateTwoSiteOp().

To create these operators in a MATLAB initialisation script you can use the function tntMatCreate2sitesOpArray() and then use tntNodesLoad() or tntNodeArraysLoad() to load these nodes from your .mat file as usual.

Modules

 MPS driver routines
 
 Command line
 

Macros

#define tntMpsExOp   tntExOp
 

Functions

void tntMpoExpecOutput (tntNetwork rho, tntMpsExOp *Op, unsigned printOutput, unsigned saveOutput, char *savename, unsigned counter)
 
tntNetwork tntMpoMpoProduct (tntNetwork mpoO, tntNetwork mpoP)
 
tntComplex tntMpoMpoTrace (tntNetwork mpoO, tntNetwork mpoP)
 
tntComplex tntMpoPmpoTrace (tntNetwork mpo, tntNodeArray *op, tntIntArray *sitenum)
 
double tntMpoPropST2scProduct (tntNetwork mpo, tntNetwork PropB, tntNetwork PropT, int chi)
 
tntComplex tntMpoTrace (tntNetwork mpo)
 
tntNetwork tntMpsAdd (tntNetwork mpsA, tntNetwork mpsB, int orthresult)
 
void tntMpsCreateBosonOp (unsigned n_max, tntNode *b, tntNode *bdag, tntNode *n, tntNode *os_int, tntNode *eye)
 
tntNetwork tntMpsCreateConfig (unsigned L, const char *config)
 
tntNetwork tntMpsCreateEyeMpo (unsigned L, tntNode basisOp)
 
tntNetwork tntMpsCreateMpo (unsigned L, tntNodeArray *nnl, tntNodeArray *nnr, tntComplexArray *nnparam, tntNodeArray *os, tntComplexArray *osparam, unsigned ignoreQN)
 
tntNetwork tntMpsCreateProductMpo (unsigned L, tntNodeArray *op, tntIntArray *sitenum)
 
tntNetwork tntMpsCreatePropST2sc (unsigned L, tntComplex dtc, tntNodeArray *nnL, tntNodeArray *nnR, tntComplexArray *nnparam, tntNodeArray *os, tntComplexArray *osparam)
 
tntNetwork tntMpsCreateRandom (unsigned L, unsigned D)
 
void tntMpsCreateSpinOp (unsigned TwoS, tntNode *Sx, tntNode *Sy, tntNode *Sz, tntNode *Sp, tntNode *Sm, tntNode *eye)
 
tntNetwork tntMpsCreateSymmRandom (unsigned L, int *qn)
 
void tntMpsExOpFree (tntMpsExOp *ExOp)
 
void tntMpsExpecOutput (tntNetwork mps, tntMpsExOp *Op, int orthCentre, unsigned printOutput, unsigned saveOutput, char *savename, unsigned counter)
 
unsigned tntMpsLength (tntNetwork mps)
 
void tntMpsMpoMpsInit (tntNetwork mps, tntNetwork mpo, tntNodeArray *betas, tntNodeArray *gammas)
 
void tntMpsMpoMpsInitOrth (tntNetwork mps, tntNetwork mpo, tntNodeArray *betas, tntNodeArray *gammas)
 
tntComplex tntMpsMpoMpsPartProduct (tntNetwork mps, tntNetwork mpo, unsigned site_left, unsigned site_right, tntNode beta, tntNode gamma)
 
tntComplex tntMpsMpoMpsProduct (tntNetwork mps, tntNetwork mpo)
 
double tntMpsMpoProduct (tntNetwork mps, tntNetwork mpo, int chi)
 
tntComplex tntMpsMpsProduct (tntNetwork mpsA, tntNetwork mpsB)
 
double tntMpsNodeNodeMpsProduct (tntNetwork mps, tntNode op, unsigned sitenum)
 
void tntMpsNodeProduct (tntNetwork mps, tntNode op, unsigned sitenum)
 
void tntMpsOrth (tntNetwork mps, unsigned orth_centre)
 
void tntMpsOrthNorm (tntNetwork mps, unsigned orth_centre)
 
tntComplex tntMpsPmpoMpsProduct (tntNetwork mps, tntNodeArray *op, tntIntArray *sitenum, int orth_centre, tntNodeArray *betas, tntNodeArray *gammas)
 
void tntMpsPmpoProduct (tntNetwork mps, tntNodeArray *op, tntIntArray *sitenum)
 
double tntMpsPropST2scProduct (tntNetwork mps, tntNetwork Prop, int chi)
 
void tntMpsSelfInit (tntNetwork mps, tntNodeArray *betas, tntNodeArray *gammas)
 
double tntMpsSelfProduct (tntNetwork mps, int orth_centre)
 
double tntMpsVarMinMpo1sStep (tntNetwork mps, int chi, tntNetwork mpo, tntNodeArray *HeffL, tntNodeArray *HeffR, double *err, unsigned start_site)
 
double tntMpsVarMinMpo2sStep (tntNetwork mps, int chi, tntNetwork mpo, tntNodeArray *HeffL, tntNodeArray *HeffR, double *err, unsigned start_site)
 

Macro Definition Documentation

#define tntMpsExOp   tntExOp

A structure that includes information about all the expectation values that should be taken.

Examples:
tntEvolve_cl.c, tntGS_cl.c, and tntThermal_cl.c.

Definition at line 75 of file tntMps.h.

Function Documentation

void tntMpoExpecOutput ( tntNetwork  rho,
tntMpsExOp Op,
unsigned  printOutput,
unsigned  saveOutput,
char *  savename,
unsigned  counter 
)

Calculates various types of one-site and two-site expectation values for the density matrix \(\rho\) represented by the MPO, the operators for which are passed in the tntMpsExOp structure.

The function can output the expectation values to the screen as well as saving them to the named output file. Use the appropriate flags to specify whether results should be output to the screen or to an output file. The function will have no effect (and nothing will be calculated) if both the screen output flag is 0 and the printOutput flag is 0 - in this case a warning will be printed to screen but execution will continue.

Note the expecation value of operator \( \hat{o} \) is given by \( \mathrm{Tr}(\rho\hat{o})/\mathrm{Tr}(\rho) \) i.e. it uses the normalised value of the MPO density matrix. However the function does not renormalise the MPO density matrix to do this - it simply divides by the norm. The value of the norm will be printed to the screen and saved to the output file if the appropriate flags are given.

Returns
No return value - the expectation values are output to the screen and/or to an output file.
See Also
tntMpsProcessExpecOptions() for a function which converts command line arguments to the arrays of operators that are required by this function.
Parameters
rhoThe network representing the density matrix. Unchanged by the function.
OpThe operators for calculating expectation values
printOutputSet to 1 to print expectation values to screen, 0 otherwise
saveOutputSet to 1 to save values to output file, 0 otherwise
savenamePath to the output file. If the extension is missing ".mat" is added. Only used if saveOutput is 1.
countercan be used if saving multiple batches of expectation values e.g. for different timesteps. Added as a suffix to the variable name, if a non-zero value is given. Pass zero if a counter is not required.

Definition at line 32 of file tntMpoExpecOutput.c.

References tntComplexArrayAlloc(), tntComplexToReal(), tntDoubleParamsSave(), tntDoubleParamsUpdate(), tntIntArrayAlloc(), tntIntArrayFree(), tntMpoPmpoTrace(), tntMpoTrace(), tntNodeArrayAlloc(), tntNodeArrayFree(), tntNodeCopy(), tntNodeFree(), tntPrintf(), tntSysQNClearWarnOff(), and tntSysQNClearWarnOn().

tntNetwork tntMpoMpoProduct ( tntNetwork  mpoO,
tntNetwork  mpoP 
)

Contracts one MPO network \(\hat{O}\) with another MPO network \(\hat{P}\) as illustrated (TBC) i.e. the first MPO network is on top and would be applied to any MPS network first. The result is returned in a new MPO network. Uses copies of the MPO networks, so they are unchanged by the function. If they are no longer required after this function is called they should be deleted using tntNetworkFree().

Returns
The MPO network that represents the operator \(\hat{P}\hat{O}\).
Parameters
mpoOAn MPO network with downwards physical legs unconnected.
mpoPAn MPO network with upwards physical legs unconnected.

Definition at line 24 of file tntMpoMpo.c.

References tntNetworkCopy(), tntNetworkToNodeGroup(), tntNodeContract(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFuse(), and tntNodeJoin().

tntComplex tntMpoMpoTrace ( tntNetwork  mpoO,
tntNetwork  mpoP 
)

Contracts one MPO network \(\hat{O}\) with another MPO network \(\hat{P}\) as illustrated (TBC) then takes the trace The result is returned in a new MPO network. Uses copies of the MPO networks, so they are unchanged by the function. If they are no longer required after this function is called they should be deleted using tntNetworkFree().

Returns
The MPO network that represents the operator \(\hat{P}\hat{O}\).
Parameters
mpoOAn MPO network with downwards physical legs unconnected.
mpoPAn MPO network with upwards physical legs unconnected.

Definition at line 87 of file tntMpoMpo.c.

References tntNetworkCopy(), tntNetworkFree(), tntNetworkToNodeGroup(), tntNodeContract(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeGetFirstEl(), and tntNodeJoin().

tntComplex tntMpoPmpoTrace ( tntNetwork  mpo,
tntNodeArray *  op,
tntIntArray *  sitenum 
)

Calculates the trace of an MPO network with zero or more single-site operators op[i] representing a product MPO (PMPO) with the following form inserted on the physical legs

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. Each of the specified operators is inserted on the relevant site, then contracted with the physical leg on the MPO to form a new MPO. The trace of the MPO is then taken.

mps_pmpo_mps.png

If multiple operators are given for a single site, then they will be applied to the wave function in the order they are given in the array i.e. in the figure above the operators given first will be on top.

Returns
The trace of the MPO network mulitplied with the product MPO.
Parameters
mpoThe network representing the MPO. Unchanged by the function.
opArray giving the non-identity single-site operators which define the product MPO. Operators are assumed to have 2 legs, with upwards facing leg having number 4, and downwards facing leg having number 3. Unchanged by the function.
sitenumArray giving the site numbers for each of the operators given in op. 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. Unchanged by the function.

Definition at line 35 of file tntMpoPmpo.c.

References tntMpoPmpoProduct(), tntMpoTrace(), tntNetworkCopy(), and tntNetworkFree().

Referenced by tntMpoExpecOutput().

double tntMpoPropST2scProduct ( tntNetwork  mpo,
tntNetwork  PropB,
tntNetwork  PropT,
int  chi 
)

Performs a single step of a second order Suzuki-Trotter staircase expansion of a site-wide propagator.

propst2sc.png

A network as that pictured above must be provided for the propagator i.e. with the gates applied in a zip across first left to right, then right to left. A suitable propagator can be built using tntMpsCreatePropST2sc(). The entire propagator is then pre and post multiplied with the MPO i.e. a sweep in both directions is performed.

The orthogonality centre of the MPS should be on the first site before applying the step, and will return to the first site after the step.

Returns
The truncation error for that step, which is the sum of the truncation error for all SVDS. The truncation error for each SVD can be defined in a few different ways - see the documentation for tntTruncType() for more details.
Parameters
mpoNetwork representing the MPS wave function. Will be changed by the function, by applying one step of the evolution operator.
PropBA network of two-site operators arranged in a left to right then right to left staircase. Unchanged by function.
PropTA network of two-site operators arranged in a left to right then right to left staircase. Unchanged by function.
chiThe maximum internal dimension. All SVD's will be truncated to this value.

Definition at line 236 of file tntMpoST2sc.c.

References tntMpoPropST2scConnect(), and tntMpoPropSTscContract().

tntComplex tntMpoTrace ( tntNetwork  mpo)

Calculates the trace if an MPO by connecting the bra and ket physical legs, then contracting the entire network to result in a single scalar value

Parameters
mpoThe network representing the MPO. Unchanged by the function.

Definition at line 20 of file tntMpoTrace.c.

References tntNetworkCopy(), tntNetworkFree(), tntNodeContract(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeGetFirstEl(), and tntNodeJoin().

Referenced by tntMpoExpecOutput(), and tntMpoPmpoTrace().

tntNetwork tntMpsAdd ( tntNetwork  mpsA,
tntNetwork  mpsB,
int  orthresult 
)

Adds two MPS networks together as a 'vector' sum. i.e. if each mpsA and mpsB each represents a state \(|\psi_A\rangle\) and \(|\psi_B\rangle\) respectively, the function will return the superposition \(|\psi_A\rangle+|\psi_B\rangle\). After performing the addition, the resulting network is orthonormalised to the orthogonality centre given in the final argument. If no orthonormalisation is required, and the result should be returned as-is, pass -1 for the last argument. The incoming networks are unchanged.

Returns
A network representing the MPS sum.
Parameters
mpsAFirst MPS network to add
mpsBSecond MPS network to add

Definition at line 123 of file tntMpsUtil.c.

References tntMpsLength(), tntMpsOrthNorm(), tntNetworkCreate(), tntNodeDirectSum(), tntNodeFindConn(), tntNodeFindFirst(), and tntNodeInsertAtEnd().

void tntMpsCreateBosonOp ( unsigned  n_max,
tntNode *  b,
tntNode *  bdag,
tntNode *  n,
tntNode *  os_int,
tntNode *  eye 
)

Creates single site operators for bosonic systems, with two legs (i.e. no internal legs), numbered to match those expected by the MPS library functions:

single_site_op.png

Each leg will have dimension \(n_\mathrm{max}+1\), where \(n_\mathrm{max}\) is the maximum number of bosons on each site.

All nodes are created as static nodes.

Only pointers to the required nodes need be passed as arguments. If any of the nodes are not required, then pass NULL.

Returns
No return value.
Parameters
n_maxMaximum number of bosons allowed on each site
bNode for annihilation operator \(\hat{b}\)
bdagNode for creation operator \(\hat{b}^{\dagger}\)
nNode for \(n = \hat{b}^{\dagger}\hat{b}\)
os_intNode for onsite interaction term \(\hat{n}(\hat{n}-1) = \hat{b}^{\dagger}\hat{b}^{\dagger}\hat{b}\hat{b}\)
eyeNode for the identity matrix with dimension \(n_\mathrm{max}+1\)

Definition at line 29 of file tntMpsCreateBosonOp.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayAlloc(), tntIntArrayFree(), tntNodeContract(), tntNodeCopy(), tntNodeCreate(), tntNodeCreateEyeOp(), tntNodeFree(), tntNodeJoin(), tntNodeMapLegs(), tntNodeSetQN(), and tntSymmTypeGet().

Referenced by tntMpsProcessExpecOptions(), and tntMpsProcessSysOptions().

tntNetwork tntMpsCreateConfig ( unsigned  L,
const char *  config 
)

Creates an MPS network which represents a single configuration of a system. The the basis for the configuration is given by the basis operator set for the global system properties e.g. using the function tntSysBasisOpSet(), see below for more details. All internal legs will have dimension 1.

mps.png

The configuration should be expressed as a string of numbers from \(0\) to \(d-1\). If the length of the string is greater than the number of nodes in the network, then the extra characters (to the right) will be ignored. If the length of the string is smaller than the number of sites, then the rest of the sites will be filled with the first basis vector.

The MPS will have a norm of 1, and will have an orthogonality centre on every site.

The basis operator defines the properties of the physical legs, and should define the local physical eigenbasis for the system e.g. for a boson system this would be the number operator \(\hat{n}\), while for a spin system it would be the operator \(\hat{s}_z\). Operators having the correct format can be generated using the functions tntMpsCreateSpinOp() and tntMpsCreateBosonOp(), or can be loaded from an initialisation file. If a global physical symmetry has been set, then the quantum number information is also set on the physical and internal network legs. If loading your operators from an initialisation file, you must ensure that the upwards facing physical leg is labelled "U", and the downwards facing physical leg is labelled "D":

single_site_op.png
Returns
The network corresponding to the configuration matrix product state.
Parameters
LNumber of nodes in the MPS network
configString representing the configuration of the MPS

Definition at line 35 of file tntMpsCreateConfig.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayAlloc(), tntIntArrayFree(), tntNetworkCreate(), tntNodeCreate(), tntNodeGetLegDim(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeMakeCovariantQN(), tntNodeSetQN(), tntSymmNumGet(), tntSymmTypeGet(), and tntSysBasisOpGet().

Referenced by tntMpsProcessSysOptions().

tntNetwork tntMpsCreateEyeMpo ( unsigned  L,
tntNode  basisOp 
)

Creates an MPO network represeting a site-wide identity operator \(\mathbb{1}_N\) where the operator elements are explicity defined. Although this operator has no effect, it may provide a useful starting point for calculations where an MPO needs to be modified in some way. A basis operator for defining the physical leg properties can be supplied in the argument, which may or may not include quantum number information. The operatory must be a sinlge site operator in the standard format i.e. having two lages labelled "U" and "D" If no argument is given, then the basis operator is used instead.

Returns
The network representing the identity matrix product operator.
Parameters
LLength of the MPO
basisOpThe operator used to define the physical legs of the MPO. If NULL is passed the basis operator is used.

Definition at line 19 of file tntMpsCreateEyeMpo.c.

References tntNetworkCreate(), tntNodeAddLeg(), tntNodeCopy(), tntNodeCreateEyeOp(), tntNodeFree(), and tntNodeInsertAtStart().

Referenced by tntMpsCreateProductMpo(), and tntMpsProcessSysOptions().

tntNetwork tntMpsCreateMpo ( unsigned  L,
tntNodeArray *  nnl,
tntNodeArray *  nnr,
tntComplexArray *  nnparam,
tntNodeArray *  os,
tntComplexArray *  osparam,
unsigned  ignoreQN 
)

Creates an MPO network represeting a site-wide operator \(\hat{O}\) formed from a sum of nearest-neighbour and onsite terms.

\[ \hat{O} = \sum_{j=0}^{L-2}\sum_i^{n_n}\alpha_{i,j}\hat{o}^l_{i}\otimes\hat{o}^r_i + \sum_{j=0}^{L-1}\sum_i^{n_o}\beta_{i,j}\hat{o}^s_{i} \]

Nearest-neighbour operators \(\hat{o}^l_{i}\) and \(\hat{o}^r_i\) should be provided in arrays nnl and nnr respectively both having length \(n_n\). Onsite operators \(\hat{o}^s_{i}\) should be provided in array os having length \(n_o\). The operators should be single-site operators or product MPOs, i.e. no internal legs, and two physical legs with the legs labelled as follows:

single_site_op.png

All the operators should have the same dimension for the physical legs.

The parameters \(\alpha_{i,j}\) and \(\beta_{i,j}\) for the nearest neighbour are onsite terms are supplied in matrices nnparam and osparam respectively. The matrix must have a number of rows equal to the length \(n_n, n_o\) of its respective operators array, but there are two options for the number of columns:

  1. All the parameters are uniform accross the lattice. In this case the parameters array should have one column (which is the default behaviour if it is created with only one dimension specified). The parameter \(\alpha_{i,j}\) or \(\beta_{i,j}\) should be in position i,1 in the matrix for all sites.
  2. One or more of the parameters can vary accross the lattice. In this case the parameters matrix should have L-1 columns for nearest neighbour operators and L columns for onsite operators. The parameter \(\alpha_{i,j}\) or \(\beta_{i,j}\) for operator i and site j should be at position i,j in the matrix. Any uniform operators should have identical entries for all the sites.

A non-product site-wide MPO is then created which represents the sum of these operators, where now each operator in the network will have non-singleton dimension internal legs. The physical legs will have the same dimension as the original single-site operators, the internal legs will have a dimension equal to the number of nearest neighbour terms + 2. The legs are labelled as follows:

mpo_op_sing.png

They are connected to form the complete network:

mpo_op_nw.png
Returns
The network representing the matrix product operator.
Parameters
LLength of system.
nnlArray of nearest neighbour operators for left site. Send NULL if there are no nearest neighbour terms.
nnrArray of nearest neighbour operators for right site. Send NULL if there are no nearest neighbour terms.
nnparamArray of parameters for nearest neighbour operators. Send NULL if there are no nearest neighbour terms.
osArray of on-site operators. Send NULL if there are no on-site operators.
osparamParameters for the on-site operators. Send NULL if there are no on-site operators.
ignoreQNOptional last argument. If it is set to 1, then even if symmetries are turned on for your system, they will not be applied to this MPO
Examples:
tntEvolve_if.c.

Definition at line 52 of file tntMpsCreateMpo.c.

References tntComplex::im, tntComplex::re, tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayAlloc(), tntIntArrayFree(), tntMpsOpGetQN(), tntNetworkCreate(), tntNodeAdd(), tntNodeContract(), tntNodeCopy(), tntNodeCreate(), tntNodeCreateEyeOp(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeFree(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeInsertAtStart(), tntNodeScaleComplex(), tntNodeSetQN(), tntSymmNumGet(), tntSymmTypeGet(), tntSysBasisOpGet(), tntSysQNClearWarnOff(), and tntSysQNClearWarnOn().

Referenced by tntMpsProcessSysOptions().

tntNetwork tntMpsCreateProductMpo ( unsigned  L,
tntNodeArray *  op,
tntIntArray *  sitenum 
)

Creates an MPO network represeting a site-wide operator \(\hat{O}\) formed from a product of \(n\) onsite terms \(\hat{o}_{i}\).

\[ \hat{O} = \prod_{i=0}^{n}\hat{o}_{i} \]

Each term \(\hat{o}_{i}\) acts on a single site \(j\) given by the entries of the array sitenum. If there is more than one operator on a site they will be contracted together to form a single operator such that the operator that appears first will be applied first. If a site does not appear in the list of site numbers, an identity operator will be placed there instead. The tensor product is represented as a network, having the same form as a non-product MPO (e.g. as created using tntMpsCreateMPO()). However unlike a non-product MPO in this this case all the internal legs (left and right legs) will have dimension 1.

mps_pmpo.png

This function therefore creates a product MPO that can be used in any of the general MPS-MPO functions However, if all that is required is a simple MPS-PMPO-MPS contraction or MPS-PMPO contraction without any quantum number conservation, it is recommended to use the tntMpsPmpo*() functions rather than creating an MPO using this function. This is because the PMPO functions can take advantage of the orthogonality properties of the MPS, and that fact that contractions with identity do no need to be carried out, to provide a more efficient algorithm.

This function should be used, however, if QN conservation is turned on, and you wish to apply operators that are not U(1) invariant, but are U(1) covariant. This would be an operator which changes the total quantum number of any state it is applied to (e.g. increases boson number), but keeps the MPS as an eigenstate of that quantum number (e.g. it will still have a well-defined total number of bosons in the system). Operators of this type are ladder operators (e.g. \(\hat{b}\) and \(\hat{b}^{\dagger}\)). The function allows these operators to be applied, while keeping track of quantum number information, by assigning suitable quantum numbers to the internal legs of the MPO to make the tensors in the MPO invariant.

Returns
The network representing the matrix product operator.
Parameters
LLength of system.
opArray of on-site operators.
sitenumSitenumbers for the operators

Definition at line 37 of file tntMpsCreateProductMpo.c.

References tntIntArrayAlloc(), tntIntArrayFree(), tntMpsCreateEyeMpo(), tntMpsPmpoProduct(), tntNodeClearQN(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeGetQN(), tntNodeIsCovariant(), tntNodeMakeCovariantQN(), tntNodeSetQN(), tntSymmNumGet(), tntSymmTypeGet(), tntSysBasisOpGet(), tntSysQNClearWarnOff(), and tntSysQNClearWarnOn().

Referenced by tntMpsNodeProduct().

tntNetwork tntMpsCreatePropST2sc ( unsigned  L,
tntComplex  dtc,
tntNodeArray *  nnL,
tntNodeArray *  nnR,
tntComplexArray *  nnparam,
tntNodeArray *  os,
tntComplexArray *  osparam 
)

Creates a network of two-site terms representing a site-wide propagator decomposed using a Suzuki-Trotter second-order staircase expansion. The propagator evolves under a site-wide operator \(\hat{O}\) formed from a sum of nearest-neighbour and onsite terms for a timestep of size dtc.

\[ \hat{O} = \sum_{j=0}^{L-2}\sum_i^{n_n}\alpha_{i,j}\hat{o}^l_{i}\otimes\hat{o}^r_i + \sum_{j=0}^{L-1}\sum_i^{n_o}\beta_{i,j}\hat{o}^s_{i} \]

The two-site propagators are formed using tntMpsCreatePropArray() using half the time-step as the uniform scale factor.

Nearest-neighbour operators \(\hat{o}^l_{i}\) and \(\hat{o}^r_i\) should be provided in arrays nnl and nnr respectively both having length \(n_n\). Onsite operators \(\hat{o}^s_{i}\) should be provided in array os having length \(n_o\). The operators should be single-site operators or product MPOs, i.e. no internal legs, and two physical legs with the legs labelled as follows:

single_site_op.png

All the operators should have the same dimension for the physical legs.

The parameters \(\alpha_{i,j}\) and \(\beta_{i,j}\) for the nearest neighbour are onsite terms are supplied in matrices nnparam and osparam respectively. The matrix must have a number of rows equal to the length \(n_n, n_o\) of its respective operators array, but there are two options for the number of columns:

  1. All the parameters are uniform accross the lattice. In this case the parameters array should have one column (which is the default behaviour if it is created with only one dimension specified). The parameter \(\alpha_{i,j}\) or \(\beta_{i,j}\) should be in position i,1 in the matrix for all sites.
  2. One or more of the parameters can vary accross the lattice. In this case the parameters matrix should have L-1 columns for nearest neighbour operators and L columns for onsite operators. The parameter \(\alpha_{i,j}\) or \(\beta_{i,j}\) for operator i and site j should be at position i,j in the matrix. Any uniform operators should have identical entries for all the sites.

The two-site operator for the on-site terms is formed from the supplied arguments as

\[ \hat{T}^s_{j,j+1} = \frac{1}{2}\sum_i^{n_o}\left[(\beta_{i,j}+\delta_{0,j}\beta_{i,0})\hat{o}^s_i\otimes\mathbb{1}+(\beta_{i,j+1}+\delta_{L-1,j+1}\beta_{i,L-1})\mathbb{1}\otimes\hat{o}^s_i\right] \]

for each pair of sites \(j,j+1\) i.e. the onsite terms are distributed symmetrically amongst the two-site terms.

The propagator \(\hat{P}_{j,j+1}\) in array entry j is then related to the operators \(\hat{T}_{j,j+1}=\hat{T}^n_{j,j+1}+\hat{T}^s_{j,j+1}\) by:

\[ \hat{P}_{j,j+1} = \mathrm{exp}\left[-\mathrm{i}\Re(dt)\hat{T}_{j,j+1}/2 \right]\times\mathrm{exp}\left[-\Im(dt)\hat{T}_{j,j+1}/2 \right]. \]

The propagators will then 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

They are then connected in a staircase network from left-to-right, then right-to-left, so the network represents a complete time step.

propst2sc.png

The orange diamonds represent the start and end of the network i.e. the network starts at the top-most propagator and ends at the bottom-most propagator.

See Also
Functions tntMpsPropST2scProduct() for then taking the product of the network with an MPS.
Returns
A network representing the site-wide propagator
Parameters
LLength of system.
dtcSize of the time step. See the main description for information on how real and imaginary parts are applied
nnLArray of nearest-neighbour operators for left site. Send NULL if there are no nearest neighbour terms.
nnRArray of nearest-neighbour operators for right site. Send NULL if there are no nearest neighbour terms.
nnparamArray of parameters for nearest-neighbour operators. Send NULL if there are no nearest neighbour terms.
osArray of onsite operators. Send NULL if there are no on-site operators.
osparamParameters for the on-site operators. Send NULL if there are no on-site operators.

Definition at line 72 of file tntMpsCreateSTstaircase.c.

References tntComplex::im, tntComplex::re, tntMpsCreatePropArray(), tntMpsPropArrayToST2sc(), and tntNodeArrayFree().

Referenced by tntMpsProcessSysOptions().

tntNetwork tntMpsCreateRandom ( unsigned  L,
unsigned  D 
)

Creates an MPS network with random tensor elements and with maximum internal dimension \(D\) having open boundary conditions. The the basis for the configuration is given by the basis operator set for the global system properties e.g. using the function tntSysBasisOpSet(), see below for more details.

mps.png

The MPS will have a norm of 1, and will have an orthogonality centre on every site.

The basis operator defines the properties of the physical legs, and should define the local physical eigenbasis for the system e.g. for a boson system this would be the number operator \(\hat{n}\), while for a spin system it would be the operator \(\hat{s}_z\). Operators having the correct format can be generated using the functions tntMpsCreateSpinOp() and tntMpsCreateBosonOp(), or can be loaded from an initialisation file. If loading your operators from an initialisation file, you must ensure that the upwards facing physical leg is labelled "U", and the downwards facing physical leg is labelled "D":

single_site_op.png
Note
Unless a random number seed is set, each new program will start with the same random number seed. Use tntSysRandSeedSet() to call a different random number stream each time. E.g. tntSysRandSeedSet(time(NULL)) to use the current time as the random number seed.
Returns
The network corresponding to the configuration matrix product state.
Parameters
LNumber of nodes in the MPS network
DMaximum internal dimension for the state

Definition at line 31 of file tntMpsCreateRandom.c.

References tntMpsSelfProduct(), tntNetworkCreate(), tntNodeCopy(), tntNodeCreate(), tntNodeGetLegDim(), tntNodeGroupFree(), tntNodeInsertAtStart(), tntNodeScaleReal(), tntNodeSVD(), and tntSysBasisOpGet().

Referenced by tntMpsCreateSymmRandom(), and tntMpsProcessSysOptions().

void tntMpsCreateSpinOp ( unsigned  TwoS,
tntNode *  Sx,
tntNode *  Sy,
tntNode *  Sz,
tntNode *  Sp,
tntNode *  Sm,
tntNode *  eye 
)

Creates single site operators for spin systems, with two legs (i.e. no internal legs), numbered to match those expected by the MPS library functions:

single_site_op.png

Each leg will have dimension \(2S+1\), where \(S\) is the spin of the particle on each site.

All nodes are created as static nodes.

Pointers to the required nodes should be passed as arguments. If any of the nodes are not required, then pass NULL.

Returns
No return value.
Parameters
TwoSTwice the spin \(S\) of the system.
SxNode for \(\hat{S}^x\)
SyNode for \(\hat{S}^y\)
SzNode for \(\hat{S}^z\)
SpNode for \(\hat{S}^+ = \hat{S}^x + \mathrm{i}\hat{S}^y\)
SmNode for \(\hat{S}^- = \hat{S}^x - \mathrm{i}\hat{S}^y\)
eyeNode for the identity matrix with dimension \(2S+1\)

Definition at line 24 of file tntMpsCreateSpinOp.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayAlloc(), tntIntArrayFree(), tntNodeAdd(), tntNodeCopy(), tntNodeCreate(), tntNodeCreateEyeOp(), tntNodeFree(), tntNodeScaleComplex(), tntNodeScaleReal(), tntNodeSetQN(), and tntSymmTypeGet().

Referenced by tntMpsProcessExpecOptions(), and tntMpsProcessSysOptions().

tntNetwork tntMpsCreateSymmRandom ( unsigned  L,
int *  qn 
)

Creates an MPS network with random tensor elements and with maximum internal dimension \(D\) having open boundary conditions, and with a given total quantum number. If there is no symmetry type set for the system, the quantum number is ignored, and a random MPS with no conservation is created, i.e. this function simply becomes equivalent to tntMpsCreateRandom(). Note: this function only currently works for the U(1) symmetry type. The the basis for the configuration is given by the basis operator set for the global system properties e.g. using the function tntSysBasisOpSet(), see below for more details.

mps.png

The MPS will have a norm of 1, and will have an orthogonality centre on every site.

The basis operator defines the properties of the physical legs, and should define the local physical eigenbasis for the system e.g. for a boson system this would be the number operator \(\hat{n}\), while for a spin system it would be the operator \(\hat{s}_z\). Operators having the correct format can be generated using the functions tntMpsCreateSpinOp() and tntMpsCreateBosonOp(), or can be loaded from an initialisation file. If loading your operators from an initialisation file, you must ensure that the upwards facing physical leg is labelled "U", and the downwards facing physical leg is labelled "D":

single_site_op.png
Note
Unless a random number seed is set, each new program will start with the same random number seed. Use tntSysRandSeedSet() to call a different random number stream each time. E.g. tntSysRandSeedSet(time(NULL)) to use the current time as the random number seed.
Returns
The network corresponding to the configuration matrix product state.
Parameters
LNumber of nodes in the MPS
qnArray containing the total quantum number label for the MPS. Size of array must be symm_num_qn.

Definition at line 33 of file tntMpsCreateSymmRandom.c.

References tntIntArrayAlloc(), tntIntArrayFree(), tntMpsCreateRandom(), tntMpsOrthNorm(), tntNetworkCreate(), tntNodeCreate(), tntNodeGetLegDim(), tntNodeGetNorm(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeScaleReal(), tntNodeSetQN_nowarn(), tntSVDTruncTolGet(), tntSVDTruncTolSet(), tntSymmNumGet(), tntSymmTypeGet(), and tntSysBasisOpGet().

Referenced by tntMpsProcessSysOptions().

void tntMpsExOpFree ( tntMpsExOp ExOp)

Frees all the dynamically allocated memory associated with the structure for holding expectation value operators.

Returns
No return value.
Parameters
ExOpThe operator structure to free.

Definition at line 97 of file tntMpsUtil.c.

References tntNodeArrayFree(), and tntStringArrayFree().

void tntMpsExpecOutput ( tntNetwork  mps,
tntMpsExOp Op,
int  orthCentre,
unsigned  printOutput,
unsigned  saveOutput,
char *  savename,
unsigned  counter 
)

Calculates various types of one-site and two-site expectation values, the operators for which are passed in the tntMpsExOp structure.

The function can output the expectation values to the screen as well as saving them to the named output file. Use the appropriate flags to specify whether results should be output to the screen or to an output file. The function will have no effect (and nothing will be calculated) if both the screen output flag is 0 and the printOutput flag is 0 - in this case a warning will be printed to screen but execution will continue.

Note the expecation value of operator \( \hat{o} \) is given by \( \langle\psi|\hat{o}|\psi\rangle/\langle\psi|\psi\rangle \) i.e. it uses the normalised value of the MPS wave function. However the function does not renormalise the MPS wave function to do this, it simply divides by the norm-squared \( \langle\psi|\psi\rangle \). The value of the norm squared will be printed to the screen and saved to the output file if the appropriate flags are given.

Returns
No return value - the expectation values are output to the screen and/or to an output file.
See Also
tntMpsProcessExpecOptions() for a function which converts command line arguments to the arrays of operators that are required by this function.
Parameters
mpsThe network representing the MPS. Unchanged by the function.
OpThe operators for calculating expectation values
orthCentreOrthogonality centre of the MPS.
printOutputSet to 1 to print expectation values to screen, 0 otherwise
saveOutputSet to 1 to save values to output file, 0 otherwise
savenamePath to the output file. If the extension is missing ".mat" is added. Only used if saveOutput is 1.
countercan be used if saving multiple batches of expectation values e.g. for different timesteps. It appends the values to a pre-exisiting array in the position given by counter. Pass zero if a counter is not required.

Definition at line 37 of file tntMpsExpecOutput.c.

References tntComplexArrayAlloc(), tntDoubleParamsSave(), tntDoubleParamsUpdate(), tntIntArrayAlloc(), tntIntArrayFree(), tntMpsLength(), tntMpsPmpoMpsProduct(), tntMpsSelfInit(), tntMpsSelfProduct(), tntNodeArrayAlloc(), tntNodeArrayFree(), tntNodeCopy(), tntNodeFree(), tntPrintf(), tntSysQNClearWarnOff(), and tntSysQNClearWarnOn().

unsigned tntMpsLength ( tntNetwork  mps)

Counts the number of nodes in the MPS by moving along the internal legs. The result is not altered by any nodes connected to the physical legs (i.e. legs labelled "D"). This function can also be used to count the number of nodes in an MPO.

Returns
The number of nodes in the network.
Parameters
mpsThe network representing the MPS. Unchanged by the function.

Definition at line 17 of file tntMpsUtil.c.

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

Referenced by tntMpsAdd(), tntMpsExpecOutput(), tntMpsMpoConnect(), tntMpsMpoContract(), tntMpsMpoMpsConnect(), tntMpsMpoMpsContract(), tntMpsMpoMpsInit(), tntMpsMpoMpsInitOrth(), tntMpsMpoMpsPartProduct(), tntMpsMpsConnect(), tntMpsMpsContract(), tntMpsNodeProduct(), tntMpsPmpoMpsProduct(), tntMpsPmpoProduct(), tntMpsPropST2scConnect(), tntMpsPropST2scProduct(), tntMpsPropSTscContract(), tntMpsSelfInit(), tntMpsSelfProduct(), tntMpsTruncate(), tntMpsVarMinMpo1sStep(), tntMpsVarMinMpo1sSweep(), tntMpsVarMinMpo2sStep(), and tntMpsVarMinMpo2sSweep().

void tntMpsMpoMpsInit ( tntNetwork  mps,
tntNetwork  mpo,
tntNodeArray *  betas,
tntNodeArray *  gammas 
)

Pre-contracts nodes in the MPS-MPO-MPS network ready for an MPS-MPO-MPS contraction or part-contraction. This can be useful when the same network contraction is required many times. for example when calculating expectation values where only a few sites on the MPO differ each time.

The function performs contractions of this network to form the arrays of pre-contracted nodes \(\mathbf{\beta}\) and \(\mathbf{\gamma}\).

Unlike tntMpsMpoMpsInitOrth(),the function does not move the orthogonality centre.

The array entry \(\beta_j\) is the node that represents all nodes to the left of site \(j\).

mps_dmrg_beta.png

The array entry \(\gamma_j\) is the node that represents all nodes to the right of site \(j\).

mps_dmrg_gamma.png

Note that \(\beta_0\) and \(\gamma_{L-1}\) are simply tensors with all leg dimensions 1 and containing the entry 1.

If only one side of the pre-contracted network is required, then NULL can be passed instead of the pointer to the tntNodeArray.

Returns
No return value.
Parameters
mpsThe wave function of the system.
mpoThe MPO representing the site-wide operator
betasA pointer to the uninitialised array that will contain the left hand nodes
gammasA pointer to the uninitialised array that will contain the right hand nodes

Definition at line 362 of file tntMpsMpoMps.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayFree(), tntMpsLength(), tntMpsMpoMpsConnect(), tntNetworkFree(), tntNodeArrayAlloc(), tntNodeCopy(), tntNodeCreate(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeFree(), tntNodeGetLegDir(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeInsertAtStart(), tntNodeJoin(), tntNodeSetQN(), and tntSymmTypeGet().

void tntMpsMpoMpsInitOrth ( tntNetwork  mps,
tntNetwork  mpo,
tntNodeArray *  betas,
tntNodeArray *  gammas 
)

Pre-contracts nodes in the MPS-MPO-MPS network ready for an MPS-MPO-MPS contraction or part-contraction. This can be useful when the same network contraction is required many times. for example when performing a variational minimisation sweep using tntMpsVarMinMpo2sSweep(). 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 \).

mps_mpo_mps_fullnw.png

The function performs contractions of this network to form the arrays of pre-contracted nodes \(\mathbf{\beta}\) and \(\mathbf{\gamma}\).

Unlike tntMpsMpoMpsInit(),the function also moves the orthogonality centre, so that the \(\mathbf{\beta}\) nodes are formed with the orthogonality centre to the right of them, and the \(\mathbf{\gamma}\) nodes are formed with the orthogonality centre to the left of them (as is required by sweeoing functions);

The array entry \(\beta_j\) is the node that represents all nodes to the left of site \(j\).

mps_dmrg_beta.png

The array entry \(\gamma_j\) is the node that represents all nodes to the right of site \(j\).

mps_dmrg_gamma.png

Note that \(\beta_0\) and \(\gamma_{L-1}\) are simply tensors with all leg dimensions 1 and containing the entry 1.

If only one side of the pre-contracted network is required, then NULL can be passed instead of the pointer to the tntNodeArray.

Note
After this function is called, the orthonomality centre of the MPS will be on the left-most site (site 0).
Returns
No return value.
Parameters
mpsThe wave function of the system.
mpoThe MPO representing the site-wide operator
betasA pointer to the uninitialised array that will contain the left hand nodes
gammasA pointer to the uninitialised array that will contain the right hand nodes

Definition at line 171 of file tntMpsMpoMps.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayFree(), tntMpsLength(), tntMpsMpoMpsConnect(), tntMpsOrth(), tntNetworkFree(), tntNodeArrayAlloc(), tntNodeCopy(), tntNodeCreate(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeFree(), tntNodeGetLegDir(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeInsertAtStart(), tntNodeJoin(), tntNodeSetQN(), and tntSymmTypeGet().

tntComplex tntMpsMpoMpsPartProduct ( tntNetwork  mps,
tntNetwork  mpo,
unsigned  site_left,
unsigned  site_right,
tntNode  beta,
tntNode  gamma 
)

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

mps_mpo_mps.png

and contracts the whole network to find the scalar value of this product.

Instead of constructing the whole network, like tntMpsMpoMpsProduct(), this function uses pre-contracted nodes from the left and/or right supplied as arguments beta and gamma. The argument site_left gives the index (counting from zero) of the leftmost site that should be used from the mps and mpo networks and the argument site_right gives the index of the rightmost site that should be used.

If either beta or gamma are passed as NULL, then the identity will be inserted instead of a pre-contracted node, but this can only be done for MPOs with a singleton internal dimension.

If the result of the contraction is real, the value itself is returned. If the result of the contraction is complex, then the absolute value is returned.

All incoming arguments are unchanged by the function.

Returns
The result of contracting the MPS-MPO-MPS network illustrated above.
Parameters
mpsNetwork representing the MPS. Unchanged by the function.
mpoNetwork representing the MPO. Unchanged by the function.
site_leftLeft-most sight to use from the mps and mpo networks
site_rightRight-most sight to use from the mps and mpo networks
betaPrecontracted nodes from the left. Use NULL if the identity should be used
gammaPrecontracted nodes from the right. Use NULL if the identity should be used

Definition at line 574 of file tntMpsMpoMps.c.

References tntMpsLength(), tntNodeAddLeg(), tntNodeContract(), tntNodeCopy(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFree(), tntNodeGetFirstEl(), tntNodeGetLegDim(), and tntNodeJoin().

tntComplex tntMpsMpoMpsProduct ( tntNetwork  mps,
tntNetwork  mpo 
)

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

mps_mpo_mps.png

and contracts the whole network to find the scalar value of this product. If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the result of the contraction is \(\langle\psi|\hat{O}|\psi\rangle \). This result gives the expectation value of the operator \(\hat{O}\) if the wave function \(|\psi\rangle\) is normalised. If the wave function is not normalised, the use tntMpsMpsContract to find the norm squared (i.e. \(\langle\psi|\psi\rangle\)) and divide the result by that.

If the result of the contraction is real, the value itself is returned. If the result of the contraction is complex, then the absolute value is returned.

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

Returns
The result of contracting the MPS-MPO-MPS network illustrated above.
Parameters
mpsNetwork representing the MPS. Unchanged by the function.
mpoNetwork representing the MPO. Unchanged by the function.

Definition at line 541 of file tntMpsMpoMps.c.

References tntMpsMpoMpsConnect(), and tntMpsMpoMpsContract().

double tntMpsMpoProduct ( tntNetwork  mps,
tntNetwork  mpo,
int  chi 
)

Constructs an MPS-MPO a network i.e.

mps_mpo.png

and contracts the whole network to return back to an MPS form with a maximum internal dimension \(\chi\) set by the input parameter chi. If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the result of the contraction is \(\hat{O}|\psi\rangle \). This result gives the expectation value of the operator \(\hat{O}\) if the wave function \(|\psi\rangle\) is normalised.

If there is no truncation, this operation would result in the internal dimension of the mps increasing from \(D\) to \(kD\), where \(k\) is the internal dimension of the MPO. Setting chi to -1 will apply the MPO with no truncation other than truncating to the global truncation tolerance set by tntSVDTruncTolSet(). Setting chi to a positive value will apply further truncation to the value given.

First a left to right sweep is performed, contracting the MPO node with it's corresponding MPS node, and truncating to the truncation tolerance for singular values 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(). After the routine, the orthogonality centre of the MPS will be on the first site.

A copy of the MPO is used in the contraction, so the MPO passed as an argument is unchanged by the operation. The MPS passed as an argument is changed by the contraction by having the operator defined by the MPO applied to it, so make a copy of it first if the original MPS will be needed again.

Returns
The truncation error that results from truncating maximum internal dimension of the MPS to chi.
Parameters
mpsNetwork representing the MPS. Values and internal dimension changed by the function.
mpoNetwork representing the MPO. Unchanged by the function.
chiMaximum internal dimension of the new MPS

Definition at line 225 of file tntMpsMpo.c.

References tntMpsMpoConnect(), and tntMpsMpoContract().

Referenced by tntMpsNodeProduct().

tntComplex tntMpsMpsProduct ( tntNetwork  mpsA,
tntNetwork  mpsB 
)

Calculates the inner product of two MPSs by first creating a 'flipped' copy joined along the physical legs, then contracting along the network.

mpsA_mpsB.png

If the original MPSs mpsA, mpsB represent a wave functions \(|\psi_\mathrm{A}\rangle\), \(|\psi_\mathrm{B}\rangle\) then this represents the overlap \(\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle\).

If the result of the contraction is real, the value itself is returned. If the result of the contraction is complex, then the absolute value is returned.

See Also
If the inner product of the MPS with itself is required, use tntMpsSelfProduct().
Returns
The inner product of the two MPSs, equivalent to \(\langle\psi_\mathrm{B}|\psi_\mathrm{A}\rangle\) if the MPSs represent wave functions, with the absolute value taken if the result is complex.
Parameters
mpsAThe network representing the first MPS. Unchanged by the function.
mpsBThe network representing the second MPS. Unchanged by the function.

Definition at line 490 of file tntMpsMps.c.

References tntMpsMpsConnect(), tntMpsMpsContract(), and tntNetworkCopy().

double tntMpsNodeNodeMpsProduct ( tntNetwork  mps,
tntNode  op,
unsigned  sitenum 
)

Calculates the inner product of an MPS with a single node and the node's hermitian conjugate. i.e. if the mps represents state \(|\psi\rangle\) and the node represents operator \(\hat{O}\) it calculates

\[ e = \langle\psi|\hat{O}^\dagger\hat{O}|\psi\rangle \]

It assumes the orthogonality centre is on the first site, and returns a real number

Parameters
mpsThe MPS to apply the node to - unchanged by function
opThe node for the operator to apply - unchanged by function
sitenumThe site number of the MPS to apply the operator to

Definition at line 170 of file tntMpsPmpoMps.c.

References tntComplexToReal(), tntIntArrayAlloc(), tntIntArrayFree(), tntMpsPmpoMpsProduct(), tntNodeArrayAlloc(), tntNodeArrayFree(), tntNodeCopy(), tntNodeMapLegs(), and tntSysQNClearWarnOff().

void tntMpsNodeProduct ( tntNetwork  mps,
tntNode  op,
unsigned  sitenum 
)

Calculates the product of an MPS with a single node. If the MPS is quantum number conserving, then the operator is turned into a site-wide product operator. This ensures that all the quantum number information is retained.

Parameters
mpsThe MPS to apply the node to
opThe operator to apply - unchanged by function
sitenumThe site number of the MPS to apply the operator to

Definition at line 146 of file tntMpsPmpo.c.

References tntIntArrayAlloc(), tntIntArrayFree(), tntMpsCreateProductMpo(), tntMpsLength(), tntMpsMpoProduct(), tntMpsPmpoProduct(), tntNodeArrayAlloc(), tntNodeArrayFree(), tntNodeCopy(), tntNodeFindFirst(), and tntNodeIsCovariant().

void tntMpsOrth ( tntNetwork  mps,
unsigned  orth_centre 
)

Sweeps through the MPS performing a sequence of (untruncated) SVDs and contractions, to leave the every node apart from the orthogonality centre either left or right orthonormalised. 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
Returns
No return value

The truncation tolerance is temporarily turned off before being returned to its initial value during this routine, so the truncation error will be exactly zero and is not returned. If truncation to the global truncation tolerance (set using tntSVDTruncTolSet()) is required, use tntMpsTruncate() with chi set to -1.

Parameters
mpsNetwork representing the MPS. Changed by function to be either left or right orthonormalised
orth_centreThe required orthogonality centre of the MPS.

Definition at line 36 of file tntMpsOrth.c.

References tntMpsTruncate(), tntSVDTruncTolGet(), and tntSVDTruncTolSet().

Referenced by tntMpsMpoMpsInitOrth(), tntMpsOrthNorm(), and tntMpsPropST2scProduct().

void tntMpsOrthNorm ( tntNetwork  mps,
unsigned  orth_centre 
)

Sweeps through the MPS performing a sequence of (untruncated) SVDs and contractions, to leave the every node apart from the orthogonality centre either left or right orthonormalised. 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
Returns
No return value

The truncation tolerance is temporarily turned off before being returned to its initial value during this routine, so the truncation error will be exactly zero and is not returned. If truncation to the global truncation tolerance (set using tntSVDTruncTolSet()) is required, use tntMpsTruncate() with chi set to -1.

After orthogonolising the MPS, also scales the network so that it is normalised i.e. so that tntMpsSelfProduct() is 1.0.

Parameters
mpsNetwork representing the MPS to orthonormalise
orth_centreThe required orthogonality centre of the MPS.

Definition at line 83 of file tntMpsOrth.c.

References tntMpsOrth(), tntMpsSelfProduct(), tntNodeFindConn(), tntNodeFindFirst(), and tntNodeScaleReal().

Referenced by tntMpsAdd(), and tntMpsCreateSymmRandom().

tntComplex tntMpsPmpoMpsProduct ( tntNetwork  mps,
tntNodeArray *  op,
tntIntArray *  sitenum,
int  orth_centre,
tntNodeArray *  betas,
tntNodeArray *  gammas 
)

Calculates the inner product of an MPS-MPS network with zero or more single-site operators op[i] representing a product MPO (PMPO) with the following form inserted between them.

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. Each of the specified operators is inserted on the relevant site, then contracted with the physical leg on the MPS to form a new MPS. The new MPS is then contracted with the original MPS which is flipped to form the bottom of the network. This function therefore represents an MPS-PMPO-MPS product.

mps_pmpo_mps.png

If multiple operators are given for a single site, then they will be applied to the wave function in the order they are given in the array i.e. in the figure above the operators given first will be on top.

The function can be made more efficient by specifying the orthogonality centre of the MPS. All sites to the right of the orthogonality centre should obey the right orthonormalisation condition:

right_orth.png

All sites to the left of the orthogonality centre should obey the left orthonormalisation condition:

left_orth.png

This means that, for example, if the orthogonality centre is site 2 the network contraction above can be simplified to:

expec_sing_part.png

This then reduces the number of contractions required to find the expectation value.

Note that after applying tntMpsPropST2scProduct(), or tntMpsVarMinMpo2sSweep() in direction "L", the orthonormality centre will be on the first site. After applying tntMpsVarMinMpo2sSweep() in direction "R", the orthonormality centre will be on the last site.

Returns
The product of the MPS-MPS network with the product MPO inserted between them.
Note
All input arguments are unchanged by the function
Parameters
mpsThe network representing the MPS
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. 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. Unchanged by the function.
orth_centreThe orthogonality centre of the MPS wave function. Set to -1 if unknown.

Definition at line 57 of file tntMpsPmpoMps.c.

References tntMpsLength(), tntMpsMpsConnect(), tntMpsMpsContract(), tntMpsPmpoProduct(), and tntNetworkCopy().

Referenced by tntMpsExpecOutput(), and tntMpsNodeNodeMpsProduct().

void tntMpsPmpoProduct ( tntNetwork  mps,
tntNodeArray *  op,
tntIntArray *  sitenum 
)

Applies on more single-site operators op[i] to the physical legs of an MPS.

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. 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 MPS-PMPO product.

mps_pmpo.png

This results in another MPS, which replaces the MPS network passed as an argument. The physical legs of the MPS 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 MPS to change, if the upwards and downwards facing legs have different dimensions.

Returns
No return value, but the input parameter mps is altered by having its product taken with the PMPO.
Parameters
mpsThe 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. Operators are assumed to have 2 legs, with upwards facing leg having number 4, and downwards facing leg having number 3. Unchanged by the function.
sitenumArray giving the site numbers for each of the operators given in op. 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. Unchanged by the function.

Definition at line 35 of file tntMpsPmpo.c.

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

Referenced by tntMpsCreateProductMpo(), tntMpsNodeProduct(), and tntMpsPmpoMpsProduct().

double tntMpsPropST2scProduct ( tntNetwork  mps,
tntNetwork  Prop,
int  chi 
)

Performs a single step of a second order Suzuki-Trotter staircase expansion of a site-wide propagator.

propst2sc.png

A network as that pictured above must be provided for the propagator i.e. with the gates applied in a zip across first left to right, then right to left. A suitable propagator can be built using tntMpsCreatePropST2sc(). The entire propagator is then multiplied with the MPS i.e. a sweep in both directions is performed.

The orthogonality centre of the MPS should be on the first site before applying the step, and will return to the first site after the step.

Returns
The truncation error for that step, which is the sum of the truncation error for all SVDS. The truncation error for each SVD can be defined in a few different ways - see the documentation for tntTruncType() for more details.
Parameters
mpsNetwork representing the MPS wave function. Will be changed by the function, by applying one step of the evolution operator.
PropA network of two-site operators arranged in a left to right then right to left staircase. Unchanged by function.
chiThe maximum internal dimension. All SVD's will be truncated to this value.

Definition at line 203 of file tntMpsST2sc.c.

References tntMpsLength(), tntMpsOrth(), tntMpsPropST2scConnect(), and tntMpsPropSTscContract().

void tntMpsSelfInit ( tntNetwork  mps,
tntNodeArray *  betas,
tntNodeArray *  gammas 
)

Pre-contracts nodes in the MPS-MPS network ready for an MPS-MPS contraction or part-contraction. This can be useful when the same network contraction is required many times, for example when finding multiple expectation values of operators that act on only a few sites in the network.

The function performs contractions of the MPS-MPS network to form the arrays of pre-contracted nodes \(\mathbf{\beta}\) and \(\mathbf{\gamma}\).

The array entry \(\beta_j\) is the node that represents all nodes to the left of site \(j\).

The array entry \(\gamma_j\) is the node that represents all nodes to the right of site \(j\).

Note that \(\beta_0\) and \(\gamma_{L-1}\) are simply tensors with all leg dimensions 1 and containing the entry 1.

If only one side of the pre-contracted network is required, then NULL can be passed instead of the pointer to the tntNodeArray.

Note
Unlike tntMpsMpoMpsInit() this function does not alter the orthonormality centre of the network when precontracting. Therefore the precontracted parts of the network will have the same orthonormality centre as the input MPS network.
Returns
No return value.
Parameters
mpsThe mps network.
betasA pointer to the uninitialised array that will contain the left hand nodes
gammasA pointer to the uninitialised array that will contain the right hand nodes

Definition at line 329 of file tntMpsMps.c.

References tntComplexArrayAlloc(), tntComplexArrayFree(), tntIntArrayFree(), tntMpsLength(), tntMpsMpsConnect(), tntNetworkCopy(), tntNetworkFree(), tntNodeArrayAlloc(), tntNodeCopy(), tntNodeCreate(), tntNodeFindConn(), tntNodeFindFirst(), tntNodeFindLast(), tntNodeFree(), tntNodeGetLegDir(), tntNodeGetQN(), tntNodeInsertAtEnd(), tntNodeInsertAtStart(), tntNodeJoin(), tntNodeSetQN(), and tntSymmTypeGet().

Referenced by tntMpsExpecOutput().

double tntMpsSelfProduct ( tntNetwork  mps,
int  orth_centre 
)

Calculates the self inner product of an MPS by first creating a 'flipped' copy joined along the physical legs, then contracting along the network.

mpsA_mpsA.png

If the MPS represents the wave function \(\psi\rangle\), then the product is \(\langle\psi|\psi\rangle\) i.e. the square of the 2-norm.

The function can be made more efficient by specifying the orthogonality centre of the MPS. All sites to the right of the orthogonality centre should obey the right orthonormalisation condition:

right_orth.png

All sites to the left of the orthogonality centre should obey the left orthonormalisation condition:

left_orth.png

This means that, for example, if the orthogonality centre is 0 the network contraction above can be simplified to:

norm_part.png

This then reduces the number of contractions required to find the product.

Note that after applying tntMpsPropST2scProduct(), or tntMpsVarMinMpo2sSweep() in direction ::"L", the orthonormality centre will be on the first site. After applying tntMpsVarMinMpo2sSweep() in direction ::"R", the orthonormality centre will be on the last site.

If the orthogonality centre is given as -1, then a full contraction is performed.

Returns
The self inner product of the MPS.
Parameters
mpsThe network representing the MPS. Unchanged by the function.
orth_centreThe orthogonality centre of the MPS wave function. Set to -1 if unknown.

Definition at line 544 of file tntMpsMps.c.

References tntComplex::re, tntMpsLength(), tntMpsMpsConnect(), tntMpsMpsContract(), and tntNetworkCopy().

Referenced by tntMpsCreateRandom(), tntMpsExpecOutput(), and tntMpsOrthNorm().

double tntMpsVarMinMpo1sStep ( tntNetwork  mps,
int  chi,
tntNetwork  mpo,
tntNodeArray *  HeffL,
tntNodeArray *  HeffR,
double *  err,
unsigned  start_site 
)

Performs a sweep varying the elements of the supplied MPS, one at a time, in order to minimise the result of the MPS-MPO-MPS network contraction. If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the network to contract represents \(\langle\psi|\hat{O}|\psi\rangle \). In this case the operator will usually by the system Hamiltonian, so this sweep can be used in a routine to minimise the energy i.e. find the ground state of the system. The function applies updates to single site in left-to-right and right-to-left sweeps to result in a single complete sweep in each direction.

This function uses the strictly single site algorithm described in PRB 91, 155115(2015) Hubig, McCulloch, Schollwoeck and Wolf.

The twist or orthogonality centre is moved as the one-site optimisations are performed. Note that after completion of the step, the orthonormality centre will be on start_site.

Returns
The current value of the MPS-MPO-MPS product.
Note
This is a beta version of the routine. Some tuning of parameters may still need optimisation. This will be addressed in future releases.
Parameters
mpsNetwork representing the MPS. Will be changed to minimise the expecation of the operator mpo.
chiThe maximum internal dimension. All SVD's will be truncated to this value.
mpoThe network representing the MPO for the operator whose expectation to minimise (usually the system Hamiltonian).
HeffLLeft precontracted nodes in the MPS-MPO-MPS network
HeffRRight precontracted nodes in the MPS-MPO-MPS network
errGives the sum of all the errors returned from the SVD.
start_siteStart and end site of routine. Assumes the orthogonality centre is on this site to start, and it will be on this site again when the routine is complete. If this argument is ommitted 0 is used.

Definition at line 318 of file tntMps1sDmrg.c.

References tntMpsLength(), and tntMpsVarMinMpo1sSweep().

double tntMpsVarMinMpo2sStep ( tntNetwork  mps,
int  chi,
tntNetwork  mpo,
tntNodeArray *  HeffL,
tntNodeArray *  HeffR,
double *  err,
unsigned  start_site 
)

Performs a sweep varying the elements of the supplied MPS, two at a time, in order to minimise the result of the MPS-MPO-MPS network contraction. If the MPS represents a wave function \(|\psi\rangle\) and the MPO represents a site-wide operator \(\hat{O}\), the network to contract represents \(\langle\psi|\hat{O}|\psi\rangle \). In this case the operator will usually by the system Hamiltonian, so this sweep can be used in a routine to minimise the energy i.e. find the ground state of the system. The function applies updates to each pair of sites in left-to-right and right-to-left sweeps to result in a single complete sweep in each direction.

The sweep consists of first building the network representing the MPS-MPO-MPS product, illustrated below for a six site system.

mps_mpo_mps.png

The two sites to be updated are then contracted with one another to form a \(\Theta\) node, as are the corresponding operators (illustrated below for sites 2 and 3).

mps_dmrg_theta.png

The effective operator for this pair of sites is then built by contracting all nodes to the left and to the right of the sites to be updated. However, rather than contracting the nodes each time, the pre-contracted nodes that are passed as arguments are used to build a new network. The resulting network has the following form:

mps_dmrg_heff.png

It corresponds to a matrix-times-vector multiplication, where \(\Theta\) is the vector and \(\beta\), \(h\) and \(\gamma\) together form the matrix that represents the effective operator. Rather than contracting the latter 3 nodes to form the matrix explicitly, this network is passed to the core function tntNetworkMinSite(). This function uses an efficient contraction pattern (defined in tntMpsVarMinMpo2sContract()) to iteratively perform the matrix-times-vector multiplication. In doing so it finds the \(\Theta\) node which represents the eigenvector of the matrix having the smallest eigenvalue.

Once this \(\Theta\) node is found, it is replaced in the network, and an SVD is performed to reform two \(A\) nodes. This SVD will be trunctated to \(\chi\) (passed in the input argument chi), and the sum of all truncation errors is passed to the value pointed to by argument err.

The precontracted nodes to the left and right an be generated using tntMpsVarMinMpoInit() if this function is being called for the first time. The nodes are updated during the routine for use in subsequent sweeps.

After the completion of the step the orthogonality centre will be on start_site.

right_orth.png
Returns
The current value of the MPS-MPO-MPS product.
Parameters
mpsNetwork representing the MPS. Will be changed to minimise the expecation of the operator mpo.
chiThe maximum internal dimension. All SVD's will be truncated to this value.
mpoThe network representing the MPO for the operator whose expectation to minimise (usually the system Hamiltonian).
HeffLLeft precontracted nodes in the MPS-MPO-MPS network
HeffRRight precontracted nodes in the MPS-MPO-MPS network
errGives the sum of all the errors returned from the SVD.
start_siteStart and end site of routine. Assumes the orthogonality centre is on this site to start, and it will be on this site again when the routine is complete. If this argument is ommitted 0 is used.
Examples:
tntEvolve_if.c, and tntGS_cl.c.

Definition at line 283 of file tntMps2sDmrg.c.

References tntMpsLength(), and tntMpsVarMinMpo2sSweep().