Computational Notebooks

A numerical result becomes scientific evidence only after its conventions, approximations, discretization, convergence, and independent checks are visible. The notebooks in this chapter are designed as reproducible validation laboratories, not as screenshots of code that happened to run once.

Each notebook starts from a physical question, identifies an analytic target or controlled limit, constructs a dimensionless numerical problem, varies every relevant numerical cutoff, and records enough metadata for another reader to repeat the calculation. The goal is not merely agreement. It is to understand why two methods agree, which error dominates, and where the comparison stops being meaningful.

What Belongs Here

A computational notebook belongs in this chapter when computation is essential to the scientific argument. Typical roles include:

• testing an asymptotic approximation against a converged numerical solution;
• optimizing a variational family and mapping its energy landscape;
• extracting an observable, such as a phase shift, from a numerical wavefunction;
• comparing exact and truncated propagators;
• resolving parameter dependence that is cumbersome analytically;
• exposing numerical instability, cutoff dependence, or branch ambiguity.

A notebook is not the canonical home of a general theorem or reusable derivation. Those belong on the relevant method page. A model calculation with a short analytic benchmark belongs in Worked Problems and Model Calculations. This chapter owns the numerical protocol, convergence evidence, and reproducibility record.

Canonical Boundaries

Scientific object	Canonical home	Notebook role
Perturbative coefficients	Perturbation-theory pages	compare truncated series with converged spectra
Variational upper-bound theorem	Variational-method pages	optimize a chosen family and verify the bound numerically
WKB connection formulas	Semiclassical pages	compare quantized actions with numerical eigenvalues
Scattering phase definition	Scattering-theory pages	extract continuous phases from radial solutions
Exact model derivation	Worked problem or canonical-system page	provide a benchmark with known answer
Numerical algorithm	Mathematical Toolkit	specialize, test, and document its use in one physical problem

Cross-linking preserves one canonical explanation while allowing many independent tests.

Notebook Contract

Every mature notebook page should make the following items explicit.

1. Physical problem

State the Hamiltonian, initial or boundary conditions, observable, and parameter regime. Name the reduced mass, unit convention, symmetry sector, and basis convention whenever they affect the answer.

2. Analytic target

Identify what the computation is meant to test. A useful target may be:

• an exact solution;
• a perturbative coefficient;
• an asymptotic scaling law;
• a variational inequality;
• a conservation law;
• a threshold or unitarity limit;
• agreement between two independent formulations.

Without a target, numerical output is exploration rather than validation.

3. Dimensionless formulation

Choose characteristic length, energy, and time scales before discretizing. For example,

$$r=L_0\widetilde r, \qquad E=E_0\widetilde E, \qquad t=T_0\widetilde t.$$

Then write the calculation in terms of dimensionless parameters. This reduces unit errors, improves conditioning, and makes parameter sweeps reusable across physical systems.

4. Numerical representation

Record the basis or grid, domain, boundary treatment, matrix structure, solver, precision, and stopping criteria. A phrase such as “solved numerically” is not enough to reproduce a result.

5. Convergence axes

Vary every independent numerical control that can bias the observable. Depending on the problem, these include:

• basis dimension $N$;
• grid spacing $h$;
• box size $L$;
• time step $\Delta t$;
• radial matching point;
• angular-momentum cutoff $\ell_{\max}$;
• quadrature order;
• iterative-solver tolerance;
• floating-point precision;
• sampling count and random seed.

Changing only one control while freezing another unconverged control can create a false plateau.

6. Independent checks

Use at least two logically different checks when practical. Agreement between two implementations of the same formula is weaker than agreement with a symmetry, exact limit, variational bound, or separately derived identity.

7. Failure modes

Document where the algorithm becomes unstable, inaccurate, or conceptually inapplicable. A trustworthy notebook should help the reader recognize a bad result, not only reproduce the good one.

8. Reproducibility metadata

Record software versions, algorithm choices, tolerances, parameter files, seeds, data transformations, and figure-generation settings. Include a license for downloadable code and data.

Separating Physical and Numerical Error

Suppose $Q$ is the observable and $Q_{mathrm{app}}$ is an analytic approximation. A numerical benchmark $Q_{mathrm{num}}$ has at least two conceptually distinct discrepancies:

