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

## Detailed Description

These functions are useful for allowing various flags on the command line to be accepted and processed for setting system parameters useful for simulations.

## Functions

void tntMpsProcessDmrgCLOptions (int argc, char **argv, int *max_it, double *precision)

void tntMpsProcessExpecOptions (int argc, char **argv, tntMpsExOp *ExOp)

void tntMpsProcessSysOptions (int argc, char **argv, tntNetwork *mps, tntNetwork *mpo, tntNetwork *prop, tntMpsExOp *ExOp)

void tntMpsProcessTebdCLOptions (int argc, char **argv, int *numsteps, int *tbigstep, int *update_chi, double *emax, int *delta_chi, int *max_chi)

## Function Documentation

 void tntMpsProcessDmrgCLOptions ( int argc, char ** argv, int * max_it, double * precision )

Function that processes additional commonly required input command line arguments for the MPS DMRG algorithm. For general input command line arguments use tntProcessCLOptions() in addition to this, and for input options that initialise the system use tntMpsProcessInitOptions().

Command line options:

Long nameShort nameDescription
--help-dmrg <n> Print this help
--max-it <n> Maximum number of DMRG iterations. If not given default 50 is set.
--max-eig-it <n> Maximum number of iterations used by eigenvalue solver.
--trunc-type <str> How to calculate the truncation error using the discarded singular values. See tntTruncType() for allowed options.
--precision <val> When energy difference between successive DMRG iterations is smaller than this value, the calculation ends. If not given default 1e-4 is used.

Note that, with the exception of --trunc-type which calls the function tntTruncType() to set the truncation type, 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.

Parameters
 argc Input argument count. argv Input arguments. max_it Maximum number of iterations. precision Maximum difference in energy between iterations for calculation to complete

Definition at line 238 of file tntMpsOptions.c.

References tntFinalize(), tntMaxEigIterSet(), tntPrintf(), and tntTruncType().

 void tntMpsProcessExpecOptions ( int argc, char ** argv, tntMpsExOp * ExOp )

Function that processes input command line arguments to create the variables needed for calculating expecation values for spin-half or boson simulations using matrix product states (MPS). Using the options given on the command line, the function can create arrays containing operators for:

1. On-site expectation values
2. Nearest neighbour expectation values
3. All pairs of sites for two-site operators
4. Centre to all other sites for two site operators.

It stores the operators required in the tntMpsExOp structure.

The system type e.g. 'spin' or 'boson' must previously have been set before calling this function.

If the flag for a given expecation value is given, then the corresponding operators are placed in the structure. This structure can then be passed to a relevant tier 2 function e.g. tntMpsExpecOutput() to calculate expectation values when they are required.

### Onsite expectation values

Setting these flags will indicate that the value $$\langle\psi|\hat{o}_j|\psi\rangle$$ should be calculated for every site $$j$$ i.e. $$L$$ values will be calculated.

For bosonic systems the allowed flags are:

Long nameDescription
--Ex1N Calculate $$\langle\psi|\hat{n}|\psi\rangle$$
--Ex1Int Calculate $$\langle\psi|\hat{n}(\hat{n}-1)/2|\psi\rangle$$
--Ex1Nsq Calculate $$\langle\psi|\hat{n}^2|\psi\rangle$$
--Ex1Q1 Calculate $$\langle\psi|\hat{b} + \hat{b}^{\dagger}|\psi\rangle$$
--Ex1Q2 Calculate $$\langle\psi|\mathrm{i}(\hat{b} - \hat{b}^{\dagger})|\psi\rangle$$

For spin systems the allowed flags are:

Long nameDescription
--Ex1Sx Calculate $$\langle\psi|\hat{S}^{x}|\psi\rangle$$
--Ex1Sy Calculate $$\langle\psi|\hat{S}^{y}|\psi\rangle$$
--Ex1Sz Calculate $$\langle\psi|\hat{S}^{z}|\psi\rangle$$

### Two-site expectation values

