High level interface

runTMS(sim_data; max_time = Inf, checkpoint_interval = 0, threading = :dense, output = nothing)

run the simulation, see SimData, in a directory named after it, and return the Simulation it ends with. A checkpoint found in the directory is resumed from, if it was written by the same program, prog.jl in the directory, given the same arguments: copying an edited program there, or setting TMS_ACCEPT_PROGRAM=1, resumes it with that one. A file restart in the directory starts the simulation over, and cleanTMS removes the directory. A destination that is a file of the directory, as log or stamp, or a text file given two lists, is refused before the run starts.

• max_time: seconds after which the run stops, writing a checkpoint
• checkpoint_interval: seconds between two checkpoints, 0 for those of a stop only
• threading: how the contractions are threaded, see set_threading: :dense, :blocks, :auto, chosen before each phase from the system of the state, or nothing, leaving the threading as it is
• output: a stream to write everything to, stdout or devnull for instance, instead of a directory; nothing can then be resumed

The first three are overridden by the environment variables TMS_MAX_TIME, TMS_CHECKPOINT_INTERVAL and TMS_THREADING, TMS_MAX_TIME=3600 julia prog.jl for instance. The run also stops, writing a checkpoint, when the file stop appears in its directory, and on an interrupt. Runs may be nested or run on several threads: the outermost one sets the threading and the behaviour of Ctrl-C, which the last to end puts back, and an interrupt stops a nested run and the runs it is in, each resuming where it was. A nested run, as in an Update, is done again when the run it is in resumes, the same way with output = devnull and a seed only: in a directory of its own, it resumes its checkpoint or starts over, a seed drawn anew.

stopped(sim)

whether the run runTMS returned stopped before the end of its phases, at max_time, on the file stop or on an interrupt: running it again resumes it

Examples

sim = runTMS(sim_data)
if stopped(sim)
    println("stopped at time ", sim.time, ", to be resumed")
end

cleanTMS(sim_data)
cleanTMS(name)

remove the directory of a simulation, refused while a run may be using it

Examples

cleanTMS(sim_data)

SimData(; name = "simulation", phases, options...)

the description of a simulation, which runTMS runs.

• name: the name of the simulation, and of the directory its results are written to
• phases: the phases, see TensorMixedStates.AbstractPhase, as a vector which may contain vectors to any depth, flattened
• description: the text of the file description of the simulation (default "")
• time_start: the time the simulation starts at (default 0)
• final_measurements: the measurements made at the end, see output (default [])
• format: the Printf format of the numbers written to text files (default "%.13g", thirteen significant digits, the precision below which a difference is taken for rounding)
• seed: the seed of the random number generator of the run, sim.rng, an integer of zero or above, drawn at random by default and written in the file stamp, so that a run can be made again

A measurement of a value that no phase provides is refused here, see TensorMixedStates.provided_values, and so is a state named by a name the run reserves, or twice in the on of a phase.

Examples

SimData(
    name = "ising",
    phases = [
        CreateState{Pure}(10, Qubit(), "Up"),
        GroundState(hamiltonian = -sum(Z(i) * Z(i + 1) for i in 1:9) - sum(X(i) for i in 1:10),
                    algo = Dmrg(nsweeps = 10), limits = Limits(maxdim = [10, 20, 50]),
                    final_measurements = "data" => [:energy, X, Z]),
    ],
)

Simulation(sim, state[, time = sim.time]; values...)

the simulation runTMS runs and returns: a state, its time and its values, which the measurements read, sim.energy as c.energy. The form above gives sim another state, and possibly another time and other values, sharing its run. A value is a number, an array, a state, anything a phase leaves for the measurements and the phases after it; a checkpoint keeps it, so that it must not be changed in place.

• sim.state, sim.time: the state and the time
• sim.step: the steps the phase being run has done
• sim.rng: the random number generator of the run, for every draw of a phase, see SimData
• sim.name: the value name, a state named by CopyState for instance
• sim.data: the rows gathered in each Data(name), under name, a table, see Data

Examples

sim = runTMS(sim_data)
rows = sim.data["magnetization"]

Data(name)

a destination kept in memory, a vector of rows, each the time then the pairs name => value measured, see DataRow, and a table of the cells of these values, see DataTable

data_to_frame(rows)

the DataFrame of the rows of a Data, DataFrame(rows), see DataTable: the column time, then the columns a text table of the same measurements has, in the order they first come, missing in a row without them. The DataFrames package must be loaded.

Examples

using DataFrames
df = data_to_frame(sim.data["magnetization"])

abstract type AbstractPhase

the supertype of the phases of a simulation. Every phase has these three fields:

• name: the name of the phase, written in the log
• time_start: the time the clock is set to when the phase starts (default nothing, keeping the time)
• final_measurements: the measurements to make at the end of the phase, see output (default [])

A phase of one's own is a subtype with these fields and either of two interfaces, runTMS logging it, applying its time_start and making its final measurements:

• a phase made of steps has methods of TensorMixedStates.prepare_phase, TensorMixedStates.step_count and TensorMixedStates.run_step; the run measures its field measurements, if it has one, every measurements_period steps (1 without that field), logs, commits and stops between two steps, and resumes it after the last step committed
• a phase of a single call has a method of TensorMixedStates.run_phase, which calls TensorMixedStates.step_done wherever it can stop

A phase providing values to the measurements, as :energy, declares them with a method of TensorMixedStates.provided_values.

CreateState(; type, system, state, randomize, on, name, time_start, final_measurements)
CreateState(state::State; options...)
CreateState{Pure|Mixed}(system, state; options...)
CreateState{Pure|Mixed}(n, site, state; options...)
CreateState{Pure|Mixed}(sites, state; options...)

a phase that creates the state of the simulation.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• type: the representation of the state, Pure or Mixed, by default that of state when it is a State
• system: the System of the state, unused when state is a State
• state: a description of the state, see State, or a State, mixed if type asks for it
• randomize: the link dimension of a random state to draw with the generator of the run, see random_state (default 0, none): a pure state randomized from state, a mixed one drawn from a purification starting from it, or without state any state of the system
• on: the name the state created takes, see CopyState (default :state)

Examples

CreateState(type = Pure, system = System(10, Qubit()), state = "Up", randomize = 50)
CreateState(graph_state(System(10, Qubit()), complete_graph(10)))
CreateState{Mixed}(4, Fermion(conserve = N), ["Occ", "Emp", "Occ", "Emp"]; randomize = 16)
CreateState{Pure}(10, Qubit(), "Up")

LoadState(; file, statename = "state", limits, on = :state, name, time_start,
            final_measurements)

a phase that loads a state from an HDF5 file written by SaveState or save_state, see load_state, and truncates it to limits, unless they are the default Limits().

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• file: the HDF5 file, taken in the directory of the simulation when it is relative: a state another simulation saved is found under ../othername/
• statename: the name of the state in the file
• limits: the truncation of the state once loaded, see Limits
• on: the name the state takes in the simulation, :state for the current state, another for a reference state, c.ref to the measurements, see Fidelity

Examples

LoadState(file = "ground.h5")
LoadState(file = "../other/ground.h5", statename = "gs", on = :ground)

SaveState(; file, statename = "state", on = :state, name, time_start, final_measurements)

a phase that saves a state in an HDF5 file, see save_state, replacing a state saved there under the same name.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• file: the HDF5 file, taken in the directory of the simulation when it is relative, not one of the files of the simulation, as log, which the run refuses before it starts
• statename: the name of the state in the file
• on: the state saved, :state the current one, or one the simulation named

Examples

SaveState(file = "states.h5", statename = "after_quench")

CopyState(from => to; move = false, name, time_start, final_measurements)

a phase that copies the state named from under the name to, :state naming the current state: CopyState(:state => :ground) keeps the current state as :ground, which the measurements read as c.ground, see Fidelity, and CopyState(:ground => :state) makes it the current state again. With move = true, from is removed, which frees its memory and its place in the checkpoints. A copy costs nothing, the two names sharing the state.

Examples

CopyState(:state => :ground)
CopyState(:ground => :state; move = true)

Update(f; nsteps = 1, provides = [], measurements, measurements_period, name, time_start,
       final_measurements)

