Reproducible Notebooks

A notebook becomes evidence only when its entire computational argument can be inspected and rerun. The relevant object is not the final plot alone. It is the model statement, conventions, environment, executable method, validation cells, raw numerical result, interpretation, and recorded limitation taken together.

This page is the status-aware index and release roadmap for notebooks connected to many-body and statistical quantum mechanics. It fixes canonical filenames and admission tests before artifacts are published, so a future notebook cannot acquire authority merely by appearing in the repository.

Current Repository Status

At this review, the repository does not contain a committed notebooks/many-body/ family. Every filename in the catalogs below is therefore planned, not downloadable, not rerun, and not admissible as evidence for a numerical claim.

That distinction is intentional:

$$\begin{aligned} \text{planned} &\neq \text{committed}, \\ \text{committed} &\neq \text{reproduced}. \end{aligned}$$

The first committed notebook family elsewhere in the repository is documented by the Canonical Systems Numerical Notebooks Index. It provides a useful implementation precedent, but its validation results do not transfer to the many-body problems listed here.

Purpose and Canonical Scope

This page owns the volume-specific notebook inventory:

• canonical filenames for the planned many-body notebook family;
• the physics page each notebook implements;
• the minimum numerical method and output contract;
• the benchmark or analytic gate required for admission;
• the current inventory state;
• release, provenance, and maintenance rules shared by the family.

It does not own the underlying physics derivations or general software policy. Those remain at the following canonical homes:

• Notebook Index owns the sitewide artifact metadata contract.
• Environments owns dependency and environment policy.
• Reproducibility Status owns artifact status labels and transition rules.
• Validation Tests owns reusable executable test families.
• Code Style owns notebook organization and review conventions.
• Benchmark Problems owns the stable MB-Bxxx physics contracts used by this family.

The notebook must link to a canonical physics page; the notebook is never the canonical definition of a Hamiltonian, observable, approximation, or theorem.

Inventory State Is Not Reproducibility Status

The catalogs use a small inventory vocabulary to say whether a proposed file exists and has entered review.

Inventory state	Meaning	May support a claim?
planned	filename and contract are reserved, but no file is committed	no
present_unreviewed	a file exists, but clean execution and checks have not been reviewed	no
candidate	clean execution succeeds and validation is under review	not yet
admitted	metadata and validation meet the index contract	only according to its reproducibility status

Once a file exists, it must also carry one of the sitewide labels such as reproduced, reproduced_with_warnings, needs_update, or broken. A notebook can be admitted to the inventory while temporarily marked needs_update; the status warns readers not to use its output as current evidence.

Do not label a nonexistent file conceptual_only. That label describes a real explanatory artifact that is intentionally non-evidential. A planned filename is not yet an artifact at all.

Canonical Filename Policy

Use one stable filename for each computational argument. The names in this page are canonical for the first many-body family under

notebooks/many-body/

A generic spin-chain exact-diagonalization artifact is deliberately split into separate transverse-field Ising and Heisenberg notebooks. The two models use different operator normalizations, symmetries, spectra, and validation targets. Likewise, the fermionic and bosonic dimers keep distinct filenames because their hopping matrix elements test different algebra.

Rename a notebook only before external pages, figures, or reports cite it. After citation, preserve the path or provide an explicit migration record.

Family-Wide Notebook Contract

Every admitted notebook must expose, in its opening cells:

1. Goal: one concrete physical or numerical question.
2. Canonical targets: links to the model, concept, formula, and benchmark pages used.
3. Conventions: Hamiltonian sign, operator normalization, basis or mode ordering, boundary condition, units, and energy shifts.
4. Method: representation, solver, quadrature, optimizer, or evolution algorithm and its approximations.
5. Parameters: physical values, numerical cutoffs, size sequence, tolerances, and seeds when relevant.
6. Environment: interpreter, direct dependency versions, environment lock or recipe, and platform notes.
7. Validation: executable checks with thresholds declared before the result is inspected.
8. Outputs: machine-readable values before plotting, followed by labeled figures or tables.
9. Evidence horizon: what the successful run does and does not validate.
10. Provenance: status, last run, implementation revision, and reviewer or automation source when available.