Setting these flags will indicate that the value $$\langle\psi|\hat{o}^{[1]}_{i}\hat{o}^{[2]}_{j}|\psi\rangle$$ should be calculated for pairs of sites $$i$$ and $$j$$. There are three different choices for the pairs of sites that will be chosen, each with a two-character code set as the argument of the flag (where an '=' must be used) i.e. Ex2<opname>=**.

• For nearest-neighbour expectation values it will be calculated for $$i=0$$ to $$L-2$$ and $$j=i+1$$ i.e. $$L-1$$ values will be calculated. Use the code nn to specify this e.g. --Ex2SzSz=nn.

• For centre-site expectation values it will be calculated for $$i=i_c$$ where $$i_c$$ is the central site $$\mathrm{floor}(L/2)$$ and $$j=0$$ to $$L-1$$ i.e. $$L$$ values will be calculated. Use the code cs to specify this e.g. --Ex2SzSz=cs.

• For all pairs of expectation values it will be calculated for both $$i=0$$ to $$L-1$$ and $$j=0$$ to $$L-1$$ i.e. $$L^2$$ values will be calculated. Use the code ap to specify this e.g. --Ex2SzSz=ap.

If no two-character code is given, or the two-character code is not recognised, then nearest-neighbour pairs will be chosen.

For bosonic systems the allowed flags are:

Long nameDescription
--Ex2bdagb Calculate $$\langle\psi|\hat{b}^{\dagger}_{i}\hat{b}_{j}|\psi\rangle$$.
--Ex2den Calculate $$\langle\psi|\hat{n}_{i}\hat{n}_{j}|\psi\rangle$$.

For spin systems the allowed flags are:

Long nameDescription
--Ex2SxSx Calculate $$\langle\psi|\hat{S}^{x}_{i}\hat{S}^{x}_{j}|\psi\rangle$$.
--Ex2SySy Calculate $$\langle\psi|\hat{S}^{y}_{i}\hat{S}^{y}_{j}|\psi\rangle$$.
--Ex2SzSz Calculate $$\langle\psi|\hat{S}^{z}_{i}\hat{S}^{z}_{j}|\psi\rangle$$.
--Ex2SxSy Calculate $$\langle\psi|\hat{S}^{x}_{i}\hat{S}^{y}_{j}|\psi\rangle$$.
--Ex2SySx Calculate $$\langle\psi|\hat{S}^{y}_{i}\hat{S}^{x}_{j}|\psi\rangle$$.
--Ex2SySz Calculate $$\langle\psi|\hat{S}^{y}_{i}\hat{S}^{z}_{j}|\psi\rangle$$.
--Ex2SzSy Calculate $$\langle\psi|\hat{S}^{z}_{i}\hat{S}^{y}_{j}|\psi\rangle$$.
--Ex2SzSx Calculate $$\langle\psi|\hat{S}^{z}_{i}\hat{S}^{x}_{j}|\psi\rangle$$.
--Ex2SxSz Calculate $$\langle\psi|\hat{S}^{x}_{i}\hat{S}^{z}_{j}|\psi\rangle$$.
--Ex2SpSm Calculate $$\langle\psi|\hat{S}^{+}_{i}\hat{S}^{-}_{j}|\psi\rangle$$.
Returns
No return value.
Parameters
 argc Input argument count. argv Input arguments. ExOp Structure that contains nodes that represent operators for finding expectation values. Unitialised on entry.

Definition at line 200 of file tntMpsProcessExpecOptions.c.

Referenced by tntMpsProcessSysOptions().

 void tntMpsProcessSysOptions ( int argc, char ** argv, tntNetwork * mps, tntNetwork * mpo, tntNetwork * prop, tntMpsExOp * ExOp )

Function that processes input command line arguments to create the system variables needed for spin-half or boson simulations using matrix product states (MPS). Using the options given on the command line, the function can create:

• A network representing the initial MPS wave function.
• A network representing the matrix product operator for the system Hamiltonian.
• An array of nodes U each of which give a two-site propagator representing evolution under the system Hamiltonian.