a phase that changes the simulation by the function f(c), which reads it as a measurement reads its context, c.state, c.time, c.step, c.rng, c.ground, and changes it by assignments:

• c.state = st, c.time = t: the state and the time
• c.x = v: a value of the simulation, measured and kept by the checkpoints, c.x = nothing removing it, which frees the memory of a state

The phase makes nsteps steps, the run measuring measurements every measurements_period steps, committing and stopping between two, as for Evolve, c.step being the steps done before. A stopped run resumes after the last step committed: f must draw with c.rng alone and act only through c, output(c, …) and log_message(c, …), what it changes elsewhere being neither kept nor done again. f works on a copy, which a failure leaves the simulation without.

• provides: the names of the values f sets, which the measurements may then read, see TensorMixedStates.provided_values

Examples

Update(c -> c.ground = c.state; provides = [:ground])
Update(c -> c.ground = nothing)
Update(nsteps = 1000, provides = [:m], measurements = "kicks" => [Z(1), :m],
       measurements_period = 10) do c
    c.m, _, c.state = collapse(apply(kick, c.state), Z(1); rng = c.rng)
end

ToMixed(; limits, on, name, time_start, final_measurements)

a phase that takes the state to the mixed representation, mix(state; limits), truncated to limits unless they are the default Limits(); a state already mixed is only truncated.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• limits: the truncation of the mixed state, see Limits
• on: the name of the state the phase acts on, see CopyState (default :state)

Examples

ToMixed(limits = Limits(cutoff = 1e-10, maxdim = 10))

Weaken(; target, on, name, time_start, final_measurements)

a phase that takes the state down to a lower level of conservation, see weaken: a phase may evolve under a strong symmetry, and the next one under a weak one, where a jump that moves the charge becomes possible.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• target: what the state must still conserve, as weaken takes it (default nothing, one level down)
• on: the name of the state the phase acts on, see CopyState (default :state)

Examples

Weaken()
Weaken(target = ())

PartialTrace(; keep | trace_out, on, name, time_start, final_measurements)

a phase that reduces the state to the sites at the positions keep, in increasing order, or traces out those at trace_out, see partial_trace. The sites kept make a new system, numbered from 1 in the order of the chain, which the operators of the phases after this one refer to. on is the name of the state it acts on, see CopyState (default :state).

Examples

PartialTrace(trace_out = [2, 3, 6])
PartialTrace(keep = [1, 4, 5])

Gates(; gates, limits, on, name, time_start, final_measurements)

a phase that applies gates to the state, see apply, by its steps, a batch of gates or an MPO, between which the run can write a checkpoint or stop.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• gates: the gates, an operator or a channel placed on sites
• limits: the truncation, see Limits
• on: the name of the state the phase acts on, see CopyState, or a vector of names, each state acted on alike (default :state)

Examples

Gates(gates = controlled(X)(1, 3) * controlled(Z)(2, 4), limits = Limits(maxdim = 20))

Evolve(; evolver, duration, time_step | nsteps, algo = Tdvp(), limits, mpo_limits,
         measurements, measurements_period, on, name, time_start, final_measurements)

a phase of time evolution, see evolve.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• evolver: -im * H for a Hamiltonian H, plus dissipators for a mixed state, or for an evolver depending on time a vector of terms [A, B => g], see evolve, the time being that of the simulation
• duration: the duration of the evolution
• time_step: the time step, adjusted to the nearest one dividing the duration into a whole number of steps, and taken with the sign of the duration (no step when that number is zero), or nsteps, the number of steps, one of the two being given
• algo: the method, see EvolutionAlgorithm
• limits: the limits of the state, see Limits
• mpo_limits: the truncation of the MPO of the evolver, see PreMPO (default none)
• measurements: the measurements made after every measurements_period steps (default 1), see output; the state the phase starts from is measured by the final measurements of the phase before
• on: the name of the state the phase evolves, see CopyState, or a vector of names, the states of one system and one representation evolved together under the evolver, the time advancing once, for two time correlations for instance (default :state)

Examples

Evolve(evolver = -im * (Z(1) * Z(2) + Z(2) * Z(3)), duration = 2., time_step = 0.1,
       measurements = "data" => [X, Y, Z])

