Skip to content

docs: content wave 1 (reference + how-to pages)#449

Draft
lkdvos wants to merge 61 commits into
mainfrom
docs/content-wave1
Draft

docs: content wave 1 (reference + how-to pages)#449
lkdvos wants to merge 61 commits into
mainfrom
docs/content-wave1

Conversation

@lkdvos

@lkdvos lkdvos commented Jul 3, 2026

Copy link
Copy Markdown
Member

Wave 1 of the documentation restructure (per docs/RESTRUCTURE_PLAN.md).

Opening as a draft so the Documenter/Vitepress PR preview build runs and the new pages can be reviewed online. Once CI finishes, the preview is deployed to:

https://quantumkithub.github.io/MPSKit.jl/previews/PR449/

What's included

  • Reference (lib) pages — observables, bond_dimension, time_evolution, excitations (plus states/operators/groundstate/public via @autodocs)
  • How-to guides — building Hamiltonians, entanglement, observables, bond dimension, states
  • References — recent publications using MPSKit
  • Quasiparticle docstrings, markdown formatting pass (one sentence per line + Runic), and PR Controlled Bond Expansion: randomized SVD approach #438 review follow-ups on bond-expansion docstrings

Notes

  • All code blocks are @example/jldoctest and were verified against real MPSKit.
  • Physics claims that need maintainer sign-off are flagged with <!-- REVIEW: ... -->.

🤖 Generated with Claude Code

lkdvos and others added 15 commits July 3, 2026 07:44
Add the curated public-API contract page (grouped @ref links to the
canonical docstrings) and expand the Library nav section in make.jl to
hold the new per-category reference pages alongside the existing full
index (lib/lib.md, now anchored as @id lib_index). Content-neutral:
lib/lib.md stays the canonical @autodocs catch-all.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Category reference for the MPS state types via @docs; canonical=false
(canonical home remains lib/lib.md), mirroring the man/algorithms.md
convention. Quasiparticle types omitted pending docstrings (REVIEW flag).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Category reference for MPO and Hamiltonian types via @docs; canonical=false.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Category reference for the ground-state interface and algorithms via
@docs; canonical=false.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a how-to guide with runnable recipes for constructing FiniteMPS,
InfiniteMPS, WindowMPS, and MultilineMPS (random/initializer/element-type,
product states, from tensors, multi-site unit cells, and U(1)-symmetric
states), and introduce the How-to nav section in make.jl. All examples are
@example blocks verified by the full build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a how-to guide for inspecting, growing (RandExpand/OptimalExpand),
and reducing (SvdCut) bond dimension, truncation schemes, dynamic growth
via DMRG2/IDMRG2 and find_groundstate(...; trscheme), and algorithm
chaining with &. All examples verified by the full build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a how-to guide for local and multi-site expectation values
(expectation_value), two-point correlators (correlator, incl. range form),
full-MPO energies, and the energy variance convergence diagnostic. Wire the
page into the How-to nav. All examples verified by the full build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reflow prose to one sentence per line (semantic line breaks) and run the
Runic formatter over the Julia code blocks across the Wave 1 reference and
how-to pages. Whitespace/style only; no content or API changes, full build
still green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add 20 entries to the "Publications using MPSKit" list: 17 from the
append-candidates review plus 3 found via web search (staelens2026,
yang2026, zemlevskiy2026). Introduce a 2026 section and extend 2025.

- Verified every arXiv ID / DOI resolves to a real paper.
- Upgraded published preprints: vancraeynestdecuiper2026 to @Article
  (SciPost Phys. Lect. Notes 128); added arXiv eprints to the already
  published zong2026pseudogap, vandamme2025pseudogenerators, sommer2025.
- Flagged with % NOTE the entries whose MPSKit citation could not be
  independently confirmed (lu2026 cites it only in its bibliography).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…volution, excitations)

Category reference pages grouping the exported observables/analysis, bond-dimension,
time-evolution, and excitation docstrings via `@docs; canonical=false`, mirroring the
existing lib/ page structure. Every listed symbol verified exported with an attached
docstring against src/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two task-oriented how-to pages following the observables.md template:
- howto/hamiltonians.md: finite/infinite MPO Hamiltonians from local terms,
  boundary-condition conversion, and window Hamiltonians.
