Add pinned polymer diffraction peak inference

docs/polymer_overlap_reconciliation.md

@@ -0,0 +1,34 @@
+# Polymer / `dev` reconciliation ledger
+
+Audit base: `origin/dev` at `dca541308cc6fa500b677cade5365969ab0db552`.
+Polymer source was inspected from the preserved `polymers` branch and the exact
+pre-maintenance backup branch. The curated branch is `paper/polymers`.
+
+| Polymer path / symbol | Current `dev` counterpart | Relationship and behavior/API differences | Callers / tests | Resolution | Risk |
+|---|---|---|---|---|---|
+| `core/ml/cnn2d.py:CNN2d`, `MultiChannelCNN2d` | `core/ml/cnn.py:CNN2d` | Similar U-Net purpose, but not checkpoint-equivalent. Defaults differ for skip connections and dropout placement; the paper network also has configurable convolution kernel size and per-output activations. The archived training runner confirms the paper checkpoint used dropout `0.0` (the historical inference constructor's `0.2` default is incompatible). These differences change parameter layout and numerical output. | Polymer notebooks, archived training runner, `BraggPeaksPolymer`; new resolver/numerical tests. | Retain the exact architecture privately in `diffraction/polymer_models.py`, pin dropout `0.0`, and continue using `dev` CNN for all non-polymer callers. | High if consolidated; paper weights cannot safely load into the `dev` class. |
+| Polymer `core/utils/augment_dp.py` and backup | `core/utils/augment_dp.py:DPAugmentor` | Same purpose. `dev` has the maintained RNG/device-aware implementation. Polymer variants include historical experiments and a large backup. The immutable release archive preserves the exact training augmentor separately. | Generator/training archive; existing core augmentor tests. | Reuse `dev`; do not transplant either polymer copy. | Low for inference; retraining reproducibility depends on the private archive. |
+| Polymer `core/io/file_readers.py:read_4dstem` | `core/io/file_readers.py:read_4dstem` | Conflicting extensions: polymer reshapes selected 3D frame stacks and optionally transposes scan axes; `dev` has maintained 4D loading, metadata overrides, and hot-pixel filtering. Scan-axis interpretation is acquisition-specific. | Tutorials load a canonical 4D scan; core reader tests exercise `dev`. | Reuse `dev`; defer the 3D-stack feature to an independent reader PR with acquisition fixtures. | Medium: silently choosing a scan axis can transpose real-space coordinates. |
+| Polymer `origin_finding.py` and `polar4dstem.find_origin` | `diffractive_imaging/origin_models.py:CenterOfMassOriginModel` | Complementary algorithms. `dev` estimates center of mass for ptychography; polymer angular-uniformity search minimizes polar angular variation and returns row/column pixel origins. | Polymer polar workflow and focused origin/polar tests; ptychography callers use COM model. | Retain angular origin finding in `diffraction/polar_transform.py`; leave COM API unchanged. | Medium: algorithms are not interchangeable for masked/anisotropic patterns. |
+| `diffraction/peak_detection.py` | No general Bragg-peak detector on `dev` | Polymer code provides strict local maxima, quadratic subpixel refinement, peak pairing, and central-beam selection in row/column convention. | `BraggPeaksPolymer`; numerical coordinate regression. | Retain, initially scoped to diffraction. | Medium: coordinate order must remain `(row, col)` internally and `(x, y)` only at plotting boundaries. |
+| `diffraction/polar_transform.py` | `diffractive_imaging/complex_probe.py` polar coordinate helpers and `_torch_polar` in direct ptychography | Complementary. `dev` helpers build frequency grids or convert tensor components; polymer code resamples whole 4D scans about per-pattern origins, optionally corrects ellipses, and defines explicit angular folding. | `BraggPeaksPolymer`, origin workflow, numerical orientation regression. | Retain the Torch-native scan transform plus minimal `Polar4dstem`; do not expose the experimental `polar.py` / `polar_new.py` duplicates. | High: angle direction, row/column origin order, and whether Friedel partners are sampled or summed affect flowline orientation and intensity. |
+| Polymer `core/utils/utils.py:parse_reciprocal_units` | `core/utils/utils.py:electron_wavelength_angstrom`; calibrated dataset metadata | Complementary. Polymer parsing converts reciprocal nm to reciprocal Å; angular sampling requires voltage-dependent wavelength conversion. The historical parser accepted ambiguous substrings. | `BraggPeaksPolymer.pixels_to_inv_A`; unit regression. | Keep strict parser in `diffraction/polymer_utils.py`, reuse `dev` electron wavelength function, warn on unknown units, and preserve the documented 300 kV compatibility default. | High: a factor-of-ten unit error changes every reported radial position. |
+| Polymer `sample_average_from_image` and broad probe-fit helpers | `dev` generic array utilities / filtering | Only local polar-neighborhood averaging is required. Probe circle/ellipse fitting and broad utility additions are unrelated. | Polymer peak intensity extraction. | Retain the local averaging helper only; do not expand generic utilities. | Low; angular axis wraps while radial axis does not. |
+| Polymer `Dataset`, `Dataset4dstem`, `polar4dstem` changes | Current `Dataset*` classes | Most polymer dataset edits are experimental or debug-only (including a constructor print). `Polar4dstem` is a genuinely distinct `(scan_y, scan_x, phi, r)` calibrated container. | Polar transform; existing dataset tests. | Reuse current datasets unchanged and add only `Polar4dstem`. | Medium: polar axes are `(phi, r)`, unlike Cartesian `(qy, qx)`. |
+| `BraggPeaksPolymer` normalization and BatchNorm adaptation | No `dev` equivalent | New capability. It caches scan-level percentiles, supports ROI masks, either adapts BatchNorm running statistics for deterministic eval or retains train-batch behavior, and performs masked inference. | Paper tutorial and forthcoming GPU comparison. | Retain. Named model specs carry normalization metadata; legacy caller-supplied normalization functions remain supported. | High: changing normalization or BN mode changes peak counts. |
+| `BraggPeaksPolymer` visualization, count maps, peak figure export, flowlines | General `core.visualization.show_2d` | Complementary. Polymer methods create domain-specific overlays and flowline orientation/color composites; generic display remains useful underneath. | Paper figure workflow. | Retain domain-specific methods and reuse `show_2d`. | Medium: orientation convention and cyclic color mapping are scientific outputs. |
+| `polar.py`, `polar_new.py`, `polymer_analytical_functions.py`, Kirkland table | Torch `polar_transform.py` or no paper inference caller | Multiple experimental/analytical paths, not required by the selected model inference/tutorial path. | Historical notebooks only. | Defer; preserve in checkpoint and private archive, omit from PR. | Low for the paper workflow; revisit as separate physics APIs. |
+| Polymer generator/training launchers, notebooks, results, workspace files, grain clustering | No relevant `dev` API | Out of scope or private/research state. | Private archive and independent WIP backup. | Exclude from public polymer PR. | None to inference; disclosure/repository hygiene risk if included. |
+
+## Final disposition summary
+
+- Reused from `dev`: maintained CNNs for non-polymer callers, augmentation, file readers,
+  generic datasets/utilities, electron wavelength conversion, and visualization.
+- Retained separately: exact checkpoint architecture, `BraggPeaksPolymer`, peak detection,
+  angular origin/polar transforms, `Polar4dstem`, strict reciprocal-unit conversion, and
+  polar neighborhood averaging.
+- Deferred: acquisition-specific 3D-stack reshaping and all experimental analytical polar
+  implementations.
+- Required follow-up before converting the draft PR to ready: compare pinned-model output
+  tensors, peak coordinates/counts, reciprocal radii, and flowline orientation against the
+  archived paper environment on the experimental scan.

src/quantem/__init__.py

@@ -10,5 +10,6 @@
 
 from quantem import imaging as imaging
 from quantem import diffractive_imaging as diffractive_imaging
+from quantem import diffraction as diffraction
 
 __version__ = version("quantem")

src/quantem/core/datastructures/__init__.py

@@ -5,3 +5,4 @@
 from quantem.core.datastructures.dataset4d import Dataset4d as Dataset4d
 from quantem.core.datastructures.dataset3d import Dataset3d as Dataset3d
 from quantem.core.datastructures.dataset2d import Dataset2d as Dataset2d
+from quantem.core.datastructures.polar4dstem import Polar4dstem as Polar4dstem