$$\begin{aligned} \Delta_{\mathrm{physics}} &= Q_{mathrm{app}}-Q_{\mathrm{exact}}, \\ \Delta_{\mathrm{numerics}} &= Q_{mathrm{num}}-Q_{mathrm{exact}}. \end{aligned}$$

The exact answer is usually unknown. The practical task is therefore to bound numerical error well below the approximation error being measured. Otherwise the benchmark cannot tell whether the analytic method or the computation is responsible for the discrepancy.

For several numerical controls, think schematically in terms of

$$\begin{aligned} Q(h,N,L,\tau) &= Q_* + \Delta_h + \Delta_N \\ &\quad + \Delta_L + \Delta_\tau + \cdots, \end{aligned}$$

where $h$ is a grid spacing, $N$ a basis cutoff, $L$ a finite domain, and $\tau$ a solver tolerance. The terms need not be independent, so convergence should also be checked under simultaneous refinement.

Convergence Evidence

Successive-refinement change

For a sequence $Q_n$, a scale-aware change is

$$\Delta_n = \frac{ |Q_{n+1}-Q_n| }{ \max(Q_{\mathrm{scale}},|Q_{n+1}|) }.$$

The reference scale $Q_{\mathrm{scale}}$ prevents a meaningless relative error when the exact observable crosses zero.

Observed order

If a discretization is expected to have error $Ch^p$ and the refinement ratio is $r$, estimate

$$p_{\mathrm{obs}} = \frac{ \log \left| \dfrac{Q_h-Q_{h/r}} {Q_{h/r}-Q_{h/r^2}} \right| }{ \log r }.$$

Agreement with the expected order is stronger evidence than a small difference at one resolution. Failure to reach the asymptotic order may indicate boundary error, roundoff, an unresolved singularity, or an insufficiently fine grid.

Residuals

For a computed eigenpair $(E,\psi)$, use a normalized residual such as

$$\rho_E = \frac{ \|H\psi-E\psi\| }{ \max \left( E_{\mathrm{scale}}\|\psi\|, \|H\psi\| \right) }.$$

A small residual shows that the represented eigenproblem is solved accurately. It does not prove that the basis, domain, or Hamiltonian model is adequate.

Conservation and structure

Useful structural diagnostics include

$$\begin{aligned} \epsilon_{\mathrm{norm}} &= \left| \langle\psi|\psi\rangle-1 \right|, \\ \epsilon_U &= \|U^\dagger U-I\|, \\ \epsilon_{\mathrm{flux}} &= |J_{\mathrm{in}}-J_{\mathrm{out}}|. \end{aligned}$$

Hermiticity, positivity, parity blocks, probability conservation, and scattering unitarity often catch errors before a high-precision comparison does.

Independent Benchmark Hierarchy

Use checks from different levels.

1. Structural checks: dimensions, normalization, Hermiticity, symmetry, and conservation.
2. Exact limits: vanishing coupling, solvable potentials, short-time behavior, or threshold laws.
3. Convergence checks: refinement in all cutoffs and tolerances.
4. Alternative formulations: basis diagonalization versus shooting, time propagation versus spectral decomposition, or direct matching versus an $S$-matrix identity.
5. External benchmarks: published high-precision values or community reference data with compatible conventions.

Several weakly independent checks are better than many versions of the same calculation.

Current Notebooks

Perturbation theory benchmarks

Perturbation Theory Benchmarks compares the quartic-oscillator series with truncated matrix diagonalization. It separates asymptotic truncation error from basis truncation and checks parity, weak-coupling coefficients, and eigenvalue convergence.

Use it when learning how an analytic approximation can fail even while the numerical reference remains stable.

Variational optimization

Variational Optimization Notebook globally optimizes a frequency-scaled Rayleigh-Ritz basis for the quartic oscillator. It maps the multi-basin energy landscape, verifies the upper-bound and virial conditions, and shows how nonlinear scale optimization accelerates finite-basis convergence.

Use it when an ansatz contains nonlinear widths or exponents and a local optimizer’s success flag is not enough evidence of a global minimum.

WKB versus exact spectrum

