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

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 tntSVDTruncErrTolGet (void)
 
void tntSVDTruncErrTolSet (double truncErrTol)
 
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)
 
void tntSysInfoPrint (void)
 
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:
create_exop.c, create_matrices.c, create_nodes.c, tntEvolve_cl.c, tntEvolve_if.c, tntGS_cl.c, and tntThermal_cl.c.

Definition at line 89 of file tntSys.c.

References systype, and tntNodeFree().

Referenced by tntMpsProcessDmrgCLOptions(), tntMpsProcessTebdCLOptions(), and tntProcessCLOptions().

void tntInitialize ( void  )

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

Examples:
create_exop.c, create_matrices.c, create_nodes.c, tntEvolve_cl.c, tntEvolve_if.c, tntGS_cl.c, and tntThermal_cl.c.

Definition at line 17 of file tntSys.c.

References systype, and tntPrintVersion().

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
maxnumThe chosen SVD type. Allowed values are TNT_LAPACK_SDD and TNT_LAPACK_SVD.

Definition at line 232 of file tntSys.c.

References systype.

Referenced by tntMpsProcessDmrgCLOptions().

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 532 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.
See Also
Use tntSVDRelTruncTolSet() to set the relative truncation tolerance to a different value.

Definition at line 330 of file tntSys.c.

References systype.

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.

See Also
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
relTruncTolThe chosen tolerance.

Definition at line 273 of file tntSys.c.

References systype.

Referenced by tntProcessCLOptions().

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
svdtypeThe chose SVD type. Allowed values are TNT_LAPACK_SDD and TNT_LAPACK_SVD.

Definition at line 221 of file tntSys.c.

References systype.

Referenced by tntProcessCLOptions().

double tntSVDTolGet ( void  )

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

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

Definition at line 206 of file tntSys.c.

References systype.

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
inpTOLThe chosen tolerance.

Definition at line 192 of file tntSys.c.

References systype.

Referenced by tntProcessCLOptions(), and tntSymmTypeUnset().

double tntSVDTruncErrTolGet ( void  )

Use this function to get the maximum error bound for each SVD.

Returns
The current value of the truncation tolerance.
See Also
Use tntSVDTruncErrTolSet() to set the error bound and for more details about what this value represents.

Definition at line 347 of file tntSys.c.

References systype.

void tntSVDTruncErrTolSet ( double  truncErrTol)

Use this function to set a maximum error bound for each SVD. The maximum number of singular values will be discarded that still allows the truncation error (for a single SVD) to be less than the error bound. Set to a negative value to ensure that all singular values up to the value \(\chi\) are kept (unless an absolute or relative truncation 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.

See Also
Use tntSVDRelTruncTolSet() and tntSVDTruncTolSet() to set an absolute or relative minimum for the singular values that will be kept in the SVD. These bounds differ as they compare the value set with each single singular value, rather than the total truncation error associated with truncating at a given point.
Returns
No return value.
Parameters
truncErrTolThe chosen tolerance.

Definition at line 293 of file tntSys.c.

References systype.

Referenced by tntProcessCLOptions().

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.
See Also
Use tntSVDTruncTolSet() to set the truncation tolerance to a different value.

Definition at line 312 of file tntSys.c.

References systype.

Referenced by tntMpsCreateSymmRandom(), and tntMpsOrth().

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.

See Also
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
truncTolThe chosen tolerance.

Definition at line 253 of file tntSys.c.

References systype.

Referenced by tntMpsCreateSymmRandom(), tntMpsOrth(), and tntProcessCLOptions().

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 512 of file tntSys.c.

References systype.

Referenced by tntMpsCreateConfig(), tntMpsCreateMpo(), tntMpsCreateProductMpo(), tntMpsCreateSymmRandom(), and tntMpsOpGetQN().

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 498 of file tntSys.c.

References systype.

Referenced by tntMpsCreateBosonOp(), tntMpsCreateConfig(), tntMpsCreateMpo(), tntMpsCreateProductMpo(), tntMpsCreateSpinOp(), tntMpsCreateSymmRandom(), tntMpsCreateTwoSiteOp(), tntMpsMpoMpsInit(), tntMpsMpoMpsInitOrth(), tntMpsProcessSysOptions(), tntMpsSelfInit(), tntNodeCreateEyeOp(), and tntSymmTypeUnset().

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
symmTypeStrString denoting the symmetry type e.g. "U(1)".
num_qnNumber of separate conserved quantities.

Definition at line 439 of file tntSys.c.

Referenced by tntMpsProcessSysOptions().

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.
Examples:
tntEvolve_if.c.

Definition at line 469 of file tntSys.c.

References systype, tntSVDTolSet(), tntSymmTypeGet(), and tntSysBasisOpGet().

void tntSysBasisOpFree ( void  )

Removes and frees the current basis operator.

Definition at line 417 of file tntSys.c.

References systype.

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 407 of file tntSys.c.

References systype.

Referenced by tntMpsCreateConfig(), tntMpsCreateMpo(), tntMpsCreateProductMpo(), tntMpsCreateRandom(), tntMpsCreateSymmRandom(), tntMpsCreateTwoSiteOp(), tntMpsOpGetQN(), tntMpsProcessExpecOptions(), and tntSymmTypeUnset().

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
basisOpNode that defines the basis operator
Examples:
create_exop.c.

Definition at line 389 of file tntSys.c.

References systype.

Referenced by tntMpsProcessSysOptions().

void tntSysInfoPrint ( void  )

Prints out the global system information

Definition at line 70 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 376 of file tntSys.c.

References systype.

Referenced by tntMpsProcessExpecOptions(), and tntMpsProcessSysOptions().

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
sysnumNumber code defining the system type.

Definition at line 361 of file tntSys.c.

References systype.

Referenced by tntMpsProcessSysOptions().

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
funcnameThe name of desired truncation type e.g. "sumsquares".

Definition at line 165 of file tntSys.c.

References systype.

Referenced by tntMpsProcessDmrgCLOptions(), and tntMpsProcessTebdCLOptions().

Variable Documentation