A notebook that omits the conventions cell should be presumed ambiguous even if its code looks familiar.

Planned Catalog: Thermal States and Ideal Statistics

All entries in this table are currently planned.

Canonical filename	Physics owner	Minimum method	Admission gate
two_level_thermal_state.ipynb	Thermal Density Operators	direct $2\times2$ diagonalization and matrix exponential	Gibbs populations, trace, Hermiticity, and positivity
canonical_ensemble_examples.ipynb	Canonical Ensemble	exact finite spectra and partition sums	energy derivative, fluctuation identity, and low/high-$T$ limits
bose_einstein_distribution.ipynb	Bose–Einstein Statistics	stable occupation-function evaluation	physical chemical-potential domain and Maxwell–Boltzmann limit
fermi_dirac_distribution.ipynb	Fermi–Dirac Statistics	stable occupation-function evaluation	$0\leq f\leq1$, half occupation, and classical limit
ideal_bose_gas_bec.ipynb	Ideal Bose Gas	polylogarithms, constrained root finding, and temperature sweep	MB-B006
ideal_fermi_gas_sommerfeld.ipynb	Ideal Fermi Gas	Fermi quadrature, number root, and low-$T$ fit	MB-B007
density_of_states_dimensions.ipynb	Density of States: First Encounter	state counting and continuum quadrature in $d=1,2,3$	discrete count, integrated density, and dimensional power law

Shared thermodynamic checks

For a finite Hamiltonian, the thermal state must satisfy

$$\rho_\beta = \frac{e^{-\beta H}}{Z}, \qquad Z=\operatorname{Tr}e^{-\beta H},$$

and the validation cell should test

$$\begin{aligned} \operatorname{Tr}\rho_\beta &=1, \\ \rho_\beta^\dagger &=\rho_\beta, \\ \lambda_{\min}(\rho_\beta) &\geq-\epsilon_{\mathrm{pos}}. \end{aligned}$$

The tolerance $\epsilon_{\mathrm{pos}}$ must be tied to arithmetic and conditioning. Clipping negative eigenvalues before reporting the test hides the quantity being validated.

For canonical partition sums, compute thermodynamic quantities by at least two identities where practical:

$$\begin{aligned} U &=-\frac{\partial\ln Z}{\partial\beta}, \\ C_V &=k_{\mathrm B}\beta^2 \left( \langle H^2\rangle - \langle H\rangle^2 \right). \end{aligned}$$

Finite differences of $\ln Z$ should be compared with direct ensemble averages over a refinement sequence. Agreement at one step size is not a derivative-convergence test.

Distribution notebooks must handle extreme arguments without overflow. A stable implementation may branch algebraically, but it must reproduce the defining limits rather than silently clipping physical occupations. The Bose notebook must enforce $\mu$ below the lowest one-particle energy in the normal phase. The Fermi notebook must solve for $\mu(T)$ when particle density, rather than chemical potential, is held fixed.

For a free quadratic dispersion in $d$ dimensions, the continuum density of states follows

$$g_d(E) \propto E^{d/2-1}.$$

The notebook should compare this law with cumulative state counts before differentiating noisy histograms. Boundary and shell effects belong in the interpretation, not in a post hoc smoothing choice.

Planned Catalog: Finite Clusters and Correlations

All entries in this table are currently planned.

Canonical filename	Physics owner	Minimum method	Admission gate
hubbard_dimer_exact.ipynb	Hubbard Dimer dossier	explicit Fock basis and complete diagonalization	MB-B003
hubbard_chain_ed.ipynb	Hubbard Chain dossier	site-major Fock basis and complete open-chain block diagonalization	MB-B004
bose_hubbard_dimer_exact.ipynb	Bose–Hubbard Dimer dossier	fixed-number occupation basis and complete diagonalization	MB-B005
transverse_field_ising_ed.ipynb	Transverse-Field Ising Model	spin-bit Hamiltonian and complete small-chain spectrum	MB-B001
heisenberg_chain_ed.ipynb	Heisenberg Chain	spin basis, symmetry labels, and complete small-ring spectrum	MB-B002
spin_correlations.ipynb	Equal-Time Correlations	finite-chain ground states and real/momentum-space contractions	connected/disconnected split, symmetry, bounds, and convention-specific sum rule
entanglement_entropy_spin_chain.ipynb	Entanglement Entropy in Many-Body Systems	reshape, singular values, and reduced density matrices	Schmidt-spectrum agreement, normalization, and entropy bounds

