Use the frozen-phonon component names of abTEM #484

[TomaSusi]

Updates the documentation for abTEM#484, which settled the names of the frozen-phonon components and added elastic_diffuse_diffraction_patterns.

Phonon-loss tutorial

docs/user_guide/tutorials/phonon_loss.ipynb:

• component="all" and component="tds" become components="all" and the default "diffuse". The prose and equations use total, elastic and diffuse in place of incoherent, coherent and TDS.
• "all" is described in its new order: total, elastic, diffuse.
• It mentions elastic_diffuse_diffraction_patterns, which forms the same decomposition without an energy axis.
• The warning on few configurations now mentions unbiased=True and reduction_dtype="float64".
• The notebook is re-executed against abTEM dev at 2b764f5c, the merge of #484, so the stored figures carry the new component labels. It runs in about 70 s on CPU, with no errors or warnings.

Changelog

docs/abtem/changelog.md, under 1.1.0:

• Feature: elastic_diffuse_diffraction_patterns, and the renamed components of phonon_loss_diffraction_patterns. The phonon-loss functions are not in a release yet, so the rename is listed with the feature rather than as a breaking change.
• Bug fix: block_direct=True in Waves.diffraction_patterns blocked a fixed 1 mrad radius. It now blocks the probe's bright-field disk plus a margin, or the zero-frequency pixel for a plane wave.
• Bug fix: lazy diffraction patterns of complex128 waves now keep float64 precision.

Not changed

frozen_phonons.ipynb (walkthrough) and charge_density.ipynb call diffraction_patterns(block_direct=True) on plane waves. With #484 that blocks only the zero-frequency pixel, where it used to block 1 mrad. Their code needs no change, but their stored figures predate the change until the notebooks are next re-run. charge_density.ipynb needs GPAW to re-run.

🤖 Generated with Claude Code

[pzeiger]

Checked against dev @ 2b764f5c: every name the notebook and the changelog use exists there (components=, the default "diffuse", "all" as total, elastic, diffuse, unbiased, reduction_dtype, frozen_phonon_component, abtem.elastic_diffuse_diffraction_patterns and the Waves method). A few sentences still use the old wording or claim more than the arithmetic gives:

1. Notebook, two sentences still say "TDS decomposition":

   • "…so the TDS decomposition can be applied bin by bin." (introduction of EnergyResolvedAtomsEnsemble)
   • "We set ensemble_mean=False, since the TDS decomposition needs the individual configurations rather than their average."

   "the decomposition into total, elastic and diffuse intensity" would match the new names.

2. Notebook, zero-energy bin: "its diffuse intensity must vanish exactly" and "the total and elastic intensities agree exactly and the diffuse intensity is zero". In float32 the diffuse part of identical configurations is zero only up to rounding; the docstring of elastic_diffuse_diffraction_patterns gives about −2.9e-7 of the maximum total. "vanishes up to float32 rounding" and "agree up to float32 rounding" in both places would avoid a reader taking a −1e-7 pixel for a bug.

3. Changelog, Documentation entry: "New tutorial on phonon-loss spectroscopy: energy-resolved frozen phonons, the TDS decomposition, …" could read "the total, elastic and diffuse decomposition".

4. Changelog, the new #484 bullet could also name the two checks that PR added: phonon_loss_diffraction_patterns refuses a bool, negative or non-finite temperature (zero puts the whole signal on the loss side), and momentum_resolved_spectrum raises a ValueError when given the total or elastic component, which contain the Bragg intensity, and picks the diffuse component out of a stacked "all" result. Optional: the exact block_direct=True rule (radius semiangle_cutoff + max(angular_sampling) for a finite cutoff above half the smaller sampling, otherwise only the zero-angle pixel; NaN or negative cutoffs raise), and that a tuple such as components=("diffuse", "elastic") stacks in the order given.

🤖 Written and posted by Claude Code on Paul's behalf

[TomaSusi]

Thanks, all four are done in 423b8f9:

1. Both "TDS decomposition" sentences now say "the decomposition into total, elastic and diffuse intensity".
2. The zero-energy bin now vanishes "up to floating-point rounding", in both places.
3. The changelog's tutorial entry uses the same wording.
4. The #484 entry now covers the temperature validation (with zero on the loss side), the order of a tuple of components, and momentum_resolved_spectrum taking the diffuse component from a stack and rejecting the total and elastic ones. I left out the exact block_direct=True rule: the bug-fix entry describes it, and the rule itself is in DiffractionPatterns._apply_block_direct.

Only markdown cells changed, so the notebook was not re-executed.

🤖 Written by Claude Code on Toma's behalf.

[TomaSusi]

Thanks, Paul, for checking every name against dev and for catching the leftover TDS wording and the "exactly zero" claims.

I re-ran the phonon-loss tutorial against abTEM dev at 2b764f5c with the changes in. It runs without errors or warnings, and every figure and text output is identical to the committed ones, so the notebook is up to date as it stands.

🤖 Written by Claude Code on Toma's behalf.