- howto/entanglement.md: entanglement entropy and spectrum from gauge tensors.
All @example blocks verified to execute against real MPSKit; physics claims flagged
with REVIEW for maintainer sign-off.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds howto/{hamiltonians,entanglement}.md to the How-to section and
lib/{bond_dimension,time_evolution,excitations,observables}.md to the Library section,
ordered to mirror the public API surface in lib/public.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Incorporate post-merge review feedback (docstring/wording only):
- changebond docstring: drop inaccurate "in place", "enriched" -> "expanded"
- OptimalExpand: reword "does not alter the state" -> "state-preserving"
  to avoid implying out-of-place operation
- TDVP: "enriches" -> "expands" the bond

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lkdvos lkdvos added the documentation Improvements or additions to documentation label Jul 3, 2026
@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

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

Apply the new docstring style guide (docs/DOCSTRING_STYLE.md) across all of
src/. Single-hash section headers, canonical section order and names
(`Keyword Arguments`, not `Keywords`), dash bullets with types only where
they earn their place, spaces around `=` in defaults and after commas in
type-parameter lists.

Templates applied:
- A1 (`@kwdef` algorithm/config structs): $(TYPEDEF) + # Fields via
  $(TYPEDFIELDS) + # See also naming the consuming driver(s) + # References.
- A2 (container/data types): $(TYPEDEF) + # Constructors + flat
  # Arguments/# Keyword Arguments + # Properties + # Notes.
- B (user-facing verbs): stacked signatures with -> returns, # Arguments,
  # Keyword Arguments, # Returns.

Also documents three previously-undocumented exports (find_groundstate!,
leftenv, rightenv) and adds <!-- REVIEW --> flags for pre-existing doc
inaccuracies surfaced during the sweep (non-existent Defaults.solver /
Defaults.trscheme references, MPOHamiltonian constructor signatures with no
matching methods) for maintainer follow-up.

Verified: MPSKit precompiles and the full doctest suite passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jul 3, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 25.00000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/algorithms/correlators.jl 0.00% 1 Missing ⚠️
...c/algorithms/excitation/quasiparticleexcitation.jl 0.00% 1 Missing ⚠️
src/operators/windowhamiltonian.jl 0.00% 1 Missing ⚠️
Files with missing lines Coverage Δ
src/algorithms/approximate/approximate.jl 0.00% <ø> (-100.00%) ⬇️
src/algorithms/changebonds/changebonds.jl 69.56% <ø> (-21.74%) ⬇️
src/algorithms/changebonds/optimalexpand.jl 22.78% <ø> (-75.95%) ⬇️
src/algorithms/changebonds/randexpand.jl 30.13% <ø> (-34.25%) ⬇️
src/algorithms/changebonds/sketchedexpand.jl 0.00% <ø> (-98.44%) ⬇️
src/algorithms/changebonds/svdcut.jl 75.67% <ø> (-13.52%) ⬇️
src/algorithms/changebonds/vumpssvd.jl 0.00% <ø> (-100.00%) ⬇️
src/algorithms/derivatives/mpo_derivatives.jl 32.39% <ø> (-40.15%) ⬇️
src/algorithms/excitation/chepigaansatz.jl 0.00% <ø> (-91.49%) ⬇️
src/algorithms/excitation/dmrgexcitation.jl 100.00% <ø> (ø)
... and 33 more

... and 28 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

lkdvos and others added 11 commits July 4, 2026 07:17
Address the batch of accurate/verifiable REVIEW comments left throughout
the docs and package docstrings:

- MPOHamiltonian: retarget the docstring constructor signatures and example
  to the concrete FiniteMPOHamiltonian / InfiniteMPOHamiltonian entry points
  (the MPOHamiltonian(lattice, ...) methods do not exist).
- excitations umbrella docstring: drop the nonexistent `solver = Defaults.solver`
  default and the oversimplified FiniteExcited `init` default; describe the real
  forwarding/default behaviour.