WKB Versus Exact Spectrum compares Bohr–Sommerfeld quantization with numerical spectra for a quadratic-plus-quartic well. It tests action integrals, turning-point handling, harmonic limits, and the improvement of WKB at higher quantum number.

Use it when studying asymptotic accuracy rather than a coupling expansion.

Wave-packet scattering

Wave-Packet Scattering Notebook propagates a Gaussian packet through an exactly solvable rectangular barrier. It separates physical bandwidth averaging from grid, time-step, box-size, boundary, and finite-separation errors while checking the late-time transmitted norm against the exact packet spectrum.

Use it when a unitary time-dependent simulation looks correct but the observable still needs quantitative convergence evidence.

Phase-shift extraction

Phase Shift Extraction solves a radial scattering problem and matches the numerical logarithmic derivative to Riccati–Bessel functions. It emphasizes phase-branch continuity, matching-radius stability, partial-wave convergence, and validation against exact square-well and hard-sphere results.

Use it when the desired observable is not a direct eigenvalue of the discretized operator.

Born-approximation numerical test

Born Approximation Numerical Test compares the analytic first Born cross section for a repulsive Gaussian potential with a converged Numerov and partial-wave calculation. It maps coupling and momentum, checks the weak-coupling scaling and elastic optical theorem, and separates radial-grid, matching-radius, and angular-momentum errors from the physical Born discrepancy.

Use it when a smooth Fourier-transform answer looks plausible but needs an observable-level validity boundary backed by numerical convergence.

Landau–Zener simulation

Landau–Zener Simulation propagates a swept two-level state with fourth-order Magnus, exponential midpoint, and RK4 methods. It separates finite-window error from time-step error, audits exact adiabatic versus bare diabatic endpoint protocols, and compares probability convergence with phase-sensitive state convergence and norm drift.

Use it when a driven transition formula must be tested without confusing a converged integrator, an asymptotic boundary condition, and a basis convention.

Double-well instanton check

Double-Well Instanton Numerical Check compares parity-resolved quartic-double-well splittings with finite-energy WKB and one-loop instanton estimates. It tracks the gap over nearly eight orders of magnitude, varies oscillator basis size and scale, and validates representative points with an independent finite-difference Sturm calculation.

Use it when agreement of a tunneling exponent is not enough and the prefactor, subtraction error, parity resolution, and floating-point floor must be audited separately.

Magnus-expansion error

Magnus Expansion Error compares the exact propagator of a noncommuting two-step drive with cumulative Magnus generators through fourth degree. It verifies weak-drive order and exact unitarity, reverses the pulse order, distinguishes a sufficient convergence bound from fixed-order accuracy, follows errors for 200 periods, and reconstructs several equivalent effective-Hamiltonian branches.

Use it when a unitary effective propagator still needs quantitative truncation, long-time, and logarithm-branch checks.

Reproducibility checklist

Reproducibility Checklist turns the notebook contract into an ordered release audit. It connects a scientific claim to its model, numerical controls, environment, inputs, validation tests, retained outputs, figure sources, provenance, and licenses, then gives a clean-room reviewer protocol and machine-readable manifest example.

Use it before promoting any notebook, script, table, or generated figure from exploratory output to evidence.

Choosing a Notebook

Goal	Notebook	Strongest check
Separate perturbative and basis errors	Perturbation Theory Benchmarks	converged diagonalization and weak-coupling coefficients
Test a semiclassical spectrum	WKB Versus Exact Spectrum	harmonic limit and high-$n$ convergence
Extract central-potential observables	Phase Shift Extraction	exact matching, flux, and branch continuity
Optimize a trial family	Variational Optimization Notebook	upper bound, global basin, and virial stationarity
Test real-time scattering	Wave-Packet Scattering Notebook	exact packet-spectrum average and asymptotic separation
Map the Born regime	Born Approximation Numerical Test	converged phase shifts, weak-coupling scaling, and unitarity
Test a driven transition formula	Landau–Zener Simulation	window, basis, state, and norm convergence
Resolve an exponentially small splitting	Double-Well Instanton Numerical Check	parity blocks, basis plateau, and independent finite differences
Audit a driven effective Hamiltonian	Magnus Expansion Error	weak-drive order, unitarity, branches, and stroboscopic error
Prepare a computation for release	Reproducibility Checklist	clean reconstruction, independent validation, and artifact trace

