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

## Data Structures

struct  tntComplex
Use this type to define complex numbers. Any complex arithmetic needs to be done manually. For example to add two complex numbers A and B to give C write: More...

## Macros

#define TNT_STRLEN

#define TNT_SYMM_U1

#define TNT_QN_IN

#define TNT_QN_OUT

#define TNT_DEFAULT_TOL

#define TNT_COMP_TOL

## Functions

void tntTruncType (const char *funcname)

void tntSVDTolSet (double inpTOL)

double tntSVDTolGet (void)

void tntSVDTruncTolSet (double truncTol)

double tntSVDTruncTolGet (void)

void tntSysTypeSet (int sysnum)

int tntSysTypeGet (void)

void tntSysBasisOpSet (tntNode basisOp)

tntNode tntSysBasisOpGet (void)

void tntSymmTypeSet (const char *symmTypeStr, unsigned num_qn)

int tntSymmTypeGet (void)

unsigned tntSymmNumGet (void)

void tntInitialize (void)

void tntFinalize (void)

void tntReshapeReuseDisable (void)

void tntReshapeReuseEnable (void)

void tntClearReshapes (int val)

void tntPrintVersion (void)

void tntProcessCLOptions (int argc, char **argv, char *loadname, char *loadname_op, char *saveprefix, int *chi, int *outputState)

double tntComplexToReal (tntComplex var)

## Detailed Description

This section contains functions that are utility functions, and do not act on nodes or networks, or are concerned with input and output of data.

## Macro Definition Documentation

 #define TNT_COMP_TOL

Default maximum ratio between imaginary and real part of complex numbers to assume values are real.

 #define TNT_DEFAULT_TOL

Default tolerance for assuming values are zero.

 #define TNT_QN_IN

Direction of incoming leg for QN conservation

 #define TNT_QN_OUT

Direction of outgoing leg for QN conservation

 #define TNT_STRLEN

Fixed length for all strings.

Examples:
dmrg.c, and tebd.c.
 #define TNT_SYMM_U1

Code for currently allowed symmetry type for the system - U(1).

## Function Documentation

 void tntClearReshapes ( int val )

Set a value which, when changed, denotes that the reuse data in tensor_reshape() calls should be freed and recalculated.

If this is called with argument 0'' then a free+recalculation is ordered each time

Returns
No return value.
Parameters
 val Indentifier to be assigned to reshape structure
 double tntComplexToReal ( tntComplex var )

Used to convert complex variables to real variables. If the imaginary part is non-negligible, calculate the absolute value, otherwise return the real part only i.e. if the variable is real it does not take the absolute value.

Returns
Real value if input was real, or absolute value if input was complex.
Parameters
 var A complex variable
Examples:
dmrg.c, and tebd.c.
 void tntFinalize ( void )

Finalize the TNT library. Should follow all other TNT calls.

Returns
No return value.
Examples:
dmrg.c, and tebd.c.
 void tntInitialize ( void )

Initalize the TNT library. Should precede all other TNT calls.

Returns
No return value.
Examples:
dmrg.c, and tebd.c.
 void tntPrintVersion ( void )

Prints the current version number.

Returns
No return value.
 void tntProcessCLOptions ( int argc, char ** argv, char * loadname, char * loadname_op, char * saveprefix, int * chi, int * outputState )

Function that processes commonly required input command line arguments.

Command line options:

Long nameShort nameDescription
--help-h print this help.
--input <file> -i <file> Input checkpoint. This file contains the networks and paramaters that change during the algorithm. Required.
--operators <file> -o <file> Input operators. This file contains operators which are not changed during the algortihm. Required.
--directory <dir> -d <dir> Output directory and prefix for the output files (which may later be used as input checkpoints). If not given no output will be saved.
--chi <n>-c <n> The maximum internal dimension $$\chi$$ of nodes in the network. If not given it is set to -1 meaning no truncation will be performed.
--TOL <val>-T <val> Tolerance for zeroing matrix values in SVD. See tntSVDTolSet() for more information. If not given default of 1e-14 will be used.
--no-output -q No output files written.

