Matrix Product Toolkit | Itools / Mp-idmrg5

mp-idmrg5 is the main iDMRG tool. Unlike the finite system tools, there is not yet any concept of a lattice file, and the Hamiltonian is hard-coded into the mp-idmrg5 program. Hence the actual options to specify the Hamiltonian are likely to change a lot, as new models and parameter options are added.

Generic command-line options:

Matrix Product Toolkit version HEAD-0.7.4.0 (subversion tree rev 1120M)
Compiled on Dec  7 2010 at 07:42:04
Copyright (c) Ian McCulloch 1999-2010 All Rights Reserved
For license conditions email ianmcc@physics.uq.edu.au
usage: mp-idmrg [options]
Allowed options:
  --help                    show this help message
  -H [ --Hamiltonian ] arg  model Hamiltonian.  Valid choices: itf, itf-z2, xxx-su2, xxx-u1, xxx, tj-zigzag-u1su2, 
                            tj-zigzag-u1, sf-zigzag-u1, klm-u1su2, klm-u1, bh, bh2, bh-u1, bh2-u1, kagome-su2
  -w [ --wavefunction ] arg wavefunction to apply DMRG (required)
  -2 [ --two-site ]         Modify two sites at once (default)
  -1 [ --one-site ]         Modify one site at a time
  -m [ --max-states ] arg   Maximum number of states to keep [default 100000]
  --min-states arg          Minimum number of states to keep [default 1]
  -r [ --trunc ] arg        Truncation error cutoff [default 0]
  -d [ --eigen-cutoff ] arg Cutoff threshold for density matrix eigenvalues [default -1]
  -f [ --mix-factor ] arg   Mixing coefficient for the density matrix [default 0]
  --evolve arg              Instead of Lanczos, do imaginary time evolution with this timestep
  -a [ --random ]           Create a new wavefunction starting from a random state
  -e [ --exactdiag ]        Start from an effective exact diagonalization of the unit cell
  -u [ --unitcell ] arg     Only if --create is specified, the size of the unit cell
  -q [ --target ] arg       the target quantum number per unit cell
  --boundary arg            use this boundary quantum number for initializing the unit cell (useful for integer spin 
                            chains)
  -b [ --bootstrap ]        boostrap iterations by starting from a single unit cell, instead of obtaining the fixed point
                            Hamiltonian ('bootstrap' is necessary if the wavefunction is not orthonormal)
  -s [ --steps ] arg        Number of DMRG steps to perform [default 10]
  --no-orthogonalize        Don't orthogonalize the wavefunction before saving
  --maxiter arg             Maximum number of Lanczos iterations per step (Krylov subspace size) [default 20]
  --miniter arg             Minimum number of Lanczos iterations per step [default 4]
  --maxtol arg              Maximum tolerance of the eigensolver [default 0.00040000000000000002]
  --fidelityscale arg       The tolerance of the eigensolver is min(maxtol, fidelityscale * sqrt(fidelity)) [default 
                            0.10000000000000001]
  --initialfidelity arg     Initial value for the fidelity to set the eigensolver tolerance, for the first iteration 
                            [default 9.9999999999999995e-08]
  --spin arg                spin (for xxx,xxz,xyz hamiltonians) [default 0.5]
  --J arg                   nearest-neighbor exchange J (for xxx,itf, etc) [default 1]
  --Jperp arg               perpendicular exchange exchange J (for xxx-ladder) [default 0]
  --periodic                periodic in the perendicular direction (for xxx-ladder)
  --J2 arg                  next-nearest-neighbor exchange J2 (for xxx) [default 0]
  --D arg                   single-ion anisotropy (for xxx-u1 and xxx) [default 0]
  --V arg                   nearest-neighbor coulomb (for bhj-u1) [default 0]
  --U arg                   coulomb repulsion [default 0]
  --B arg                   magnetic field (for xxx) [default 0]
  --Jz arg                  Jz coupling (for Kondo) [default 1]
  --Jleg arg                Jleg coupling (for Kagome strop) [default 1]
  --Jcross arg              Jcross coupling (for Kagome strip) [default 1]
  --mu arg                  Chemical potential (bose-hubbard) [default 0]
  --kagome-cell arg         Unit cell for kagome with plaquette (for Kagome strip with field, kagome-field-su2) [default 
                            24]
  --nlegs arg               Number of legs (for triangular ladder) [default 1]
  --tprime arg              next-nearest-neighbor hopping t' (for tj-zigzag, sf-zigzag) [default 1]
  --nmax arg                Maximum number of particles (for bose-hubbard model) [default 3]
  --delta arg               Zigzag ladder potential imbalance (for tj-zigzag, sf-zigzag) [default 0]
  --theta arg               theta (for biquadratic xxx) [default 0]
  --Beta arg                Beta (for biquadratic xxx) [default 0]
  --lambda arg              transverse field strength (for itf hamiltonian) [default 1]
  --seed arg                random seed
  -v [ --verbose ]          increase verbosity

The -H parameter determines the Hamiltonian to use, which is of the form of a string (such as xxx or hubbard-u1). Most models have some additional parameters (eg, coupling coefficients) which can also be specified; see below.

The -w option specifies the filename for the wavefunction file. For a new calculation, use the -b option to 'bootstrap' the calculation from a single unit cell. In this case, you must also supply the unit cell size (with -u), the target quantum number per unit cell (with -q), and either -e or -a to start from either an exact diagonalization of a unit cell (OBC), or from a random state. If the unit cell is small enough that an exact diagonalization is practical, use -e. Otherwise, use -a.

Example:

mp-idmrg5 -H xxx-su2 --spin 1 --theta 0.25 -w psi -b -e -u 1 --boundary 1 -q 0 -m 50 -s 50

This will start a calculation for the bilinear-biquadratic spin-1 chain (XXX model with spin-1 and SU(2) symmetry), at the point theta=0.25*pi, which corresponds to the exactly-solvable SU(3) Uimin-Lai-Sutherland point. We have specified that the unit cell will be one site (-u 1), with quantum number 0 (-q 0). No other quantum numbers are possible for SU(2) symmetry, but for other models we could find a ferromagnetic or a doped state by choosing the quantum number per unit cell. The -b -e options mean that we are starting a new calculation from an exact diagonalization of one unit cell. Because the unit cell in this case is a single site with spin 1, but we want our final state to have spin 0, this initial exact diagonalization is going to fail unless we set an appropriate boundary condition. Here we choose the boundary condition to be spin 1 (--boundary 1), which allows a solution.

Note that the exact groundstate energy per site of this model is (2 - ln 3 - pi / (3 sqrt(3))) / sqrt(2) = 0.209860753107

Another use for the --boundary option is in a Haldane phase, where we have a spin-1 chain but we want spin-1/2 boundaries.

For a continuing calculation, omit the -b option. The -q, -u, -e, -a options can also be omitted, as they are read from the wavefunction file anyway.

For an SU(2) symmetry, the target quantum number per unit cell must be zero. It is not possible to do ferri- or ferromagnetic SU(2) states with this code. This limitation does not apply to abelian quantum numbers.

The 1, 2, m, minstates, r, d, f options act similarly to the finite size DMRG code. Note that two-site DMRG with no mix factor (-2 -f 0) is the default for iDMRG. The 1-site option isn't completely implemented - it uses a one-site scheme when traversing the unit cell, but at the turning points it uses the 2-site scheme. Note that there is no conflict between using a 2-site DMRG scheme and having a unit cell of one site! You still end up with a wavefunction that is translationally invariant under 1-site shifts.

The -s option specifies how many 'sweeps' to perform. A sweep in iDMRG means updating the unit cell twice, once in a left-moving direction and once in a right moving direction.

In summary, typical usage of idmrg for starting a calculation from scratch (create/overwrite the wavefunction file), here for an XX spin chain with U(1) symmetry -H xxx-u1, a unit cell size of 6 sites -u 6 and a magnetization of 1/6 -q 1, with 30 states kept -m 30 and 20 sweeps -s 20:

mp-idmrg5 -H xxx-u1 -m 30 -s 20 -b -e -u 6 -q 1 -w psi

This will result in a wavefunction psi, and the final energy in this example is ~ -2.00866 per unit cell = -0.33478 per site.

The --evolve parameter is often useful. This replaces the Lanczos solver with a 1st order imaginary time step 1-tH, where t is the timestep (typically ~0.1 - 0.0001). This results in a smoother convergence and is useful for optimizing wavefunctions prior to calculating transfer matrix spectra, critical exponents, etc. Note that this does an evolution of the entire wavefunction using the full Hamiltonian. This does not use the Suzuki-Trotter decomposition, so is different to the TEBD approach.

It is possible to interrupt the mp-idmrg5 program in the middle of a calculation. Pressing ^C on the keyboard, or sending the process SIGINT, SIGTERM, SIGUSR1 or SIGUSR2 will stop the program at the end of the current sweep. Note that in this case, the wavefunction is NOT orthogonalized at the end. It is necessary to manually orthogonalize the wavefunction using mp-iorthogonalize.

Model-specific parameters

A Hamiltonian may use additional parameters to specify the spin, coupling coefficients etc. To see exactly what these do, look at the code. Some examples:

  --spin arg                spin (for xxx,xxz,xyz hamiltonians) [default 0.5]
  --J arg                   nearest-neighbor exchange J (for xxx,itf, etc) [default 1]
  --J2 arg                  next-nearest-neighbor exchange J2 (for xxx) [default 0]
  --D arg                   single-ion anisotropy (for xxx-u1 and xxx) [default 0]
  --U arg                   coulomb repulsion [default 0]
  --B arg                   magnetic field (for xxx) [default 0]
  --Jz arg                  Jz coupling (for Kondo) [default 0]
  --Jleg arg                Jleg coupling (for Kagome strop) [default 1]
  --Jcross arg              Jcross coupling (for Kagome strip) [default 1]
  --nlegs arg               Number of legs (for triangular ladder) [default 1]
  --tprime arg              next-nearest-neighbor hopping t' (for tj-zigzag, sf-zigzag) [default 1]
  --nmax arg                Maximum number of particles (for bose-hubbard model) [default 3]
  --delta arg               Zigzag ladder potential imbalance (for tj-zigzag, sf-zigzag) [default 0]
  --theta arg               theta (for biquadratic xxx) [default 0]
  --Beta arg                Beta (for biquadratic xxx) [default 0]
  --lambda arg              transverse field strength (for itf hamiltonian) [default 1]

Make sure that you understand the convention that the code uses for each coupling coefficient! If in doubt, look at the code. In some cases, the code may use an unusual or awkward convention. In that case, feel free to change it, but you should add a note both to the help message for the mp-idmrg5 program and on this wiki.

Other parameters

There are a couple of other generic parameters to mp-idmrg5, which are not so important. --maxiter specifies the maximum number of iterations of the Lanczos procedure. This is a maximum value only, the actual number of iterations is determined by a tolerance value, so the maximum is only reached when the calculation is converging slowly.

The tolerance of the eigensolver is determined by the fidelity of the wavefunction over the previous few iterations. Define f^2 = 1 - |<psi|\psi_old>| to be the 'fidelity loss' at the previous iteration. Then choose the desired residual length as r = f \times f_scale, where f_scale} is the --fidelityscale parameter, default of 0.1. To stop the tolerance from getting too large in some corner cases, the --maxtol parameter defaults to 0.0004.

Output

The idmrg program writes out one line per step to standard output:

X Energy= States= TruncError= Entropy= Fidelity= Iter= Tol=

The first character is one of L,R,A,B. L and R are the left- and right-moving sweeps through the unit cell. A and B are the turning points where the infinite scheme is applied. Energy per unit cell, number of states kept, truncation error, von Neumann entropy (base e), fidelity squared, number of Lanczos iterations performed, and final tolerance of the eigensolver. If the eigensolver didn't converge to the desired tolerance (ie, after maxtol iterations), then the Tol value is the negative of the final tolerance.