Overhaul on error reporting of algorithms

[borisdevos]

[Relevant update deeper in conversation]

Description

The main motivation started with TDVP2 not reporting its truncation error. I noticed it could just make use of gauge2! to remove duplication. While doing this, I realised multiple parts in the code didn't report their error, or didn't clarify clearly what the error actually means. In particular for the time evolution code which isn't variational, it made me realise that ϵ could mean anything. So this PR ended up expanding massively to also documenting per algorithm where relevant what the returned error represents.

Details of the changes are mentioned in the changelog, and motivation for the errors in the docstrings or documentation. Importantly:

• timestep/timestep!/time_evolve/time_evolve! now return (ψ, envs, ϵ). time_evolve also logs more correctly. Tests added for this.
• Documentation of what every reported error actually means.

Something I noticed along the way with changebonds is that the meaning of its truncations differ too strongly to unify and justify returning the error. There's an argument to returning it for (VUMPS)SvdCut as the error there is genuinely a truncation error, but I didn't do that.

Checklist

• Tests pass locally (julia --project=test test/runtests.jl, or the relevant subset)
• Documentation updated, if this PR changes public API (docstrings, docs/src/)
• Runic formatter is run
• Changelog entry added under [Unreleased] in docs/src/changelog.md, if this PR is user-facing (new feature, behavior change, bug fix, deprecation, or removal)

[github-actions]

After the build completes, the updated documentation will be available here

[lkdvos]

Left some comments throughout, but as a more general idea here, since this is breaking anyways:

I think the entire idea of psi, envs, eps is probably not great to begin with, precisely because it is hard (or important) to keep that to meaning the same in every part. If we are making breaking changes anyways, it might be a convenient time to just go to a more KrylovKit-related approach where we just return an info struct, where we are then actually free to return the different quantities, and name them appropriately. This both keeps the signature the same everywhere, without unwantedly promising meaning to the number.

Thanks for taking the time to properly document many of these things by the way, this is definitely a welcome addition. There are some subtleties about the prose not lining up with the theory or the implementation, since especially for the convergence measures being practical had higher priority than being rigorous, and it seems like the language kind of mixes between the two. I'm not sure if you wanted to describe the theory or the implementation?

[codecov]

Codecov Report

❌ Patch coverage is 86.39456% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utility/algorithminfo.jl	63.88%	13 Missing ⚠️
src/algorithms/approximate/fvomps.jl	66.66%	2 Missing ⚠️
src/algorithms/approximate/idmrg.jl	92.30%	1 Missing ⚠️
src/algorithms/approximate/vomps.jl	50.00%	1 Missing ⚠️
src/algorithms/groundstate/dmrg.jl	87.50%	1 Missing ⚠️
src/algorithms/statmech/idmrg.jl	91.66%	1 Missing ⚠️
src/algorithms/statmech/vomps.jl	66.66%	1 Missing ⚠️

Files with missing lines	Coverage Δ
src/MPSKit.jl	100.00% <ø> (ø)
src/algorithms/approximate/approximate.jl	56.00% <ø> (ø)
src/algorithms/approximate/zipup.jl	98.61% <100.00%> (ø)
src/algorithms/groundstate/find_groundstate.jl	76.92% <ø> (ø)
src/algorithms/groundstate/gradient_grassmann.jl	88.57% <100.00%> (+0.69%)	⬆️
src/algorithms/groundstate/idmrg.jl	99.39% <100.00%> (+0.02%)	⬆️
src/algorithms/groundstate/vumps.jl	98.68% <100.00%> (ø)
src/algorithms/propagator/corvector.jl	95.50% <ø> (ø)
src/algorithms/statmech/gradient_grassmann.jl	100.00% <100.00%> (+20.00%)	⬆️
src/algorithms/statmech/leading_boundary.jl	46.15% <ø> (ø)
... and 13 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[borisdevos]

Thanks for the review! I agree I was inconsistent in separating theory vs what's effectively done in the code. I think it's beneficial to give both, so I'll see how far I get in that. I'm also in favor of the info struct, so I'll try that out!

[borisdevos]

Okay, a bunch has happened, and the goal of this PR has completely shifted, but the changes are better, and it's good that they're done at once (or at least shown here bunched up, there's an argument to splitting up some parts).

I introduced AlgorithmInfo as the info struct, done in such a way that every algorithm that can return an error does it via this one struct. Along the way I actually found more algorithms than TDVP2 which calculated truncation errors, but didn't return them. So I think I found them all now. I think the interface is clean, but do let me know if anything's weird about it.

I expanded on the docs a bunch more as well, correcting some of the false statements I made along the way. I think it reads more clearly now what a user could expect from these errors versus what they actually get. I think I'm less wrong than last time, but there might still be mistakes 🙃

[borisdevos]

Alright, the new AlgorithmInfo with a Dict field is now available! The most important related change is that the old info.normres is now replaced by certain "convergence keys", which I've managed to fix to 4 that occur in the current algorithms. Of course, this can be expanded, and it should be such that the new convergence_measure function can call it (as well as for pretty printing). I think the names I chose there make sense, the only one I have some doubt for is :localchange for the finite VOMPS code.

Concerning the unicode, I decided to keep them as aliases, but the ASCII versions are promoted everywhere, and it's also what you see when you show/display the info. The aliases are mentioned briefly in the docs and docstring of AlgorithmInfo.

Just to give an idea of how this displays, an example for DMRG2:

julia> eps
AlgorithmInfo:
  converged              = true after 6 iterations
  galerkin               = 6.417388341837349e-7
  max_truncation_error   = 1.2567011712421484e-6        (largest single factorisation)
  total_truncation_error = 1.6092084215067107e-6        (quadrature over 32 truncations)

I forgot to mention last time, but I haven't regenerated the docs. This should be done before merging.