Note that, with the exception of --TOL which calls the function tntSVDTolSet() to set the tolerance, this function just sets the required variables. The way these variables will be used is implementation dependent. If any of the variables are not required or should not be allowed to be set from the command line for your implementation, simply pass the NULL pointer in place of that argument. Passing NULL instead of a pointer to the variable will over-ride the 'Required' status for the command line option.

Returns
No return value.
Parameters
 argc Input argument count argv Input arguments loadname Name of network file to be loaded loadname_op Name of operator file to be loaded saveprefix Directory and prefix for saving results chi Initial chi value outputState Flag for enabling output
Examples:
dmrg.c, and tebd.c.
 void tntReshapeReuseDisable ( void )

Disables the storage of the translations done in the reshape component. This will conserve memory but typically at a great expense computationally. It is recommended to use this function when the size of the tensors is constantly changing, for example in cases where the tolerance is set for the minimum size singular value to keep using tntSVDTruncTolSet().

Returns
No return value.
 void tntReshapeReuseEnable ( void )

Enables the storage of the translations done in the reshape component. This will consume memory but typically at a great saving of computational time. Enabled by default.

Returns
No return value.
 double tntSVDTolGet ( void )

User function to get the tolerance below which values are treated as zero in the SVD (which leads to significant performance improvements).

Returns
The current truncation tolerance.
Function tntSVDTolSet() sets the tolerance.
 void tntSVDTolSet ( double inpTOL )

User function to set the tolerance below which values are treated as zero in the SVD - this leads to significant performance improvements. However, to ensure all values are kept, set this to a negative number. This function will typically only be called once at the start of program execution. If using the command line options routine tntProcessCommandLineOptions this is called automatically.

Note
Our tests have found that for most systems, and when the truncation error is small, this does not make any significant difference to results. However for certain systems, when the truncation error is large, we have seen this lead to small differences in expectation values. Therefore we recommend first testing the effect of TOL on your results for small systems/run times to determine its effect.
Returns
No return value.
Parameters
 inpTOL The chosen tolerance.
 double tntSVDTruncTolGet ( void )

Use this function to get the (relative) minimum for the singular values that will be kept in the SVD. Any singluar values which are truncTol' times smaller than the maximum singluar value are be discarded, along with their associated right and left singluar vectors. A negative value means that all singular values up to the value $$\chi$$ are kept.

Returns
The current value of the truncation tolerance.
Use tntSvdTrunTolSet() to set the truncation tolerance to a different value.
 void tntSVDTruncTolSet ( double truncTol )

Use this function to set a (relative) minimum for the singular values that will be kept in the SVD. Any singluar values which are truncTol' times smaller than the maximum singluar value will be discarded, along with their associated right and left singluar vectors. Set to a negative value to ensure that all singular values up to the value $$\chi$$ are kept.

Calling this function sets the tolerance for all subsequent SVDs. It is set to a negative value by default i.e. all singular values kept. However, if there are any parts of your algorithm that takes the inverse of nodes that result from taking the SVD, it is recommended to set this value (e.g. to 1e-8) to ensure that your matrices are not singular.

Use tntSvdTrunTolGet() to find out the current value of the truncation tolerance.
Returns
No return value.
Parameters
 truncTol The chose tolerance.
Examples:
dmrg.c, and tebd.c.
 unsigned tntSymmNumGet ( void )

Gets the number of seperate conserved quantities, or the number of quantum numbers required for a quantum number labels e.g for an two-species system will return 2. The return value will be zero if no symmetry type is set.

Returns
The number of quantum numbers required for each quantum number label.
 int tntSymmTypeGet ( void )

Gets the symmetry type for the system, returning the result as an integer code more than 1, which will be one of the allowed symmetry types given by the defined variables. The return value will be zero if no symmetry type is set.

In the current version, the only currently allowed value is TNT_SYMM_U1.

Returns
Integer code for the symmetry type, 0 if no symmetry type is set.
 void tntSymmTypeSet ( const char * symmTypeStr, unsigned num_qn )

Sets the symmetry type for the system. If it is set, then quantum number information is tracked, and the releavant quantities are conserved.

For example if U(1) is set, (tntSymmetrySet("U(1)")) and spin or boson operators created using tntMpsCreateSpinOp and tntMpsCreateBosonOp, and wave functions created using tntMpsCreateRandom() tntMpsCreateConfig() will be set up with the necessary information to ensure that the total z-projection of spin or boson number are conserved respectively. This can significantly speed up calculations.