If any of these is not required, then set the relevant argument to NULL.

The system to build can either be a spin-half system or a boson system, each with their own terms. It is not possible to mix terms for the different systems.

### Spin system

The spin system Hamiltonian will have the following form:

$H = \sum_{j=0}^{L-2} J_{xx}\hat{S}^{x}_{j}\hat{S}^{x}_{j+1} + J_{yy}\hat{S}^{y}_{j}\hat{S}^{y}_{j+1} + J_{zz}\hat{S}^{z}_{j}\hat{S}^{z}_{j+1}+\sum_{j=0}^{L-1} B_{x}\hat{S}^{x}_{j} + B_{y}\hat{S}^{y}_{j} + B_{z}\hat{S}^{z}_{j}$

$+\sum_{j=0}^{L-2} J_{xy}\hat{S}^{x}_{j}\hat{S}^{y}_{j+1} + J_{yx}\hat{S}^{y}_{j}\hat{S}^{x}_{j+1} + J_{yz}\hat{S}^{y}_{j}\hat{S}^{z}_{j+1} + J_{zy}\hat{S}^{z}_{j}\hat{S}^{y}_{j+1} + J_{zx}\hat{S}^{z}_{j}\hat{S}^{x}_{j+1} + J_{xz}\hat{S}^{x}_{j}\hat{S}^{z}_{j+1}.$

Where the $$\hat{S}_{j}^{x,y,z}$$ are the spin operators for site $$j$$ in units where $$\hbar = 1$$.

Boson system

The boson system Hamiltonian will have the following form:

$H = \sum_{j=0}^{L-2}\left[-(J\hat{b}_{j}^{\dagger}\hat{b}_{j+1} + J^{\ast}\hat{b}_{j}\hat{b}_{j+1}^{\dagger}) + V\hat{n}_{j}\hat{n}_{j+1} + (\Delta\hat{b}_{j}\hat{b}_{j+1}+\Delta^{\ast}\hat{b}_{j}^{\dagger}\hat{b}_{j+1}^{\dagger}) \right]$

$+ \sum_{j=0}^{L-1} \left[\frac{U}{2} \hat{n}_{j}(\hat{n}_{j}-1) - \mu \hat{n}_{j} + \frac{1}{2}\epsilon_{\mathrm{harm}}\hat{n}_{j} (j - j_c)^2 + \Omega\hat{b}_{j}+\Omega^{\ast}\hat{b}_{j}^{\dagger} \right],$

Where $$\hat{b}_j$$ is the bosonic annihilation operator for site $$j$$, and $$\hat{n}_j = \hat{b}_j^{\dagger}\hat{b}_j$$.

### Operators

For both of the above Hamiltonians, the terms are only included if the relevant parameter is given in the command line options. Values can be real or complex but must be printed without spaces e.g. the following types of numbers would be recognised 2.1,-1e4,10i,3-2i,-4i+1e-5 but 3 + 3i would not.

The Hamiltonian is built as a network representing the matrix product operator (MPO) using function tntMpsCreateMpo(), which contains the sum of all the terms, and has the following form:

The physical dimension (i.e. the dimension of leg 3 and leg 4) will be $$2S+1$$ for the spin system, and $$n_{\mathrm{max}} + 1$$ for the boson system, where $$\hat{n}_{\mathrm{max}}$$ is the maximum number of bosons allowed on each site. The internal dimension (i.e. the dimension of leg 1 and leg 2) will be equal to 2 + the number of nearest neighbour terms.

If one or both of the parameters --dt= $$\delta t$$ and --idt = $$\delta t_i$$ are given as a command line option the network representing the evolution in real or imaginary time can be built. The time steps are assumed to be scaled by $$\hbar$$, and the propagators are formed into a network formed of two-site propagators arranged in a left-to-right then right-to-left staircase i.e. forming a second order Suzuki-Trotter decomposition. Each two-site propagator evolves its respective pair of sites for half the time-step i.e. each two site propagator will have the form

