Skip to content

Add DMRG spinless-fermion tutorial series (DMRG-07 – DMRG-11) - #146

Open
marcusr2ML wants to merge 22 commits into
ALPSim:mainfrom
marcusr2ML:main
Open

Add DMRG spinless-fermion tutorial series (DMRG-07 – DMRG-11)#146
marcusr2ML wants to merge 22 commits into
ALPSim:mainfrom
marcusr2ML:main

Conversation

@marcusr2ML

@marcusr2ML marcusr2ML commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator

Adds a five-module DMRG tutorial series on the one-dimensional spinless-fermion chain, under content/en/tutorials/dmrg/spinless-fermions/, plus a style pass over the existing DMRG-01 – DMRG-06 modules.

The open vs closed BC was almost cut from the lineup, but I decided to keep. DMRG-10 could possibly benchmark the two model types more, e.g. time to convergence, numerical accuracy, etc.

New series

Module Topic
DMRG-07 Introduction — XXZ chain, Jordan–Wigner transformation, U(1) symmetry
DMRG-08 Ground state energies — free-fermion point and the Heisenberg point
DMRG-09 Particle-number sectors — the fixed-N blocks built by CONSERVED_QUANTUMNUMBERS="N"
DMRG-10 Model types in 1D — spinless fermions vs hardcore boson
DMRG-11 Boundary conditions — open vs periodic chains

Every module follows the tutorial-page conventions in CLAUDE.md: physics motivation, model with DOI citations, parameter tables, full parameter files, lattice diagrams, method justification, execution commands, results, and extension questions.

Numerical results

All energies and figures come from actual ALPS runs (dmrg, sparsediag) and are checked against closed forms where available:

  • DMRG-08/10 reproduce the exact open-chain free-fermion energy to twelve digits.
  • DMRG-09 reproduces E = 0 in the vacuum and the exact standing-wave energy and profile at N = 1, for any V.
  • DMRG-11 compares open and periodic chains at equal bond dimension against the Bethe ansatz value 1/4 - ln 2: the ring converges as 1/L^2 with the conformal coefficient -pi^2/12, the open chain only as 1/L because of its surface term, while the ring costs roughly eight times the bond dimension at L = 32.

Driver scripts (run_bethe_ansatz.py, run_number_sectors.py, run_free_theory.py) reproduce every table and figure.

Note: density profiles in DMRG-09 are measured with sparsediag rather than dmrg, because the legacy dmrg application evaluates MEASURE_LOCAL only on the final two-site sweep window and returns zero on all other sites. The two applications' energies agree to 6.5e-13, which the script checks.

Style pass on DMRG-01 – DMRG-06

Consistent American spellings, sentence-case section headings (these modules were title case while the new ones were not), colons introducing displayed equations, and typo fixes. No content or numerical changes.

marcusr2ML and others added 19 commits August 20, 2026 11:10
Nest a new Spinless Fermions section under the DMRG tutorials, giving
the sidebar a collapsible entry below the existing six spin-chain pages.

- Rename "spinless fermions" to spinless-fermions to avoid the space in
  the directory name.
- Add the section landing page, without which Hugo renders no section
  page at all and the dropdown never appears.
- Add front matter to dmrg07.md so it is titled "DMRG-07 Introduction"
  rather than being derived from the filename.
- Weight dmrg01-06 explicitly; Hugo sorts weight-0 pages last, so the
  weighted subsection would otherwise jump above them.
- Fix dmrg07.md: renumber sections (they ran 1,2,3,6,7,8), repair two
  broken math delimiters, separate a paragraph from a following "---"
  that was promoting it to a heading, convert to US spelling, and
  correct spelling and grammar.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Drop section numbering from all headings and replace the three
  cross-references that pointed at numbered sections with descriptions
  of the results they referred to.
- Collapse the spin-1/2 anticommutator into a single relation covering
  both the on-site and off-site cases via Kronecker deltas, replacing
  the split presentation.
- Fix a stray "$" inside a display block, which made KaTeX fail and the
  page return HTTP 500 (math is rendered server-side via
  transform.ToMath, so a parse error breaks the build).
- Add a colon to the five lead-in lines that introduced a display
  equation without one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two ground state energy tutorials under the Spinless Fermions section,
both run against the ALPS dmrg code and reporting measured numbers.

DMRG-08 Free Theory benchmarks the V=0 chain against the closed-form
sum over single-particle levels, which is exact at finite L with open
boundaries, so the residual is DMRG truncation error alone. At L=32,
D=200 the energy matches to 1e-14.

DMRG-09 turns the interaction on at V=2t, where the Jordan-Wigner
mapping lands on the isotropic Heisenberg point and the Bethe ansatz
supplies an exact bulk energy. Extrapolating open chains to L=128
against a 1/L surface term recovers 1/4 - ln2 to 4.9e-06.

Both use MODEL="hardcore boson" rather than "spinless fermions". The
legacy dmrg binary returns energies far below the exact ground state for
the fermionic model (-467 against -4.759 at L=8), which is variationally
impossible; sparsediag handles the same model correctly, so the fault is
in dmrg. On an open chain with nearest-neighbour hopping the two models
share every eigenvalue, since the Jordan-Wigner strings cancel between
adjacent sites. Both pages say so and state where the substitution stops
being valid.

Sectors are fixed with N_total rather than Sz_total throughout, there
being no spin to project.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ground-state energies of the t-V chain at L=32, half filling, computed
with the ALPS dmrg application in the Jordan-Wigner-equivalent
hardcore-boson basis: the free point (V=0) matches the exact open-chain
result to twelve digits, and the V=2t point reproduces the DMRG-03
Heisenberg energy through the JW shift -V(L-1)/4. Includes parameter
files, a special-edges lattice for the site-dependent chemical
potential, convergence figures, and zh-cn/ja translations of the whole
spinless-fermions subsection (also standardizing 开放边界条件 in zh-cn).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W3S6Ue49fS2qAFEepgsmUR
DMRG-07 Simulations and DMRG-08 both carried weight 2 after the two
branches merged; order the section as 07-intro, 07-simulations, 08, 09.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W3S6Ue49fS2qAFEepgsmUR
The page argued that the surface term was tolerable because the
extrapolated answer came out as accurate as the ring's. That reasoned
from the outcome: the two agreed only because the correct fit form was
known in advance, which is exactly what an unknown calculation lacks.

Measured both effects instead of asserting:

- Stability across fit windows is not the issue. Refitting over every
  choice of lengths moves the extrapolated value by 1.70e-04 on the open
  chain against 1.45e-04 on the ring, which is the same to within noise.

- Sensitivity to the fit form is the issue, and it is badly asymmetric.
  Omitting the surface term that is really present costs a factor of 850
  (4.2e-03 against 4.9e-06); including one that is not present costs a
  factor of 4 (1.2e-05 against 3.1e-06). A ring cannot get this wrong,
  since translational symmetry forbids a surface contribution outright.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The three simulation pages after the introduction shared a number with it
and overlapped heavily in content: DMRG-07 Simulations, DMRG-08 Free
Theory, and DMRG-09 Bethe Ansatz each rederived the hardcore-boson
substitution, and the boundary-condition discussion was a digression
inside the Bethe ansatz page.

Renumber them 08/09/10 so the series has no duplicate, and give the last
two a subject each rather than a calculation each:

- DMRG-09 Model now compares spinless fermions against hardcore bosons
  directly. It collects the sparsediag-vs-dmrg table that was duplicated
  verbatim in both pages, and explains the failure: the reported -467.3
  lies ~98x below the smallest eigenvalue the L=8 Hamiltonian possesses,
  outside the spectrum entirely, which no truncation error can produce.
  Notes explicitly that this is Jordan-Wigner string bookkeeping and not
  a sign problem, DMRG being deterministic.

- DMRG-10 Boundary Conditions promotes the open-vs-periodic material to
  the spine of the page: the 1/L surface term, the convergence it costs
  against the ring's conformal 1/L^2, and the asymmetry in getting the
  fit form wrong. Adds the ring parameter file and lattice diagram.

DMRG-08 keeps its physical argument for the boson form and now points
forward to the numerical demonstration instead of restating it.

Also fix relative links throughout these pages. They sit one URL level
deeper than dmrg01-06, so bare "](dmrg07)" resolved to
/spinless-fermions/dmrg08/dmrg07 and "](../../../documentation/...)" to
/tutorials/documentation/...; both 404ed. Verified against the build.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The renumbering in 8a9ee78, 0482229 and 2850d8b renamed
dmrg07-simulations.md -> dmrg08.md, dmrg08.md -> dmrg09.md and added
dmrg10.md, but left _index.md pointing at the old slugs. The DMRG-08
entry linked to a page that no longer exists, and the DMRG-09 and
DMRG-10 entries pointed one module short of their targets.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Runs the spinless-fermion chain in the fixed-N blocks built by
CONSERVED_QUANTUMNUMBERS="N", stacking { N_total=... } blocks to get
one DMRG run per sector from a single invocation.

The three dilute sectors are the only ones whose answers are known in
closed form, which makes them a calibration rather than a calculation:
N=0 is the vacuum at E=0; N=1 is exactly the free standing wave for any
V, since a nearest-neighbour interaction needs two particles; N=2 is
the first sector where V acts at all, worth +1.4e-3 in energy and a
4e-3 redistribution of the density. In spin language these are
S^z_tot = N - L/2, so <n_i> is the magnon density -- the fermionic
counterpart of the magnetisation sectors in DMRG-05.

All energies and profiles come from dmrg (L=32, D=100); sparsediag runs
on the same parameter file as an exact cross-check via --check, and
agrees to ~1e-14 on the energies.

Note that MEASURE_LOCAL requires an ALPS build containing the 2026
rework of the site-resolved measurement path (local observables
accumulated as dmtk::Term). Older binaries return a vector that is
nonzero only on the two central sites and violates the sum rule; the
page carries a callout to that effect.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reorder the spinless-fermion series so the particle-number sectors module
follows directly from the U(1) symmetry established in DMRG-07:

  DMRG-09  Particle-Number Sectors  (was DMRG-11)
  DMRG-10  Model Types in 1D        (was DMRG-09)
  DMRG-11  Boundary Conditions      (was DMRG-10)

DMRG-11 Boundary Conditions: rebuild around two convergence tables — energy
per bond for open and periodic chains at equal bond dimension (D=200), and a
bond-dimension scan at L=32. The ring converges as 1/L^2 against the open
chain's 1/L surface term, but needs roughly eight times the bond dimension to
reach the same truncation error. Drop the fit-form extrapolation section and
make the surface-energy argument explicit against the Bethe ansatz value.

DMRG-09 Particle-Number Sectors: de-duplicate against DMRG-07 and DMRG-08
(symmetry, model definition, standing-wave levels are now cited, not restated).
Fix the density-profile pipeline: the legacy ALPS dmrg application measures
MEASURE_LOCAL only on the final two-site sweep window and returns zero
elsewhere, so profiles now come from sparsediag, whose energies agree with
the DMRG ones to 6.5e-13. Corrects three claims that the old pipeline could
not produce (profile deviation, sum rule) and regenerates the figure.

DMRG-10 Model Types: replace the runtime GRAPH and TERM dumps with the
spinless-fermions definition from the ALPS model library, where type="fermionic"
carries the Jordan-Wigner point directly.

Series-wide style pass over DMRG-01 through DMRG-11: American spellings,
sentence-case section headings (DMRG-01..06 were title case), colons before
displayed equations, and assorted typo fixes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Aug 21 commits on main (deleting Model Types and renumbering
dmrg10/dmrg11 down to dmrg09/dmrg10) are superseded by this branch,
which renumbers the series as:

  DMRG-09  Particle-Number Sectors
  DMRG-10  Model Types in 1D
  DMRG-11  Boundary Conditions

Resolved wholly in favor of the branch.
Rework DMRG spinless-fermion modules and normalize series style
@marcusr2ML
marcusr2ML requested review from Ooolab and afeiguin August 28, 2026 00:32
@Ooolab

Ooolab commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Reviewed by checking out the branch and re-running the simulations locally against ALPS 2.3.3, rather than reading the numbers only. Every numerical claim in the PR description holds. Details below, then two things I think are worth fixing before merge.

Verified by re-running

Claim Result
DMRG-08 free fermions reproduce the exact energy "to twelve digits" Confirmed. Analytic $\sum_{n=1}^{16}\varepsilon_n = -20.0163879005,t$; my dmrg run gave the same to $|\Delta| = 1.6\times10^{-11}$
DMRG-08 interacting point $V=2t$ Confirmed. Ran it with the generated my_lattice.xml: $E_0 = -21.7473156$, $|\Delta| = 1.8\times10^{-8}$. The Jordan–Wigner arithmetic also checks out: $-13.9973156 - 31/4 = -21.7473156$
DMRG-09 $N=1$ standing wave, $V$-independent Confirmed to 12 digits: $-1.990943845146$ in both the $V=0$ and $V=2t$ rows
DMRG-09 $N=2$ free-fermion reference Confirmed to 12 digits: $-3.954801239672$
DMRG-11 table at $L=32$ Reproduced all 12 digits for both geometries: open $-0.473039369885$, ring $-0.443953974654$
DMRG-11 conformal $1/L^2$ with coefficient $-\pi^2/12$ Confirmed. Ring deviation $\times L^2$ runs $-0.8311, -0.8276, -0.8262, -0.8247, -0.8227$, converging monotonically onto $-\pi^2/12 = -0.8225$
DMRG-11 open chain converges as $1/L$ Confirmed. Open deviation $\times L$ is flat at $\approx -0.95$ across the whole series
Style pass on DMRG-01–06 is "no content or numerical changes" Confirmed programmatically — extracted every numeric token from added vs. removed lines in all six files; the multisets are identical. Changes are heading case, neighbourneighbor, and hyphenation only

Also checked: the build is clean, the three driver scripts publish correctly as branch-bundle resources, and the alps-download handler this relies on is already on main. The Lieb–Schultz–Mattis DOI with parentheses in it renders fine — Goldmark percent-encodes them.

The DMRG-11 discussion of why the open chain converges slower — a fixed surface cost spread over $N_b$ bonds, so $1/L$ by construction rather than as a fitted prefactor — is the clearest treatment of this I have seen in the tutorials, and the $-\pi^2/12$ check lands convincingly.

1. The ja and zh-cn trees are out of sync with the new series

This one I would fix before merge, because it degrades pages that currently work.

The English series is dmrg07 … dmrg11, but the translations ship:

ja/zh-cn:  _index.md, dmrg07.md, dmrg07-simulations.md
en:        _index.md, dmrg07.md, dmrg08.md, dmrg09.md, dmrg10.md, dmrg11.md

dmrg07-simulations.md is 345 lines — exactly en/dmrg08.md — and its content is a genuine, good translation of DMRG-08. It just kept the filename and title from before the module was renumbered. Its front matter still reads title: DMRG-07 シミュレーション / DMRG-07 模拟 while the body is DMRG-08.

Two consequences, both confirmed in the built output:

  • The language switcher silently drops off DMRG-08. Hugo pairs translations by path, so /tutorials/dmrg/spinless-fermions/dmrg08/ has no counterpart at that path. Grepping the built HTML, the DMRG-07 page emits both href="/ja/…/dmrg07/" and href="/zh-cn/…/dmrg07/"; the DMRG-08 page emits no language links at all. A reader on DMRG-08 loses the ability to switch language entirely.
  • DMRG-09/10/11 have no translations, so ja and zh-cn present a two-module series that ends mid-story, with _index.md listing only Introduction and Simulations.

Renaming the two translated files to dmrg08.md and updating their title: fixes the switcher and the numbering with no new translation work. Whether 09–11 get translated now or later is a separate call — but if later, it may be cleaner to hold the partial translations back rather than ship a series that stops at 08 in two languages.

2. Two modules have no citation

CLAUDE.md asks each tutorial for a model reference with a doi.org link.

  • dmrg07 derives the Jordan–Wigner transformation (7 mentions) and carries zero DOI citations. dmrg08 and dmrg10 both cite 10.1007/BF01331938 for exactly this — the module that does the derivation seems like the one that most needs it.
  • dmrg09 has no external links of any kind.

3. Nit

## Choice of method is present in dmrg08 and dmrg09 but absent from dmrg10 and dmrg11, so "Every module follows the tutorial-page conventions in CLAUDE.md" is very slightly overstated. dmrg07 is a pure derivation page, so the simulation-specific items obviously do not apply to it — no issue there.

Nothing above touches the physics, which is solid and reproducible.

marcusr2ML and others added 2 commits August 28, 2026 11:22
DMRG-07 was the only module in the spinless-fermion series without
references. Add the seminal sources inline, matching the citation
style already used in DMRG-08, DMRG-10 and DMRG-11:

- Jordan and Wigner (1928) for the transformation itself
- Lieb, Schultz and Mattis (1961) for the exact XY-chain solution
- Bethe (1931) and Yang and Yang (1966) for the exactly solved
  points the DMRG runs are benchmarked against
- Fradkin (1989) for the two-dimensional Jordan-Wigner constructions
- White (1992) and Schollwoeck (2005) where the U(1) block structure
  is tied to how DMRG exploits it

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Expanded explanation of the parity operator and its role in fermionic systems, emphasizing its non-locality and the significance of the string operator in maintaining anticommutation relations.
@marcusr2ML

Copy link
Copy Markdown
Collaborator Author

@Ooolab I just updated the spinless-fermion introduction. Cut down on some explainations and added a few citations.

@Ooolab Ooolab left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great! Hope to merge this asap after @afeiguin review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants