How to Use Computational Notebooks

Computational notebooks are arguments with executable parts. They should not be treated as screenshots of answers or as black boxes that become true because a plot appeared.

A useful notebook states the model, units, algorithm, parameters, convergence checks, benchmark cases, and interpretation of the output.

What a Notebook Should Tell You

Before trusting a notebook, identify:

• the physical system;
• the Hamiltonian or evolution equation;
• the units and dimensionless variables;
• the basis, grid, or discretization;
• boundary conditions;
• input parameters;
• numerical method;
• convergence or stability checks;
• benchmark comparison;
• expected output and failure modes.

If the notebook does not make these visible, treat it as exploratory rather than authoritative.

Read the Model Before the Code

Start with the model statement. Ask:

• What continuum problem is being approximated?
• What Hilbert space or finite-dimensional truncation is being used?
• Which physical effects are included or omitted?
• Which parameter range is being explored?
• What would count as a correct limiting case?

For example, a finite-difference bound-state calculation should say the interval, boundary conditions, potential, grid spacing, Hamiltonian matrix, and normalization convention.

Check Units and Scaling

Many quantum notebooks use dimensionless variables. That is good practice when declared clearly. It is dangerous when hidden.

Always ask:

• Are $\hbar$, mass, length, and energy scales explicit or scaled away?
• How are dimensionless variables converted back to physical units?
• Does the output have the expected units?
• Are plotted axes labeled with units or dimensionless quantities?

If a result changes under a unit conversion that should be harmless, the notebook has a modeling or scaling problem.

Check Convergence

A numerical answer should not depend strongly on arbitrary numerical choices. Check convergence with respect to:

• grid spacing;
• box size;
• basis size;
• time step;
• truncation cutoff;
• random sample count;
• solver tolerance.

Use Convergence Tests and Benchmark Problems as the numerical-method starting points.

Compare Against a Benchmark

Every notebook should have at least one sanity benchmark:

Notebook type	Useful benchmark
Bound-state diagonalization	harmonic oscillator or infinite square well spectrum
Time evolution	norm conservation for closed-system unitary evolution
WKB approximation	comparison with exact spectra where available
Scattering	known phase shift, unitarity, or low-energy limit
Monte Carlo	analytic integral or reproducible seed test
Matrix exponential	comparison with diagonalization for a small matrix

For examples of notebook-style pages, see WKB Versus Exact Spectrum and Phase Shift Extraction.

Distinguish Exploration from Evidence

Notebooks can serve different roles:

• exploratory visualization;
• homework support;
• benchmark reproduction;
• numerical experiment;
• figure generation;
• research calculation.

The evidential standard should match the role. An exploratory plot can be useful without proving a claim. A benchmark notebook should be reproducible and should state expected numerical values. A research calculation needs stronger validation and uncertainty estimates.

Read Plots Skeptically

A plot is not a result until you know:

• what is being plotted;
• what units are used;
• how data were generated;
• whether resolution or sampling changes the image;
• whether normalization is preserved;
• whether omitted data ranges hide failures;
• what analytic or numerical benchmark supports it.

Plots should clarify structure, not substitute for the model.

When You Modify a Notebook

Change one thing at a time:

1. Save the original parameter set in your notes.
2. Change one parameter or numerical resolution.
3. Record what changed in the output.
4. Check whether the change is physical or numerical.
5. Repeat with a convergence or limiting-case test.

If several changes are made at once, it becomes difficult to tell whether the observed effect is physics, numerics, or a mistake.

Common Mistakes

• Trusting a plot without checking the model.
• Confusing dimensionless variables with physical units.
• Using too small a box or basis and mistaking truncation error for physics.
• Forgetting boundary conditions.
• Changing parameters without rerunning convergence tests.
• Comparing numerical results to a formula with different conventions.
• Treating exploratory notebooks as reviewed calculations.

References

• W. H. Press, S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery, Numerical Recipes, 3rd ed., Cambridge University Press, 2007.
• L. N. Trefethen, Spectral Methods in MATLAB, SIAM, 2000.
• J. M. Thijssen, Computational Physics, 2nd ed., Cambridge University Press, 2007.
• M. Hjorth-Jensen, Computational Physics, lecture notes and open materials.

Exercises

1. A notebook computes energy eigenvalues on a finite grid. Name three convergence checks.

Solution

Check convergence as the grid spacing decreases, as the box size increases, and as the solver tolerance changes. Depending on the method, also check boundary-condition sensitivity or basis-size convergence.

2. A plot of a wave packet looks smooth. Why is that not enough to trust the simulation?

Solution

Smoothness does not show that the model, units, boundary conditions, time step, normalization, or convergence are correct. The simulation should be checked against norm conservation, limiting cases, resolution changes, and any available analytic benchmark.