$U_{j,j+1} = \mathrm{e}^{-\mathrm{i}h_{j,j+1} \delta t/2}\times\mathrm{e}^{-h_{j,j+1} \delta t_i/2},$

and when the entire sequence of left-to-right and right-to-left staircases are applied they result in a total propagator for a timestep:

$U_{\mathrm{total}} = \mathrm{e}^{-\mathrm{i}H \delta t}\times\mathrm{e}^{-H \delta t_i},$

The resulting network is suitable for applying using the MPS library function tntMpsPropST2scProduct(), which multplies an MPS by a staircase propagator i.e. it evolves the MPS one time-step. If neither of dt or idt is specified prop cannot be constructed, and if the argument prop is not set to NULL then an error will result.

### Start state

There are four options for the start state, and network representing the starting wave function will be created if the argument mps is a pointer to a tntNetwork variable, which should be unitialised on entry to the function, and if one of these options is given. If a wave function is not required (because you are loading it from an initialisation file), set the argument of the function to NULL.

#### Random state

This creates a random state having internal dimension $$D$$ - this is useful as a starting state when using DMRG or imaginary time evolution to find the ground state. The initial wave function will be orthonormalised with the orthogonality centre on the first site. This wave function is then in the correct format for an initial left to right sweep using the TEBD or DMRG algorithms.

#### Quantum number conserving random state

This creates a random start state with a given quantum number Q, and sets the system properties to conserve this quantum number during any subsequent simulations. If the sytem is a bosonic system, then the quantum number Q representes the total number of bosons in the system. If the system is a spin system the the quantum number Q represents $$2\sum\hat{S}^{z}_{j}$$.

Note that keeping track of symmetry information to conserve the quantum number causes any part of the MPO, two-site gates, and wave function that do not obey the U(1) symmetry to be discarded, and only the symmetry-invariant parts of the tensors are kept. This greatly speeds up the calculations.

#### Configuration state

This creates a starting configuration e.g. for a spin system:

$|\psi\rangle = |\uparrow\rangle_0\otimes|\uparrow\rangle_1\otimes|\downarrow\rangle_2\otimes|\downarrow\rangle_3\otimes|\uparrow\rangle_4\otimes\downarrow\rangle_5$

or for a boson system:

$|\psi\rangle = |0\rangle_0\otimes|1\rangle_1\otimes|1\rangle_2\otimes|2\rangle_3\otimes|1\rangle_4\otimes|1\rangle_5\otimes|0\rangle_6$

which will have internal dimension 1. This is useful as the start state of real time evolution. To select the first option, use --rand-state <n>, where <n> is an integer that gives the internal dimension. To select the second option, use --config-state=<n> where <n> is a number representing the configuration. The number is given by writing the configuration as a string of digits, with the maximum digit being ( $$d-1$$) e.g. 00110 for the spin example above (0 signifies spin up, 1 signifies spin down) and 0112110 for the boson example above. If the number of digits in the configuration is less than the number of sites specified, then all sites to the right will be filled with 0.

#### Quantum number conserving configuration state

This creates a configuration state in exactly the same way as above, however quantum numbers are added to the internal indices, and a flat is set in the system configuration, to ensure that the quantum number of the initial state is conserved in all subsequent simulations. If the sytem is a bosonic system, then the total number of bosons is conserved. If the system is a spin system then the total spin $$2\sum\hat{S}^{z}_{j}$$ is conserved.

Note that keeping track of symmetry information to conserve the quantum number causes any part of the MPO, two-site gates, and wave function that do not obey the U(1) symmetry to be discarded, and only the symmetry-invariant parts of the tensors are kept. This greatly speeds up the calculations.

### List of command line options