Reproducibility Record

For every published run, retain the following information.

Physics specification

• Hamiltonian or evolution equation;
• units and dimensionless variables;
• initial and boundary conditions;
• symmetry sector;
• parameter values and sweep ranges;
• observable definitions and normalization conventions.

Numerical specification

• basis, grid, or mesh;
• domain and boundary treatment;
• solver and algorithm version;
• tolerances and precision;
• quadrature and interpolation methods;
• random-number generator and seed;
• refinement schedule and stopping rule.

Artifact provenance

• source revision;
• software environment and dependency versions;
• raw data before plotting or filtering;
• transformation steps;
• figure-generation parameters;
• machine-readable tables for quoted values;
• code and data license.

The record should distinguish parameters chosen before inspecting the result from choices adjusted afterward. This matters whenever a fit window, smoothing scale, cutoff, or model family can bias the conclusion.

Common Failure Modes

• Showing one resolution and calling it converged.
• Comparing an approximation with a numerical result whose error is of the same size.
• Using relative error near a zero without a reference scale.
• Reporting a small algebraic residual while ignoring basis or domain truncation.
• Changing several controls at once and losing the observed convergence order.
• Selecting a favorable parameter or fit window after inspecting the answer without reporting that choice.
• Hiding phase, gauge, branch, normalization, or Fourier-transform conventions.
• Treating visual agreement of curves as a quantitative error estimate.
• Reusing cached data after changing the Hamiltonian or unit convention.
• Publishing only a notebook interface without stable source, data, and environment metadata.
• Omitting known instability regions because the preferred parameter set happens to avoid them.

Readiness Levels

Exploratory: the calculation runs and reveals qualitative behavior, but convergence and provenance are incomplete.

Verified: numerical controls are varied, residuals and structural checks pass, and at least one independent benchmark agrees.

Reference-grade: conventions, data, code, metadata, failure modes, and uncertainty accounting are complete enough for another researcher to reproduce quoted values.

Research claim: in addition to reference-grade computation, the physical model, inferential assumptions, external data, and comparison with prior literature have been critically assessed. A notebook alone does not supply that broader validation.

Cross-Links

• Volume Overview
• Choosing a Method
• Small Parameters and Error Estimates
• Worked Problems and Model Calculations
• Numerical Mathematics
• Error-Estimate Checklist
• Method Comparison Table
• Perturbation Theory Benchmarks
• Variational Optimization Notebook
• WKB Versus Exact Spectrum
• Wave-Packet Scattering Notebook
• Phase Shift Extraction
• Born Approximation Numerical Test
• Landau–Zener Simulation
• Double-Well Instanton Numerical Check
• Magnus Expansion Error
• Reproducibility Checklist

References

• G. Wilson et al., “Good Enough Practices in Scientific Computing,” PLOS Computational Biology 13, e1005510 (2017), doi:10.1371/journal.pcbi.1005510.
• G. K. Sandve, A. Nekrutenko, J. Taylor, and E. Hovig, “Ten Simple Rules for Reproducible Computational Research,” PLOS Computational Biology 9, e1003285 (2013), doi:10.1371/journal.pcbi.1003285.
• M. D. Wilkinson et al., “The FAIR Guiding Principles for Scientific Data Management and Stewardship,” Scientific Data 3, 160018 (2016), doi:10.1038/sdata.2016.18.
• National Academies of Sciences, Engineering, and Medicine, Reproducibility and Replicability in Science, National Academies Press, 2019, doi:10.17226/25303.
• N. J. Higham, Accuracy and Stability of Numerical Algorithms, 2nd ed., SIAM, 2002.
• G. H. Golub and C. F. Van Loan, Matrix Computations, 4th ed., Johns Hopkins University Press, 2013.
• E. Hairer, S. P. Nørsett, and G. Wanner, Solving Ordinary Differential Equations I: Nonstiff Problems, 2nd rev. ed., Springer, 1993.
• J. M. Thijssen, Computational Physics, 2nd ed., Cambridge University Press, 2007.