Overhaul on error reporting of algorithms

README.md

@@ -40,7 +40,7 @@ g_values = 0.1:0.1:2
 
 M = @showprogress map(g_values) do g
     H = transverse_field_ising(; g=g)
-    groundstate, environment, δ = find_groundstate(init_state, H, VUMPS(; verbosity=0))
+    groundstate, environment, info = find_groundstate(init_state, H, VUMPS(; verbosity=0))
     return abs(expectation_value(groundstate, 1 => σᶻ()))
 end
 

docs/src/assets/mpskit.bib

@@ -999,3 +999,31 @@ @article{hubig2015
   doi = {10.1103/PhysRevB.91.155115},
   url = {https://link.aps.org/doi/10.1103/PhysRevB.91.155115}
 }
+
+@article{li2024,
+  title = {Time-{{Dependent Variational Principle}} with {{Controlled Bond Expansion}} for {{Matrix Product States}}},
+  author = {Li, Jheng-Wei and Gleis, Andreas and {von Delft}, Jan},
+  year = {2024},
+  month = jul,
+  journal = {Physical Review Letters},
+  volume = {133},
+  number = {2},
+  pages = {026401},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevLett.133.026401},
+  url = {https://link.aps.org/doi/10.1103/PhysRevLett.133.026401}
+}
+
+@article{schollwoeck2011,
+  title = {The density-matrix renormalization group in the age of matrix product states},
+  author = {Schollw{\"o}ck, Ulrich},
+  year = {2011},
+  month = jan,
+  journal = {Annals of Physics},
+  volume = {326},
+  number = {1},
+  pages = {96--192},
+  issn = {0003-4916},
+  doi = {10.1016/j.aop.2010.09.012},
+  url = {https://www.sciencedirect.com/science/article/pii/S0003491610001752}
+}

docs/src/changelog.md

@@ -27,7 +27,7 @@ When releasing a new version, move the "Unreleased" changes to a new version sec
   a single sweep, optionally followed by a sweep in the opposite direction that imposes the final
   truncation. The sweep direction is selected by the `left_to_right` keyword. Both
   `approximate((O, ϕ), alg)` and `approximate!(ψ, (O, ϕ), alg)` are supported, where the destination
-  `ψ` is a write target rather than an initial guess and may alias `ϕ`; they return `(ψ, ϵ)`.
+  `ψ` is a write target rather than an initial guess and may alias `ϕ`; they return `(ψ, info)`.
 - `BUG` time-evolution algorithm: a Basis-Update & Galerkin integrator for finite MPS.
   Unlike `TDVP` it has no backward-in-time substep (stable for imaginary-time evolution),
   and passing a truncating `trunc` enables rank-adaptivity (the bond dimension grows and shrinks
@@ -45,6 +45,16 @@ When releasing a new version, move the "Unreleased" changes to a new version sec
   virtual channels between terms that start out with the same operators, up to a scalar factor,
   and add up terms that are linearly dependent. The resulting Hamiltonian is unchanged, but its
   bond dimension is generally smaller ([#518](https://github.com/QuantumKitHub/MPSKit.jl/pull/518))
+- `find_groundstate(!)`, `leading_boundary`, `approximate(!)`, `timestep(!)` and `time_evolve(!)`
+  now have the return signature `(ψ, envs, info)` with `info` an `AlgorithmInfo` that contains
+  diagnostics about the run and convergence. See the updated docs or `AlgorithmInfo`'s
+  docstring for more information. ([#512](https://github.com/QuantumKitHub/MPSKit.jl/pull/512))
+- The manual has a new section on [Errors and accuracy](@ref) covering definitions and interpretations
+  of the various returned measures. ([#512](https://github.com/QuantumKitHub/MPSKit.jl/pull/512))
+- Convergence tolerances are now compared with `<=` everywhere, so an error exactly equal to `tol`
+  counts as converged for `DMRG`/`DMRG2` in `approximate`, the `IDMRG`/`IDMRG2` variants of
+  `approximate` and `leading_boundary`, and the gauge fixing of `InfiniteMPS`, as it already did for
+  the other algorithms. ([#512](https://github.com/QuantumKitHub/MPSKit.jl/pull/512))
 - Renormalization during time evolution is now controlled by an explicit `normalize` keyword on
   `timestep`/`time_evolve` (default `false`), decoupled from `imaginary_evolution`. By default the
   norm is preserved, so it retains useful information (the accumulated truncation error in real time,
@@ -132,11 +142,18 @@ When releasing a new version, move the "Unreleased" changes to a new version sec
   `TensorKit` 0.17.2 and `BlockTensorKit` <= 0.3.18, a permuted contraction into a sparse block
   tensor (e.g. an environment sweep near a `FiniteMPS` chain boundary when the operator and state
   have different `scalartype`s) could silently drop data instead of erroring.
+- `approximate` with `IDMRG2` on a `MultilineMPS` with more than one row wrote the right-to-left
+  edge update into the wrong row and refreshed the unit cell edge of the first row only, so the
+  rows ended up mixed. ([#512](https://github.com/QuantumKitHub/MPSKit.jl/pull/512))
+- `leading_boundary` with `GradientGrassmann` ignored the algorithm's `hasconverged` and `shouldstop`
+  criteria, always using the optimizer's defaults instead. ([#512](https://github.com/QuantumKitHub/MPSKit.jl/pull/512))
 
 ### Performance
 
 - Reorganised the test suite to reduce CI wall time, as well as added the `--fast` test flag
   to test fewer sector and scalar types. ([#517](https://github.com/QuantumKitHub/MPSKit.jl/pull/517))
+- `TDVP2` now performs its two-site split through the shared `gauge2!` (as two-site DMRG already
+  did), avoiding unnecessary re-orthogonalisation and complexification where applicable). ([#517](https://github.com/QuantumKitHub/MPSKit.jl/pull/517))
 
 ## [0.13.11](https://github.com/QuantumKitHub/MPSKit.jl/compare/v0.13.10...v0.13.11) - 2026-05-04