Basis and eigensystem checks

Before calling an eigensolver, every finite-cluster notebook should verify:

$$\begin{aligned} N_{\mathrm{basis}} &=N_{\mathrm{expected}}, \\ \frac{\|H-H^\dagger\|_F} {\max(\|H\|_F,1)} &<\epsilon_H, \\ [H,Q_a] &\approx0 \end{aligned}$$

for every conserved quantity $Q_a$ used to reduce the problem. If matrix elements are generated within a sector, every transition must either remain in the sector or vanish for a stated algebraic reason.

For each reported eigenpair,

$$r_n = \left\| H|\widetilde n\rangle - \widetilde E_n|\widetilde n\rangle \right\|_2$$

must be small on the declared energy scale. A tiny residual validates the eigenpair of the encoded matrix; the MB-Bxxx spectrum and moment checks validate that the encoded matrix is the intended Hamiltonian.

Correlation and entanglement checks

The correlation notebook must state whether it computes

$$C_{ij} = \langle O_iO_j\rangle$$

or the connected quantity

$$C_{ij}^{\mathrm c} = \langle O_iO_j\rangle - \langle O_i\rangle \langle O_j\rangle.$$

Fourier normalization, boundary conditions, and whether site averaging is used must be visible beside the output. A structure-factor sum rule is meaningful only after those conventions are fixed.

For a pure bipartite state with Schmidt values $s_\alpha$, two independent constructions should agree:

$$\begin{aligned} p_\alpha &=s_\alpha^2, \\ \operatorname{spec}_{+}(\rho_A) &= \operatorname{spec}_{+}(\rho_B) = \{p_\alpha\}, \\ S_A &=-\sum_\alpha p_\alpha\ln p_\alpha. \end{aligned}$$

The notebook should test $\sum_\alpha p_\alpha=1$, nonnegativity within tolerance, $S_A=S_B$, and the dimension bound $S_A\leq\ln\dim\mathcal H_A$. A scaling plot belongs after these finite-state identities pass.

Planned Catalog: Response, Scaling, Mean Field, and Dynamics

All entries in this table are currently planned.

Canonical filename	Physics owner	Minimum method	Admission gate
finite_size_scaling_tfim.ipynb	Finite-Size Scaling in Numerics	exact small-chain gaps and correction-aware fits	MB-B009
spectral_function_lanczos_preview.ipynb	Dynamical Correlation Functions Numerically	Lehmann lines and Lanczos continued fraction on an overlap cluster	matched broadening, zeroth moment, poles, and cross-method agreement
kubo_response_two_level.ipynb	Kubo Formula	exact two-level Lehmann response and direct driven evolution	causality convention, detailed balance, and weak-drive agreement
gross_pitaevskii_1d_ground_state.ipynb	Gross–Pitaevskii Equation	normalized imaginary-time or constrained energy minimization	stationary residual, norm, energy descent, and grid/box refinement
bcs_gap_equation.ipynb	BCS Mean-Field Theory	bracketed quadrature and self-consistent root solving	MB-B008
quantum_quench_tfim_small_system.ipynb	Quantum Quenches	exact finite-matrix evolution after a parameter quench	norm, energy, $t=0$, recurrence, and spectral-decomposition checks

Scaling notebooks

A scaling notebook must preserve the raw size sequence and distinguish a pointwise spectrum failure from a fit-model failure. For the critical Ising contract,

$$R_L = \frac{ \Delta_L^{\mathrm{num}} }{ 4J\sin[\pi/(4L+2)] } -1$$