- ChepigaAnsatz2: document the real field defaults
  (Arnoldi(; krylovdim=30, tol=1e-10, eager=true) and notrunc()).
- time_evolve / timestep: `alg` is a required positional argument, not
  defaulted to TDVP; correct both docstrings accordingly.
- Fix a used-before-assignment bug in the InfiniteMPO QuasiparticleAnsatz
  excitations method (EffectiveExcitationHamiltonian(H_eff, ...) -> H).
- observables reference page: surface the known source-status concerns for
  expectation_value(::MultilineMPS, ::MultilineMPO) and
  variance(::InfiniteQP, ::InfiniteMPOHamiltonian) as !!! warning admonitions.

Doctests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Maintainer-confirmed resolutions for the remaining REVIEW comments:

- hamiltonians.md: add a short TFIM description (X⊗X coupling, transverse
  field g along Z, quantum phase transition at g=1).
- observables.md / entanglement.md: drop the connected-correlator,
  area-law, and sector-spectrum REVIEWs, leaving the text neutral (no
  phase-dependent physical interpretation asserted).
- entanglement.md: replace the random-ψ∞ REVIEW with a !!! note clarifying
  it is not a converged ground state and pointing to find_groundstate.
- entanglement.md: drop the WindowMPS REVIEW after verifying
  entropy(::WindowMPS, site) runs.
- finite_envs.jl: drop the left/right environment REVIEWs; the wording
  matches the code (GRs[ind+1] contracts sites ind+1..end, gauge-compatible
  with the tensor at site ind, and mirror for leftenv).

No REVIEW comments remain in src/ or docs/src/. Doctests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…es, citation

- CHANGELOG.md now canonical at repo root (visible on GitHub); make.jl
  copies it into docs/src at build time, generated copy gitignored
