Document probability-weighted ensemble reduction (abTEM#466)

[TomaSusi]

Docs for abTEM#466, which applies distribution weights as probabilities when an ensemble is reduced. abTEM#466 is now merged (f14de11e). The notebooks were executed against its branch (e3d0d47b) and checked again against the merged dev: ensembles and partial_coherence give identical outputs there. hrtem_quickstart uses unseeded frozen phonons and Poisson noise, so its figures differ from run to run on any version.

Changes

• Changelog: a Bugfixes entry explaining how the old behaviour was wrong and what changed. STEM defocus distributions were effectively a top-hat, HRTEM spreads were too narrow by √2, and tilt, energy and aperture weights were ignored. It gives the size of the STEM change and the change to .weights.
• tutorials/partial_coherence.ipynb:
  • The defocus ensembles are reduced with reduce_ensemble(). They used .sum(0)/.mean(0), which now ignore the weights, and the .mean(0) was already a top-hat average before #466.
  • The text describes the ensemble members as unweighted images whose weights are applied at reduction.
  • The probe equations put p outside the norm (it was ‖p M[ψ]‖², which squares the weight), and the Riemann sum is normalized by the weights.
  • Also fixed: the Gaussian was missing its minus sign, and the text gave σ = 52.5 Å with truncation 78.75 Å, while the code uses σ = δ/√2 = 37.12 Å and 55.68 Å.
• appendix/ensembles.ipynb: explains that weights are probabilities, and that reduce_ensemble(axis=...) applies them to a kept axis while a plain .sum()/.mean() does not. The printed weights now sum to one.
• examples/notebooks/hrtem_quickstart.ipynb: an older bug, not caused by #466. It passed the standard deviation of the defocus spread as focal_spread, which expects the 1/e width √2·σ, so its envelope was too narrow. Its Cc comment also said 1.2 mm while the code uses 1.0 mm. The thumbnail is regenerated by the notebook.

Checks

• All three notebooks execute without errors or warnings. scripts/check_notebook_widgets.py passes, and only the recorded Python version changed in the notebook metadata.
• The partial-coherence conclusions still hold after re-execution. The quasi-coherent and incoherent images are qualitatively similar, and spatial coherence still dominates in STEM.

Not included

tutorials/time_resolved.ipynb has the same focal_spread σ-vs-1/e mistake as hrtem_quickstart, but it imports ase.md.velocitydistribution.thermalize_momenta, which no locally installed ASE (up to 3.27) provides, so it could not be re-executed here. It will follow separately.

🤖 Generated with Claude Code