GitHub

TEBD And TDVP

MPSToolkit.jl keeps physical-state evolution explicit. TEBD is represented as scheduled local-gate application, while TDVP is represented as MPO-driven variational evolution. Both are first-class public APIs rather than hidden internals.

TEBD

The TEBD layer is designed around three ideas:

  1. a local dense gate or gate provider
  2. an explicit schedule describing where those gates act
  3. a truncation budget applied at each scheduled step

For many workflows, the helper constructors are the easiest entry point:

using MPSToolkit
using ITensors
using ITensorMPS

nsites = 6
sites = siteinds("S=1/2", nsites)
psi = MPS(sites, n -> isodd(n) ? "Up" : "Dn")

evolution = tebd_strang_evolution(
  nsites,
  0.05;
  local_hamiltonian=(bond, weight) -> weight * spinhalf_tfim_bond_hamiltonian(nsites, bond; J=1.0, g=0.8),
  maxdim=32,
  cutoff=1e-12,
)

evolve!(psi, evolution)

If you need more control, you can build LocalGateEvolution manually or generate gates with local_gates_from_hamiltonians and tebd_evolution_from_hamiltonians. The scheduler notebooks under Examples show standard sweeps, brick schedules, and mixed-span shallow circuits.

TDVP

TDVPEvolution is the MPO-based evolution path. It is a good fit when the generator is naturally represented as an MPO and you want variational time stepping instead of explicit dense local gates.

using MPSToolkit

evolution = TDVPEvolution(
  generator_mpo,
  -0.1im;
  time_step=-0.1im,
  nsteps=1,
  normalize=true,
  solver_kwargs=(; maxdim=64, cutoff=1e-10),
)

evolve!(psi, evolution)

Choosing Step Counts

For plain TEBD or TDVP usage, the evolution objects keep their own constructor defaults. In other words:

  • LocalGateEvolution(...; nstep=1) still means one complete schedule pass
  • DMTGateEvolution(...; nstep=1) still means one forward-and-reverse DMT sweep
  • TDVPEvolution(...; nsteps=1) still means one TDVP step

ScarFinder is the only place with extra policy on top of those defaults. If you intend to pass one of these evolution objects into scarfinder_step!, scarfinder!, or trajectory_refine!, prefer setting:

  • nstep=10 for TEBD- or DMT-style evolutions
  • nsteps=10 for TDVP evolutions

If you pass a single-step evolution object into ScarFinder, ScarFinder will warn and internally upgrade it to 10 for that ScarFinder call only.

API

MPSToolkit.LocalGateEvolution — Type
LocalGateEvolution

Configuration for dense local-gate evolution on a finite MPS.

Fields

  • gate: One dense gate, a per-step gate vector, or a callable gate provider.
  • dt: Logical time increment associated with one call to evolve!.
  • schedule: Bond schedule that determines where each gate application acts.
  • nstep: Number of complete passes through schedule per evolve! call.
  • maxdim: Maximum bond dimension passed to the underlying ITensor gate application.
  • cutoff: Singular-value cutoff passed to the underlying ITensor gate application.

Notes

  • LocalGateEvolution does not hide the schedule. A caller can inspect or modify it directly, which is useful for explicit TEBD-style workflows.
source
MPSToolkit.local_gates_from_hamiltonians — Function
local_gates_from_hamiltonians(hamiltonians, dt; map_hamiltonian=_default_gate_from_hamiltonian)

Convert dense local Hamiltonian data into dense TEBD gates. hamiltonians may be one dense matrix, a per-step vector of matrices, or a callable provider.

Arguments

  • hamiltonians: Hamiltonian specification. Supported forms match the gate conventions of LocalGateEvolution.
  • dt: Time increment passed to map_hamiltonian.

Keyword Arguments

  • map_hamiltonian: Function (h, dt) -> gate, defaulting to exp(-im * dt * h).

Returns

  • One gate, a vector of gates, or a callable gate provider with the same structural shape as hamiltonians.
source
MPSToolkit.tebd_evolution_from_hamiltonians — Function
tebd_evolution_from_hamiltonians(hamiltonians, dt; map_hamiltonian=_default_gate_from_hamiltonian, schedule=nothing, nstep=1, maxdim=0, cutoff=0.0)

Construct a LocalGateEvolution from dense local Hamiltonians.