should be tested before fitting $z$. The notebook must show at least two lower-size cutoffs, retain excluded sizes in the data record, and report the drift of parameters and goodness-of-fit diagnostics. A visually straight log–log plot is not an acceptance criterion.

Response notebooks

The spectral notebook should retain the exact finite-system line list separately from every plotted broadening. For a chosen convention, its zeroth moment must reproduce the corresponding equal-time correlator. Spectral Functions and Sum Rules own the formulas; the notebook owns their executable verification.

The Kubo notebook must state the Fourier sign and retarded-response convention. It should compare the Lehmann susceptibility with direct evolution under a weak probe over a declared time window. Agreement should improve as the probe amplitude enters the linear regime while remaining above floating-point and finite-time noise.

Nonlinear stationary equations

For a normalized one-dimensional Gross–Pitaevskii state, monitor a stationary residual of the form

$$\begin{aligned} \mathcal G[\psi] ={}& \left[ -\frac{\hbar^2}{2m}\partial_x^2 +V(x) \right]\psi(x) \\ &+ g|\psi(x)|^2\psi(x) -\mu\psi(x), \\ r_{\mathrm{GP}} &= \left\|\mathcal G[\psi]\right\|. \end{aligned}$$

The norm, residual, energy, grid spacing, box size, and stopping criterion are distinct diagnostics. Imaginary-time energy descent alone can converge to a discretization artifact or an unintended stationary branch.

The BCS notebook must distinguish the exact finite-cutoff root from its weak-coupling approximation. It should report the integral-equation residual, guard against false convergence to the normal solution, and compare free energies when selecting the stable branch.

Quench dynamics

For a time-independent post-quench Hamiltonian,

$$|\psi(t)\rangle = e^{-iH_f t/\hbar} |\psi(0)\rangle.$$

The small-system notebook should compare direct matrix exponentiation with evolution in the eigenbasis of $H_f$. It must monitor

$$\begin{aligned} \langle\psi(t)|\psi(t)\rangle &=1, \\ \langle H_f\rangle_t &=\langle H_f\rangle_0, \end{aligned}$$

while also checking at least one nontrivial observable against the spectral decomposition. Norm conservation alone does not validate phases or observable dynamics.

Cell Order for Reviewable Notebooks

Use a predictable top-to-bottom execution order:

1. Identity cell: title, purpose, canonical links, inventory state, reproducibility status, and last run.
2. Physics cell: equations, assumptions, units, conventions, and evidence horizon.
3. Environment cell: interpreter, imported package versions, platform, and optional dependency flags.
4. Parameter cell: one visible immutable parameter record used by all later cells.
5. Implementation cells: small functions with explicit inputs and outputs.
6. Structural validation: dimensions, domains, Hermiticity, normalization, and sector closure.
7. Reference validation: analytic target or MB-Bxxx result with predeclared tolerance.
8. Refinement validation: size, cutoff, precision, time step, quadrature, or fit-window sequence.
9. Production calculation: the result the notebook exists to compute.
10. Figures and tables: generated from retained machine-readable arrays.
11. Interpretation and limits: what passed, what remains uncertain, and what is not claimed.
12. Provenance record: environment digest, implementation revision, run date, and output hashes when exported.

Validation should appear before a polished figure. A reader should not need to scroll past the conclusion to discover that a check failed.

Environment and Execution Contract

The first committed artifact should include a family-level environment recipe. Until that recipe exists, this page does not prescribe a fictitious package version.

The eventual environment must record:

• exact Python version;
• Jupyter execution tooling;
• direct numerical dependencies and versions;
• a resolved lock, explicit environment export, or equivalently reproducible recipe;
• operating-system and architecture notes when results are platform sensitive;
• optional plotting dependencies separately from validation requirements.

Prefer the smallest dependency surface that expresses the method correctly. NumPy and SciPy are natural foundations for the planned dense linear algebra, quadrature, and roots; that observation is not a license to rely on unrecorded package defaults.

Every release candidate must be executed from a fresh process or clean kernel in top-to-bottom order. A notebook that works only after an interactive session has hidden state, even if its saved outputs look correct.

Determinism and stochastic extensions

The initial catalog is mostly deterministic. If stochastic sampling is added later, record:

• pseudorandom generator and seed policy;
• warmup, sample count, binning, and autocorrelation treatment;
• independent chains or seeds;
• uncertainty estimator;
• acceptance and sign diagnostics when relevant.

One fixed seed can support regression testing, but it cannot by itself establish a statistical uncertainty.

Validation Record

Each admitted notebook should expose or generate a compact record with these fields:

Field	Required meaning
artifact	canonical notebook path
canonical_targets	pages and formulas implemented
benchmark_ids	MB-Bxxx contracts or named analytic tests
physical_parameters	couplings, temperatures, density, sizes, and boundaries
numerical_parameters	tolerances, cutoffs, fit windows, precision, and seeds
environment	interpreter and dependency record
observed	raw values used by checks
tolerances	thresholds declared before execution
test_status	pass, warning, fail, or skipped for each check
artifact_status	sitewide reproducibility label
last_run	date and implementation revision
evidence_horizon	claims that the run does not support

Do not compress several checks into one Boolean. A notebook may pass Hermiticity and fail the benchmark spectrum; the record should preserve that distinction.

Figures, Tables, and Data

An exported figure or table needs a provenance chain back to the exact notebook run that generated it:

$$\begin{gathered} \text{canonical physics page} \\ \updownarrow \\ \text{notebook revision} \\ \updownarrow \\ \text{environment and parameters} \\ \updownarrow \\ \text{validated data} \\ \downarrow \\ \text{exported asset}. \end{gathered}$$

Keep numerical arrays or compact tables separately from rendered pixels when they are needed for review. Record the broadening kernel, binning, interpolation, or smoothing used by a plot. Interactive widgets may supplement a static result, but they should not be the only way to recover the parameter values or conclusion.

Large cached intermediates should not be embedded merely to make a notebook look precomputed. If runtime is too large for routine execution, provide a smaller benchmark path and identify separately archived production data by an immutable digest.

Promotion Gates

A planned entry becomes admitted only after all applicable gates pass:

1. The canonical file exists at the indexed path.
2. A clean environment can execute all cells in order without manual intervention.
3. The opening metadata states physics, units, conventions, method, and limitations.
4. Structural tests pass.
5. At least one analytic or MB-Bxxx target passes at a predeclared tolerance.
6. A numerical refinement or independent implementation check is present.
7. Figures and tables are regenerated from the same run as their reported data.
8. The environment and provenance record are complete.
9. A sitewide reproducibility status has been assigned conservatively.
10. Any page using the output links back to the artifact and states the relevant approximation.

An artifact that fails a gate can remain useful for development. It simply remains outside the admitted evidence set.

Maintenance Triggers

Rerun the affected notebooks when:

• the environment or a direct dependency changes;
• a canonical Hamiltonian, operator convention, or benchmark value changes;
• an implementation function is modified;
• a figure, table, or data export changes;
• the supported parameter range is broadened;
• a validation tolerance is reconsidered;
• a platform-specific discrepancy is reported.

A text-only correction to an unrelated page does not require every notebook to rerun. Maintenance should follow dependency and evidence links, not ritual.

Common Mistakes

Treating saved output as a successful run

Saved cells can survive after imports, files, or APIs break. Reproducibility requires clean execution, not merely visible output.

Hiding state in cell order

If execution depends on running cell 17 before cell 6, the notebook is not a linear computational record. Move shared state into explicit parameters and functions.

Letting package defaults define the physics

Matrix ordering, Fourier signs, sparse-solver selection, broadening, interpolation, and optimizer stopping criteria must be stated. A package version alone does not document these choices.

Validating only the solver

A small eigensolver residual does not prove that the Hamiltonian matrix is correct. Use dimensions, symmetries, moments, limiting cases, and the relevant benchmark contract.

Mixing finite and thermodynamic claims

A notebook may exactly solve one finite cluster. Its title, captions, and conclusion must not silently promote that result to a bulk phase statement.

Updating stored answers without diagnosis

When a regression target changes, first determine whether the cause is a bug fix, convention change, dependency drift, nondeterminism, or a wrong reference. Record the decision.