- add CONTRIBUTING.md, issue templates (bug/question), PR template
- CITATION.cff bumped to v0.13.13 (tag date 2026-06-09)
- README gains a Citing section with BibTeX

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace the bare auto-generated title list with a curated gallery:
difficulty ordering within each grouping, 1-2 sentence teasers stating
the physics question and MPSKit features showcased, and thumbnail
figures from the existing example outputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The trailing CLOSING NOTES maintainer-comment blocks claimed the pages'
outputs were unverified and listed make.jl changes that have since
landed. All @example blocks in the three pages were re-verified to
execute end-to-end against the current package (32/32 pass, no code
changes needed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
First page of the tutorial track: prerequisites, project environment,
the full recommended package set with one-line roles, a verified
smoke-test @example (TFIM Hamiltonian + FiniteMPS), and troubleshooting
notes. Registered a Tutorials section in the nav.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
index.md now lists the full environment the documentation actually uses
(MPSKit, TensorKit, TensorOperations, MPSKitModels, TensorKitTensors,
Plots) with one-line roles, including the verified note that truncrank
reaches users via TensorKit's re-export from MatrixAlgebraKit.
howto/states.md and howto/bond_dimension.md gain a packages-used
preamble linking the installation tutorial.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- remove the empty man/lattices.md stub from nav and delete it; the
  forward reference in man/operators.md now points to MPSKitModels docs
- fix off-by-one comment (3-site chain) in man/operators.md
- repair garbled finite-excitations LaTeX in man/algorithms.md,
  formula verified against the FiniteExcited implementation
- verbosity=false -> verbosity=0 in the leading-boundary snippet
- fix empty MKL.jl link in man/parallelism.md
- make hidden @setup imports visible in man/operators.md (13/13 blocks
  re-verified to execute)
- add packages-used preambles to the remaining three how-to pages

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
lkdvos and others added 10 commits July 5, 2026 06:57
…ation_value unit-cell convention

The i < j precondition previously only logged @error and continued into a
meaningless contraction, while howto/observables.md promised an error.
Also add a docstring note that expectation_value of an infinite operator
returns the unit-cell total, not a per-site value.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Maintainer decisions from the round-1 review walkthrough (2026-07-04):
- delete the 22 confirmed REVIEW flags; physics framing stands as written
- fix the DMRG log description (Galerkin error + energy, not 'improvement')
- switch the finite magnetization sweeps (tutorial section 5 and the
  example's finite branch) from periodic_boundary_conditions to the open
  FiniteChain, and re-verify both empirically
- rewrite the abs()/symmetry-breaking story: exact finite-L ground state
  is symmetric; DMRG lands on a broken branch because it carries less
  entanglement; genuine SSB only in the thermodynamic limit
- align crossover prose with the verified runs: the finite-chain drop is
  an algorithm-selection effect below g = 1, the infinite curve pins the
  transition at g = 1 (two new REVIEW flags mark this changed story)
- state correlation_length units; soften 'maximally entangled'
- re-render the TFIM example (figures + index.md + notebook)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…solve xy-finiteT todos

- verbosity = 0 for the log-dumping ground-state calls in 1.ising-cft,
  3.ising-dqpt and 6.hubbard; verbosity = 1 in 4.xxz-heisenberg so the
  pedagogical convergence-failure warnings survive without the ~400-line
  iteration logs
- cite Essler-Frahm-Goehmann-Kluemper-Korepin for the Lieb-Wu energy
  integral (the empty 'Eq. (6.82) in []()' link)
- replace the two xy-finiteT derivation todos with Lieb-Schultz-Mattis
  (1961) references; drop the stale figure todo

Rendered index.md pages intentionally not regenerated here (expensive);
the examples pipeline will pick these up on its next run via Cache.toml.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Maintainer decision 2026-07-04: Discussions (already enabled on the repo)
is the community venue; questions go there, bugs to the issue tracker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…tually apply

Re-renders 1.ising-cft, 3.ising-dqpt, 4.xxz-heisenberg, 6.hubbard and
7.xy-finiteT with the verbosity/citation/todo changes: raw iteration logs
are gone, the xxz failure demo keeps its one-line 'VUMPS cancel' /
'CG: not converged' warnings, and the Essler et al. and Lieb-Schultz-Mattis
references render.

The Random.seed! lines in 4.xxz-heisenberg and 6.hubbard were '#src'-only,
which Literate strips from the executed markdown - renders were never
seeded, and an unlucky draw NaN'd the xxz GradientGrassmann failure demo
into a LAPACK error mid-pipeline. The seeds are now regular executed code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
make.jl computed quantum_pages/classic_pages from readdir but never used
them; the Examples nav entry was a single leaf page, so the rendered site
showed no children in the sidebar, unlike every other section. Wire the
lists in as Overview + Quantum (1+1)d + Classical (2+0)d groups
(verified against the generated VitePress sidebar config).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Collapse the five top-level FiniteMPS sections into a single '## 1. A finite
MPS' section with '###' subheadings, matching the structure of the infinite,
window, and multiline sections, and renumber the remaining sections.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
lkdvos and others added 19 commits July 6, 2026 13:34
Task recipes for find_groundstate: keyword-form heuristic, explicit
DMRG/DMRG2/VUMPS/IDMRG/IDMRG2/GradientGrassmann configuration, &-chaining,
verbosity/tolerance control. All 12 @example blocks verified against real
MPSKit; physics claims salvaged from man/algorithms.md carry REVIEW flags.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Recipes for timestep/time_evolve with TDVP/TDVP2, bond growth during
evolution, infinite-state evolution, imaginary time, and time-evolution
MPOs (WII/TaylorCluster/WI) applied via approximate. All 11 @example
blocks verified against real MPSKit; physics claims carry REVIEW flags.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Recipes for QuasiparticleAnsatz (infinite gap, dispersion scan, charged
Z2 sector), finite-chain excitations (finite QP, FiniteExcited,
ChepigaAnsatz/2), and variance quality checks; domain-wall usage is
prose-only pending in-repo test coverage. All 11 @example blocks
verified against real MPSKit.

Note: verification exposed a numerical bug — find_groundstate on
InfiniteMPS at g=10, chi=12 hits a LAPACK SVD ArgumentError inside the
auto-chained GradientGrassmann step (over-parametrized bond dimension
on a near-product state); reproducible across seeds and single-threaded.
The recipe uses g=2.0 to avoid it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Router page listing every how-to page and its numbered recipes, grouped
by theme, with a missing-recipe issue invitation. All @ref anchors
verified; no code blocks.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New Concepts section with the finite/infinite x task decision table and
per-task prose salvaged from man/algorithms.md. Zero code blocks. Every
physics/convergence claim carries a REVIEW flag (26 total) for
maintainer vetting per CLAUDE.md; dropped-claim inventory in a trailing
comment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Hand-held TDVP quench: TFIM ground state at g=0.5, quench to g=2.0,
explicit 40-step timestep loop tracking mid-chain transverse
magnetization, plotted with Plots. Verified end-to-end twice: the
initial sigma-z story was rewritten to track sigma-x after verification
showed DMRG at D=16 converges to the symmetric ground state (flat
sigma-z trace); the sigma-x trace shows order-1 relaxation dynamics
(0.26 -> peak 0.61 -> plateau 0.49).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Hand-held dispersion walk-through on the infinite TFIM at g=2: single
momentum gap, 16-momentum sweep, plot against the exact Jordan-Wigner
dispersion. Verified end-to-end; the k=0 gap matches 2(g-1) to 1e-11.
Physics claims (phase, ansatz framing, exact formula) carry REVIEW
flags.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Flagship TFIM redone with explicit Z2 symmetry: graded spaces, energy
agreement with the trivial run (1e-14), sector-resolved virtual space
and entanglement spectrum, and the charged-sector excitation payoff.
Plan deviation noted in-file: MPSKitModels' transverse_field_ising only
supports Trivial/Z2Irrep/FermionParity, so the plan's U(1) framing is
replaced by Z2; U(1)/SU(2) are pointed to via states how-to and
examples. All 13 @example blocks verified twice (unseeded RNG).

Also replaces the two TODO(link) stubs in thermodynamic_limit.md with
real links to the new excitations and using-symmetries tutorials.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
content-wave1 folded the five FiniteMPS construction recipes into one
section; mirror that in the index listing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- lead the hero tagline and feature cards with the finite/infinite and
  symmetry differentiators; drop emoji icons; add a performance card
- rebuild the example as build -> optimize -> measure sections, using a
  from-scratch FiniteMPOHamiltonian and an entanglement-entropy plot
- add a "Beyond this example" section hinting at infinite systems,
  symmetries, and fermions, and a "Citing MPSKit" section
- lead the where-next and beyond bullets with their links; tighten the
  intro; drop TensorOperations from install (@tensor is re-exported)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- author four green SVG line icons (finite/infinite, symmetry, algorithm
  suite, performance) and wire them into the hero features frontmatter as
  icon.src; VitePress renders them in its default soft icon box
- add an MPS tensor-network diagram (assets/mps.svg) after the "A first
  calculation" intro, with colours that work in both themes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…entry points

Reference-depth pass (IMPROVEMENT_PLAN W4). find_groundstate now documents its
keyword defaults, the previously undocumented `trscheme` keyword, and the full
automatic algorithm-selection heuristic. Adds runnable jldoctest examples to the
first-touch entry points that lacked them: FiniteMPS, InfiniteMPS,
FiniteMPOHamiltonian/InfiniteMPOHamiltonian, changebonds, and timestep. Every
golden value is a real run; the whole doctest(MPSKit) suite passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Begins retiring the man/ section (IMPROVEMENT_PLAN W4). Splits
man/parallelism.md along the Diátaxis seam:
- concepts/parallelism_model.md — the Julia/BLAS thread interaction, where
  MPSKit parallelizes (OhMyThreads over sites), sector-level parallelism, and
  why memory pressure arises.
- howto/parallelism_gpu.md — recipes for BLAS threads, set_scheduler!,
  threadinfo diagnostics, OutOfMemory mitigation, and an experimental
  Adapt-based GPU note (marked with a warning admonition).
Wires both into the nav and the how-to recipe index; unwires
man/parallelism.md (kept on disk pending review). Physics/performance claims
carry <!-- REVIEW --> flags for maintainer sign-off.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replaces the (already build-disabled) man/environments.md with a Diátaxis
concept page: what environment objects are (cached partial contractions),
why algorithms take and return an optional environments argument, the finite
===-identity cache and its in-place-mutation pitfall, and how infinite
environments differ (iterative fixed-point solves, no auto-recompute).

Re-derives the current API against src/ — the legacy page carried stale calls
(poison!(state,i), recalculate!(cache,state), cache.tol) that are dropped or
reframed to the real internal signatures. Uncertain points (infinite-env
precision control, exact invalidation route) carry <!-- REVIEW --> flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Salvages the conceptual heart of man/states.md into a Diátaxis concept page
on MPS gauge freedom and canonical forms: the C·C⁻¹ gauge insertion, the
left/right isometry forms (AL/AR), the center bond tensor C and center-site
AC = AL·C = C·AR, automatic ("automagic") gauge management, and the
center-gauge overlap insight (dot(state,state) = dot(C,C) at any bond).

The gauge-relation checks are exact identities for any valid gauged MPS, so
they are written as jldoctest blocks returning `true` and verified by the full
doctest suite (green). Construction recipes and type reference are left to
howto/states.md and lib/states.md respectively; internal field-layout details
are dropped. Two diagrams copied in with text descriptions; image leg
convention and the finite-vs-infinite recompute wording carry REVIEW flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Salvages the conceptual core of man/operators.md into a Diátaxis concept page:
what an MPO is (finite vs infinite, two physical + two virtual legs), the gauge
non-uniqueness caveat, virtual-dimension growth under products/sums, and — the
centrepiece — the Jordan-block MPO-Hamiltonian structure presented as math with
the finite-state-automaton reading (D→1-site, C·B→2-site, C·Aᵏ·B→(k+2)-site),
the explicit TFIM W matrix, boundary vectors, and H = V_L W^⊗N V_R. Keeps the
Symbolics expansion as a run-verified @example, and covers the sparse
BlockTensorMap/JordanMPOTensor block structure.

Construction recipes (incl. the 2D lattice example) are left to
howto/hamiltonians.md; type reference to lib/operators.md; the legacy WIP-stub
section is dropped. Physics/convention claims (virtual-dim growth law, automaton
index convention, long-range decay/power-law approximation) carry REVIEW flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replaces man/intro.md with a Diátaxis concept page that lowers the TensorKit
cliff. Part A takes the positive path first — TensorMap as a linear map, the
spin-1/2 ℂ^2 running example, then the ℤ₂ symmetric-tensor payoff — and only
afterwards introduces the domain/codomain partition mismatch as a diagnostic
(reframing the legacy page, which opened with two errors). Part B leads with
the planarity/fermion-sign rationale for the Vₗ ⊗ P ← P ⊗ Vᵣ ordering, then
shows the MPS/bond/MPO tensor diagrams, each with a math leg-order fallback.

All code is verified: four jldoctest blocks pass the full doctest suite and the
three @example blocks were run standalone. Fixes a latent legacy bug (the old
permute(t2,(1,2,3),()) does not actually make the addition succeed). The
planarity/fermion claim and the three image conventions carry REVIEW flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Manual pages have been superseded by the tutorials, how-to guides,
concept pages, and library reference built over waves 1-3:
- intro.md      → concepts/vector_spaces.md
- states.md     → concepts/matrix_product_states.md
- operators.md  → concepts/operators_and_hamiltonians.md
- algorithms.md → concepts/algorithm_landscape.md + how-tos + lib/
- environments.md → concepts/environments.md
- parallelism.md → concepts/parallelism_model.md + howto/parallelism_gpu.md

Removes the Manual group from the nav, deletes the man/ sources and their
images (finite_mps_definition/mps_gauge_freedom copied into concepts/; the
D_*_strided/blas threading plots were unreferenced), and repoints the landing
page "Where next" router from the manual to the concept pages.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The landing-page MPS diagram used a bare relative `assets/mps.svg`, which
Rollup treats as a module import and fails to resolve, breaking the full
VitePress build. Use an explicit-relative `./assets/mps.svg` (base-path
independent, unlike an absolute `/assets/...`), matching the pattern the
concept pages use for `../assets/...`. Full `makedocs` build now completes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant