Skip to content
Quantum Mechanics

Code Style

Code style for computational quantum mechanics is not cosmetic. It is how a reader sees the Hamiltonian, units, method, approximation, and validation. A short, explicit notebook is more valuable than a clever notebook whose assumptions are hidden in helper functions.

Notebook Structure

Section titled “Notebook Structure”

Use a predictable structure:

  1. purpose and canonical page,
  2. imports and environment record,
  3. parameters and units,
  4. model construction,
  5. numerical method,
  6. validation checks,
  7. plots or tables,
  8. limitations and next steps.

Keep exploratory cells out of reference notebooks. If exploratory work is useful, archive it separately or convert it into a clean narrative.

Physics Naming

Section titled “Physics Naming”

Prefer variable names that preserve the physics:

  • hbar, mass, omega, dx, dt,
  • hamiltonian, psi, rho, energy,
  • x_grid, k_grid, basis_size,
  • norm_error, trace_error, unitarity_error.

Avoid unexplained names such as foo, tmp, magic, or result2 in reviewed notebooks.

Units and Parameters

Section titled “Units and Parameters”

State whether the calculation uses SI, atomic units, natural units, or dimensionless units. If dimensionless variables are used, state the scale used to nondimensionalize length, energy, and time.

Do not bury physical constants in code. Put them in a parameter cell and cite the relevant convention page when needed.

Validation Cells

Section titled “Validation Cells”

Validation should be executable and close to the computation. A validation cell should:

  • compute the benchmark quantity,
  • compare it to the reference result,
  • state the tolerance,
  • fail visibly when the comparison fails,
  • print or store a compact diagnostic.

Do not validate only by eye. A plot can support a benchmark, but it cannot replace the numerical check.

Figures

Section titled “Figures”

Generated figures should include:

  • labeled axes,
  • units or dimensionless variables,
  • parameter values,
  • legend or direct labels when multiple curves appear,
  • a caption explaining the plotted quantity,
  • source notebook or script path,
  • validation status.

Avoid exporting large generated figures unless the page uses them. Regenerate rather than hand-edit notebook output.

Hidden State

Section titled “Hidden State”

Reference notebooks should run from a clean kernel. Avoid relying on:

  • cells executed out of order,
  • hidden global variables,
  • local files outside the repository,
  • network downloads during ordinary execution,
  • machine-specific paths,
  • mutable defaults or stateful helper objects without explanation.

If a notebook needs optional data or a long runtime, make that explicit before the computation starts.

Review Checklist

Section titled “Review Checklist”

Before accepting a notebook or script:

  • Does it run from a clean environment?
  • Does it name the canonical page and formula target?
  • Are units and conventions stated?
  • Are package versions recorded?
  • Is there at least one benchmark check?
  • Are tolerances justified?
  • Are stochastic errors reported when relevant?
  • Are figures generated from tracked source?
  • Is the result status recorded?
Section titled “Cross-Links”

References

Section titled “References”