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

## Detailed Description

The system has several global parameters that are used in all calculations. These can be based on the physical properties of your system, e.g. setting the basis operator and the global physical symmetries. In addition some of these are related to values used during calculations, for examples tolerances used in the SVD.

## Functions

void tntFinalize (void)

void tntInitialize (void)

void tntMaxEigIterSet (int maxnum)

void tntReshapeReuseDisable (void)

double tntSVDRelTruncTolGet (void)

void tntSVDRelTruncTolSet (double relTruncTol)

void tntSVDRoutineSet (int svdtype)

double tntSVDTolGet (void)

void tntSVDTolSet (double inpTOL)

double tntSVDTruncTolGet (void)

void tntSVDTruncTolSet (double truncTol)

unsigned tntSymmNumGet (void)

int tntSymmTypeGet (void)

void tntSymmTypeSet (const char *symmTypeStr, unsigned num_qn)

void tntSymmTypeUnset (void)

void tntSysBasisOpFree (void)

tntNode tntSysBasisOpGet (void)

void tntSysBasisOpSet (tntNode basisOp)

int tntSysTypeGet (void)

void tntSysTypeSet (int sysnum)

void tntTruncType (const char *funcname)

## Variables

tntSystem systype

## Function Documentation

 void tntFinalize ( void )

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

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

Definition at line 72 of file tntSys.c.

 void tntInitialize ( void )

Initalize the TNT library and the system variables. Should precede all other TNT calls.

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

Definition at line 17 of file tntSys.c.

 void tntMaxEigIterSet ( int maxnum )

Use this function to change the number of iterations for the sparse eigenvalue solver

• you may want to do this if you are getting convergence errors.
Parameters
 maxnum The chosen SVD type. Allowed values are TNT_LAPACK_SDD and TNT_LAPACK_SVD.

Definition at line 204 of file tntSys.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.

Definition at line 467 of file tntSys.c.

 double tntSVDRelTruncTolGet ( 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 singular 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 tntSVDRelTruncTolSet() to set the relative truncation tolerance to a different value.

Definition at line 282 of file tntSys.c.

 void tntSVDRelTruncTolSet ( double relTruncTol )

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 (unless an absolute value has also been set).

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.

Use tntSVDRelTruncTolGet() to find out the current value of the relative truncation tolerance, and tntSVDTruncTolSet() to set an absolute minimum for the singular values that will be kept in the SVD.
Returns
No return value.
Parameters
 relTruncTol The chosen tolerance.

Definition at line 245 of file tntSys.c.

 void tntSVDRoutineSet ( int svdtype )

Use this function to change the SVD routine used in the core library. By default the LAPACK divide and conquer SVD is used (TNT_LAPACK_SDD). If you are having issues with the SVD converging or accuracy, please try using the LAPACK standard SVD (TNT_LAPACK_SVD). This performs more slowly but we have found it to be better behaved.

Returns
No return value.
Parameters
 svdtype The chose SVD type. Allowed values are TNT_LAPACK_SDD and TNT_LAPACK_SVD.

Definition at line 193 of file tntSys.c.

 double tntSVDTolGet ( void )

Get the tolerance below which values are treated as zero in the SVD.

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

Definition at line 178 of file tntSys.c.

 void tntSVDTolSet ( double inpTOL )

Sets 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.
Parameters
 inpTOL The chosen tolerance.

Definition at line 164 of file tntSys.c.

 double tntSVDTruncTolGet ( void )

Use this function to get the absolute minimum for the singular values that will be kept in the SVD. Any singluar values which are smaller than truncTol' will 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 tntSVDTruncTolSet() to set the truncation tolerance to a different value.

Definition at line 264 of file tntSys.c.

 void tntSVDTruncTolSet ( double truncTol )

Use this function to set an absolute minimum for the singular values that will be kept in the SVD. Any singluar values which are smaller than truncTol' 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 (unless a relative value has also been set).

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 take the inverse of nodes that result from an SVD, it is recommended to set this value (e.g. to 1e-8) to ensure that your matrices are not singular.

Use tntSVDTruncTolGet() to find out the current value of the truncation tolerance, and tntSVDRelTruncTolSet() to set a relative minimum for the singular values that will be kept in the SVD.
Parameters
 truncTol The chosen tolerance.

Definition at line 225 of file tntSys.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.

Definition at line 447 of file tntSys.c.

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

Definition at line 433 of file tntSys.c.

 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() or tntMpsCreateConfig(), they will be set up 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.

Parameters
 symmTypeStr String denoting the symmetry type e.g. "U(1)". num_qn Number of separate conserved quantities.

Definition at line 374 of file tntSys.c.

 void tntSymmTypeUnset ( void )

Turns off keeping track of symmetries in the system. The quantum number information is removed from the basis operator, and library functions will no longer enforce number conservation.

Note that nodes that are in the blocked or symmetric format will be converted to VALS structure as they are encountered by library functions, rather than as soon as this function is called.

Note also that the SVD tolerance for zeroing values is turned back on to the default value of TNT_DEFAULT_TOL.

If symmetry information is not turned on prior to calling this function, it will have to effect.

Returns
No return value.

Definition at line 404 of file tntSys.c.

 void tntSysBasisOpFree ( void )

Removes and frees the current basis operator.

Definition at line 352 of file tntSys.c.

 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.

Definition at line 342 of file tntSys.c.

 void tntSysBasisOpSet ( tntNode basisOp )

Sets the operator which defines the physical basis for the system. Note that a copy of the supplied node basisOp is taken, so any changes can be made to basisOp after the function has been called will not affect the system basis operator. Instead use tntSysBasisOpGet() to get a handle to the basis operator after this function has been called.

Parameters
 basisOp Node that defines the basis operator

Definition at line 324 of file tntSys.c.

 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.

Definition at line 311 of file tntSys.c.

 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.

Parameters
 sysnum Number code defining the system type.

Definition at line 296 of file tntSys.c.

 void tntTruncType ( const char * funcname )

Sets the function used to calculate the truncation error $$e_{\mathrm{trunc}}$$ when taking the SVD of a node. Once this function is set the same truncation type will be used for all subsequent calculations, unless it is called again a different argument. Note the choice will automatically be saved to any output file, and reloaded when that file is loaded. 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.

Parameters
 funcname The name of desired truncation type e.g. "sumsquares".

Definition at line 136 of file tntSys.c.

## Variable Documentation

 tntSystem systype

Global definition of system type

Definition at line 12 of file tntSys.c.