Listing a planned artifact as available

A reserved filename is useful project structure, but it is not a download and should not be linked as though it exists.

Exercises

Exercise 1: Hidden state

A notebook succeeds in an author’s long-running kernel but fails after “restart and run all” because a variable was created during an earlier experiment. Which gate failed, and what is the appropriate status?

Solution

The clean-execution gate failed. The variable is hidden state, so saved output does not establish reproducibility. If the artifact was a candidate, it remains unadmitted until the dependency is made explicit. If an admitted notebook begins failing this way, its reproducibility status should move to broken until repaired and rerun.

Exercise 2: Two solvers, one matrix

The Hubbard-dimer notebook obtains the same eigenvalues from two eigensolver libraries. Does this independently validate the fermionic signs in the Hamiltonian? Give a stronger check.

Solution

No. Both solvers consume the same assembled matrix, so agreement tests diagonalization but not the matrix elements. A stronger check compares the six-state spectrum with MB-B003, verifies triplet degeneracy and the Feynman–Hellmann double occupancy, or constructs the Hamiltonian independently from a second Fock-sign representation.

Exercise 3: Approximation versus numerical error

An ideal-Fermi-gas notebook at $T/T_F=0.1$ disagrees with the quadratic Sommerfeld expansion by much more than its quadrature residual. Why is tightening the quadrature tolerance not necessarily the right response?

Solution

The displayed Sommerfeld formula omits higher powers of $T/T_F$. Once quadrature and root residuals are below that truncation scale, tighter numerical tolerance cannot remove the analytic approximation error. The notebook should use a decreasing temperature sequence and verify convergence of scaled coefficients toward their asymptotic values.

Exercise 4: Figure provenance

A spectral plot was exported from a notebook, but the line broadening was later changed and only the image file was committed. What evidence is missing?

Solution

The exported asset is no longer tied to a reproducible parameter record. The notebook revision, exact broadening kernel and width, validated unbroadened line data, environment, run date, and regenerated figure should be committed or otherwise identified together. The old image should not be treated as current evidence.

Exercise 5: Planned versus conceptual

Why should a reserved filename with no file not be labeled conceptual_only?

Solution

conceptual_only is a reproducibility status for an existing explanatory artifact that intentionally makes no numerical evidence claim. A reserved filename is only an inventory plan. Calling it conceptual would imply that a reviewable artifact exists when it does not.

References

1. J. M. Perkel, “Why Jupyter is data scientists’ computational notebook of choice,” Nature 563, 145–146 (2018).
2. A. Rule et al., “Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks,” PLOS Computational Biology 15, e1007007 (2019).
3. G. K. Sandve, A. Nekrutenko, J. Taylor, and E. Hovig, “Ten simple rules for reproducible computational research,” PLOS Computational Biology 9, e1003285 (2013).
4. G. Wilson et al., “Good enough practices in scientific computing,” PLOS Computational Biology 13, e1005510 (2017).
5. T. Kluyver et al., “Jupyter Notebooks: a publishing format for reproducible computational workflows,” in Positioning and Power in Academic Publishing, 87–90 (2016).
6. C. R. Harris et al., “Array programming with NumPy,” Nature 585, 357–362 (2020).
7. P. Virtanen et al., “SciPy 1.0: fundamental algorithms for scientific computing in Python,” Nature Methods 17, 261–272 (2020).
8. The Turing Way Community, The Turing Way: A Handbook for Reproducible, Ethical and Collaborative Data Science.
9. Project Jupyter, Jupyter documentation.

Further Study

• How to Use Computational Notebooks for the reader-facing audit workflow.
• Notebook Index for the sitewide inventory contract.
• Environments for dependency and platform records.
• Reproducibility Status for artifact labels and transitions.
• Validation Tests for executable test families.
• Code Style for reviewable notebook structure.
• Benchmark Problems for the nine stable many-body physics contracts.
• Computational Many-Body Overview for method selection and evidence horizons.
• Dynamical Correlation Functions Numerically for matched-resolution spectral validation.