docs: content wave 2 (headline how-tos, tutorials, algorithm landscape)

[lkdvos]

Stacked on #449 (docs/content-wave1). Second wave of the docs restructure per docs/RESTRUCTURE_PLAN.md / docs/IMPROVEMENT_PLAN.md W2: the headline-workflow task recipes and the back half of the tutorial track, plus the algorithm-landscape decision guide.

Pages added (one commit each)

How-to (task recipes)

• howto/groundstate_algorithms.md — find_groundstate heuristic, DMRG/DMRG2/VUMPS/IDMRG/IDMRG2/GradientGrassmann config, &-chaining, tolerances/verbosity
• howto/time_evolution.md — timestep/time_evolve with TDVP/TDVP2, imaginary time, time-evolution MPOs (WII/TaylorCluster/WI) via approximate
• howto/excitations.md — QuasiparticleAnsatz (gap, dispersion, charged Z2 sector), FiniteExcited, ChepigaAnsatz/2, variance checks; domain-wall usage prose-only (no in-repo test coverage to copy)
• howto/index.md — browsable recipe index (new How-to landing page) with per-recipe listing and a missing-recipe issue invitation

Tutorials

• tutorials/time_evolution.md — hand-held TFIM quench with an explicit TDVP loop and a plotted observable
• tutorials/excitations.md — dispersion of the infinite TFIM; computed points match the exact Jordan–Wigner dispersion (k=0 gap agrees with 2(g−1) to 1e-11)
• tutorials/using_symmetries.md — flagship redone with explicit Z2 symmetry; graded spaces, sector-resolved entanglement, charged-sector excitation payoff
• Wired the two TODO(link) stubs in tutorials/thermodynamic_limit.md to the new tutorials

Concepts

• concepts/algorithm_landscape.md — decision table (task × finite/infinite) + per-task comparison prose salvaged from man/algorithms.md. 26 <!-- REVIEW: --> flags — every physics/convergence claim is gated on maintainer review per CLAUDE.md.

Needs maintainer attention

1. REVIEW flags: heaviest on concepts/algorithm_landscape.md (26); each tutorial/how-to carries 3–6 for its physics framing.
2. Plan deviation — Z2, not U(1): MPSKitModels.transverse_field_ising only accepts Trivial/Z2Irrep/FermionParity (throws otherwise), so the symmetries tutorial uses Z2 and points at states-how-to §9 / XXZ / Haldane examples for U(1)/SU(2). Noted in-file.
3. Tutorial physics changed after verification: at L=12, D=16 DMRG converges to the symmetric TFIM ground state (⟨σᶻ⟩ ≈ 1e-11), so the quench tutorial tracks ⟨σˣ⟩ (visible 0.26 → 0.61 → 0.49 relaxation) instead of a σᶻ-decay story.
4. Upstream bug found during verification: find_groundstate on InfiniteMPS at g=10 (also g=5), χ=12 deterministically throws ArgumentError: invalid argument #4 to LAPACK call in MatrixAlgebraKit's divide-and-conquer SVD, from the auto-chained GradientGrassmann step — over-parametrized bond dimension on a near-product state; reproduces across seeds, single-threaded. g ≤ 2 is fine. Probably worth an issue on TensorKitManifolds/MatrixAlgebraKit.
5. approximate's docstring says it returns a 2-tuple; every method returns (ψ, envs, ϵ) — docstring fix candidate for the W4 wave.
6. examples/index.md and lib/public.md's spectral-functions section have no @id anchors, so pages can't deep-link them.

Verification

Every @example block on every new page was executed against real MPSKit before its commit (extracted per-page into a single Julia session, julia --project=docs), with semantic spot-checks (energy agreement trivial-vs-Z2 to 1e-14 across two RNG seeds; charged sector below trivial sector; dispersion vs exact formula). Final gate: full docs/make.jl Documenter run over the whole tree (doctest = true, all cross-references) — green, no new warnings.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 11 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[github-actions]

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

[lkdvos]

Folded into #449 by rebasing onto docs/content-wave1 and fast-forwarding; branch removed.