docs: content wave 1 (reference + how-to pages)#449
Draft
lkdvos wants to merge 52 commits into
Draft
Conversation
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>
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>
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>
Complete TFIM walkthrough: Hamiltonian, FiniteMPS, DMRG via find_groundstate, energy/magnetization/variance, and the magnetization curve across the phase transition (mirroring the README quickstart). All blocks verified to execute (E = -16.146, variance ~7e-8, M sweeps 1 -> 0 across g = 1). Physics claims carry REVIEW flags for the maintainer. Registered in nav; installation tutorial now links here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Landing page: 30-second verified hero example replaces the gauge-tensor walkthrough; 'Where next' router, ecosystem and community sections; hero button routes to the tutorial track; stale TOC removed. Thermodynamic-limit tutorial: the near-identical-code payoff page (InfiniteMPS + VUMPS, correlation length as the infinite-only observable, magnetization sweep). All 9 blocks verified: E/site = -1.0635 at g = 0.5, correlation length 0.58 -> 7.45 approaching g = 1, sharp finite-D crossover just past g = 1. Physics claims carry REVIEW flags. Registered in nav; flagship now links here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rank attribution truncbelow does not exist in MatrixAlgebraKit or TensorKit (verified at runtime); truncrank reaches users via TensorKit's re-export, not MPSKit's. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New 0.tfim-groundstate Literate example bridging the tutorial track into the gallery: finite-ring DMRG vs infinite VUMPS magnetization in one figure, entanglement entropy and correlation length across the transition. Executed for real by examples/make.jl (3 figures + notebook); physics claims carry REVIEW flags. Gallery index gains its entry as the new first rung. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…xamples Their main.jl sources were edited during wave 1 without regeneration, so the cached checksums no longer matched; examples/make.jl re-executed both. Diffs are floating-point noise in captured outputs plus refreshed figures. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…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>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
@autodocs)Notes
@example/jldoctestand were verified against real MPSKit.<!-- REVIEW: ... -->.🤖 Generated with Claude Code