Upgrading from 1.x

TensorMixedStates 2.0 is a rewrite of the package. What it computes is the same, but its interface was made smaller and uniform, so that a program written for 1.x needs edits, most of them mechanical, which this page lists from version 1.6. A name or a keyword that 2.0 removed, renamed or moved is refused with an error rather than taken for something else, and for most of them the error Julia prints ends with a line beginning with TensorMixedStates 2.0: that says what to write instead.

Saved states and checkpoints

The states saved by save_state or SaveState with 1.x are read by 2.0. The checkpoints are not: 2.0 refuses to resume a simulation stopped under 1.x. Finish it with 1.x, or start it over, by putting a file named restart in its directory or by calling cleanTMS(sim_data) before runTMS.

A program converted

These lines of the manual of 1.6 compute a ground state, three evolutions and a steady state:

energy, ground = dmrg(hamiltonian, RandomState{Pure}(mysystem, 8); nsweeps = 10,
                      limits = Limits(maxdim = 20))
myevolved = tdvp(-im * sum(Z(i) for i in 1:4), 0.5, State{Pure}(System(4, Qubit()), "+");
                 nsweeps = 10)
mydecayed = tdvp(sum(Dissipator(Sm)(i) for i in 1:4), 1.0, myrho; nsweeps = 10)
mydecayed = approx_W(sum(Dissipator(Sm)(i) for i in 1:4), 1.0, myrho; order = 4, w = 2,
                     nsweeps = 10)
value, mysteady = steady_state(sum(Dissipator(Sm)(i) + 0.5Dissipator(Sp)(i) for i in 1:4),
                               myrho; nsweeps = 10)

With 2.0, they are written

energy, ground = ground_state(hamiltonian, random_state(Pure, mysystem, 8);
                              algo = Dmrg(nsweeps = 10), limits = Limits(maxdim = 20))
myevolved = evolve(-im * sum(Z(i) for i in 1:4), 0.5, State{Pure}(System(4, Qubit()), "+");
                   nsteps = 10)
mydecayed = evolve(sum(Dissipator(Sm)(i) for i in 1:4), 1.0, myrho; nsteps = 10)
mydecayed = evolve(sum(Dissipator(Sm)(i) for i in 1:4), 1.0, myrho;
                   algo = ApproxW(order = 4, w = 2), nsteps = 10)
value, mysteady = steady_state(sum(Dissipator(Sm)(i) + 0.5Dissipator(Sp)(i) for i in 1:4),
                               myrho; algo = Dmrg(nsweeps = 10))

and they give the same results: the same ground state energy, -12.381489999654791, and the same expectation values to 1e-14.

Solvers

The solvers are four functions, evolve, ground_state, steady_state and thermalize, each given its method as algo, see Algorithms. The options of a method are the fields of algo, and no option is passed on to ITensorMPS any more: the truncation is given by limits = Limits(cutoff = …, maxdim = …, mindim = …), and a Krylov method by krylov = Krylov(…).

Dmrg has no default number of sweeps, which dmrg took as 1. ground_state no longer takes an MPO: give the operator, or its PreMPO(state, operator), prepared once for several calls. A mixed state is refused by ground_state: search the pure state and mix it. ground_state, steady_state and thermalize return named tuples, (energy, state), (residual, state) and (log_trace, state), which destructure as before.

Measurements

The value of a Hermitian operator is real, its imaginary part dropped with a warning when it is more than rounding, and that of an operator that is not Hermitian is complex, whatever the state: the columns of a file do not depend on it. For the same reason, Trace is complex. expect, expect1 and expect2 follow that rule, where 1.x gave the complex numbers computed, which complex = true gives.

A list of measurements given to measure is one list: measure(state, [Measure(…), Measure(…)]) measures the two as one, where 1.x returned a group for each. A measurement alone gives its value, where 1.x gave a vector of one pair: last(only(measure(state, m))) is now measure(state, m), and measure(state, [m]) gives the pair.

Simulations

The data files are tables: a line naming the columns, then a line per time measured. sim.data holds the rows of each Data destination, a row reading a value by its name, row["X(1)"], and the rows a table with the columns of the data files, which data_to_frame and DataFrame take.

A phase of one's own is a subtype of TensorMixedStates.AbstractPhase, which replaces the union Phases, with the fields name, time_start and final_measurements, and it runs by run_phase(phase, sim, done), or step by step by prepare_phase, step_count and run_step, see Extending TMS. run_steps, resume_step and Algo are gone, TensorMixedStates.EvolutionAlgorithm and TensorMixedStates.SearchAlgorithm taking the place of the last.

Operators, sites and states

Defaults that changed

Some results change without any edit beyond those above:

• The truncation. A field of Limits left out takes the default of the function the limits are given to, almost everywhere the cutoff 1e-26, which discards the singular values below 1e-13 of the norm, what rounding leaves, where 1.x kept everything. The bond dimensions are smaller, the results differing at the level of rounding. Limits(maxdim = 50) truncates at 1e-26 as well, and Limits(cutoff = 0) keeps everything.
• Tdvp enlarges the bonds of a state whose bond dimension is below both 5 and maxdim before a step, which makes an evolution from a product state much more precise, and expand_period adds such expansions periodically. It tests the convergence of each local exponentiation after every Krylov vector, where 1.x waited for the Krylov space to be full.
• ApproxW multiplies by its MPOs exactly before truncating, apply_algo = "naive", where 1.x used "densitymatrix", and its approximation WII, w = 2, is built after Zaletel et al.: its results change at the order of the error of the method, with smaller bond dimensions. With an evolver depending on time, the orders 3 and 4 use the commutator-free Magnus integrator of order 4 of Blanes and Moan, where 1.x read the time functions at the middle of each step.
• steady_state and SteadyState solve each local problem with Krylov(dim = 8, maxiter = 3), which the spectrum of $L^\dagger L$, crowded near zero, needs, where 1.x took those of ITensorMPS, 3 and 1: they converge where the searches of 1.x could stall. Krylov(dim = 3, maxiter = 1) with Limits(cutoff = 0) gives the results of 1.x again.
• The values measured. Whether an operator is Hermitian is decided numerically: an operator 1.x could not prove Hermitian, as Sp(1)Sm(2) + Sm(1)Sp(2), has a real value, and an anti-Hermitian one its complex value, where 1.x gave its imaginary part as Im(name). A pair of operators is named (X, Y), where 1.x named it XY.
• The files. Every number is written with SimData(format = "%.13g"), thirteen significant digits, the time included, where 1.x wrote the values with eight and the time with four; format = "%.8g" gives the width of 1.x back. A .json file is the array of an object per time, where 1.x wrote an object per measurement, and a .jsonl file the same objects as JSON Lines, written as they are measured.
• runTMS no longer changes the working directory: a relative path in the code of a phase is taken from the directory runTMS was called in, where 1.x ran in that of the simulation.
• data_to_frame gives the columns of the data files, a vector or a matrix spread over several, as X(1), X(2), in the order the measurements were first made, where 1.x gave a column per measurement, a vector or a matrix in each cell.
• The random draws of a run use its own generator, seeded by SimData(; seed), or by a seed drawn and written in stamp, and kept by its checkpoints.