Long nameDescription
--system [spin | boson] System type. Required if operators are to be built.
--dt <val> Size of real time step (real double). Required to build U if –idt is not given. Default is 0.
--idt <val> Size of imaginary time step (real double). Required to build U if –dt is not given. Default is 0.
--rand-state <n> Create a random start state with internal dimension D given by the integer argument.
--qnum-rand-state <n> Create a random start state with total quantum number Q given by the integer argument, and conserve the total quantum number in subsequent simulations.
--config-state <str>Create a starting state having a configuration given by the supplied string.
--qnum-config-state <n> Create a starting state having a configuration given by the supplied string, and conserve the total quantum number of this configuration in subsequent simulations.
--length <n> Number of sites in the MPS. Required.
--qnum-eye-state <str> Use an identity operator as the start state, and turn on quantum number conservation (so all operators that act on the MPO must be quantum number conserving)
--eye-state <str> Use an identity operator as the start state, no symmetries will be applied

If --system=spin is chosen, then the following options are available:

Long nameDescription
--2S <n> Twice the spin $$S$$ of each particle in the system. Default is 1 i.e. a spin half system.
--Jxx <cval> Adds the term $$J_{xx}\hat{S}^{x}_{j}\hat{S}^{x}_{j+1}$$ to the Hamiltonian for a complex $$J_{xx} = \mathtt{<cval>}$$.
--Jyy <cval> Adds the term $$J_{yy}\hat{S}^{y}_{j}\hat{S}^{y}_{j+1}$$ to the Hamiltonian for a complex $$J_{yy} = \mathtt{<cval>}$$.
--Jzz <cval> Adds the term $$J_{zz}\hat{S}^{z}_{j}\hat{S}^{z}_{j+1}$$ to the Hamiltonian for a complex $$J_{zz} = \mathtt{<cval>}$$.
--Jxy <cval> Adds the term $$J_{xy}\hat{S}^{x}_{j}\hat{S}^{y}_{j+1}$$ to the Hamiltonian for a complex $$J_{xy} = \mathtt{<cval>}$$.
--Jyx <cval> Adds the term $$J_{yx}\hat{S}^{y}_{j}\hat{S}^{x}_{j+1}$$ to the Hamiltonian for a complex $$J_{yx} = \mathtt{<cval>}$$.
--Jyz <cval> Adds the term $$J_{yz}\hat{S}^{y}_{j}\hat{S}^{z}_{j+1}$$ to the Hamiltonian for a complex $$J_{yz} = \mathtt{<cval>}$$.
--Jzy <cval> Adds the term $$J_{zy}\hat{S}^{z}_{j}\hat{S}^{y}_{j+1}$$ to the Hamiltonian for a complex $$J_{zy} = \mathtt{<cval>}$$.
--Jzx <cval> Adds the term $$J_{zx}\hat{S}^{z}_{j}\hat{S}^{x}_{j+1}$$ to the Hamiltonian for a complex $$J_{zx} = \mathtt{<cval>}$$.
--Jxz <cval> Adds the term $$J_{xz}\hat{S}^{x}_{j}\hat{S}^{z}_{j+1}$$ to the Hamiltonian for a complex $$J_{xz} = \mathtt{<cval>}$$.
--Bx <cval> Adds the term $$B_x\hat{S}^{x}_{j}$$ to the Hamiltonian for a complex $$B_x = \mathtt{<cval>}$$.
--By <cval> Adds the term $$B_y\hat{S}^{y}_{j}$$ to the Hamiltonian for a complex $$B_y = \mathtt{<cval>}$$.
--Bz <cval> Adds the term $$B_z\hat{S}^{z}_{j}$$ to the Hamiltonian for a complex $$B_z = \mathtt{<cval>}$$.

If --system=boson is chosen, then the following options are available:

