Bloch waves: changelog and notebooks for abTEM#447, #448 and #521

[TomaSusi]

Changelog entries for abTEM#447, abTEM#448 and abTEM#521. All three are merged into dev (6ec0bed7, 08ee6e8c and 98bbae60), so this is ready to merge.

Changes

docs/abtem/changelog.md (Upcoming 1.1.0):

• Features, under energy ensembles (#257): Bloch-wave rotation ensembles accept a list of energies (#521). Results get an EnergyAxis after the rotation axes, the axis order of a multislice rotation series, and each energy and orientation keeps its own beams.

• Features: BlochWaves now defaults to use_wave_eq="exact", the non-paraxial counterpart of FourierMultislice(order="exact"). The entry calls out that results computed with default arguments change, with the sizes measured in #448: below 1 % R at 100–300 keV, but up to 24 % at 20 keV off zone axis. It also covers:

  • the kinematical-pattern weighting, which now follows the selected form
  • evanescent beams, which are excluded with a warning
  • the new calculate_scattering_matrix(lazy=True) option and the GPU fix

• Bugfixes: the inconsistent Bloch-wave metric:

  • the two solution paths disagreed off zone axis
  • the wave-equation forms carried a metric that does not belong to them
  • use_wave_eq=False now solves the textbook equation exactly, which moves it away from the full Helmholtz equation. The entry explains why, so the change is not mistaken for a regression in accuracy.

• tutorials/blochwave.ipynb, re-executed against abTEM dev 08ee6e8c (≈ 59 min on CPU, no errors, no new warnings):

  • The structure-matrix dropdown described the old formulation, which was the bug: diagonal $2k_0 s_g/\sqrt{1+g_z/k_0}$ and the metric $\mathbf{M}$ applied to every form. It now gives the default use_wave_eq="exact" form (no metric), the paraxial True form, and the standard False form with $M^2$ on the diagonal. It also notes that evanescent beams are excluded.
  • Bloch waves vs multislice: the very weak [-21 1 -1] reflection used to differ from multislice by up to ~2×, which the text blamed on an unconverged Bloch-wave calculation. It was the metric bug: the curves now coincide. The text now says both solve the same non-paraxial equation by default.
  • The excitation-error paragraph said the Ewald sphere is "approximated as a parabola"; $-g_z - g^2/2k_0$ is the Ewald sphere itself (to first order in $s_g/k_0$). This error predates #447/#448.
  • The other outputs move by ~0.1–1 % (e.g. the thickness curves), as expected from the new default. Several figures changed layout from earlier plotting fixes, with colorbars now spanning all rows.

• examples/notebooks/blochwave_quickstart.ipynb (and its thumbnail), re-executed against abTEM dev b634b93a (≈ 8 min, no errors). The printed outputs are unchanged at the displayed precision. The kinematical panel changes slightly, because its excitation-error weighting now follows the default form. The thumbnail is pixel-identical. The text needed no changes.

• walkthrough/wave_functions.ipynb, re-executed against the same dev. It mentions BlochWaves only in its text, so its output changes come from other dev changes: a renamed dask task in two array reprs, and plot layout. One sentence said every BlochWaves method accepts an energy ensemble. calculate_structure_matrix and calculate_scattering_matrix require a single energy (since abTEM#456), so it now says so and points to select_energy.

• scripts/check_notebook_widgets.py passes for all three notebooks.

🤖 Posted by Claude Code on behalf of Toma