Thermalize(; hamiltonian, beta, beta_step | nsteps, algo = Tdvp(), limits, mpo_limits,
             measurements, measurements_period, on, name, time_start, final_measurements)

a phase that takes a mixed state $\rho$ to $e^{-\beta H/2} \rho \, e^{-\beta H/2}$, normalized to trace one, by an evolution in imaginary time, see thermalize: from "FullyMixed", the thermal state $e^{-\beta H}/Z$. The time does not move. It provides the values :beta, the inverse temperature reached, and :log_trace, the logarithm of the trace before normalization, see thermalize: 0 both for a beta shorter than half a step, which leaves the state normalized only.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• hamiltonian: the Hamiltonian $H$
• beta: the inverse temperature $\beta$
• beta_step: its step, adjusted as the time step of Evolve, or nsteps, the number of steps, one of the two being given
• algo: the method, see EvolutionAlgorithm
• limits: the limits of the state, see Limits
• mpo_limits: the truncation of the MPO of the Hamiltonian, see PreMPO (default none)
• measurements: the measurements made after every measurements_period steps (default 1)
• on: the name of the state the phase acts on, see CopyState (default :state)

Examples

Thermalize(hamiltonian = -sum(Z(i) * Z(i + 1) for i in 1:9) - sum(X(i) for i in 1:10),
           beta = 2., beta_step = 0.1, limits = Limits(maxdim = 64),
           measurements = "thermo" => [:beta, :log_trace, Z(5)])

GroundState(; hamiltonian, algo, limits, mpo_limits, orthogonal_to, weight, measurements,
              measurements_period, on, name, time_start, final_measurements)

a phase that searches the ground state of a Hamiltonian from the pure state, see ground_state, or an excited state, the value :energy taking the energy of each sweep.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• hamiltonian: the Hamiltonian
• algo: the method, see SearchAlgorithm
• limits: the limits of the sweeps, see Limits, which may give one value per sweep
• mpo_limits: the truncation of the MPO of the Hamiltonian, see PreMPO (default none)
• orthogonal_to: the eigenstates the state searched is orthogonal to, by their names in the simulation, see CopyState, or given, and weight, see ground_state (default none)
• measurements: the measurements made after every measurements_period sweeps (default 1)
• on: the name of the state the phase acts on, see CopyState (default :state)

Examples

GroundState(hamiltonian = X(1) * X(2), algo = Dmrg(nsweeps = 10, tol = 1e-10),
            limits = Limits(maxdim = [10, 20, 30]))
[GroundState(hamiltonian = H, algo = Dmrg(nsweeps = 10)), CopyState(:state => :ground),
 GroundState(hamiltonian = H, algo = Dmrg(nsweeps = 20), orthogonal_to = [:ground])]

SteadyState(; lindbladian, algo, limits, mpo_limits, measurements, measurements_period, on,
              name, time_start, final_measurements)

a phase that searches the steady state of a Lindbladian from the mixed state, see steady_state, the value :residual taking the eigenvalue of $L^\dagger L$ of each sweep, 0 for a steady state, and the state measured after a sweep having trace one. Its lists of measurements cannot read :energy, which would be that of another phase.

• name, time_start, final_measurements: the fields of every phase, see TensorMixedStates.AbstractPhase
• lindbladian: the Lindbladian $L$, -im * H plus dissipators
• algo: the method, see SearchAlgorithm
• limits: the limits of the sweeps, see Limits
• mpo_limits: the truncation of the MPO of $L^\dagger L$, see PreMPO (default none)
• measurements: the measurements made after every measurements_period sweeps (default 1)
• on: the name of the state the phase acts on, see CopyState (default :state)

Examples

SteadyState(lindbladian = -im * H + D, algo = Dmrg(nsweeps = 10, tol = 1e-5),
            limits = Limits(maxdim = [10, 20, 50]))

TensorMixedStates.prepare_phase(phase, sim)
TensorMixedStates.step_count(prepared)
TensorMixedStates.run_step(prepared, sim, k)