Arguments

Keyword Arguments

  • map_hamiltonian: Function used to convert each Hamiltonian into a gate.
  • schedule: Explicit bond schedule.
  • nstep: Number of complete schedule passes per evolve! call.
  • maxdim: Bond dimension cap for gate application.
  • cutoff: Truncation cutoff for gate application.

Returns

  • A LocalGateEvolution whose gate field contains the converted dense TEBD gates.
source
MPSToolkit.tebd_strang_schedule — Function
tebd_strang_schedule(nsites)

Return the nearest-neighbor odd-even-odd Strang schedule for a finite OBC chain.

Arguments

  • nsites: Number of sites in the chain.

Returns

  • (schedule, weights) where:
    • schedule is the ordered bond list
    • weights stores the Strang half-step / full-step prefactors for each entry

Notes

  • The weights are intended to be passed into a local Hamiltonian builder so that half steps on odd bonds and full steps on even bonds are handled explicitly.
source
MPSToolkit.tebd_strang_evolution — Function
tebd_strang_evolution(nsites, dt; local_hamiltonian, map_hamiltonian=_default_gate_from_hamiltonian, nstep=1, maxdim=0, cutoff=0.0)

Construct a nearest-neighbor odd-even-odd Strang LocalGateEvolution from a local Hamiltonian builder. local_hamiltonian(bond, weight) must return the dense local Hamiltonian for one scheduled update.

Arguments

  • nsites: Number of sites in the open chain.
  • dt: Logical time step associated with one Strang sweep.

Keyword Arguments

  • local_hamiltonian: Function (bond, weight) -> h_local used to build each scheduled Hamiltonian term.
  • map_hamiltonian: Function used to exponentiate each local Hamiltonian.
  • nstep: Number of full Strang sweeps per evolve! call.
  • maxdim: Bond dimension cap for TEBD gate application.
  • cutoff: Truncation cutoff for TEBD gate application.

Returns

  • A LocalGateEvolution with explicit Strang schedule metadata.
source
MPSToolkit.tebd_evolve! — Function
tebd_evolve!(psi, gate, bond; maxdim, cutoff)

Apply one dense local TEBD gate to a finite MPS block starting at bond. If bond == length(psi) and the gate is two-site, the update is applied across the periodic boundary between the last and first sites.

Arguments

  • psi: Finite matrix-product state to mutate in place.
  • gate: Dense one-site, two-site, or few-site gate matrix.
  • bond: Left-edge location of the update window.

Keyword Arguments

  • maxdim: Maximum bond dimension allowed during gate application.
  • cutoff: Truncation cutoff used by ITensor operations.

Returns

  • The mutated psi.

Notes

  • Periodic wraparound is currently supported only for two-site gates and only when the schedule explicitly uses bond == length(psi).
source
MPSToolkit.TDVPEvolution — Type
TDVPEvolution

Configuration for finite-MPS TDVP evolution driven by an MPO generator.

Fields

  • generator: MPO or compatible object passed to tdvp.
  • t: Total evolution interval passed to tdvp.
  • time_step: Internal TDVP time step.
  • nsteps: Preferred number of TDVP steps.
  • nsweeps: Legacy fallback step-count field used when nsteps is nothing.
  • reverse_step: Whether TDVP should alternate sweep direction.
  • updater_backend: Backend name forwarded to tdvp.
  • updater: Optional custom TDVP updater.
  • normalize: Whether TDVP should normalize the state.
  • solver_kwargs: Additional keyword arguments forwarded to tdvp.
  • schedule: Optional metadata field kept for interface symmetry with TEBD-based code.

Notes

  • tdvp_evolve! interprets the effective step count as nsteps if present, otherwise nsweeps.
source
MPSToolkit.tdvp_evolve! — Function
tdvp_evolve!(psi, evo)

Run one TDVP evolution call on a finite OBC MPS.

Arguments

  • psi: Finite matrix-product state to evolve in place.
  • evo: TDVPEvolution carrying the MPO generator and TDVP solver settings.

Returns

  • The mutated psi.

Notes

  • The effective TDVP step count is evo.nsteps if present, otherwise evo.nsweeps.
  • The underlying tdvp call returns a new state, so this wrapper copies the result back into the original storage to preserve the package-wide in-place API convention.
source

References