The algorithm landscape
MPSKit deliberately separates what you want to compute from how it gets computed. Entry points such as find_groundstate, timestep, excitations, leading_boundary, and approximate each accept several interchangeable algorithm structs, and the package ships more than a dozen of them. That flexibility exists because no single algorithm wins everywhere: some only apply to finite or only to infinite systems, some can grow the bond dimension while others cannot, and their relative performance depends on the model at hand. <!– REVIEW: "their relative performance depends on the model at hand" — this is the framing claim inherited from man/algorithms.md ("figuring out the optimal algorithm is not always straightforward, since this may strongly depend on the model"); please confirm it is the message we want to lead with. –>
This page is the decision guide. It starts from a table that maps each task onto the algorithm(s) of choice, and then walks through the reasoning behind each row. It explains why you would pick one algorithm over another; for the how — the actual calls, keywords, and worked recipes — follow the links into the how-to pages.
The decision table
| Task | Finite system | Infinite system |
|---|---|---|
Ground state (find_groundstate) | DMRG (workhorse, fixed bond dimension); DMRG2 (grows bond dimension, requires trscheme); GradientGrassmann (final polish) | VUMPS (workhorse, needs a unique ground state); IDMRG / IDMRG2 (two-site requires trscheme and a unit cell of at least two sites); GradientGrassmann (final polish) |
Time evolution (timestep / time_evolve) | TDVP (fixed bond dimension); TDVP2 (grows bond dimension, requires trscheme); or make_time_mpo (WI / WII / TaylorCluster) applied with approximate | TDVP (no two-site variant exists); or make_time_mpo applied with approximate |
Excitations (excitations) | QuasiparticleAnsatz (the only one supporting charged sectors); FiniteExcited (penalty method); ChepigaAnsatz / ChepigaAnsatz2 (cheap, from ground-state environments) | QuasiparticleAnsatz (momentum-resolved, the only choice) |
Boundary / statistical mechanics (leading_boundary) | apply the transfer MPO row by row with approximate | VUMPS; VOMPS (power method); IDMRG / IDMRG2; GradientGrassmann (hermitian, positive transfer matrices) |
Compression / approximation (approximate, changebonds) | approximate with DMRG / DMRG2; SvdCut via changebonds for local truncation | approximate with IDMRG / IDMRG2 / VOMPS; SvdCut via changebonds for local truncation |
<!– REVIEW: the finite boundary/statmech cell — recommending row-by-row application of the transfer MPO via approximate for finite partition functions. leading_boundary itself has no finite-MPS methods (verified in src/algorithms/statmech/), so this is the natural finite counterpart, but please confirm it is the recommended workflow before this row ships. –>
A few structural facts hold across the whole table and are worth internalizing early. Every two-site algorithm (DMRG2, IDMRG2, TDVP2) requires an explicit trscheme keyword and can change the bond dimension as it runs; the single-site variants with their default settings cannot. IDMRG2 additionally needs a unit cell of at least two sites, and TDVP2 exists only for finite MPS. Finally, algorithms compose: the & operator chains two algorithms into one, running the first to completion and handing its result to the second, which is how two-site warm-up passes and gradient-descent polishing stages are combined with a workhorse algorithm in a single call.
Ground states
The classic approach is alternating local optimization: DMRG sweeps through a finite chain, optimizing one site while all others are held fixed. <!– REVIEW: man/algorithms.md calls DMRG "probably the most widely used algorithm for optimizing groundstates with MPS", and claims the global optimum "follows by alternating through the system"; both are convergence/consensus claims — confirm the phrasing. –> The catch is the fixed bond dimension: a single-site update can never enlarge the virtual spaces, so the precision of the calculation is locked in by the initial state. This bites hardest when symmetries are involved, because then not just the total bond dimension but its distribution over charge sectors is frozen, and a poor initial distribution cannot be repaired. <!– REVIEW: the claim that single-site DMRG cannot repair a bad charge distribution across symmetry sectors (from man/algorithms.md "finding a good distribution of charges is also required") — confirm. –> DMRG2 fixes this by optimizing two neighbouring sites jointly and truncating back down, which lets the bond dimension (and its sector distribution) adapt, at a higher cost per sweep. <!– REVIEW: "at a higher cost per sweep" — confirm the cost comparison between single-site and two-site DMRG as stated. –>
For infinite systems, two philosophies compete. IDMRG grows the system from the middle outwards, repeatedly inserting and optimizing new sites until the boundary is no longer felt; IDMRG2 is its two-site, bond-growing variant. <!– REVIEW: the middle-insertion description of IDMRG — confirm this matches the implementation's actual iteration scheme. –> Because convergence requires the effective system to outgrow the correlation length, IDMRG can be slow to converge for critical systems, where that length diverges. <!– REVIEW: "the number of steps needs to be larger than the correlation length" claim for IDMRG on critical systems, from man/algorithms.md — confirm. –> VUMPS instead works with a genuinely uniform state: each local update is followed by a re-gauging step that replaces every tensor in the infinite chain with the updated one, so the effect of an update is felt throughout the system immediately. <!– REVIEW: the mechanism claim that re-gauging propagates the update globally and that this is why VUMPS converges faster — confirm. –> This often gives VUMPS a higher convergence rate than IDMRG, which is why it is the default infinite-system workhorse. <!– REVIEW: "often achieves a higher rate of convergence" (VUMPS vs IDMRG), from man/algorithms.md — confirm. –> The price is an injectivity requirement: VUMPS assumes a unique ground state, and it is not the right tool when the state it should converge to is non-injective. <!– REVIEW: the injectivity caveat for VUMPS ("only works whenever the state is injective, i.e. there is a unique ground state") — confirm the precise condition, and whether degenerate/symmetry-broken ground states should be explicitly called out here as the failure mode. –> Like DMRG, VUMPS is single-site and cannot alter the bond dimension.
GradientGrassmann approaches the problem from a third direction: the MPS tensors form a Riemannian manifold (a Grassmann manifold), and one can run gradient descent directly on it, for finite and infinite states alike. Its niche is the tail of the optimization: close to convergence its rate is often the best of the lot, while far from convergence the sweeping algorithms tend to make faster progress. <!– REVIEW: the "gradient descent shines in the tail" claim ("quite often the convergence rate in the tail of the optimization procedure is higher"), from man/algorithms.md — confirm. –> The practical consequence is the chaining pattern: run a cheap workhorse first, then hand over to gradient descent, e.g. VUMPS(...) & GradientGrassmann(...). <!– REVIEW: "often the fastest method combines a different algorithm far from convergence with this algorithm close to convergence" — confirm this combined strategy is still the recommended default. –> This pattern is baked into find_groundstate itself: called with only keywords, it picks DMRG for a finite state and VUMPS for an infinite one, appends a GradientGrassmann stage on infinite states when the requested tolerance is tighter than 1e-4, and prepends a two-site pass (DMRG2 or IDMRG2) whenever you supply a trscheme. Since gradient descent is also a single-site method, growing the bond dimension remains the job of that two-site pre-pass or of changebonds.
For call syntax, keyword tables, and worked chaining examples, see Ground-state algorithms.
Time evolution
MPSKit solves the time-dependent Schrödinger equation along two distinct routes, and the choice between them is a genuine trade-off rather than a finite/infinite split.
The first route, TDVP, never builds the evolution operator at all. It projects the Schrödinger equation onto the tangent space of the current MPS, solves the projected equation for a small time step, and repeats. <!– REVIEW: the tangent-space projection description of TDVP — confirm this one-sentence summary is accurate enough for a concept page. –> Its two-site variant TDVP2 plays the same role as DMRG2 does for DMRG: it lets the bond dimension grow to absorb the entanglement generated by the evolution, at extra cost, and it exists only for finite systems. <!– REVIEW: framing entanglement growth during evolution as the generic reason to reach for TDVP2 — confirm this is general enough to state, or whether it should be qualified as quench-dependent. –>
The second route splits the problem in two: first approximate the evolution operator make_time_mpo — with WI, WII, or TaylorCluster as the approximation scheme — and then apply that MPO to the state with approximate. The appeal is amortization: for a time-independent Hamiltonian and a fixed step size the MPO is built once and reused for every step, and the accuracy of the operator approximation is controlled independently of the accuracy of its application. <!– REVIEW: the amortization argument for the MPO route over TDVP, and the claim that operator accuracy and application accuracy are independently controllable — this guidance goes beyond man/algorithms.md, which only describes the two routes without ranking them; confirm or soften. –> <!– REVIEW: should this page give any guidance on when the MPO route actually beats TDVP in practice (long-range Hamiltonians? many identical steps?), or is the neutral presentation the right call? Currently left neutral on purpose. –>
Both routes accept an imaginary_evolution keyword for evolution in imaginary time. For step-by-step recipes along either route, see Time evolution.
Excitations
Resolving states deep in the spectrum is generally out of reach, but three families of algorithms target the low-lying part, each with a distinct character. <!– REVIEW: "it is typically not feasible to resolve states in the middle of the energy spectrum", from man/algorithms.md — confirm. –>
The QuasiparticleAnsatz is the most broadly applicable: it works for finite and infinite systems, and it is the only algorithm that can target excitations carrying a nontrivial symmetry charge, via the sector keyword. It builds an excited state by replacing a single tensor of the ground-state MPS — summed over all positions on a finite chain, or in a momentum-carrying plane-wave superposition on an infinite one — and solves the resulting eigenvalue problem. <!– REVIEW: the one-tensor-perturbation summary of the quasiparticle ansatz (haegeman2013) — confirm the description, in particular that the infinite version requires a momentum label while the finite version has none. –> Because the variational class consists of local perturbations on top of the ground state, it is the natural choice for quasiparticle-like excitations, and on infinite systems it is the only option, giving direct access to dispersion relations. <!– REVIEW: "natural choice for quasiparticle-like excitations" — a suitability claim about which physical states the ansatz captures well; confirm. –>
FiniteExcited takes a brute-force approach available only on finite chains: it reruns a full ground-state optimization on a modified Hamiltonian that carries an energy penalty for overlapping with all previously found states. Each new excited state therefore costs another complete ground-state search, and the orthogonality to earlier states is only approximate (enforced by the penalty weight, not exactly). <!– REVIEW: the cost claim (one full ground-state optimization per excited state) and the "only approximately orthogonal" characterization — confirm both. –> Its advantage is that it makes no assumption about the form of the excited state: since each state is a fully variational FiniteMPS, it can capture excitations that are not well described as a local perturbation of the ground state. <!– REVIEW: the claim that FiniteExcited's niche is excitations of a qualitatively different character than the ground state (where the quasiparticle ansatz's local-perturbation form is a limitation) — this is my synthesis, not stated in man/algorithms.md; confirm or cut. –>
The ChepigaAnsatz (and its two-site refinement ChepigaAnsatz2) is the cheapest of the three, also finite-only. It observes that the gauged ground-state MPS tensors act as isometries projecting the Hamiltonian into a low-energy subspace, so the low-lying spectrum can be read off by diagonalizing the effective Hamiltonian already available from the ground-state environments, with no additional sweeping. <!– REVIEW: the "MPS gauge tensors project H into the low-energy sector" mechanism and the "without any additional DMRG costs" claim, from man/algorithms.md (chepiga2017) — confirm. –> This works best precisely where excitations are hard for the other methods: in critical systems with long-range correlations, where the excitation weight is spread across the whole chain. <!– REVIEW: the claim that the Chepiga ansatz is particularly effective for critical/long-range systems because excitations are delocalized — from man/algorithms.md; confirm, and confirm the implied contrast with the quasiparticle ansatz. –>
For the call signatures, momentum scans, and sector-targeting recipes, see Excited states.
Boundaries and statistical mechanics
MPS algorithms are not limited to Hamiltonian problems. A two-dimensional classical partition function can be written as an infinite power of a row-to-row transfer MPO, and contracting the network amounts to finding that operator's dominant eigenvector — a boundary MPS. <!– REVIEW: the transfer-matrix framing of 2D classical partition functions as a leading-boundary problem — standard, but confirm the phrasing. –> This is the job of leading_boundary, which accepts a familiar cast: VUMPS and IDMRG/IDMRG2 carry over directly from the ground-state problem, GradientGrassmann applies when the transfer MPO is hermitian and positive, and VOMPS is a power method specific to this setting, which iteratively approximates the operator-times-state product by a new state of the same bond dimension. <!– REVIEW: the hermitian-and-positive condition for using GradientGrassmann in leading_boundary, from man/algorithms.md ("If the mpo satisfies certain properties (positive and hermitian)") — confirm the exact requirement. –> <!– REVIEW: should this page give guidance on VUMPS vs VOMPS for boundary problems (e.g. VOMPS for non-hermitian transfer matrices where VUMPS's eigensolver framing struggles)? No recommendation is currently made because none is stated in the existing docs — please supply one if there is a house preference. –>
Compression and changing bond dimension
Two mechanisms round out the landscape by manipulating states rather than solving for new ones. approximate variationally fits a new MPS, typically of different bond dimension, to the result of applying an MPO to a state; the sweeping ground-state algorithms (DMRG/DMRG2 for finite, IDMRG/IDMRG2/VOMPS for infinite) double as its optimization engines. This is the same machinery that applies time-evolution MPOs, and combined with SvdCut it yields a globally optimal truncation of a state. <!– REVIEW: "a globally optimal truncation can be obtained by using the SvdCut algorithm in combination with approximate", from man/algorithms.md — confirm this claim and whether the SvdCut+approximate combination is the intended reading. –> changebonds, by contrast, performs direct local surgery on a state: truncating with SvdCut, or expanding with OptimalExpand, RandExpand, or VUMPSSvdCut so that the single-site algorithms above have room to work with. The trade-offs between those expansion schemes, and recipes for when to grow, are covered in Controlling bond dimension.
Where to go next
The how-to pages turn each row of the table into runnable recipes: Ground-state algorithms, Time evolution, and Excited states, with Controlling bond dimension supporting all three. For the complete signatures, keyword lists, and docstrings of every algorithm named here, see the library reference: Ground-state algorithms, Time evolution, and Excitations.
<!– Notes for the maintainer / plan:
This page names SketchedExpand nowhere, although it is exported; the bond-dimension how-to and lib/bond_dimension.md cover it, and it felt too experimental for a decision-guide table. Add it to the compression row if you disagree.
Dropped from man/algorithms.md rather than salvaged here: Dynamical DMRG / propagator, fidelity_susceptibility, periodic/open_boundary_conditions, and exact_diagonalization ("Varia" section) — they are not decision-table tasks per the plan entry. If the plan wants them surfaced, a short "Beyond the table" paragraph could be appended.
The finite cell of the boundary/statmech row is thin (leading_boundary has no finite methods); if a finite-partition-function workflow page ever lands, that cell should link to it.
–>