the interface of a phase made of steps: prepare_phase returns what the steps need, from the simulation as the phase starts, step_count the number of steps, and run_step makes step k, returning the simulation it leaves, see Simulation. On a resume, prepare_phase is given the state of the last step committed, with the time the phase started from, and the steps go on after it: what it prepares may depend on the system of the state, not on the state.

Examples

struct Kicks <: TensorMixedStates.AbstractPhase
    name::String
    time_start
    final_measurements
    nkicks::Int
    measurements
end

TensorMixedStates.prepare_phase(p::Kicks, _) = p
TensorMixedStates.step_count(p::Kicks) = p.nkicks
TensorMixedStates.run_step(::Kicks, sim, _) =
    Simulation(sim, apply(exp(-0.3im * X)(1), sim.state), sim.time + 0.1)

TensorMixedStates.run_phase(phase, sim, done)

run phase on the simulation sim, its first done steps already done, and return the simulation it leaves. For a phase made of steps, it prepares the phase and runs the steps after done, ending each with step_done; a phase of a single call has a method of its own.

TensorMixedStates.step_done(sim, phase, k; last = false, resume_from = sim)

the end of step k of phase, the simulation sim holding what it reached: its measurements, when due, and its line in the log, then the commit of the step, a checkpoint when one is due, and the stop of the run when one is asked for. It returns the simulation, its value step set to k. A phase of a single call calls it wherever it can stop, a sweep of a search for instance: its run_phase(phase, sim, done) is then called with the steps already done and the simulation committed, resume_from, which is sim unless the phase goes on from another state than the one measured, as a search measuring its eigenvector divided by its trace. With last, the phase ends there, sim holding its result, which a resumed run takes without running the phase again (a search ending on its tolerance would otherwise go on): resume_from is then sim.

TensorMixedStates.provided_values(phase)

the names of the values phase gives the simulation, (:energy,) for GroundState for instance, none by default. A measurement of a value that no phase provides is refused when the SimData is written, and one that is not there yet is missing.

evolve_step(algo, pre, state, time, dt, step, limits)

the state after one step of dt from time by the method algo, under the evolver pre, whose time functions are pre.functions, one per term, nothing when it does not depend on time, see make_mpo, step being the number of the step, from 1, and limits its limits, see step_limits. An EvolutionAlgorithm of one's own adds a method.

search(algo, mpo, state, limits; sweep_done = nothing, krylov = Krylov(), done = 0,
       energy = nothing[, orthogonal_to, weight])

the lowest eigenvalue of mpo and its eigenvector, normalized, searched from state by the method algo, limits the limits of the sweeps, see Limits; sweep_done(sweep, energy, state, ends) is called at the end of each sweep, ends telling whether the search ends there, on its tolerance or its last sweep, with the state it returns, and krylov gives the defaults of the method of the caller. A search resumed after done sweeps takes the rest of the schedules, energy being that of the last sweep, which it returns when no sweep is left. Given orthogonal_to, pure states on the system of state, the search is that of the lowest eigenvector orthogonal to them, which dmrg makes by adding weight times their projectors to mpo, the energy being that of mpo alone. A single site, which dmrg does not take, is diagonalized whole, in one sweep, see lowest_on_site. A SearchAlgorithm of one's own adds a method, taking these two keywords only if it searches excited states.

write_row(o, time, row)

write to the destination opened o the values row, pairs name => value, measured at time, see Destination

check_list(o, names)

refuse a list of measurements, by their names, that the destination opened o cannot take, see Destination; it takes any by default

resume_mark(o)

the mark that a resumed simulation reopens the destination opened o at, open(d, mark), see Destination; nothing by default, the destination then starting anew

write_state(group, state)

write the tensors of state in the HDF5 group group, where save_state writes its type and its sites: the MPS of a State. The state of an extension needs a method of its own, and one of read_state.

read_state(::Type{S}, group, sites)

the state of type S that save_state wrote in the HDF5 group group, on the sites sites. The state of an extension needs a method of its own, reading what its write_state wrote.

expect_value(state, op)

the expectation value of the operator op placed on sites, as the state computes it, divided by the real part of its trace: the number expect gives with complex = true, and makes real for a Hermitian operator otherwise. The state of an extension adds a method, which expect, expect1, expect2 and measure go through, see AbstractState.