From 98ad75adb95341a967a61cfb247b00559c51dbc7 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Fri, 13 Nov 2026 09:11:37 -0600 Subject: [PATCH 1/2] Name the scattering-matrix backend for what it is, not PRISM "bloch_prism" / BlochPrismBackend solves the Bloch-wave model by Sturkey's scattering matrix (a matrix exponential stepped through the depth slices), equal to the eigendecomposition; it is not Ophus's PRISM, which interpolates a STEM scattering matrix in Fourier space. It is now backend="bloch_smatrix", BlochScatteringMatrixBackend in de_ebsd.diffraction.smatrix, with its references (Sturkey 1962; Wang & De Graef 2016; Singh & De Graef 2018; Winkelmann et al. 2007; Callahan & De Graef 2013; and Ophus 2017 for what it is not) in the module and the architecture notes. The old names still work, with a DeprecationWarning: "bloch_prism", de_ebsd.BlochPrismBackend, de_ebsd.diffraction.BlochPrismBackend and de_ebsd.diffraction.prism. Results are unchanged. Claude-Session: https://claude.ai/code/session_01DzXsKAUJSM4XYpqqzrcuV5 --- README.md | 2 +- docs/dev/algorithm.rst | 2 +- docs/dev/architecture.rst | 14 +- docs/dev/index.rst | 2 +- examples/cif_to_master_pattern.ipynb | 2 +- examples/indexing/dictionary_indexing.py | 2 +- examples/indexing/spherical_indexing.py | 2 +- examples/simulation/cif_to_detector.py | 2 +- examples/simulation/compare_emsoft.py | 2 +- .../simulation/energy_resolved_simulation.py | 2 +- .../simulation/resolution_and_backends.py | 6 +- scripts/validate_master_pattern.py | 6 +- src/de_ebsd/__init__.py | 14 +- src/de_ebsd/crystal/structure_factors.py | 2 +- src/de_ebsd/diffraction/__init__.py | 19 +- src/de_ebsd/diffraction/backends.py | 21 +- src/de_ebsd/diffraction/prism.py | 226 +--------------- src/de_ebsd/diffraction/smatrix.py | 250 ++++++++++++++++++ src/de_ebsd/sim/simulator.py | 6 +- src/de_ebsd/viz/depth_widget.js | 2 +- tests/test_api.py | 4 +- tests/test_display_widgets.py | 2 +- tests/test_dynamical.py | 2 +- tests/test_experiment_widgets.py | 2 +- tests/test_montecarlo_sim.py | 2 +- ...est_prism.py => test_scattering_matrix.py} | 90 ++++--- .../+scattering-matrix.deprecation.rst | 1 + 27 files changed, 399 insertions(+), 288 deletions(-) create mode 100644 src/de_ebsd/diffraction/smatrix.py rename tests/{test_prism.py => test_scattering_matrix.py} (72%) create mode 100644 upcoming_changes/+scattering-matrix.deprecation.rst diff --git a/README.md b/README.md index 5383184..d7dc4e3 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ sim = de.MasterPatternSimulator( npx=500, dmin=0.05, bethe=de.BetheParameters(), - # backend="bloch_prism" is the default: the batched dynamical solve. + # backend="bloch_smatrix" is the default: the batched dynamical solve. # "bloch" is the one-direction-at-a-time float64 reference it reproduces. ) diff --git a/docs/dev/algorithm.rst b/docs/dev/algorithm.rst index 99564be..e67589f 100644 --- a/docs/dev/algorithm.rst +++ b/docs/dev/algorithm.rst @@ -43,7 +43,7 @@ The master pattern is computed as in EMsoft's ``EMEBSDmaster`` positive), and ``L_gh = conj(C) I C^T``. ``lambda_E(z)`` is the Monte Carlo exit-depth fraction times ``exp(+2 pi z / x_gp)``, which cancels the normal absorption already in the eigenvalues; the depth limit is the 99 % histogram - depth. ``bloch_prism`` evaluates the same integral through the scattering + depth. ``bloch_smatrix`` evaluates the same integral through the scattering matrix instead of an eigendecomposition. 7. **S_gh weighting.** Per asymmetric-unit site, diff --git a/docs/dev/architecture.rst b/docs/dev/architecture.rst index d384ed2..8f66135 100644 --- a/docs/dev/architecture.rst +++ b/docs/dev/architecture.rst @@ -61,7 +61,7 @@ Every intensity model sits behind one seam, then ``intensities(directions)`` in chunks. The simulator owns gridding, chunking and assembly; backends own the physics. -``bloch_prism`` (the default) +``bloch_smatrix`` (the default) Replaces the eigendecomposition with the physically equivalent scattering matrix ``exp(2 pi i A z / (2 k_n))`` (batched ``torch.linalg.matrix_exp``, pure matrix products) followed by a depth recurrence. Everything is batched: @@ -70,11 +70,19 @@ chunking and assembly; backends own the physics. bucketed by strong-beam count so each batch is a uniform ``[B, S, S]``. It reproduces ``bloch`` to about 1e-13 in float64 and 1e-4 in float32. + The scattering-matrix form of dynamical diffraction is Sturkey's (Proc. + Phys. Soc. 80, 321, 1962); with Bethe potentials it is Wang and De Graef's + (Ultramicroscopy 160, 35, 2016) and on GPUs Singh and De Graef's (Microsc. + Microanal. 24 S1, 222, 2018). Before 0.6 it was called ``bloch_prism``, but + it is not Ophus's PRISM (Adv. Struct. Chem. Imaging 3, 13, 2017), which + interpolates a STEM scattering matrix in Fourier space: nothing here is + interpolated, and the result equals ``bloch``. + ``bloch`` The float64 reference, one direction at a time. A non-Hermitian eigendecomposition neither batches nor accelerates on a GPU (cuSOLVER has no batched general-eigenvalue kernel), so this backend is CPU-bound and exists - to validate ``bloch_prism``, not for production. + to validate ``bloch_smatrix``, not for production. Symmetry reduction is independent of the backend: only the point group's fundamental sector is sampled and the result is replicated, which is exact (the @@ -101,7 +109,7 @@ Differentiability ================= Gradients flow end to end from crystal parameters to intensity. The -``bloch_prism`` path is torch-native (``matrix_exp``, a depth recurrence and +``bloch_smatrix`` path is torch-native (``matrix_exp``, a depth recurrence and ``S_gh``), so gradients pass through the non-Hermitian complex solve back to ``U_g``. ``differentiable_ucg_lut`` assembles ``U_g`` in torch, and ``scattering_torch.wk_scattering_factor_torch`` ports the full diff --git a/docs/dev/index.rst b/docs/dev/index.rst index e0a31ce..e4aff99 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -23,7 +23,7 @@ not done when it runs -- it is done when it still reproduces the oracle: .. code-block:: shell - uv run python scripts/validate_master_pattern.py --material ni --backend bloch_prism + uv run python scripts/validate_master_pattern.py --material ni --backend bloch_smatrix Nickel uses kikuchipy's bundled master pattern and needs no external files. Silicon needs a local EMsoft ``Si_MC.h5`` run, which is not redistributed here; diff --git a/examples/cif_to_master_pattern.ipynb b/examples/cif_to_master_pattern.ipynb index e93b990..157e449 100644 --- a/examples/cif_to_master_pattern.ipynb +++ b/examples/cif_to_master_pattern.ipynb @@ -445,7 +445,7 @@ "source": [ "## 2. Set up the simulation\n", "\n", - "The default `backend=\"bloch_prism\"` is the batched dynamical solver; `\"bloch\"` is the\n", + "The default `backend=\"bloch_smatrix\"` is the batched dynamical solver; `\"bloch\"` is the\n", "one-direction-at-a-time float64 reference it reproduces.\n", "\n", "`npx` and `dmin` are the accuracy/cost knobs: `npx` sets the Lambert grid\n", diff --git a/examples/indexing/dictionary_indexing.py b/examples/indexing/dictionary_indexing.py index f2b8115..5e30f0f 100644 --- a/examples/indexing/dictionary_indexing.py +++ b/examples/indexing/dictionary_indexing.py @@ -67,7 +67,7 @@ npx=100, dmin=0.05, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) master = sim.compute(device=device, dtype=torch.float32) print(master) diff --git a/examples/indexing/spherical_indexing.py b/examples/indexing/spherical_indexing.py index 3a5a9d6..4a1300d 100644 --- a/examples/indexing/spherical_indexing.py +++ b/examples/indexing/spherical_indexing.py @@ -64,7 +64,7 @@ npx=100, dmin=0.05, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) master = sim.compute(device=device, dtype=torch.float32) symmetry = phase_from_crystal(crystal).point_group diff --git a/examples/simulation/cif_to_detector.py b/examples/simulation/cif_to_detector.py index 2172d51..658ab42 100644 --- a/examples/simulation/cif_to_detector.py +++ b/examples/simulation/cif_to_detector.py @@ -86,7 +86,7 @@ npx=100, dmin=0.05, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) sim.structure_factors().show(n=12) diff --git a/examples/simulation/compare_emsoft.py b/examples/simulation/compare_emsoft.py index a35f9d5..95d47fe 100644 --- a/examples/simulation/compare_emsoft.py +++ b/examples/simulation/compare_emsoft.py @@ -95,7 +95,7 @@ dmin=dmin, bethe=bethe, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) started = perf_counter() simulated = simulator.compute(device=device, dtype=torch.float64, chunk_size=512).to("cpu") diff --git a/examples/simulation/energy_resolved_simulation.py b/examples/simulation/energy_resolved_simulation.py index 9fb33ae..efb273f 100644 --- a/examples/simulation/energy_resolved_simulation.py +++ b/examples/simulation/energy_resolved_simulation.py @@ -78,7 +78,7 @@ npx=100, dmin=0.05, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) master = sim.compute(device=device, dtype=torch.float64, energy_resolved=True, chunk_size=512) assert master.data.shape == (3, 2, 2 * sim.npx + 1, 2 * sim.npx + 1) diff --git a/examples/simulation/resolution_and_backends.py b/examples/simulation/resolution_and_backends.py index 18ec665..ac6384e 100644 --- a/examples/simulation/resolution_and_backends.py +++ b/examples/simulation/resolution_and_backends.py @@ -99,7 +99,7 @@ # # These are normal-depth integration slices, not crystal layers or a simulated # electron trajectory. The stored exponential is sampled at z = j * dz; -# PRISM evaluates the propagated wave at (j + 1) * dz. Both solvers use the +# The scattering matrix evaluates the propagated wave at (j + 1) * dz. Both solvers use the # absorption-corrected weights internally; this viewer shows uncorrected exit # statistics, so it does not mistake an increasing correction for deeper yield. @@ -115,7 +115,7 @@ npx=100, dmin=0.05, monte_carlo=depth, - backend="bloch_prism", + backend="bloch_smatrix", ) coarse_sim.structure_factors() fine_sim = coarse_sim.refine(npx=200) @@ -180,7 +180,7 @@ scale = reference.data.abs().max().clamp_min(1e-30) relative_max = (coarse.data - reference.data).abs().max() / scale assert torch.isfinite(relative_max) and relative_max < 1e-7 -print(f"PRISM versus Bloch maximum relative difference: {relative_max.item():.3e}") +print(f"Scattering matrix versus eigendecomposition maximum relative difference: {relative_max.item():.3e}") # %% # Continue a convergence study diff --git a/scripts/validate_master_pattern.py b/scripts/validate_master_pattern.py index 903cfab..4945504 100644 --- a/scripts/validate_master_pattern.py +++ b/scripts/validate_master_pattern.py @@ -24,8 +24,8 @@ Usage:: - uv run python scripts/validate_master_pattern.py --material ni --backend bloch_prism - uv run python scripts/validate_master_pattern.py --material si --backend bloch_prism \\ + uv run python scripts/validate_master_pattern.py --material ni --backend bloch_smatrix + uv run python scripts/validate_master_pattern.py --material si --backend bloch_smatrix \\ --mc /path/to/Si_MC.h5 --device cuda """ @@ -126,7 +126,7 @@ def main() -> None: "--dmin", type=float, default=None, help="dmin in nm (default: the reference run's value)" ) parser.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu") - parser.add_argument("--backend", default="bloch_prism") + parser.add_argument("--backend", default="bloch_smatrix") parser.add_argument( "--mc", default=None, diff --git a/src/de_ebsd/__init__.py b/src/de_ebsd/__init__.py index 4fca779..481fd28 100644 --- a/src/de_ebsd/__init__.py +++ b/src/de_ebsd/__init__.py @@ -25,7 +25,7 @@ from de_ebsd.crystal import AtomSite, Crystal from de_ebsd.diffraction import ( BetheParameters, - BlochPrismBackend, + BlochScatteringMatrixBackend, BlochWaveBackend, MasterPatternBackend, ) @@ -45,7 +45,7 @@ __all__ = [ "AtomSite", "BetheParameters", - "BlochPrismBackend", + "BlochScatteringMatrixBackend", "BlochWaveBackend", "Crystal", "CrystalExplorer", @@ -72,6 +72,16 @@ def __getattr__(name: str): + if name == "BlochPrismBackend": # the scattering-matrix backend's old name + import warnings + + warnings.warn( + "BlochPrismBackend is now BlochScatteringMatrixBackend; " + "the old name goes in a later release", + DeprecationWarning, + stacklevel=2, + ) + return BlochScatteringMatrixBackend module = _LAZY.get(name) if module is None: raise AttributeError(f"module 'de_ebsd' has no attribute {name!r}") diff --git a/src/de_ebsd/crystal/structure_factors.py b/src/de_ebsd/crystal/structure_factors.py index 140a31a..9ba2d19 100644 --- a/src/de_ebsd/crystal/structure_factors.py +++ b/src/de_ebsd/crystal/structure_factors.py @@ -245,7 +245,7 @@ def differentiable_ucg_lut( When ``debye_waller`` is None the amplitudes are evaluated in numpy and held constant (positions/occupancy gradients only). Feed the result to a torch - backend (``bloch_prism``) as its ``u_lut`` for end-to-end + backend (``bloch_smatrix``) as its ``u_lut`` for end-to-end ``d(intensity)/d(crystal parameter)``. Lattice gradients (through ``g``) remain a further step. """ diff --git a/src/de_ebsd/diffraction/__init__.py b/src/de_ebsd/diffraction/__init__.py index 1f65f74..7ac3c14 100644 --- a/src/de_ebsd/diffraction/__init__.py +++ b/src/de_ebsd/diffraction/__init__.py @@ -15,7 +15,6 @@ reduce_to_fundamental_sector, sample_incident_directions, ) -from de_ebsd.diffraction.prism import BlochPrismBackend from de_ebsd.diffraction.reflections import ( ReflectionList, candidate_reflections, @@ -23,10 +22,11 @@ master_reflection_list, partition_strong_weak, ) +from de_ebsd.diffraction.smatrix import BlochScatteringMatrixBackend __all__ = [ "BetheParameters", - "BlochPrismBackend", + "BlochScatteringMatrixBackend", "BlochWaveBackend", "DynamicalMatrix", "KVectorGrid", @@ -43,3 +43,18 @@ "resolve_backend", "sample_incident_directions", ] + + +def __getattr__(name: str): + # The scattering-matrix backend's old name, kept a release with a warning. + if name == "BlochPrismBackend": + import warnings + + warnings.warn( + "BlochPrismBackend is now BlochScatteringMatrixBackend; " + "the old name goes in a later release", + DeprecationWarning, + stacklevel=2, + ) + return BlochScatteringMatrixBackend + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") diff --git a/src/de_ebsd/diffraction/backends.py b/src/de_ebsd/diffraction/backends.py index e8b6bfb..39358b5 100644 --- a/src/de_ebsd/diffraction/backends.py +++ b/src/de_ebsd/diffraction/backends.py @@ -2,9 +2,10 @@ :class:`BlochWaveBackend` is the dynamical solver (Bethe-perturbed dynamical matrix, eigen-decomposition, depth integration) in float64, one direction at a -time; :class:`~de_ebsd.diffraction.prism.BlochPrismBackend` is its batched GPU -equivalent. The dynamical matrix, depth integration and ``S_gh`` weighting port -EMsoft's ``GetDynMat``, ``CalcLgh`` and ``preCalcSgh``. +time; :class:`~de_ebsd.diffraction.smatrix.BlochScatteringMatrixBackend` is its +batched GPU equivalent, by the scattering matrix. The dynamical matrix, depth +integration and ``S_gh`` weighting port EMsoft's ``GetDynMat``, ``CalcLgh`` and +``preCalcSgh``. """ from __future__ import annotations @@ -303,12 +304,22 @@ def resolve_backend(backend: str | MasterPatternBackend) -> MasterPatternBackend """Map a backend name to an instance; pass instances through.""" if isinstance(backend, MasterPatternBackend): return backend - from de_ebsd.diffraction.prism import BlochPrismBackend # deferred: prism imports this module + # deferred: smatrix imports this module + from de_ebsd.diffraction.smatrix import BlochScatteringMatrixBackend named = { "bloch": BlochWaveBackend, - "bloch_prism": BlochPrismBackend, + "bloch_smatrix": BlochScatteringMatrixBackend, } + if backend == "bloch_prism": # the old name, kept a release with a warning + import warnings + + warnings.warn( + 'backend "bloch_prism" is now "bloch_smatrix"; the old name goes in a later release', + DeprecationWarning, + stacklevel=2, + ) + backend = "bloch_smatrix" try: return named[backend]() except KeyError: diff --git a/src/de_ebsd/diffraction/prism.py b/src/de_ebsd/diffraction/prism.py index ef40cf2..f4fa69f 100644 --- a/src/de_ebsd/diffraction/prism.py +++ b/src/de_ebsd/diffraction/prism.py @@ -1,219 +1,21 @@ -"""Scattering-matrix Bloch backend: the batched, differentiable form of ``bloch``. - -Replaces the per-direction dynamical matrix with batched solves of the -scattering matrix, much faster for dense direction grids and equal to -:class:`~de_ebsd.diffraction.backends.BlochWaveBackend` in double precision. -""" +"""Deprecated: the scattering-matrix backend is in +:mod:`de_ebsd.diffraction.smatrix`. It was called PRISM, but it is not Ophus's +PRISM algorithm (see that module); the old names go in a later release.""" from __future__ import annotations -import numpy as np -import torch - -import de_ebsd.diffraction.reflections as _R -from de_ebsd.diffraction.backends import BlochWaveBackend, SimulationInputs -from de_ebsd.diffraction.reflections import excitation_errors, master_reflection_list - - -class BlochPrismBackend(BlochWaveBackend): - """Scattering-matrix (PRISM) Bloch backend: one shared eigen-decomposition. - - ``cdtype`` selects the working precision: ``torch.complex128`` (default, - exact against the reference) or ``torch.complex64`` (faster, ~1e-4). - - The whole intensity path is torch (``matrix_exp`` + a depth recurrence), so - it is autograd-differentiable: with a ``requires_grad`` structure-factor LUT - (``u_lut``) gradients flow through the Bloch solve back to ``U_g`` (matching - finite differences; M4). Connecting ``U_g`` to crystal parameters needs torch - structure factors -- the remaining M4 piece. - """ +import warnings - name = "bloch_prism" +from de_ebsd.diffraction.smatrix import BlochScatteringMatrixBackend - def __init__(self, cdtype: torch.dtype = torch.complex128): - self.cdtype = cdtype - self.rdtype = torch.float64 if cdtype == torch.complex128 else torch.float32 - # class_chunk bounds the [chunk, Cmax, Cmax] candidate-Bethe tensor; block - # is classified up front so buckets span it (large, GPU-efficient batches); - # matmul_batch caps the [B, S, S] matrix_exp batch. - self.class_chunk = 1024 - self.block = 65536 - self.matmul_batch = 4096 - # ---- setup ---------------------------------------------------------- # - def prepare(self, inputs: SimulationInputs) -> None: - super().prepare( - inputs - ) # structure_factors, bethe, depth profile, Sgh LUT, kn, gzero, n_atoms, hmax - dev = torch.device(self.device if self.device is not None else "cpu") - self.tdev = dev - self.off = 2 * self.hmax - self.u_lut = torch.as_tensor(self.structure_factors.ucg_lut, device=dev, dtype=self.cdtype) - self.sgh_t = torch.as_tensor(self.sgh_lut, device=dev, dtype=self.cdtype) - self.lam = float(self.structure_factors.wavelength) - self.upz0 = float(self.structure_factors.upz0) - self.lambda_t = torch.as_tensor(self.lambda_e, device=dev, dtype=self.rdtype) - self.n_depths = self.lambda_t.shape[0] - - # fixed, direction-independent tables (g = 0 prepended at index 0) - master = master_reflection_list(self.structure_factors) - z1 = np.zeros((1, 3), np.int64) - self.hkl_aug = torch.as_tensor(np.concatenate([z1, master.hkl]), device=dev) - self.n_beams = self.hkl_aug.shape[0] - u0 = float(np.abs(self.structure_factors.lookup(np.zeros(3, np.int64)))) - self.u_mod = torch.as_tensor( - np.concatenate([[u0], master.u_mod]), device=dev, dtype=self.rdtype - ) - self.forbidden = torch.as_tensor(np.concatenate([[False], master.forbidden]), device=dev) - self.g_cart = torch.as_tensor( - self.structure_factors.crystal.g_cartesian(master.hkl), device=dev, dtype=self.rdtype +def __getattr__(name: str): + if name == "BlochPrismBackend": + warnings.warn( + "BlochPrismBackend is now BlochScatteringMatrixBackend " + "(de_ebsd.diffraction.smatrix); the old name goes in a later release", + DeprecationWarning, + stacklevel=2, ) - - def _pairs(self) -> None: - """Every pair of beams' U(h_g - h_h) and S(h_h - h_g): the Bethe test and - each bucket gather from these small matrices instead of building - (directions, beams, beams, 3) index differences to look up in the 3D - tables, which was most of their time. Taken from the tables as they are - when :meth:`intensities` is called, so a ``u_lut`` swapped in for its - gradient is the one used.""" - hkl = self.hkl_aug - self.u_pair = self._lookup(self.u_lut, hkl[:, None, :] - hkl[None, :, :]) - self.u_pair_abs = self.u_pair.detach().abs().to(self.rdtype) - self.sgh_pair = self._lookup(self.sgh_t, hkl[None, :, :] - hkl[:, None, :]) # [g,h]=h-g - - def _lookup(self, lut: torch.Tensor, hkl: torch.Tensor) -> torch.Tensor: - i = hkl + self.off - return lut[i[..., 0], i[..., 1], i[..., 2]] - - # ---- depth integration via the scattering matrix -------------------- # - def _depth_intensity(self, a: torch.Tensor, sgh: torch.Tensor) -> torch.Tensor: - """Each direction's depth-integrated intensity ``sum_n lambda_n psi_n^H S - psi_n``, the wave ``psi_n = Sigma^n e_gzero`` after n depth steps and S the - ``Sgh`` matrix: what ``sum(L_gh * S_gh)`` is, with ``L_gh = sum_n lambda_n - conj(psi_g) psi_h``, without forming L one depth at a time (a batched - outer product per depth was most of the bucket's time). Unnormalized by the - atom count.""" - phase = 2.0 * np.pi * self.depthstep / (2.0 * self.kn) - step = torch.complex( - torch.zeros((), device=self.tdev, dtype=self.rdtype), - torch.as_tensor(phase, device=self.tdev, dtype=self.rdtype), - ) - sigma = torch.linalg.matrix_exp(step * a) # exp(i phase A) - psi = sigma[:, :, self.gzero] # psi_1 = Sigma e_gzero - waves = [] - for _ in range(self.n_depths): - waves.append(psi) - psi = torch.matmul(sigma, psi[:, :, None]).squeeze(-1) - waves = torch.stack(waves, 1) # (b, depths, beams) - scattered = torch.matmul(waves, sgh.transpose(1, 2)) # (S psi_n)^T, (b, depths, beams) - per_depth = (waves.conj() * scattered).sum(-1) # (b, depths) - weights = self.lambda_t.to(per_depth.real.dtype) - return (per_depth * weights).sum(-1).real * (self.depthstep / self.thick) - - # ---- one intensity per incident direction --------------------------- # - def intensities(self, directions: torch.Tensor) -> torch.Tensor: - self._pairs() - k_all = directions.to(self.tdev, self.rdtype) - total = k_all.shape[0] - out = torch.empty(total, device=self.tdev, dtype=self.out_dtype) - for m0 in range(0, total, self.block): - k = k_all[m0 : m0 + self.block] - strong, weak, sg = self._classify(k) - counts = strong.sum(1) - for s in torch.unique(counts).tolist(): - sub = torch.nonzero(counts == s, as_tuple=False).squeeze(1) - for b0 in range(0, sub.shape[0], self.matmul_batch): - self._bucket( - int(s), sub[b0 : b0 + self.matmul_batch], strong, weak, sg, out, m0 - ) - return out - - def _classify(self, k: torch.Tensor): - bethe = self.bethe - d = k.shape[0] - strong = torch.zeros(d, self.n_beams, dtype=torch.bool, device=self.tdev) - weak = torch.zeros_like(strong) - sg_all = torch.empty(d, self.n_beams, device=self.tdev, dtype=self.rdtype) - for c0 in range(0, d, self.class_chunk): - kc = k[c0 : c0 + self.class_chunk] - c = kc.shape[0] - sg = excitation_errors(self.g_cart, kc, self.lam) - sg = torch.cat([torch.zeros(c, 1, device=self.tdev, dtype=self.rdtype), sg], dim=1) - absg = sg.abs() - cand = (absg / (self.lam * self.u_mod.clamp_min(1e-300))) <= bethe.cutoff - cand[:, self.forbidden] = absg[:, self.forbidden] <= bethe.sg_double - cand[:, 0] = True - - # gather the candidate beams to a padded [c, Cmax] index list - cc = cand.sum(1) - cmax = int(cc.max().item()) - nz = cand.nonzero(as_tuple=False) # [T, 2], row-sorted - rows = nz[:, 0] - starts = torch.zeros(c, dtype=torch.long, device=self.tdev) - starts[1:] = cc.cumsum(0)[:-1] - within = torch.arange(rows.shape[0], device=self.tdev) - starts[rows] - cidx = torch.zeros(c, cmax, dtype=torch.long, device=self.tdev) - creal = torch.zeros(c, cmax, dtype=torch.bool, device=self.tdev) - cidx[rows, within] = nz[:, 1] - creal[rows, within] = True - - # Bethe min over candidate h only - absg_c = absg.gather(1, cidx) # [c, Cmax] - u = self.u_pair_abs[cidx[:, :, None], cidx[:, None, :]] - good = (u > _R._FORBIDDEN_TOL) & creal[:, None, :] - rh = torch.where( - good, - (absg_c[:, :, None] / self.lam) / u.clamp_min(1e-300), - torch.full_like(u, 1.0e4), - ) - m_c = rh.min(dim=2).values # [c, Cmax] - st_c = (m_c <= bethe.strong) & creal - wk_c = (m_c > bethe.strong) & (m_c <= bethe.weak) & creal - - st = torch.zeros(c, self.n_beams, dtype=torch.bool, device=self.tdev) - wk = torch.zeros_like(st) - st.scatter_(1, cidx, st_c) - wk.scatter_(1, cidx, wk_c) - st[:, 0] = True - st[:, self.forbidden] = False - wk[:, self.forbidden] = False - wk[:, 0] = False - strong[c0 : c0 + c] = st - weak[c0 : c0 + c] = wk - sg_all[c0 : c0 + c] = sg - return strong, weak, sg_all - - def _bucket(self, s, sub, strong, weak, sg, out, c0): - b = sub.shape[0] - st, wk, sgs = strong[sub], weak[sub], sg[sub] - s_idx = st.nonzero(as_tuple=False)[:, 1].reshape(b, s) # ascending -> g0 first - sg_s = sgs.gather(1, s_idx) # [b, s] - - wc = wk.sum(1) - w_max = int(wc.max().item()) if b else 0 - a = self.u_pair[s_idx[:, :, None], s_idx[:, None, :]] - weak_diag = torch.zeros(b, s, device=self.tdev, dtype=self.rdtype) - if w_max > 0: - nz = wk.nonzero(as_tuple=False) # [T, 2], row-sorted - rows, cols = nz[:, 0], nz[:, 1] - starts = torch.zeros(b, dtype=torch.long, device=self.tdev) - starts[1:] = wc.cumsum(0)[:-1] - within = torch.arange(rows.shape[0], device=self.tdev) - starts[rows] - w_idx = torch.zeros(b, w_max, dtype=torch.long, device=self.tdev) - w_ok = torch.zeros(b, w_max, dtype=torch.bool, device=self.tdev) - w_idx[rows, within] = cols - w_ok[rows, within] = True - sg_w = sgs.gather(1, w_idx) - inv_sgw = torch.where(w_ok, 1.0 / sg_w, torch.zeros_like(sg_w)) - u_gw = self.u_pair[s_idx[:, :, None], w_idx[:, None, :]] - u_wh = self.u_pair[w_idx[:, :, None], s_idx[:, None, :]] - a = a - 0.5 * self.lam * torch.matmul(u_gw * inv_sgw[:, None, :], u_wh) - weak_diag = 0.5 * self.lam * (u_gw.abs() ** 2 * inv_sgw[:, None, :]).sum(2) - - di = torch.arange(s, device=self.tdev) - diag = (2.0 * sg_s / self.lam - weak_diag).to(self.cdtype) + 1j * self.upz0 - a[:, di, di] = diag - - sgh = self.sgh_pair[s_idx[:, :, None], s_idx[:, None, :]] # [g,h]=h-g - inten = self._depth_intensity(a, sgh) / self.n_atoms - out[sub + c0] = inten.to(self.out_dtype) + return BlochScatteringMatrixBackend + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") diff --git a/src/de_ebsd/diffraction/smatrix.py b/src/de_ebsd/diffraction/smatrix.py new file mode 100644 index 0000000..d9bc4e5 --- /dev/null +++ b/src/de_ebsd/diffraction/smatrix.py @@ -0,0 +1,250 @@ +"""Scattering-matrix Bloch backend: the batched, differentiable form of ``bloch``. + +The same Bloch-wave model as :class:`~de_ebsd.diffraction.backends.BlochWaveBackend` +(EMsoft's dynamical matrix, Bethe potentials and depth integration), solved +through the scattering matrix instead of an eigendecomposition: the wave at +depth ``n dz`` is ``Sigma^n`` applied to the incident beam, with ``Sigma = exp(i +phase A)`` one depth step of the structure matrix ``A``. Since ``exp(iAz) = V +exp(i Lambda z) V^-1``, the two are the same calculation; this one batches +many directions into one ``matrix_exp`` on a GPU and is differentiable, and +equals the eigendecomposition to machine precision in double precision. + +The scattering-matrix formulation is Sturkey's [1]_; with Bethe potentials it +is Wang and De Graef's [2]_, and on GPUs Singh and De Graef's [3]_. The EBSD +model it solves is Winkelmann et al.'s and Callahan and De Graef's [4]_ [5]_. +It is NOT the PRISM algorithm of Ophus [6]_, which gains its speed from Fourier +interpolation of a STEM scattering matrix: nothing here is interpolated. + +References +---------- +.. [1] L. Sturkey, "The calculation of electron diffraction intensities", + Proc. Phys. Soc. 80, 321 (1962). +.. [2] A. Wang and M. De Graef, "Modeling dynamical electron scattering with + Bethe potentials and the scattering matrix", Ultramicroscopy 160, 35 (2016). +.. [3] S. Singh and M. De Graef, "GPU-accelerated matrix exponentiation for 5-D + STEM-DCI simulations", Microsc. Microanal. 24 (S1), 222 (2018), + doi:10.1017/S1431927618001605. +.. [4] A. Winkelmann, C. Trager-Cowan, F. Sweeney, A. P. Day and P. Parbrook, + "Many-beam dynamical simulation of electron backscatter diffraction + patterns", Ultramicroscopy 107, 414 (2007), doi:10.1016/j.ultramic.2006.10.006. +.. [5] P. G. Callahan and M. De Graef, "Dynamical electron backscatter + diffraction patterns. Part I: Pattern simulations", Microsc. Microanal. 19, + 1255 (2013), doi:10.1017/S1431927613001840. +.. [6] C. Ophus, "A fast image simulation algorithm for scanning transmission + electron microscopy", Adv. Struct. Chem. Imaging 3, 13 (2017), + doi:10.1186/s40679-017-0046-1. +""" + +from __future__ import annotations + +import numpy as np +import torch + +import de_ebsd.diffraction.reflections as _R +from de_ebsd.diffraction.backends import BlochWaveBackend, SimulationInputs +from de_ebsd.diffraction.reflections import excitation_errors, master_reflection_list + + +class BlochScatteringMatrixBackend(BlochWaveBackend): + """Scattering-matrix Bloch backend: the Bloch-wave solve by ``matrix_exp``, + batched over directions (see the module's references). + + ``cdtype`` selects the working precision: ``torch.complex128`` (default, + exact against the reference) or ``torch.complex64`` (faster, ~1e-4). + + The whole intensity path is torch (``matrix_exp`` + a depth recurrence), so + it is autograd-differentiable: with a ``requires_grad`` structure-factor LUT + (``u_lut``) gradients flow through the Bloch solve back to ``U_g`` (matching + finite differences; M4). Connecting ``U_g`` to crystal parameters needs torch + structure factors -- the remaining M4 piece. + """ + + name = "bloch_smatrix" + + def __init__(self, cdtype: torch.dtype = torch.complex128): + self.cdtype = cdtype + self.rdtype = torch.float64 if cdtype == torch.complex128 else torch.float32 + # class_chunk bounds the [chunk, Cmax, Cmax] candidate-Bethe tensor; block + # is classified up front so buckets span it (large, GPU-efficient batches); + # matmul_batch caps the [B, S, S] matrix_exp batch. + self.class_chunk = 1024 + self.block = 65536 + self.matmul_batch = 4096 + + # ---- setup ---------------------------------------------------------- # + def prepare(self, inputs: SimulationInputs) -> None: + super().prepare( + inputs + ) # structure_factors, bethe, depth profile, Sgh LUT, kn, gzero, n_atoms, hmax + dev = torch.device(self.device if self.device is not None else "cpu") + self.tdev = dev + self.off = 2 * self.hmax + self.u_lut = torch.as_tensor(self.structure_factors.ucg_lut, device=dev, dtype=self.cdtype) + self.sgh_t = torch.as_tensor(self.sgh_lut, device=dev, dtype=self.cdtype) + self.lam = float(self.structure_factors.wavelength) + self.upz0 = float(self.structure_factors.upz0) + self.lambda_t = torch.as_tensor(self.lambda_e, device=dev, dtype=self.rdtype) + self.n_depths = self.lambda_t.shape[0] + + # fixed, direction-independent tables (g = 0 prepended at index 0) + master = master_reflection_list(self.structure_factors) + z1 = np.zeros((1, 3), np.int64) + self.hkl_aug = torch.as_tensor(np.concatenate([z1, master.hkl]), device=dev) + self.n_beams = self.hkl_aug.shape[0] + u0 = float(np.abs(self.structure_factors.lookup(np.zeros(3, np.int64)))) + self.u_mod = torch.as_tensor( + np.concatenate([[u0], master.u_mod]), device=dev, dtype=self.rdtype + ) + self.forbidden = torch.as_tensor(np.concatenate([[False], master.forbidden]), device=dev) + self.g_cart = torch.as_tensor( + self.structure_factors.crystal.g_cartesian(master.hkl), device=dev, dtype=self.rdtype + ) + + def _pairs(self) -> None: + """Every pair of beams' U(h_g - h_h) and S(h_h - h_g): the Bethe test and + each bucket gather from these small matrices instead of building + (directions, beams, beams, 3) index differences to look up in the 3D + tables, which was most of their time. Taken from the tables as they are + when :meth:`intensities` is called, so a ``u_lut`` swapped in for its + gradient is the one used.""" + hkl = self.hkl_aug + self.u_pair = self._lookup(self.u_lut, hkl[:, None, :] - hkl[None, :, :]) + self.u_pair_abs = self.u_pair.detach().abs().to(self.rdtype) + self.sgh_pair = self._lookup(self.sgh_t, hkl[None, :, :] - hkl[:, None, :]) # [g,h]=h-g + + def _lookup(self, lut: torch.Tensor, hkl: torch.Tensor) -> torch.Tensor: + i = hkl + self.off + return lut[i[..., 0], i[..., 1], i[..., 2]] + + # ---- depth integration via the scattering matrix -------------------- # + def _depth_intensity(self, a: torch.Tensor, sgh: torch.Tensor) -> torch.Tensor: + """Each direction's depth-integrated intensity ``sum_n lambda_n psi_n^H S + psi_n``, the wave ``psi_n = Sigma^n e_gzero`` after n depth steps and S the + ``Sgh`` matrix: what ``sum(L_gh * S_gh)`` is, with ``L_gh = sum_n lambda_n + conj(psi_g) psi_h``, without forming L one depth at a time (a batched + outer product per depth was most of the bucket's time). Unnormalized by the + atom count.""" + phase = 2.0 * np.pi * self.depthstep / (2.0 * self.kn) + step = torch.complex( + torch.zeros((), device=self.tdev, dtype=self.rdtype), + torch.as_tensor(phase, device=self.tdev, dtype=self.rdtype), + ) + sigma = torch.linalg.matrix_exp(step * a) # exp(i phase A) + psi = sigma[:, :, self.gzero] # psi_1 = Sigma e_gzero + waves = [] + for _ in range(self.n_depths): + waves.append(psi) + psi = torch.matmul(sigma, psi[:, :, None]).squeeze(-1) + waves = torch.stack(waves, 1) # (b, depths, beams) + scattered = torch.matmul(waves, sgh.transpose(1, 2)) # (S psi_n)^T, (b, depths, beams) + per_depth = (waves.conj() * scattered).sum(-1) # (b, depths) + weights = self.lambda_t.to(per_depth.real.dtype) + return (per_depth * weights).sum(-1).real * (self.depthstep / self.thick) + + # ---- one intensity per incident direction --------------------------- # + def intensities(self, directions: torch.Tensor) -> torch.Tensor: + self._pairs() + k_all = directions.to(self.tdev, self.rdtype) + total = k_all.shape[0] + out = torch.empty(total, device=self.tdev, dtype=self.out_dtype) + for m0 in range(0, total, self.block): + k = k_all[m0 : m0 + self.block] + strong, weak, sg = self._classify(k) + counts = strong.sum(1) + for s in torch.unique(counts).tolist(): + sub = torch.nonzero(counts == s, as_tuple=False).squeeze(1) + for b0 in range(0, sub.shape[0], self.matmul_batch): + self._bucket( + int(s), sub[b0 : b0 + self.matmul_batch], strong, weak, sg, out, m0 + ) + return out + + def _classify(self, k: torch.Tensor): + bethe = self.bethe + d = k.shape[0] + strong = torch.zeros(d, self.n_beams, dtype=torch.bool, device=self.tdev) + weak = torch.zeros_like(strong) + sg_all = torch.empty(d, self.n_beams, device=self.tdev, dtype=self.rdtype) + for c0 in range(0, d, self.class_chunk): + kc = k[c0 : c0 + self.class_chunk] + c = kc.shape[0] + sg = excitation_errors(self.g_cart, kc, self.lam) + sg = torch.cat([torch.zeros(c, 1, device=self.tdev, dtype=self.rdtype), sg], dim=1) + absg = sg.abs() + cand = (absg / (self.lam * self.u_mod.clamp_min(1e-300))) <= bethe.cutoff + cand[:, self.forbidden] = absg[:, self.forbidden] <= bethe.sg_double + cand[:, 0] = True + + # gather the candidate beams to a padded [c, Cmax] index list + cc = cand.sum(1) + cmax = int(cc.max().item()) + nz = cand.nonzero(as_tuple=False) # [T, 2], row-sorted + rows = nz[:, 0] + starts = torch.zeros(c, dtype=torch.long, device=self.tdev) + starts[1:] = cc.cumsum(0)[:-1] + within = torch.arange(rows.shape[0], device=self.tdev) - starts[rows] + cidx = torch.zeros(c, cmax, dtype=torch.long, device=self.tdev) + creal = torch.zeros(c, cmax, dtype=torch.bool, device=self.tdev) + cidx[rows, within] = nz[:, 1] + creal[rows, within] = True + + # Bethe min over candidate h only + absg_c = absg.gather(1, cidx) # [c, Cmax] + u = self.u_pair_abs[cidx[:, :, None], cidx[:, None, :]] + good = (u > _R._FORBIDDEN_TOL) & creal[:, None, :] + rh = torch.where( + good, + (absg_c[:, :, None] / self.lam) / u.clamp_min(1e-300), + torch.full_like(u, 1.0e4), + ) + m_c = rh.min(dim=2).values # [c, Cmax] + st_c = (m_c <= bethe.strong) & creal + wk_c = (m_c > bethe.strong) & (m_c <= bethe.weak) & creal + + st = torch.zeros(c, self.n_beams, dtype=torch.bool, device=self.tdev) + wk = torch.zeros_like(st) + st.scatter_(1, cidx, st_c) + wk.scatter_(1, cidx, wk_c) + st[:, 0] = True + st[:, self.forbidden] = False + wk[:, self.forbidden] = False + wk[:, 0] = False + strong[c0 : c0 + c] = st + weak[c0 : c0 + c] = wk + sg_all[c0 : c0 + c] = sg + return strong, weak, sg_all + + def _bucket(self, s, sub, strong, weak, sg, out, c0): + b = sub.shape[0] + st, wk, sgs = strong[sub], weak[sub], sg[sub] + s_idx = st.nonzero(as_tuple=False)[:, 1].reshape(b, s) # ascending -> g0 first + sg_s = sgs.gather(1, s_idx) # [b, s] + + wc = wk.sum(1) + w_max = int(wc.max().item()) if b else 0 + a = self.u_pair[s_idx[:, :, None], s_idx[:, None, :]] + weak_diag = torch.zeros(b, s, device=self.tdev, dtype=self.rdtype) + if w_max > 0: + nz = wk.nonzero(as_tuple=False) # [T, 2], row-sorted + rows, cols = nz[:, 0], nz[:, 1] + starts = torch.zeros(b, dtype=torch.long, device=self.tdev) + starts[1:] = wc.cumsum(0)[:-1] + within = torch.arange(rows.shape[0], device=self.tdev) - starts[rows] + w_idx = torch.zeros(b, w_max, dtype=torch.long, device=self.tdev) + w_ok = torch.zeros(b, w_max, dtype=torch.bool, device=self.tdev) + w_idx[rows, within] = cols + w_ok[rows, within] = True + sg_w = sgs.gather(1, w_idx) + inv_sgw = torch.where(w_ok, 1.0 / sg_w, torch.zeros_like(sg_w)) + u_gw = self.u_pair[s_idx[:, :, None], w_idx[:, None, :]] + u_wh = self.u_pair[w_idx[:, :, None], s_idx[:, None, :]] + a = a - 0.5 * self.lam * torch.matmul(u_gw * inv_sgw[:, None, :], u_wh) + weak_diag = 0.5 * self.lam * (u_gw.abs() ** 2 * inv_sgw[:, None, :]).sum(2) + + di = torch.arange(s, device=self.tdev) + diag = (2.0 * sg_s / self.lam - weak_diag).to(self.cdtype) + 1j * self.upz0 + a[:, di, di] = diag + + sgh = self.sgh_pair[s_idx[:, :, None], s_idx[:, None, :]] # [g,h]=h-g + inten = self._depth_intensity(a, sgh) / self.n_atoms + out[sub + c0] = inten.to(self.out_dtype) diff --git a/src/de_ebsd/sim/simulator.py b/src/de_ebsd/sim/simulator.py index 0c193d9..6a94f56 100644 --- a/src/de_ebsd/sim/simulator.py +++ b/src/de_ebsd/sim/simulator.py @@ -54,10 +54,10 @@ class MasterPatternSimulator: Energy/depth statistics for the depth integration (required by the the Bloch-wave backends; when omitted, a native Monte Carlo is run). backend - ``"bloch_prism"`` (default), ``"bloch"``, or any + ``"bloch_smatrix"`` (default), ``"bloch"``, or any :class:`~de_ebsd.diffraction.backends.MasterPatternBackend` instance. Both named backends solve the same Bloch-wave model. ``"bloch"`` is the - float64 reference, one direction at a time; ``"bloch_prism"`` batches it + float64 reference, one direction at a time; ``"bloch_smatrix"`` batches it on the GPU and reproduces it (r = 1.0000 against the EMsoft master of Si at npx = 500), so it is the default. """ @@ -70,7 +70,7 @@ def __init__( dmin: float = 0.1, bethe: BetheParameters | None = None, monte_carlo: DepthDistribution | None = None, - backend: str | MasterPatternBackend = "bloch_prism", + backend: str | MasterPatternBackend = "bloch_smatrix", ) -> None: if npx < 1: raise ValueError("npx must be >= 1") diff --git a/src/de_ebsd/viz/depth_widget.js b/src/de_ebsd/viz/depth_widget.js index f64ce99..24d3e1a 100644 --- a/src/de_ebsd/viz/depth_widget.js +++ b/src/de_ebsd/viz/depth_widget.js @@ -67,7 +67,7 @@ function render({model,el}) { const cum=p.slice(0,selected+1).reduce((a,b)=>a+b,0); host.querySelector('.detail').textContent=`Slice ${selected+1}: ${selected*dz}–${(selected+1)*dz} nm · `+ `yield ${p[selected].toPrecision(4)} · cumulative ${total?(100*cum/total).toFixed(2):'0.00'}% of this energy's yield. `+ - `${selected 0 # real dynamical contrast @@ -48,7 +62,7 @@ def test_prism_matches_bloch_reference(si_sf): assert ((ip - io).abs().max() / denom).item() < 1e-9 -def test_prism_batches_across_strong_counts(si_sf): +def test_smatrix_batches_across_strong_counts(si_sf): """Directions spanning many strong-beam counts (multiple buckets) all match.""" inp = SimulationInputs( structure_factors=si_sf, @@ -59,17 +73,17 @@ def test_prism_batches_across_strong_counts(si_sf): ) oracle = resolve_backend("bloch") oracle.prepare(inp) - prism = resolve_backend("bloch_prism") - prism.prepare(inp) + smatrix = resolve_backend("bloch_smatrix") + smatrix.prepare(inp) d = _dirs(64, seed=2) io = oracle.intensities(d) - ip = prism.intensities(d) + ip = smatrix.intensities(d) denom = io.abs().max().clamp_min(1e-30) assert ((ip - io).abs().max() / denom).item() < 1e-9 -def test_prism_complex64_matches_reference(si_sf): +def test_smatrix_complex64_matches_reference(si_sf): """The complex64 (production-fast) path tracks the fp64 reference to ~1e-4. complex128 is exact against the eig reference; complex64 trades a little @@ -86,7 +100,7 @@ def test_prism_complex64_matches_reference(si_sf): oracle = resolve_backend("bloch") oracle.prepare(inp64) - prism = BlochPrismBackend(cdtype=torch.complex64) + smatrix = BlochScatteringMatrixBackend(cdtype=torch.complex64) inp32 = SimulationInputs( structure_factors=si_sf, bethe=BetheParameters(), @@ -94,26 +108,26 @@ def test_prism_complex64_matches_reference(si_sf): device=torch.device("cpu"), dtype=torch.float32, ) - prism.prepare(inp32) + smatrix.prepare(inp32) d = _dirs(24, seed=1) io = oracle.intensities(d) - ip = prism.intensities(d) + ip = smatrix.intensities(d) assert ip.dtype == torch.float32 denom = io.abs().max().clamp_min(1e-30) assert ((ip.double() - io).abs().max() / denom).item() < 1e-3 def test_bloch_solve_is_differentiable(si_sf): - """Autograd flows through the prism Bloch solve to the structure factors. + """Autograd flows through the scattering-matrix Bloch solve to the structure factors. The production backend is torch-native (matrix_exp + a depth recurrence), so gradients propagate through the non-Hermitian complex Bloch solve, the weak-beam folding, and the Sgh reduction back to U_g -- the differentiability the project is built for. Validated against complex finite differences. """ - prism = resolve_backend("bloch_prism") - prism.prepare( + smatrix = resolve_backend("bloch_smatrix") + smatrix.prepare( SimulationInputs( structure_factors=si_sf, bethe=BetheParameters(), @@ -122,23 +136,23 @@ def test_bloch_solve_is_differentiable(si_sf): dtype=torch.float64, ) ) - u0 = prism.u_lut.detach().clone() - prism.u_lut = u0.clone().requires_grad_(True) + u0 = smatrix.u_lut.detach().clone() + smatrix.u_lut = u0.clone().requires_grad_(True) d = _dirs(4, seed=0) - intensity = prism.intensities(d) + intensity = smatrix.intensities(d) assert intensity.requires_grad intensity.sum().backward() - grad = prism.u_lut.grad + grad = smatrix.u_lut.grad assert grad is not None and torch.isfinite(grad).all() and bool((grad.abs() > 0).any()) # complex finite-difference check on the most influential U_g entry idx = np.unravel_index(int(grad.abs().flatten().argmax()), grad.shape) def total(pert): - prism.u_lut = u0.clone() - prism.u_lut[idx] = prism.u_lut[idx] + pert - return float(prism.intensities(d).sum()) + smatrix.u_lut = u0.clone() + smatrix.u_lut[idx] = smatrix.u_lut[idx] + pert + return float(smatrix.intensities(d).sum()) eps = 1e-4 g_re_fd = (total(eps) - total(-eps)) / (2 * eps) @@ -149,7 +163,7 @@ def total(pert): def test_intensity_differentiable_wrt_positions(si_sf): - """End-to-end: atom positions -> torch structure factors -> prism Bloch solve + """End-to-end: atom positions -> torch structure factors -> scattering-matrix Bloch solve -> intensity, with the gradient matching finite differences. This closes the differentiable chain from a crystal parameter to the master- @@ -158,8 +172,8 @@ def test_intensity_differentiable_wrt_positions(si_sf): from de_ebsd.crystal.structure_factors import differentiable_ucg_lut crystal = si_sf.crystal - prism = resolve_backend("bloch_prism") - prism.prepare( + smatrix = resolve_backend("bloch_smatrix") + smatrix.prepare( SimulationInputs( structure_factors=si_sf, bethe=BetheParameters(), @@ -175,10 +189,10 @@ def total(shift): pos = [b.clone() for b in base] pos[0] = pos[0].clone() pos[0][0, 0] = pos[0][0, 0] + shift - prism.u_lut = differentiable_ucg_lut( + smatrix.u_lut = differentiable_ucg_lut( crystal, si_sf.energy_kev, si_sf.dmin, positions=pos ).to(torch.complex128) - return prism.intensities(d).sum() + return smatrix.intensities(d).sum() s = torch.zeros((), dtype=torch.float64, requires_grad=True) total(s).backward() @@ -190,12 +204,12 @@ def total(shift): def test_intensity_differentiable_wrt_debye_waller(si_sf): """End-to-end d(intensity)/d(Debye-Waller) through the torch WK amplitude, - the structure factors, and the prism Bloch solve, matching finite diffs.""" + the structure factors, and the scattering-matrix Bloch solve, matching finite diffs.""" from de_ebsd.crystal.structure_factors import differentiable_ucg_lut crystal = si_sf.crystal - prism = resolve_backend("bloch_prism") - prism.prepare( + smatrix = resolve_backend("bloch_smatrix") + smatrix.prepare( SimulationInputs( structure_factors=si_sf, bethe=BetheParameters(), @@ -208,10 +222,10 @@ def test_intensity_differentiable_wrt_debye_waller(si_sf): b0 = float(crystal.sites[0].debye_waller) def total(bval): - prism.u_lut = differentiable_ucg_lut( + smatrix.u_lut = differentiable_ucg_lut( crystal, si_sf.energy_kev, si_sf.dmin, debye_waller=[bval] ).to(torch.complex128) - return prism.intensities(d).sum() + return smatrix.intensities(d).sum() b = torch.tensor(b0, dtype=torch.float64, requires_grad=True) total(b).backward() diff --git a/upcoming_changes/+scattering-matrix.deprecation.rst b/upcoming_changes/+scattering-matrix.deprecation.rst new file mode 100644 index 0000000..7c425da --- /dev/null +++ b/upcoming_changes/+scattering-matrix.deprecation.rst @@ -0,0 +1 @@ +The scattering-matrix backend is now ``backend="bloch_smatrix"`` and :class:`~de_ebsd.diffraction.BlochScatteringMatrixBackend` (module :mod:`de_ebsd.diffraction.smatrix`): it is Sturkey's scattering-matrix form of the Bloch-wave solve, not Ophus's PRISM, whose name it carried. ``"bloch_prism"``, ``BlochPrismBackend`` and ``de_ebsd.diffraction.prism`` still work, with a DeprecationWarning, and go in a later release. Results are unchanged. From 9b6da5d0f09e598bf83d7693001f1daea98a8a53 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Fri, 13 Nov 2026 10:45:08 -0600 Subject: [PATCH 2/2] Keep the renamed example's line within 100 characters Claude-Session: https://claude.ai/code/session_01DzXsKAUJSM4XYpqqzrcuV5 --- examples/simulation/resolution_and_backends.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/simulation/resolution_and_backends.py b/examples/simulation/resolution_and_backends.py index ac6384e..f88f9b5 100644 --- a/examples/simulation/resolution_and_backends.py +++ b/examples/simulation/resolution_and_backends.py @@ -180,7 +180,7 @@ scale = reference.data.abs().max().clamp_min(1e-30) relative_max = (coarse.data - reference.data).abs().max() / scale assert torch.isfinite(relative_max) and relative_max < 1e-7 -print(f"Scattering matrix versus eigendecomposition maximum relative difference: {relative_max.item():.3e}") +print(f"Scattering matrix vs eigendecomposition, max relative diff: {relative_max.item():.3e}") # %% # Continue a convergence study