de-ebsd 0.2.0__py3-none-any.whl

de_ebsd/crystal/structure_factors.py

@@ -0,0 +1,291 @@
+"""Structure factors U_g for every reflection within ``dmin``.
+
+Sums Weickenmeier-Kohl form factors over the symmetry-expanded basis. Provides
+the numpy path (:func:`compute_structure_factors`) used by the Bloch-wave
+backend and a differentiable lookup (:func:`differentiable_ucg_lut`). Follows
+EMsoft ``CalcUcg`` (Weickenmeier-Kohl branch).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+import torch
+
+from de_ebsd.core.constants import C_PI, DWWK, PREF_COEF, PREG, SWK, electron_wavelength_nm
+from de_ebsd.core.device import resolve_device
+from de_ebsd.crystal.lattice import Crystal
+from de_ebsd.crystal.scattering import atomic_number, wk_scattering_factor
+from de_ebsd.crystal.scattering_torch import wk_scattering_factor_torch
+
+if TYPE_CHECKING:
+    from anyplotlib import Figure
+
+__all__ = ["StructureFactors", "compute_structure_factors", "differentiable_ucg_lut"]
+
+
+@dataclass
+class StructureFactors:
+    """Structure factors of a crystal at one beam energy (inspectable stage).
+
+    Attributes
+    ----------
+    crystal, energy_kev, dmin
+        The inputs that produced this table.
+    hmax
+        Largest Miller index with d >= dmin along any axis; the lookup table
+        spans ``-2 hmax .. 2 hmax`` per axis so any difference of two
+        reflections in the sphere is available.
+    ucg_lut
+        Complex U_g in nm^-2, shape (4 hmax + 1,) * 3, indexed
+        ``[h + 2 hmax, k + 2 hmax, l + 2 hmax]``.
+    v0
+        Mean inner potential in volts.
+    upz0
+        Normal absorption coefficient U'_0 in nm^-2.
+    wavelength
+        Relativistic electron wavelength in nm, refraction corrected with v0.
+    normal_absorption_length
+        Normal absorption length ``1 / (U'_0 lambda)`` in nm (EMsoft ``xgp``
+        for g = 0), used to correct the Monte Carlo depth profile.
+    hkl, g, d, ucg
+        Flat listing of the reflections with 0 < g and d >= dmin that are
+        allowed by the lattice centering, sorted by g: Miller indices (N, 3),
+        lengths (N,) in nm^-1, spacings (N,) in nm and complex U_g (N,).
+    """
+
+    crystal: Crystal
+    energy_kev: float
+    dmin: float
+    hmax: int
+    ucg_lut: np.ndarray
+    v0: float
+    upz0: float
+    wavelength: float
+    hkl: np.ndarray = field(repr=False)
+    g: np.ndarray = field(repr=False)
+    d: np.ndarray = field(repr=False)
+    ucg: np.ndarray = field(repr=False)
+
+    @property
+    def normal_absorption_length(self) -> float:
+        """Normal absorption length 1 / (U'_0 lambda) in nm."""
+        if self.upz0 <= 0:
+            return 1.0e8
+        return 1.0 / (self.upz0 * self.wavelength)
+
+    def lookup(self, hkl: np.ndarray) -> np.ndarray:
+        """U_g for Miller indices (..., 3); indices must lie within the table."""
+        hkl = np.asarray(hkl, dtype=np.int64)
+        if np.any(np.abs(hkl) > 2 * self.hmax):
+            raise IndexError(f"|hkl| exceeds the lookup range 2*hmax = {2 * self.hmax}")
+        idx = hkl + 2 * self.hmax
+        return self.ucg_lut[idx[..., 0], idx[..., 1], idx[..., 2]]
+
+    def families(self, n: int | None = None) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Group the reflection list by ``|g|``; representative hkl, g, and U_g.
+
+        Returns the first ``n`` (or all) families sorted by g length.
+        """
+        keys = np.round(self.g, 6)
+        _, first = np.unique(keys, return_index=True)
+        order = np.sort(first)
+        if n is not None:
+            order = order[:n]
+        return self.hkl[order], self.g[order], self.ucg[order]
+
+    def show(self, n: int = 25) -> Figure:
+        """Bar chart of ``|U_g|`` for the first ``n`` reflection families.
+
+        Systematic absences appear as (near-)zero bars.
+        """
+        from de_ebsd.viz.figures import bar_figure
+
+        hkl, g, ucg = self.families(n)
+        labels = [f"{h} {k} {l_}" for h, k, l_ in hkl]
+        return bar_figure(
+            np.abs(ucg),
+            labels,
+            title=f"|U_g| [nm^-2] at {self.energy_kev:g} keV (V0 = {self.v0:.2f} V)",
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"StructureFactors({self.crystal!r}, energy={self.energy_kev:g} keV, "
+            f"dmin={self.dmin:g} nm, {len(self.hkl)} reflections, "
+            f"V0={self.v0:.2f} V, lambda={self.wavelength * 1e3:.4f} pm)"
+        )
+
+
+def _hmax_for_dmin(crystal: Crystal, dmin: float) -> int:
+    hmax = 0
+    for axis in range(3):
+        h = 1
+        while True:
+            hkl = np.zeros(3)
+            hkl[axis] = h
+            if crystal.d_spacing(hkl) < dmin:
+                break
+            h += 1
+            if h > 200:
+                raise ValueError("dmin is unreasonably small for this lattice")
+        hmax = max(hmax, h)
+    return hmax
+
+
+def compute_structure_factors(
+    crystal: Crystal,
+    energy_kev: float,
+    dmin: float,
+    absorption: bool = True,
+) -> StructureFactors:
+    """Compute U_g over the full lookup box for one beam energy.
+
+    Parameters
+    ----------
+    crystal
+        The crystal.
+    energy_kev
+        Beam energy in keV (numerically equal to the accelerating voltage
+        in kV).
+    dmin
+        Smallest interplanar spacing to include, in nm.
+    absorption
+        Include the WK absorptive parts (imaginary U''_g).
+    """
+    hmax = _hmax_for_dmin(crystal, dmin)
+    m = 2 * hmax
+    rng = np.arange(-m, m + 1)
+    h, k, l = np.meshgrid(rng, rng, rng, indexing="ij")  # noqa: E741
+    hkl_box = np.stack([h, k, l], axis=-1).reshape(-1, 3)
+
+    g_len = crystal.g_length(hkl_box)  # nm^-1
+    g_wk = g_len * SWK  # WK units
+
+    # Scattering factors depend on the element and |g| only: evaluate on the
+    # unique lengths and scatter back.
+    g_unique, inverse = np.unique(np.round(g_wk, 9), return_inverse=True)
+
+    volume = crystal.volume
+    pref = PREF_COEF / volume / (4.0 * C_PI)
+    pre = pref * PREG
+
+    ff = np.zeros(len(hkl_box), dtype=np.complex128)
+    gg = np.zeros(len(hkl_box), dtype=np.complex128)
+    for site, positions in zip(crystal.sites, crystal.positions, strict=True):
+        z = atomic_number(site.element)
+        ul = float(np.sqrt(site.debye_waller * DWWK))
+        structure_factors = wk_scattering_factor(z, g_unique, ul, energy_kev, absorption=absorption)
+        structure_factors = structure_factors[inverse] * site.occupancy
+        phase = np.exp(-2j * np.pi * (hkl_box @ positions.T)).sum(axis=1)
+        ff += phase * structure_factors.real
+        gg += phase * structure_factors.imag
+
+    if absorption:
+        ucg = pre * (ff + 1j * gg)
+    else:
+        ucg = pre * ff
+
+    center = len(hkl_box) // 2  # index of (0, 0, 0)
+    v0 = float(pref * np.abs(ff[center]))
+    upz0 = float(PREG * pref * np.abs(gg[center])) if absorption else 0.0
+    wavelength = electron_wavelength_nm(energy_kev, v0mod=v0)
+
+    # Flat reflection listing for inspection: allowed by centering, inside the
+    # dmin sphere, g > 0, sorted by g.
+    keep = (g_len > 0) & (1.0 / np.maximum(g_len, 1e-12) >= dmin)
+    keep &= crystal.allowed_by_centering(hkl_box)
+    keep &= np.all(np.abs(hkl_box) <= hmax, axis=1)
+    order = np.argsort(g_len[keep], kind="stable")
+    hkl_list = hkl_box[keep][order]
+    g_list = g_len[keep][order]
+
+    n = 4 * hmax + 1
+    return StructureFactors(
+        crystal=crystal,
+        energy_kev=float(energy_kev),
+        dmin=float(dmin),
+        hmax=hmax,
+        ucg_lut=ucg.reshape(n, n, n),
+        v0=v0,
+        upz0=upz0,
+        wavelength=float(wavelength),
+        hkl=hkl_list,
+        g=g_list,
+        d=1.0 / g_list,
+        ucg=ucg[keep][order],
+    )
+
+
+def differentiable_ucg_lut(
+    crystal: Crystal,
+    energy_kev: float,
+    dmin: float,
+    *,
+    positions: list[torch.Tensor] | None = None,
+    occupancies: list[torch.Tensor] | None = None,
+    debye_waller: list[torch.Tensor] | None = None,
+    absorption: bool = True,
+    device: torch.device | str | None = None,
+    dtype: torch.dtype = torch.complex128,
+) -> torch.Tensor:
+    """Assemble the ``U_g`` lookup table in torch, differentiable in the crystal.
+
+    ``U_g = pre * sum_site occ_site * f_site(g) * sum_r exp(-2 pi i g.r)``. All
+    three parameter groups are differentiable when passed as ``requires_grad``
+    tensors:
+
+    - **positions** -- the structure-factor phase ``sum_r exp(-2 pi i g.r)``;
+    - **occupancies** -- the linear per-site weight;
+    - **debye_waller** (``B`` in nm^2, one per site) -- feeds the torch WK
+      amplitude (:func:`de_ebsd.crystal.scattering_torch.wk_scattering_factor_torch`),
+      so ``U_g`` differentiates w.r.t. the thermal factor.
+
+    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
+    ``d(intensity)/d(crystal parameter)``. Lattice gradients (through ``g``)
+    remain a further step.
+    """
+    dev = resolve_device(device)
+    hmax = _hmax_for_dmin(crystal, dmin)
+    m = 2 * hmax
+    rng = np.arange(-m, m + 1)
+    h, k, ll = np.meshgrid(rng, rng, rng, indexing="ij")
+    hkl_box = np.stack([h, k, ll], axis=-1).reshape(-1, 3)
+    g_wk = crystal.g_length(hkl_box) * SWK
+    g_unique, inverse = np.unique(np.round(g_wk, 9), return_inverse=True)
+    pre = PREF_COEF / crystal.volume / (4.0 * C_PI) * PREG
+
+    hkl_t = torch.as_tensor(hkl_box, device=dev, dtype=torch.float64)
+    inverse_t = torch.as_tensor(inverse, device=dev)
+    g_unique_t = torch.as_tensor(g_unique, device=dev, dtype=torch.float64)
+    if positions is None:
+        positions = [torch.as_tensor(p, device=dev, dtype=torch.float64) for p in crystal.positions]
+    if occupancies is None:
+        occupancies = [
+            torch.as_tensor(s.occupancy, device=dev, dtype=torch.float64) for s in crystal.sites
+        ]
+    dw = debye_waller if debye_waller is not None else [None] * len(crystal.sites)
+
+    ucg = torch.zeros(len(hkl_box), device=dev, dtype=dtype)
+    for site, pos, occ, b in zip(crystal.sites, positions, occupancies, dw, strict=True):
+        z = atomic_number(site.element)
+        if b is None:  # detached WK amplitude (numpy)
+            ul = float(np.sqrt(site.debye_waller * DWWK))
+            f = wk_scattering_factor(z, g_unique, ul, energy_kev, absorption=absorption)
+            f_t = torch.as_tensor(f, device=dev, dtype=dtype)[inverse_t]
+        else:  # torch WK amplitude, differentiable in the Debye-Waller factor
+            ul = torch.sqrt(b.to(dev, torch.float64) * DWWK)
+            f_unique = wk_scattering_factor_torch(
+                z, g_unique_t, ul, energy_kev, absorption=absorption
+            )
+            f_t = f_unique.to(dtype)[inverse_t]
+        # structure-factor phase sum over the site's atoms (differentiable in pos)
+        phase = torch.exp(-2j * np.pi * (hkl_t @ pos.to(dev, torch.float64).T)).sum(dim=1)
+        ucg = ucg + pre * occ.to(dev, dtype) * f_t * phase
+
+    n = 4 * hmax + 1
+    return ucg.reshape(n, n, n)

de_ebsd/diffraction/__init__.py

@@ -0,0 +1,45 @@
+"""Dynamical electron diffraction: reflection lists, Bethe potentials, Bloch waves."""
+
+from de_ebsd.diffraction.backends import (
+    BlochWaveBackend,
+    DynamicalMatrix,
+    MasterPatternBackend,
+    SimulationInputs,
+    build_dynamical_matrix,
+    classify_reflections,
+    resolve_backend,
+)
+from de_ebsd.diffraction.bethe import BetheParameters
+from de_ebsd.diffraction.kvectors import (
+    KVectorGrid,
+    reduce_to_fundamental_sector,
+    sample_incident_directions,
+)
+from de_ebsd.diffraction.prism import BlochPrismBackend
+from de_ebsd.diffraction.reflections import (
+    ReflectionList,
+    candidate_reflections,
+    excitation_errors,
+    master_reflection_list,
+    partition_strong_weak,
+)
+
+__all__ = [
+    "BetheParameters",
+    "BlochPrismBackend",
+    "BlochWaveBackend",
+    "DynamicalMatrix",
+    "KVectorGrid",
+    "MasterPatternBackend",
+    "ReflectionList",
+    "SimulationInputs",
+    "build_dynamical_matrix",
+    "candidate_reflections",
+    "classify_reflections",
+    "excitation_errors",
+    "master_reflection_list",
+    "partition_strong_weak",
+    "reduce_to_fundamental_sector",
+    "resolve_backend",
+    "sample_incident_directions",
+]

de_ebsd/diffraction/backends.py

@@ -0,0 +1,318 @@
+"""Master-pattern backends: how a set of incident directions becomes intensity.
+
+: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``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+import torch
+
+from de_ebsd.crystal.scattering import atomic_number
+from de_ebsd.crystal.structure_factors import StructureFactors
+from de_ebsd.diffraction.bethe import BetheParameters
+from de_ebsd.diffraction.reflections import (
+    STRONG,
+    WEAK,
+    ReflectionList,
+    candidate_reflections,
+    excitation_errors,
+    master_reflection_list,
+    partition_strong_weak,
+)
+
+if TYPE_CHECKING:
+    from anyplotlib import Figure
+
+    from de_ebsd.sim.montecarlo.depth import DepthDistribution
+
+__all__ = [
+    "DynamicalMatrix",
+    "MasterPatternBackend",
+    "BlochWaveBackend",
+    "build_dynamical_matrix",
+    "classify_reflections",
+]
+
+
+def classify_reflections(
+    structure_factors: StructureFactors,
+    k_hat: np.ndarray,
+    bethe: BetheParameters,
+) -> ReflectionList:
+    """Candidate + strong/weak classification for one beam direction.
+
+    ``k_hat`` is a unit vector in the Cartesian crystal frame.
+    """
+    refl = master_reflection_list(structure_factors)
+    k = torch.as_tensor(k_hat, dtype=torch.float64)
+    g_cart = torch.as_tensor(structure_factors.crystal.g_cartesian(refl.hkl), dtype=torch.float64)
+    sg = excitation_errors(g_cart, k, structure_factors.wavelength).numpy()
+
+    keep = candidate_reflections(refl, sg, structure_factors.wavelength, bethe)
+    # prepend the incident beam g = 0
+    hkl = np.concatenate([np.zeros((1, 3), dtype=np.int64), refl.hkl[keep]])
+    sg_c = np.concatenate([[0.0], sg[keep]])
+    u_mod = np.concatenate(
+        [[np.abs(structure_factors.lookup(np.zeros(3, dtype=np.int64)))], refl.u_mod[keep]]
+    )
+    forbidden = np.concatenate([[False], refl.forbidden[keep]])
+
+    status = partition_strong_weak(hkl, sg_c, forbidden, structure_factors, bethe)
+    g_len = structure_factors.crystal.g_length(hkl)
+    return ReflectionList(
+        hkl=hkl,
+        g=g_len,
+        d=1.0 / np.maximum(g_len, 1e-12),
+        u_mod=u_mod,
+        forbidden=forbidden,
+        k=np.asarray(k_hat, dtype=np.float64),
+        sg=sg_c,
+        status=status,
+    )
+
+
+def build_dynamical_matrix(structure_factors: StructureFactors, refl: ReflectionList) -> np.ndarray:
+    """The Bloch dynamical matrix A (complex, nm^-2) for one classified list.
+
+    Port of EMsoft ``GetDynMat`` (Bloch branch, with Bethe corrections).
+    """
+    if refl.status is None or refl.sg is None:
+        raise ValueError("reflection list must be classified for one beam direction")
+    strong = refl.status == STRONG
+    weak = refl.status == WEAK
+    hkl_s = refl.hkl[strong]
+    hkl_w = refl.hkl[weak]
+    sg_s = refl.sg[strong]
+    sg_w = refl.sg[weak]
+    lam = structure_factors.wavelength
+
+    diff = hkl_s[:, None, :] - hkl_s[None, :, :]
+    a = structure_factors.lookup(diff).astype(np.complex128)  # off-diagonal U_{g-h}
+
+    if len(hkl_w) > 0:
+        u_gw = structure_factors.lookup(hkl_s[:, None, :] - hkl_w[None, :, :])  # (Ns, Nw)
+        u_wh = structure_factors.lookup(hkl_w[:, None, :] - hkl_s[None, :, :])  # (Nw, Ns)
+        a -= 0.5 * lam * (u_gw / sg_w[None, :]) @ u_wh
+        weak_diag = 0.5 * lam * (np.abs(u_gw) ** 2 / sg_w[None, :]).sum(axis=1)
+    else:
+        weak_diag = np.zeros(len(hkl_s))
+
+    np.fill_diagonal(a, 2.0 * sg_s / lam - weak_diag + 1j * structure_factors.upz0)
+    return a
+
+
+@dataclass
+class DynamicalMatrix:
+    """The dynamical matrix for one beam direction (inspectable stage)."""
+
+    matrix: np.ndarray
+    hkl: np.ndarray
+    k: np.ndarray
+    reflections: ReflectionList
+
+    @property
+    def n_beams(self) -> int:
+        return self.matrix.shape[0]
+
+    def show(self) -> Figure:
+        """Heat map of ``log10 |A_gh|``."""
+        from de_ebsd.viz.figures import image_figure
+
+        with np.errstate(divide="ignore"):
+            image = np.log10(np.maximum(np.abs(self.matrix), 1e-12))
+        return image_figure(
+            image,
+            title=f"log10 |A| for k = {np.round(self.k, 4)} ({self.n_beams} strong beams)",
+            cmap="viridis",
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"DynamicalMatrix({self.n_beams} strong beams, "
+            f"{self.reflections.n_weak} weak folded in, k={np.round(self.k, 4)})"
+        )
+
+
+@dataclass
+class SimulationInputs:
+    """Everything a backend needs, prepared once by the simulator."""
+
+    structure_factors: StructureFactors
+    bethe: BetheParameters
+    monte_carlo: DepthDistribution | None
+    device: torch.device
+    dtype: torch.dtype
+
+
+class MasterPatternBackend(ABC):
+    """Interface every master-pattern intensity backend implements.
+
+    A backend receives a batch of unit incident-beam directions (Cartesian
+    crystal frame) and returns one backscatter intensity per direction. The
+    simulator handles gridding, chunking, and assembly into the Lambert maps.
+    """
+
+    name: str = "abstract"
+    #: whether this backend consumes a Monte Carlo exit-depth profile; the
+    #: simulator builds a native one (EMsoft-free) when the user supplies none.
+    uses_depth_profile: bool = False
+
+    @abstractmethod
+    def prepare(self, inputs: SimulationInputs) -> None:
+        """Build and cache per-simulation tensors on the target device."""
+
+    @abstractmethod
+    def intensities(self, directions: torch.Tensor) -> torch.Tensor:
+        """Intensities (K,) for unit directions (K, 3). Called after prepare."""
+
+
+def calc_lgh(
+    a: np.ndarray,
+    kn: float,
+    thick: float,
+    depthstep: float,
+    lambda_e: np.ndarray,
+    gzero: int,
+) -> np.ndarray:
+    """The depth-integrated intensity matrix L_gh (EMsoft ``CalcLgh``).
+
+    Eigendecompose the dynamical matrix ``a`` (complex, nm^-2), scale
+    eigenvalues by ``1/(2 kn)``, and integrate the Bloch-wave interference
+    against the Monte Carlo exit-depth profile ``lambda_e`` (already corrected
+    for normal absorption), returning ``L_gh = conj(C) I C^T``.
+    """
+    w, c = np.linalg.eig(a)  # right eigenvectors are the columns of c (LAPACK zgeev)
+    c_inv = np.linalg.inv(c)
+    w = w / (2.0 * kn)
+    alpha = c_inv[:, gzero]  # incident-beam excitation amplitudes CGinv(:, gzero)
+
+    tpi = 2.0 * np.pi * depthstep
+    re, im = w.real, w.imag
+    q_re = tpi * (im[:, None] + im[None, :])  # real part of q_jk
+    q_im = tpi * (re[:, None] - re[None, :])  # imaginary part
+    qold = q_re + 1j * q_im
+    qold = np.where(q_re < 0.0, -qold, qold)  # fold the real part positive
+
+    # sum_z lambda_E[z] exp(-qold z) is a Horner polynomial in r = exp(-qold):
+    # sum_{z=1..Z} lambda_z r^z, evaluated with Z complex multiply-adds instead
+    # of materializing and exponentiating the full [S, S, Z] tensor -- identical
+    # to machine precision, ~20x fewer exponentials (the dominant cost here).
+    r = np.exp(-qold)
+    q = np.zeros_like(r)
+    for z in range(len(lambda_e), 0, -1):
+        q = q * r + lambda_e[z - 1]
+    q = q * r
+    ijk = np.conj(alpha)[:, None] * q * alpha[None, :] * (depthstep / thick)
+    return np.conj(c) @ ijk @ c.T
+
+
+class BlochWaveBackend(MasterPatternBackend):
+    """The physical Bloch-wave backend (EMsoft ``CalcLgh`` + ``Sgh``).
+
+    Per beam direction: classify reflections (Bethe), build the dynamical
+    matrix, eigendecompose and depth-integrate (:func:`calc_lgh`), weight with
+    the structure-factor-like ``Sgh`` matrix, and reduce to one backscatter
+    intensity ``I(k) = Re sum_gh L_gh S_gh / n_atoms``.
+
+    This is the float64 reference path (one direction at a time), the M2
+    correctness milestone; the batched GPU path (bucket by strong-beam count +
+    batched eig) is the follow-up optimization behind the same interface.
+    """
+
+    name = "bloch"
+    uses_depth_profile = True
+
+    def prepare(self, inputs: SimulationInputs) -> None:
+        from de_ebsd.sim.montecarlo.depth import DepthDistribution
+
+        self.structure_factors = inputs.structure_factors
+        self.bethe = inputs.bethe
+        self.device = inputs.device
+        self.out_dtype = inputs.dtype
+        crystal = inputs.structure_factors.crystal
+
+        # depth integration (EMsoft lambdaE / thick / izzmax, one energy bin)
+        energy = inputs.structure_factors.energy_kev
+        mc = inputs.monte_carlo or DepthDistribution.single_energy(energy)
+        izzmax = max(int(mc.integration_depths()[mc.energy_index(energy)]), 1)
+        self.depthstep = float(mc.depth_step)
+        self.thick = izzmax * self.depthstep
+        weights = mc.depth_weights(energy, inputs.structure_factors.normal_absorption_length)
+        self.lambda_e = np.ascontiguousarray(weights[:izzmax], dtype=np.float64)
+        self.kn = 1.0 / inputs.structure_factors.wavelength
+        self.gzero = 0
+        self.n_atoms = int(sum(p.shape[0] for p in crystal.positions))
+
+        self._build_sgh_lut(inputs.structure_factors, crystal)
+
+    def _build_sgh_lut(self, structure_factors: StructureFactors, crystal) -> None:
+        self.hmax = structure_factors.hmax
+        m = 2 * self.hmax
+        rng = np.arange(-m, m + 1)
+        hh, kk, ll = np.meshgrid(rng, rng, rng, indexing="ij")
+        box = np.stack([hh, kk, ll], axis=-1).reshape(-1, 3)
+        g2 = crystal.g_length(box) ** 2  # |h-g|^2 in the reciprocal frame
+
+        pos, z2occ, bfac = [], [], []
+        for site, positions in zip(crystal.sites, crystal.positions, strict=True):
+            z = atomic_number(site.element)
+            pos.append(positions)
+            z2occ.append(np.full(positions.shape[0], z**2 * site.occupancy))
+            bfac.append(np.full(positions.shape[0], site.debye_waller))
+        pos = np.concatenate(pos)
+        z2occ = np.concatenate(z2occ)
+        bfac = np.concatenate(bfac)
+
+        phase = np.exp(2j * np.pi * (box @ pos.T))
+        dwf = np.exp(-0.25 * g2[:, None] * bfac[None, :])
+        sgh = (phase * dwf * z2occ[None, :]).sum(axis=1)
+        n = 4 * self.hmax + 1
+        self.sgh_lut = sgh.reshape(n, n, n).astype(np.complex128)
+
+    def _sgh_matrix(self, hkl_strong: np.ndarray) -> np.ndarray:
+        diff = hkl_strong[None, :, :] - hkl_strong[:, None, :]  # [g, h] = h - g
+        idx = diff + 2 * self.hmax
+        return self.sgh_lut[idx[..., 0], idx[..., 1], idx[..., 2]]
+
+    def _intensity(self, k_hat: np.ndarray) -> float:
+        refl = classify_reflections(self.structure_factors, k_hat, self.bethe)
+        hkl_s = refl.hkl[refl.status == STRONG]
+        a = build_dynamical_matrix(self.structure_factors, refl)
+        lgh = calc_lgh(a, self.kn, self.thick, self.depthstep, self.lambda_e, self.gzero)
+        sgh = self._sgh_matrix(hkl_s)
+        return float(np.real(np.sum(lgh * sgh)) / self.n_atoms)
+
+    def intensities(self, directions: torch.Tensor) -> torch.Tensor:
+        dirs = directions.detach().cpu().numpy().astype(np.float64)
+        out = np.empty(dirs.shape[0], dtype=np.float64)
+        for i in range(dirs.shape[0]):
+            out[i] = self._intensity(dirs[i])
+        return torch.as_tensor(out, device=self.device, dtype=self.out_dtype)
+
+
+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
+
+    named = {
+        "bloch": BlochWaveBackend,
+        "bloch_prism": BlochPrismBackend,
+    }
+    try:
+        return named[backend]()
+    except KeyError:
+        raise ValueError(
+            f"unknown backend {backend!r}; expected one of {sorted(named)} "
+            "or a MasterPatternBackend instance"
+        ) from None

de_ebsd/diffraction/bethe.py

@@ -0,0 +1,28 @@
+"""Bethe potential cutoffs that split reflections into strong/weak/ignored.
+
+The scheme is EMsoft's ``Apply_BethePotentials``; the defaults here differ from
+EMsoft's own (4 / 8 / 50) and must be matched to compare against it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["BetheParameters"]
+
+
+@dataclass(frozen=True)
+class BetheParameters:
+    """Strong/weak/ignore thresholds for the Bethe-potential truncation."""
+
+    strong: float = 8.0
+    weak: float = 50.0
+    cutoff: float = 100.0
+    sg_double: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not 0 < self.strong < self.weak <= self.cutoff:
+            raise ValueError(
+                "require 0 < strong < weak <= cutoff, got "
+                f"strong={self.strong}, weak={self.weak}, cutoff={self.cutoff}"
+            )