Long nameDescription
--n-max <n> Maximum number of bosons allowed per site. Default is 1.
--Jb <cval> Adds a hopping term to the Hamiltonian with the form $$-(J\hat{b}_{j}^{\dagger}\hat{b}_{j+1}+J^{\ast}\hat{b}_{j}\hat{b}_{j+1}^{\dagger})$$ for a complex $$J = \mathtt{<cval>}$$.
--Ub <cval> Adds an on-site interaction term to the Hamiltonian with the form $$\frac{U}{2}\hat{n}_{j}(\hat{n}_{j}-1)$$ for a complex $$U = \mathtt{<cval>}$$.
--Vb <cval> Adds a nearest-neighbour interaction term to the Hamiltonian with the form $$V\hat{n}_{j}\hat{n}_{j+1}$$ for a complex $$V = \mathtt{<cval>}$$.
--mub <cval> Adds a chemical potential term to the Hamiltonian with the form $$-\mu\hat{n}_{j}$$ for a complex $$\mu = \mathtt{<cval>}$$.
--E-harm <cval> Adds a harmonic potential term to the Hamiltonian with the form $$\epsilon_{\mathrm{harm}}\hat{n}_{j}(j-j_c)^2/2$$ for a complex $$E_{h} = \mathtt{<cval>}$$.
--jc-harm <val> Centre of harmonic potential $$j_c$$. Only applied when --E-harm is set and must be a real value. Default is centre of the system.
--coher-driv <cval> Adds a coherent driving term to the Hamiltonian with the form $$\Omega\hat{b}_{j}+\Omega^{\ast}\hat{b}_{j}^{\dagger}$$ for a complex $$\Omega = \mathtt{<cval>}$$.
--param-driv <cval> Adds a parametric driving term to the Hamiltonian with the form $$\Delta\hat{b}_{j}\hat{b}_{j+1}+\Delta^{\ast}\hat{b}_{j}^{\dagger}\hat{b}_{j+1}^{\dagger}$$ for a complex $$\Delta = \mathtt{<cval>}$$.

This function can also be used to create a structure that contains operators for: 1) On-site expectation values 2) Nearest neighbour expectation values 3) All pairs of sites for two-site operators 4) Centre to all other sites for two site operators.

It does this by calling tntMpsProcessExpecOptions() - see the documentation for this function for more information.

Returns
No return value.
Parameters
 argc Input argument count. argv Input arguments. mps The MPS or MPO network represeting the start state. Set to NULL if not required. mpo The MPO network representing the system Hamiltonian. Set to NULL if not required. prop Array of nodes representing the two-site gates for evolution. ExOp Structure that contains nodes that represent operators for finding expectation values.

Definition at line 210 of file tntMpsProcessInitOptions.c.

 void tntMpsProcessTebdCLOptions ( int argc, char ** argv, int * numsteps, int * tbigstep, int * update_chi, double * emax, int * delta_chi, int * max_chi )

Function that processes additional commonly required input command line arguments for the MPS TEBD algorithm. For general input command line arguments use tntProcessCLOptions() in addition to this, and for input options that initialise the system use tntMpsProcessInitOptions().

Command line options:

Long nameShort nameDescription
--help-tebd <n> Print this help
--timesteps <n> -t <n> Number of timesteps to be performed.
--tbigstep <n> -b <n>Number of timesteps to be performed between each calculation of expectation values. If not given, then expectation values are calculated at the end of the routine only.
--trunc-type <str> How to calculate the truncation error using the discarded singular values. See tntTruncType() for allowed options.
--update-chi-u Update chi with increasing truncation error. Turned off by default.
--error-tol <val>Truncation error tolerance for increasing chi. Default is 1e-6.
--delta-chi <n> Amount by which to increase chi. Default value 50.
--max-chi <n> Value at which to stop increasing chi, even if the error exceeds error-tol. Default value 500.

Note that, with the exception of --trunc-type which calls the function tntTruncType() to set the truncation type, 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

Parameters
 argc Input argument count. argv Input arguments. numsteps Number of timesteps to run for. tbigstep Number of timesteps between each calculation of expectation values. update_chi Flag for allowing chi to change. emax Tolerance for truncation error for changing chi. delta_chi Amount by which to increase chi. max_chi Value at which to stop increasing chi.

Definition at line 60 of file tntMpsOptions.c.

References tntFinalize(), tntPrintf(), and tntTruncType().