The argument num_qn sets the number of seperate conserved quantities e.g. set to 2 for a two species system where the number of species 1 and the number of species 2 is conserved.

Note that any nodes manually entered through an initialisation file must also have quantum number specified for quantiities to be conserved.

Returns
No return value.
Parameters
 symmTypeStr String denoting the symmetry type e.g. "U(1)". num_qn Number of separate conserved quantities.
 tntNode tntSysBasisOpGet ( void )

Returns the operator which defines the physical basis for the system. Note that this returns the handle to the actual basis operator, rather than a copy of it, so any modifications to it will alter the basis operator for the entire system. Therefore we recommend only inspecting properties of the operator rather than making changes to it unless you know exactly what you are doing.

Returns
The tntNode which represents the operator which defines the physical basis for the system, or NULL if no basis operator has been set yet.
 void tntSysBasisOpSet ( tntNode basisOp )

Sets the operator which defines the physical basis for the system. Note that a copy of the supplied node is taken, so any changes can be made to the operator supplied as an argument after the function has been called will not have any effect on the basis operator itself.

Returns
No return value.
Parameters
 basisOp Node that defines the basis operator
 int tntSysTypeGet ( void )

Returns a number which defines the type of system, where definitions for these numbers are given in the header file for the tier 2 library being used. Currently the only tier 2 library is libtntMps, which can give the values TNT_MPS_SPIN and TNT_MPS_BOSON.

Returns
Integer which encodes the system type. See the header or documentation for your tier 2 library for the currently supported system types.
 void tntSysTypeSet ( int sysnum )

Sets the system type using the integer code given. Note that no checks are made that the integer given actually corresponds to a system type known by the tier 2 library - users can define custom system types if they wish.

See the header or documentation for your tier 2 library for the currently supported system types. Currently the only tier 2 library is libtntMps, which can give the values TNT_MPS_SPIN and TNT_MPS_BOSON.

Returns
No return value.
Parameters
 sysnum Number code defining the system type.
 void tntTruncType ( const char * funcname )

Sets the function used to calculate the truncation error $$e_{\mathrm{trunc}}$$ when taking the SVD of a node using tntNodeSVD(). Once this function is set the same truncation type will be used for all subsequent calculations, unless it is called again a different argument. The currently supported truncation types are:

• 'sumsquares'

The error is given by the sum of the squares of the discarded singluar values i.e.

$e_{\mathrm{trunc}} = \sum_{j=\chi}^{\chi_{\mathrm{orig}}-1} |S_{j}|^2.$

• '1norm'

The error is given by the 1-norm of the discarded singluar values i.e.

$e_{\mathrm{trunc}} = \sum_{j=\chi}^{\chi_{\mathrm{orig}}-1} |S_{j}|.$

• '1normscaled'

The error is given by the 1-norm of the discarded singluar values divided by the 1-norm of all the singular values i.e.

$e_{\mathrm{trunc}} = \left( \sum_{j=\chi}^{\chi_{\mathrm{orig}}-1} |S_{j}| \right)\Bigg{/}\left( \sum_{j=0}^{\chi_{\mathrm{orig}}-1} |S_{j}| \right).$

• '2norm'

The the error $$e$$ is given by the 2-norm of the discarded singluar values i.e.

$e_{\mathrm{trunc}} = \left( \sum_{j=\chi}^{\chi_{\mathrm{orig}}-1} |S_{j}|^2 \right)^{1/2}.$

• '2normscaled'

The error $$e$$ is given by the 2-norm of the discarded singluar values divided by the 2-norm of all the singular values i.e.

$e_{\mathrm{trunc}} = \left( \sum_{j=\chi}^{\chi_{\mathrm{orig}}-1} |S_{j}|^2 \right)^{1/2}\Bigg{/}\left( \sum_{j=0}^{\chi_{\mathrm{orig}}-1} |S_{j}|^2 \right)^{1/2}.$

In all the above cases, the indexing in the sum starts from zero.

The default is '2norm', and will be used if no value is set using this function.

Returns
No return value.
Parameters
 funcname The name of desired truncation type e.g. "sumsquares".