de-ebsd 0.2.0__py3-none-any.whl

de_ebsd/index/spherical/wigner.py

@@ -0,0 +1,190 @@
+"""Wigner d/D matrices and the SOFT grid on SO(3).
+
+Real Wigner-d at beta = pi/2 by stable recursion, the (alpha, beta, gamma) SOFT
+sampling grid, and the bridge from ZYZ Euler angles to orix ``Rotation``.
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+__all__ = [
+    "euler_zyz_to_orix",
+    "grid_to_rotation",
+    "n_orientations",
+    "so3_grid",
+    "wigner_D",
+    "wigner_d",
+    "wigner_small_d",
+]
+
+
+def _small_d_generator(
+    ell: int, device: torch.device | str | None, dtype: torch.dtype
+) -> torch.Tensor:
+    n = 2 * ell + 1
+    k = torch.zeros((n, n), device=device, dtype=dtype)
+    if ell > 0:
+        i = torch.arange(2 * ell, device=device, dtype=dtype)
+        c = 0.5 * torch.sqrt((2 * ell - i) * (i + 1))  # coupling on the i-th sub-diagonal
+        idx = torch.arange(2 * ell, device=device)
+        k[idx + 1, idx] = -c  # (m+1, m)
+        k[idx, idx + 1] = c  # (m, m+1) = -(m+1, m) -> antisymmetric
+    return k
+
+
+def wigner_small_d(
+    ell: int,
+    beta: torch.Tensor,
+) -> torch.Tensor:
+    """Real small Wigner-d matrix ``d^l_{m'm}(beta)`` for a single degree ``ell``.
+
+    ``beta`` is a real tensor of any shape. Returns ``(*beta.shape, 2l+1, 2l+1)``
+    real, with row index ``m'`` and column index ``m`` (both ``-l .. l``), computed
+    as ``matrix_exp(beta * K_l)`` (the ``exp(-i beta J_y)`` convention).
+    """
+    k = _small_d_generator(ell, beta.device, beta.dtype)
+    mats = beta[..., None, None] * k  # (*beta.shape, n, n)
+    return torch.matrix_exp(mats)
+
+
+def wigner_d(
+    bandwidth: int,
+    beta: torch.Tensor,
+) -> torch.Tensor:
+    """Small Wigner-d matrices ``d^l_{m'm}(beta)`` for all ``l <= bandwidth``.
+
+    Returns a padded real tensor of shape ``(*beta.shape, L+1, 2L+1, 2L+1)``: axis
+    ``-3`` is the degree ``l = 0 .. L``, axes ``-2`` / ``-1`` are the orders
+    ``m' = idx - L`` (row) and ``m = idx - L`` (column). Entries with ``|m'| > l`` or
+    ``|m| > l`` are zero, so degree ``l`` occupies the centred ``(2l+1)``-block.
+    """
+    L = int(bandwidth)
+    out = beta.new_zeros((*beta.shape, L + 1, 2 * L + 1, 2 * L + 1))
+    for ell in range(L + 1):
+        d_l = wigner_small_d(ell, beta)  # (*beta.shape, 2l+1, 2l+1)
+        lo, hi = L - ell, L + ell + 1
+        out[..., ell, lo:hi, lo:hi] = d_l
+    return out
+
+
+def wigner_D(
+    bandwidth: int,
+    alpha: torch.Tensor,
+    beta: torch.Tensor,
+    gamma: torch.Tensor,
+) -> torch.Tensor:
+    """Full complex Wigner-D matrices ``D^l_{m'm}(alpha, beta, gamma)`` for ``l <= L``.
+
+    ``alpha``, ``beta``, ``gamma`` are real tensors, broadcast to a common shape
+    ``S``. Returns a padded complex tensor ``(*S, L+1, 2L+1, 2L+1)`` with
+
+        D^l_{m'm} = exp(-i m' alpha) d^l_{m'm}(beta) exp(-i m gamma),
+
+    row index ``m'`` (axis ``-2``), column index ``m`` (axis ``-1``), both
+    ``m = idx - L``. Entries outside ``|m'|, |m| <= l`` are zero.
+    """
+    L = int(bandwidth)
+    alpha, beta, gamma = torch.broadcast_tensors(alpha, beta, gamma)
+    d = wigner_d(L, beta)  # (*S, L+1, 2L+1, 2L+1), real
+    cdtype = torch.complex128 if d.dtype == torch.float64 else torch.complex64
+    orders = torch.arange(-L, L + 1, device=d.device, dtype=d.dtype)  # (2L+1,)
+    # row phase exp(-i m' alpha) and column phase exp(-i m gamma)
+    row_phase = torch.exp(-1j * orders * alpha[..., None].to(d.dtype))  # (*S, 2L+1)
+    col_phase = torch.exp(-1j * orders * gamma[..., None].to(d.dtype))  # (*S, 2L+1)
+    D = d.to(cdtype)
+    D = D * row_phase[..., None, :, None]  # broadcast over degree and column
+    D = D * col_phase[..., None, None, :]  # broadcast over degree and row
+    return D
+
+
+def so3_grid(
+    bandwidth: int,
+    device: torch.device | str | None = None,
+    dtype: torch.dtype = torch.float64,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """The equiangular SOFT SO(3) sampling grid for bandwidth ``L``.
+
+    Returns the three 1-D angle vectors ``(alpha, beta, gamma)`` of the separable
+    grid, each of length ``N = 2L + 2`` (SOFT bandwidth ``B = L + 1``):
+
+    - ``alpha[j] = 2 pi j / N`` and ``gamma[p] = 2 pi p / N`` -- equiangular in
+      ``[0, 2 pi)``, the Fourier grids conjugate to the orders ``m', m`` (so the
+      correlation is an inverse FFT over ``alpha`` and ``gamma``);
+    - ``beta[k] = pi (2k + 1) / (2 N)`` -- the ``2N``-point equiangular colatitude
+      grid in ``(0, pi)`` (no samples at the poles).
+
+    The cross-correlation returned by :func:`.so3_cross_correlation` is indexed
+    ``C[..., j, k, p]`` on this ``(alpha, beta, gamma)`` grid; :func:`grid_to_rotation`
+    converts an ``(j, k, p)`` index to an orix Rotation.
+    """
+    L = int(bandwidth)
+    n = 2 * L + 2
+    j = torch.arange(n, device=device, dtype=dtype)
+    alpha = 2.0 * math.pi * j / n
+    gamma = 2.0 * math.pi * j / n
+    beta = math.pi * (2.0 * j + 1.0) / (2.0 * n)
+    return alpha, beta, gamma
+
+
+def n_orientations(bandwidth: int) -> int:
+    """Number of SOFT grid points ``(2L + 2) ** 3`` for bandwidth ``L``."""
+    return (2 * bandwidth + 2) ** 3
+
+
+def euler_zyz_to_orix(
+    alpha,
+    beta,
+    gamma,
+):
+    """Convert active ``ZYZ`` Euler angles to an :class:`orix.quaternion.Rotation`.
+
+    ``alpha``, ``beta``, ``gamma`` are array-likes (numpy arrays, torch tensors, or
+    scalars, in radians) broadcast to a common shape. The returned Rotation has that
+    shape and satisfies ``R.to_matrix() == (R_z(alpha) R_y(beta) R_z(gamma))^T``:
+    the SOFT triple is passed to orix's Bunge (``ZXZ``) ``from_euler`` as
+    ``(alpha + pi/2, beta, gamma - pi/2)``.
+    """
+    import numpy as np
+    from orix.quaternion import Rotation
+
+    def _to_np(x):
+        if isinstance(x, torch.Tensor):
+            return x.detach().cpu().numpy()
+        return np.asarray(x, dtype=float)
+
+    a = _to_np(alpha)
+    b = _to_np(beta)
+    g = _to_np(gamma)
+    a, b, g = np.broadcast_arrays(a, b, g)
+    phi1 = a + np.pi / 2.0
+    Phi = b
+    phi2 = g - np.pi / 2.0
+    euler = np.stack([phi1, Phi, phi2], axis=-1)
+    return Rotation.from_euler(euler)
+
+
+def grid_to_rotation(
+    bandwidth: int,
+    alpha_index=None,
+    beta_index=None,
+    gamma_index=None,
+):
+    """Map SOFT grid indices to orix Rotations.
+
+    With no indices, returns the full grid as a Rotation of shape
+    ``(N, N, N)`` (``N = 2L + 2``) matching the ``C[..., j, k, p]`` correlation
+    layout -- index it directly with the peak location, e.g.
+    ``grid_to_rotation(L)[j, k, p]``. Passing ``alpha_index`` / ``beta_index`` /
+    ``gamma_index`` (ints or index arrays, broadcast together) returns the Rotation
+    at just those grid points. The conversion is :func:`euler_zyz_to_orix`.
+    """
+    alpha, beta, gamma = so3_grid(bandwidth)
+    if alpha_index is None and beta_index is None and gamma_index is None:
+        a, b, g = torch.meshgrid(alpha, beta, gamma, indexing="ij")
+        return euler_zyz_to_orix(a, b, g)
+    if alpha_index is None or beta_index is None or gamma_index is None:
+        raise ValueError("pass all three of alpha_index, beta_index, gamma_index, or none")
+    return euler_zyz_to_orix(alpha[alpha_index], beta[beta_index], gamma[gamma_index])

de_ebsd/sim/__init__.py

@@ -0,0 +1,20 @@
+"""Master-pattern generation: the simulator, its output, and the detector geometry.
+
+The crystallography lives in :mod:`de_ebsd.crystal`, the diffraction physics in
+:mod:`de_ebsd.diffraction`, and the electron transport in
+:mod:`de_ebsd.sim.montecarlo`.
+"""
+
+from de_ebsd.sim.detector import EBSDDetector
+from de_ebsd.sim.masterpattern import MasterPattern
+from de_ebsd.sim.microscope import Microscope
+from de_ebsd.sim.montecarlo import DepthDistribution
+from de_ebsd.sim.simulator import MasterPatternSimulator
+
+__all__ = [
+    "DepthDistribution",
+    "EBSDDetector",
+    "MasterPattern",
+    "MasterPatternSimulator",
+    "Microscope",
+]

de_ebsd/sim/detector.py

@@ -0,0 +1,145 @@
+"""EBSD detector geometry and per-pixel direction cosines.
+
+Torch port of kikuchipy's ``EBSDDetector`` (Bruker pattern-center convention),
+so patterns projected here match kikuchipy pixel for pixel.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+
+from de_ebsd.core.geometry import sample_to_detector_matrix
+
+__all__ = ["EBSDDetector"]
+
+
+@dataclass(frozen=True)
+class EBSDDetector:
+    """An EBSD detector with a fixed pattern center.
+
+    Parameters
+    ----------
+    shape
+        (n_rows, n_cols) in pixels.
+    pattern_center
+        Pattern center (PCx, PCy, PCz) in the Bruker convention.
+    sample_tilt
+        Sample tilt in degrees (usually set from ``Microscope.sample_tilt``).
+    tilt
+        Detector tilt in degrees.
+    azimuthal
+        Detector azimuthal angle in degrees.
+    twist
+        Detector twist about its normal, in degrees.
+    px_size
+        Effective screen pixel pitch in micrometers, including binning (not
+        camera sensor pitch). Used for physical dimensions in the inspector;
+        pattern projection itself only depends on the normalized PC.
+    """
+
+    shape: tuple[int, int] = (480, 480)
+    pattern_center: tuple[float, float, float] = (0.5, 0.5, 0.5)
+    sample_tilt: float = 70.0
+    tilt: float = 0.0
+    azimuthal: float = 0.0
+    twist: float = 0.0
+    px_size: float = 1.0
+
+    @property
+    def nrows(self) -> int:
+        return int(self.shape[0])
+
+    @property
+    def ncols(self) -> int:
+        return int(self.shape[1])
+
+    @property
+    def size(self) -> int:
+        return self.nrows * self.ncols
+
+    @property
+    def aspect_ratio(self) -> float:
+        return self.ncols / self.nrows
+
+    @property
+    def gnomonic_bounds(self) -> np.ndarray:
+        """Detector bounds [x_min, x_max, y_min, y_max] in gnomonic coordinates."""
+        pcx, pcy, pcz = self.pattern_center
+        x_min = -self.aspect_ratio * pcx / pcz
+        x_max = self.aspect_ratio * (1.0 - pcx) / pcz
+        y_min = -(1.0 - pcy) / pcz
+        y_max = pcy / pcz
+        return np.array([x_min, x_max, y_min, y_max])
+
+    @property
+    def corners_sample_mm(self) -> np.ndarray:
+        """Top-left clockwise corners relative to the beam impact, in mm.
+
+        Uses the same Bruker PC and frame transform as direction_cosines.
+        Physical distances assume px_size is the effective screen pixel pitch
+        (including binning), not the camera sensor's pixel pitch.
+        """
+        height = self.nrows * self.px_size / 1000.0
+        width = self.ncols * self.px_size / 1000.0
+        x, y, z = self.pattern_center
+        corners = np.array(
+            [
+                [-x * width, y * height, z * height],
+                [(1 - x) * width, y * height, z * height],
+                [(1 - x) * width, -(1 - y) * height, z * height],
+                [-x * width, -(1 - y) * height, z * height],
+            ]
+        )
+        return corners @ sample_to_detector_matrix(
+            self.sample_tilt, self.tilt, self.azimuthal, self.twist
+        )
+
+    @property
+    def pattern_center_sample_mm(self) -> np.ndarray:
+        """Perpendicular foot from impact to screen, in sample coordinates."""
+        distance = self.pattern_center[2] * self.nrows * self.px_size / 1000.0
+        return (
+            distance
+            * sample_to_detector_matrix(self.sample_tilt, self.tilt, self.azimuthal, self.twist)[2]
+        )
+
+    def direction_cosines(
+        self,
+        device: torch.device | str | None = None,
+        dtype: torch.dtype = torch.float32,
+    ) -> torch.Tensor:
+        """Unit direction vectors (n_rows * n_cols, 3) in the sample frame.
+
+        Row-major over the detector (row 0 = top). Port of kikuchipy
+        ``_get_direction_cosines_for_fixed_pc``.
+        """
+        bounds = self.gnomonic_bounds
+        pcz = self.pattern_center[2]
+        x_scale = (bounds[1] - bounds[0]) / self.ncols
+        y_scale = (bounds[3] - bounds[2]) / self.nrows
+
+        gn_x = bounds[0] + x_scale * np.arange(self.ncols) + 0.5 * x_scale
+        gn_y = bounds[3] - y_scale * np.arange(self.nrows) - 0.5 * y_scale
+
+        det = np.empty((self.nrows, self.ncols, 3))
+        det[..., 0] = gn_x[None, :] * pcz
+        det[..., 1] = gn_y[:, None] * pcz
+        det[..., 2] = pcz
+
+        om = sample_to_detector_matrix(self.sample_tilt, self.tilt, self.azimuthal, self.twist)
+        dc = det.reshape(-1, 3) @ om  # (det_to_sample = om.T; row vectors: v @ om)
+        dc /= np.linalg.norm(dc, axis=-1, keepdims=True)
+        return torch.as_tensor(dc, device=device, dtype=dtype)
+
+    def show(self, microscope=None, crystal=None):
+        """Interactive screen placement and PC editor, also exportable to HTML.
+
+        If a microscope is supplied, its sample tilt and azimuth must match.
+        Edits are a separate snapshot; read them with widget.to_detector().
+        """
+        from de_ebsd.viz.widgets import MicroscopeWidget
+
+        return MicroscopeWidget.from_setup(microscope=microscope, detector=self, crystal=crystal)

de_ebsd/sim/masterpattern.py

@@ -0,0 +1,231 @@
+"""The simulated master pattern and projection onto a detector."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import h5py
+import numpy as np
+import torch
+
+from de_ebsd.core.constants import DIVISION_FLOOR
+from de_ebsd.core.lambert import sample_texture
+from de_ebsd.core.rotation import quaternion_to_matrix
+from de_ebsd.sim.detector import EBSDDetector
+
+if TYPE_CHECKING:
+    from anyplotlib import Figure
+
+__all__ = ["MasterPattern"]
+
+
+@dataclass
+class MasterPattern:
+    """Backscatter intensity on the sphere in square-Lambert storage.
+
+    Attributes
+    ----------
+    data
+        Intensities, shape ``(n_energies, 2, n, n)``; hemisphere 0 is north.
+    energies_kev
+        Energy bin centers in keV, shape ``(n_energies,)``.
+    metadata
+        Free-form provenance (crystal, dmin, backend name, ...).
+    """
+
+    data: torch.Tensor
+    energies_kev: np.ndarray
+    metadata: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        shape_ok = (
+            self.data.ndim == 4
+            and self.data.shape[1] == 2
+            and self.data.shape[2] == self.data.shape[3]
+        )
+        if not shape_ok:
+            raise ValueError("data must have shape (n_energies, 2, n, n)")
+        self.energies_kev = np.atleast_1d(np.asarray(self.energies_kev, dtype=np.float64))
+        if len(self.energies_kev) != self.data.shape[0]:
+            raise ValueError("energies_kev length must match data.shape[0]")
+
+    @property
+    def npx(self) -> int:
+        """Half-width of the Lambert grid (n = 2 npx + 1)."""
+        return (self.data.shape[-1] - 1) // 2
+
+    @property
+    def device(self) -> torch.device:
+        return self.data.device
+
+    def to(self, device: torch.device | str) -> MasterPattern:
+        """Copy to another device."""
+        return MasterPattern(self.data.to(device), self.energies_kev, dict(self.metadata))
+
+    def energy_index(self, energy_kev: float | None) -> int:
+        if energy_kev is None:
+            return len(self.energies_kev) - 1  # highest energy bin
+        return int(np.argmin(np.abs(self.energies_kev - energy_kev)))
+
+    def sample(self, directions: torch.Tensor, energy_kev: float | None = None) -> torch.Tensor:
+        """Interpolate the master pattern at unit vectors (..., 3).
+
+        Bilinear interpolation on the square-Lambert grid via
+        ``grid_sample(align_corners=True)``, identical to kikuchipy's
+        interpolation. The hemisphere is selected by ``sign(z)``.
+        """
+        directions = directions.to(self.data.device, self.data.dtype)
+        return sample_texture(self.data[self.energy_index(energy_kev)][None], directions)
+
+    def project(
+        self,
+        detector: EBSDDetector,
+        orientation,
+        energy_kev: float | None = None,
+        rescale: bool = True,
+    ) -> torch.Tensor:
+        """Project onto a detector for one or more crystal orientations.
+
+        Parameters
+        ----------
+        detector
+            The detector geometry (fixed pattern center).
+        orientation
+            Crystal orientation(s): an ``orix.quaternion.Rotation`` or a
+            tensor/array of unit quaternions (N, 4) in (a, b, c, d) order.
+        energy_kev
+            Energy bin to project (default: highest).
+        rescale
+            Linearly rescale each pattern to [-1, 1].
+
+        Returns
+        -------
+        torch.Tensor
+            Patterns of shape (N, n_rows, n_cols).
+        """
+        q = _as_quaternions(orientation).to(self.data.device, self.data.dtype)
+        dc = detector.direction_cosines(device=self.data.device, dtype=self.data.dtype)
+
+        rot = quaternion_to_matrix(q)  # (N, 3, 3)
+        v = torch.einsum("nij,pj->npi", rot, dc)  # sample frame -> crystal frame
+        pattern = self.sample(v, energy_kev=energy_kev)  # (N, P)
+
+        if rescale:
+            pmin = pattern.amin(dim=1, keepdim=True)
+            pmax = pattern.amax(dim=1, keepdim=True)
+            pattern = 2.0 * (pattern - pmin) / (pmax - pmin).clamp_min(DIVISION_FLOOR) - 1.0
+        return pattern.reshape(-1, detector.nrows, detector.ncols)
+
+    def to_stereographic(
+        self, n: int = 501, hemisphere: str = "north", energy_kev: float | None = None
+    ) -> torch.Tensor:
+        """Resample one hemisphere into a stereographic (equal-angle) image."""
+        sign = 1.0 if hemisphere == "north" else -1.0
+        coords = torch.linspace(-1.0, 1.0, n, device=self.device)
+        ys, xs = torch.meshgrid(coords, coords, indexing="ij")
+        r2 = xs * xs + ys * ys
+        # inverse stereographic projection of the unit disk
+        vz = sign * (1.0 - r2) / (1.0 + r2)
+        vx = 2.0 * xs / (1.0 + r2)
+        vy = 2.0 * ys / (1.0 + r2)
+        v = torch.stack([vx, vy, vz], dim=-1)
+        image = self.sample(v, energy_kev=energy_kev)
+        return torch.where(r2 <= 1.0, image, torch.zeros_like(image))
+
+    def to_equirectangular(
+        self, height: int = 256, energy_kev: float | None = None
+    ) -> torch.Tensor:
+        """Resample the full sphere into an equirectangular (lat-long) image.
+
+        Row 0 is the north pole; used as the texture for the sphere view.
+        """
+        width = 2 * height
+        theta = torch.linspace(0.0, math.pi, height, device=self.device)  # polar
+        phi = torch.linspace(-math.pi, math.pi, width, device=self.device)
+        t, p = torch.meshgrid(theta, phi, indexing="ij")
+        v = torch.stack(
+            [torch.sin(t) * torch.cos(p), torch.sin(t) * torch.sin(p), torch.cos(t)], dim=-1
+        )
+        return self.sample(v, energy_kev=energy_kev)
+
+    def show(
+        self,
+        projection: str = "lambert",
+        energy_kev: float | None = None,
+        texture_height: int = 256,
+        **kwargs,
+    ) -> Figure:
+        """Display the master pattern.
+
+        Parameters
+        ----------
+        projection
+            ``"lambert"`` (both hemispheres side by side), ``"stereographic"``
+            (both hemispheres, equal-angle), or ``"sphere"`` (interactive 3D
+            sphere with the pattern as texture).
+        energy_kev
+            Energy bin to display (default: highest).
+        texture_height
+            Height of the equirectangular texture used by the interactive
+            sphere. Lower values reduce notebook/SpyDE payload size while
+            leaving the master-pattern data unchanged.
+        """
+        from de_ebsd.viz.patterns import hemispheres_figure, sphere_figure
+
+        i_e = self.energy_index(energy_kev)
+        label = f"{self.energies_kev[i_e]:g} keV"
+        if projection == "lambert":
+            north = self.data[i_e, 0].detach().cpu().numpy()
+            south = self.data[i_e, 1].detach().cpu().numpy()
+            return hemispheres_figure(north, south, title=f"Master pattern ({label})")
+        if projection == "stereographic":
+            north = self.to_stereographic(hemisphere="north", energy_kev=energy_kev)
+            south = self.to_stereographic(hemisphere="south", energy_kev=energy_kev)
+            return hemispheres_figure(
+                north.detach().cpu().numpy(),
+                south.detach().cpu().numpy(),
+                title=f"Master pattern, stereographic ({label})",
+            )
+        if projection == "sphere":
+            if texture_height < 8:
+                raise ValueError("texture_height must be >= 8")
+            texture = self.to_equirectangular(height=int(texture_height), energy_kev=energy_kev)
+            return sphere_figure(
+                texture.detach().cpu().numpy(), title=f"Master pattern ({label})", **kwargs
+            )
+        raise ValueError("projection must be 'lambert', 'stereographic', or 'sphere'")
+
+    def save(self, path: str) -> None:
+        """Save to HDF5 (data, energies, and string metadata)."""
+        with h5py.File(path, "w") as f:
+            f.create_dataset("master_pattern", data=self.data.detach().cpu().numpy())
+            f.create_dataset("energies_kev", data=self.energies_kev)
+            meta = f.create_group("metadata")
+            for key, value in self.metadata.items():
+                meta.attrs[key] = str(value)
+
+    @classmethod
+    def load(cls, path: str, device: torch.device | str | None = None) -> MasterPattern:
+        """Load a master pattern saved with :meth:`save`."""
+        with h5py.File(path, "r") as f:
+            data = torch.as_tensor(np.asarray(f["master_pattern"]), device=device)
+            energies = np.asarray(f["energies_kev"])
+            metadata = dict(f["metadata"].attrs) if "metadata" in f else {}
+        return cls(data=data, energies_kev=energies, metadata=metadata)
+
+    def __repr__(self) -> str:
+        e = self.energies_kev
+        return (
+            f"MasterPattern(npx={self.npx}, {len(e)} energy bin(s) "
+            f"[{e.min():g}..{e.max():g} keV], device={self.data.device.type}, "
+            f"backend={self.metadata.get('backend', '?')})"
+        )
+
+
+def _as_quaternions(orientation) -> torch.Tensor:
+    data = getattr(orientation, "data", orientation)  # orix Rotation -> .data
+    q = torch.as_tensor(np.asarray(data) if not isinstance(data, torch.Tensor) else data)
+    q = q.reshape(-1, 4)
+    return q / q.norm(dim=-1, keepdim=True).clamp_min(DIVISION_FLOOR)

de_ebsd/sim/microscope.py

@@ -0,0 +1,93 @@
+"""Microscope: beam energy and sample geometry.
+
+The :class:`Microscope` collects the experimental parameters that belong to
+the instrument rather than to the crystal or the detector: accelerating
+voltage and the sample tilt. Detector geometry lives on
+:class:`de_ebsd.sim.detector.EBSDDetector`.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from de_ebsd.core.constants import (
+    interaction_constant,
+    relativistic_correction,
+)
+
+__all__ = ["Microscope"]
+
+
+@dataclass(frozen=True)
+class Microscope:
+    """An SEM configured for EBSD.
+
+    Parameters
+    ----------
+    energy
+        Beam energy in eV (e.g. ``20e3``).
+    sample_tilt
+        Sample tilt from the horizontal in degrees (70 is standard for EBSD).
+    azimuthal
+        Detector azimuthal angle with respect to the tilt axis, in degrees.
+    probe_diameter_nm
+        Nominal circular beam diameter perpendicular to the beam, in nm.
+        Optional geometry metadata, not a finite-probe scattering model.
+    """
+
+    energy: float = 20e3
+    sample_tilt: float = 70.0
+    azimuthal: float = 0.0
+    probe_diameter_nm: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.energy <= 0:
+            raise ValueError("energy must be positive (in eV)")
+        if self.probe_diameter_nm is not None and (
+            not math.isfinite(self.probe_diameter_nm) or self.probe_diameter_nm <= 0
+        ):
+            raise ValueError("probe_diameter_nm must be finite and positive")
+
+    @property
+    def probe_footprint_nm(self) -> tuple[float, float] | None:
+        """Major/minor diameters on a flat surface; None at grazing incidence.
+
+        Geometric projection of a circular parallel probe, not an interaction
+        volume, beam broadening prediction, or a measured spatial resolution.
+        """
+        cosine = math.cos(math.radians(self.sample_tilt))
+        if self.probe_diameter_nm is None or cosine <= 1e-12:
+            return None
+        return self.probe_diameter_nm / cosine, self.probe_diameter_nm
+
+    @property
+    def energy_kev(self) -> float:
+        """Beam energy in keV."""
+        return self.energy / 1e3
+
+    @property
+    def gamma(self) -> float:
+        """Relativistic correction factor 1 + e V / (m0 c^2)."""
+        return relativistic_correction(self.energy_kev)
+
+    @property
+    def sigma(self) -> float:
+        """Interaction constant in (V nm)^-1."""
+        return interaction_constant(self.energy_kev, v0mod=0.0)
+
+    def show(self, detector=None, crystal=None):
+        """Editable beam, footprint and optional detector geometry inspector.
+
+        When supplied, detector sample tilt/azimuth must agree with this object.
+        Edits are a separate snapshot; read them with widget.to_microscope().
+        """
+        from de_ebsd.viz.widgets import MicroscopeWidget
+
+        return MicroscopeWidget.from_setup(microscope=self, detector=detector, crystal=crystal)
+
+    def __repr__(self) -> str:
+        return (
+            f"Microscope(energy={self.energy:g} eV, sample_tilt={self.sample_tilt:g} deg, "
+            f"azimuthal={self.azimuthal:g} deg)"
+        )