de-ebsd 0.2.0__py3-none-any.whl

de_ebsd/sim/simulator.py

@@ -0,0 +1,291 @@
+"""The master-pattern simulation chain.
+
+:class:`MasterPatternSimulator` composes a crystal, a microscope and a backend,
+exposing each intermediate (structure factors, reflections, k-vectors) as an
+inspectable, showable object before ``compute()`` runs the full simulation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+import torch
+
+from de_ebsd.core.device import resolve_device
+from de_ebsd.crystal.lattice import Crystal
+from de_ebsd.crystal.structure_factors import StructureFactors, compute_structure_factors
+from de_ebsd.diffraction.backends import (
+    DynamicalMatrix,
+    MasterPatternBackend,
+    SimulationInputs,
+    build_dynamical_matrix,
+    classify_reflections,
+    resolve_backend,
+)
+from de_ebsd.diffraction.bethe import BetheParameters
+from de_ebsd.diffraction.kvectors import reduce_to_fundamental_sector, sample_incident_directions
+from de_ebsd.diffraction.reflections import ReflectionList, master_reflection_list
+from de_ebsd.sim.masterpattern import MasterPattern
+from de_ebsd.sim.microscope import Microscope
+from de_ebsd.sim.montecarlo.depth import DepthDistribution
+
+__all__ = ["MasterPatternSimulator"]
+
+
+class MasterPatternSimulator:
+    """Simulate an EBSD master pattern for one crystal and beam energy.
+
+    Parameters
+    ----------
+    crystal
+        The crystal structure.
+    microscope
+        Beam energy and sample geometry.
+    npx
+        Half-width of the square Lambert grid; the master pattern maps have
+        shape ``(2 npx + 1, 2 npx + 1)`` per hemisphere.
+    dmin
+        Smallest interplanar spacing (nm) still included as a reflection.
+        Lowering it adds beams and raises accuracy and cost.
+    bethe
+        Bethe-potential truncation thresholds.
+    monte_carlo
+        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
+        :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
+        on the GPU and reproduces it (r = 1.0000 against the EMsoft master of
+        Si at npx = 500), so it is the default.
+    """
+
+    def __init__(
+        self,
+        crystal: Crystal,
+        microscope: Microscope,
+        npx: int = 150,
+        dmin: float = 0.1,
+        bethe: BetheParameters | None = None,
+        monte_carlo: DepthDistribution | None = None,
+        backend: str | MasterPatternBackend = "bloch_prism",
+    ) -> None:
+        if npx < 1:
+            raise ValueError("npx must be >= 1")
+        if dmin <= 0:
+            raise ValueError("dmin must be positive (nm)")
+        self.crystal = crystal
+        self.microscope = microscope
+        self.npx = int(npx)
+        self.dmin = float(dmin)
+        self.bethe = bethe if bethe is not None else BetheParameters()
+        self.monte_carlo = monte_carlo
+        self.backend = backend
+        self._sf: StructureFactors | None = None
+
+    @property
+    def energy_kev(self) -> float:
+        return self.microscope.energy_kev
+
+    def structure_factors(self) -> StructureFactors:
+        """U_g with absorption for all reflections down to dmin (cached)."""
+        if self._sf is None:
+            self._sf = compute_structure_factors(self.crystal, self.energy_kev, self.dmin)
+        return self._sf
+
+    def reflections(self, k=None) -> ReflectionList:
+        """The reflection list; with ``k``, classified strong/weak for that beam.
+
+        ``k`` is a beam direction in the Cartesian crystal frame (any length;
+        it is normalized). For cubic crystals Cartesian components coincide
+        with lattice directions.
+        """
+        structure_factors = self.structure_factors()
+        if k is None:
+            return master_reflection_list(structure_factors)
+        return classify_reflections(structure_factors, _unit(k), self.bethe)
+
+    def dynamical_matrix(self, k) -> DynamicalMatrix:
+        """The Bloch dynamical matrix (with Bethe corrections) for one beam."""
+        structure_factors = self.structure_factors()
+        refl = classify_reflections(structure_factors, _unit(k), self.bethe)
+        matrix = build_dynamical_matrix(structure_factors, refl)
+        return DynamicalMatrix(matrix=matrix, hkl=refl.strong(), k=refl.k, reflections=refl)
+
+    def compute(
+        self,
+        device: torch.device | str | None = None,
+        dtype: torch.dtype = torch.float32,
+        chunk_size: int = 262_144,
+        mc_electrons: int = 200_000,
+        symmetry: bool = True,
+        energy_resolved: bool = False,
+        progress: Callable[[int, int], None] | None = None,
+    ) -> MasterPattern:
+        """Compute the master pattern on the Lambert grid.
+
+        Parameters
+        ----------
+        device
+            Torch device (e.g. ``"cuda"``); default: torch's current default.
+        dtype
+            Floating point type for the direction batch (FP32 recommended).
+        chunk_size
+            Number of beam directions per batch, bounding peak memory.
+        mc_electrons
+            Electron count for the native Monte Carlo depth profile built when
+            the backend needs one and no ``monte_carlo`` was supplied. Ignored if
+            a depth profile is provided or the backend does not use one.
+        symmetry
+            Fold the beam directions onto the point-group fundamental sector so
+            each symmetry-distinct direction is computed once (exact; ~15x fewer
+            evaluations for cubic). Disable to evaluate every grid point.
+        energy_resolved
+            Compute one Lambert map per Monte Carlo energy bin (structure factors
+            and depth profile per energy), giving an ``(nE, 2, n, n)`` master.
+            Requires a depth-integrating backend; ignored otherwise. Default is a
+            single map at the beam energy.
+        progress
+            Called as ``progress(done, total)`` after each batch of beam
+            directions, counting batches over all energies, so a caller can show
+            how far a long simulation has got. At the default *chunk_size* a
+            master of any usual size is one batch per energy, so a single-energy
+            compute reports only its end. The Monte Carlo, the symmetry fold and
+            the first energy all run before the first call. It is called on the
+            calling thread, inside the loop, so it should be quick and never
+            block; an exception raised in it stops the simulation.
+        """
+        device = resolve_device(device)
+        backend = resolve_backend(self.backend)
+
+        # depth-integrating backends need a Monte Carlo exit-depth profile; when
+        # the user supplied none, run the native (EMsoft-free) MC at the
+        # experimental tilt so a plain compute() stays standalone and accurate.
+        monte_carlo = self.monte_carlo
+        if monte_carlo is None and backend.uses_depth_profile:
+            monte_carlo = DepthDistribution.from_simulation(
+                self.crystal,
+                self.energy_kev,
+                tilt_deg=self.microscope.sample_tilt,
+                n_electrons=mc_electrons,
+                device=device,
+                seed=0,
+            )
+
+        # beam directions and the (energy-independent) symmetry fold
+        grid = sample_incident_directions(self.npx, device=device, dtype=dtype)
+        directions = grid.flat()
+        if symmetry:
+            reps, inverse = reduce_to_fundamental_sector(
+                directions, self.crystal.space_group, cache_key=self.npx
+            )
+        else:
+            reps, inverse = directions, None
+        n = 2 * self.npx + 1
+
+        if energy_resolved and backend.uses_depth_profile:
+            energies = np.asarray(monte_carlo.energies_kev, dtype=float)
+        else:
+            energies = np.array([self.energy_kev])
+
+        starts = range(0, reps.shape[0], chunk_size)
+        total, done = len(energies) * len(starts), 0
+        maps = []
+        for energy in energies:
+            structure_factors = (
+                self.structure_factors()
+                if abs(energy - self.energy_kev) < 1e-9
+                else compute_structure_factors(self.crystal, float(energy), self.dmin)
+            )
+            backend.prepare(
+                SimulationInputs(
+                    structure_factors=structure_factors,
+                    bethe=self.bethe,
+                    monte_carlo=monte_carlo,
+                    device=device,
+                    dtype=dtype,
+                )
+            )
+            rep_values = torch.empty(reps.shape[0], device=device, dtype=dtype)
+            for start in starts:
+                stop = min(start + chunk_size, reps.shape[0])
+                rep_values[start:stop] = backend.intensities(reps[start:stop])
+                done += 1
+                if progress is not None:
+                    progress(done, total)
+            values = rep_values if inverse is None else rep_values[inverse]
+            maps.append(values.reshape(2, n, n))
+
+        return MasterPattern(
+            data=torch.stack(maps, dim=0),
+            energies_kev=energies,
+            metadata={
+                # the object, not its repr: the indexers derive the phase and
+                # point group from it (save() stringifies metadata on write)
+                "crystal": self.crystal,
+                "backend": backend.name,
+                "npx": self.npx,
+                "dmin": self.dmin,
+                "energy_kev": self.energy_kev,
+                "bethe": repr(self.bethe),
+                "energy_resolved": len(energies) > 1,
+            },
+        )
+
+    def refine(self, **changes) -> MasterPatternSimulator:
+        """A new simulator with updated parameters, reusing valid caches.
+
+        Accepted keys: ``npx``, ``dmin``, ``bethe``, ``backend``,
+        ``monte_carlo``, ``microscope``, ``crystal``. Example::
+
+            better = sim.refine(npx=300, dmin=0.05)
+
+        Structure factors are carried over when the crystal, energy, and dmin
+        are unchanged (raising ``npx`` or adjusting Bethe thresholds is free).
+        """
+        allowed = {"npx", "dmin", "bethe", "backend", "monte_carlo", "microscope", "crystal"}
+        unknown = set(changes) - allowed
+        if unknown:
+            raise TypeError(f"unknown refine() parameters: {sorted(unknown)}")
+        new = MasterPatternSimulator(
+            crystal=changes.get("crystal", self.crystal),
+            microscope=changes.get("microscope", self.microscope),
+            npx=changes.get("npx", self.npx),
+            dmin=changes.get("dmin", self.dmin),
+            bethe=changes.get("bethe", self.bethe),
+            monte_carlo=changes.get("monte_carlo", self.monte_carlo),
+            backend=changes.get("backend", self.backend),
+        )
+        same_sf = (
+            new.crystal is self.crystal
+            and new.dmin == self.dmin
+            and new.energy_kev == self.energy_kev
+        )
+        if same_sf:
+            new._sf = self._sf
+        return new
+
+    def show_setup(self, detector=None):
+        """Interactive geometry widget for this simulation's setup."""
+        from de_ebsd.viz.widgets import MicroscopeWidget
+
+        return MicroscopeWidget.from_setup(
+            microscope=self.microscope, detector=detector, crystal=self.crystal
+        )
+
+    def __repr__(self) -> str:
+        backend = self.backend if isinstance(self.backend, str) else self.backend.name
+        return (
+            f"MasterPatternSimulator({self.crystal!r}, {self.microscope!r}, "
+            f"npx={self.npx}, dmin={self.dmin} nm, backend={backend!r})"
+        )
+
+
+def _unit(k) -> np.ndarray:
+    v = np.asarray(k, dtype=np.float64).reshape(3)
+    norm = np.linalg.norm(v)
+    if norm == 0:
+        raise ValueError("beam direction must be nonzero")
+    return v / norm

de_ebsd/viz/__init__.py

@@ -0,0 +1,53 @@
+"""The anyplotlib display layer: every ``.show()`` in de_ebsd renders through here.
+
+anyplotlib and the widget stack are imported lazily, so headless compute jobs
+never pay for (or require) them.
+"""
+
+__all__ = [
+    "CrystalExplorer",
+    "DepthWidget",
+    "MicroscopeWidget",
+    "PhaseOverview",
+    "bar_figure",
+    "crystal_structure_figure",
+    "hemispheres_figure",
+    "image_figure",
+    "phase_overview_figure",
+    "sampling_sphere_figure",
+    "show_correlation",
+    "show_map",
+    "show_match",
+    "show_refinement",
+    "sphere_figure",
+    "to_uint8_rgb",
+]
+
+_MODULES = {
+    "explorer": ("CrystalExplorer",),
+    "figures": ("bar_figure", "image_figure", "to_uint8_rgb"),
+    "patterns": (
+        "crystal_structure_figure",
+        "hemispheres_figure",
+        "phase_overview_figure",
+        "sampling_sphere_figure",
+        "sphere_figure",
+    ),
+    "maps": ("show_correlation", "show_map", "show_match", "show_refinement"),
+    "views": ("PhaseOverview",),
+    "widgets": ("DepthWidget", "MicroscopeWidget"),
+}
+_ORIGIN = {name: module for module, names in _MODULES.items() for name in names}
+
+
+def __getattr__(name: str):
+    module = _ORIGIN.get(name)
+    if module is None:
+        raise AttributeError(f"module 'de_ebsd.viz' has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(f"de_ebsd.viz.{module}"), name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

de_ebsd/viz/camera.py

@@ -0,0 +1,56 @@
+"""Camera and great-circle geometry for the orientation explorer's 3-D sphere."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+__all__ = ["band_path", "camera_angles", "camera_direction", "camera_frame"]
+
+
+def camera_direction(azimuth: float, elevation: float) -> np.ndarray:
+    """Near-facing sphere direction for anyplotlib's Plot3D camera convention."""
+    a, e = np.deg2rad([float(azimuth), float(elevation)])
+    return np.array([math.cos(e) * math.sin(a), -math.cos(e) * math.cos(a), math.sin(e)])
+
+
+def camera_angles(direction: np.ndarray) -> tuple[float, float]:
+    n = np.asarray(direction, dtype=float) / np.linalg.norm(direction)
+    return float(np.rad2deg(np.arctan2(n[0], -n[1]))), float(
+        np.rad2deg(np.arcsin(np.clip(n[2], -1, 1)))
+    )
+
+
+def camera_frame(azimuth: float, elevation: float) -> np.ndarray:
+    """The exact right/up/facing basis used by anyplotlib's Plot3D renderer."""
+    a, e = np.deg2rad([float(azimuth), float(elevation)])
+    ca, sa, ce, se = np.cos(a), np.sin(a), np.cos(e), np.sin(e)
+    facing = np.array([ce * sa, -ce * ca, se])
+    right = np.array([ca, sa, 0.0])
+    up = np.array([-se * sa, se * ca, ce])
+    return np.column_stack([right, up, facing])
+
+
+def band_path(normals: np.ndarray) -> np.ndarray:
+    """Pack reciprocal-plane great circles into a dense native point path.
+
+    Plot3D has one connected line primitive and no pen-lift/NaN contract.  A
+    fine point cloud preserves each great circle without drawing false chords
+    between unrelated planes.
+    """
+    normals = np.asarray(normals, dtype=float).reshape(-1, 3)
+    rings = []
+    t = np.linspace(0.0, 2.0 * np.pi, 256)
+    for normal in normals:
+        n = normal / max(np.linalg.norm(normal), 1e-15)
+        if not np.isfinite(n).all():
+            continue
+        ref = np.array([1.0, 0.0, 0.0]) if abs(n[0]) < 0.9 else np.array([0.0, 1.0, 0.0])
+        u = ref - np.dot(ref, n) * n
+        u /= max(np.linalg.norm(u), 1e-15)
+        v = np.cross(n, u)
+        rings.append(np.cos(t)[:, None] * u + np.sin(t)[:, None] * v)
+    if not rings:
+        return np.zeros((2, 3), dtype=float)
+    return np.concatenate(rings, axis=0)

de_ebsd/viz/depth_widget.js

@@ -0,0 +1,76 @@
+function render({model,el}) {
+  const host=el.shadowRoot||el.attachShadow({mode:'open'});
+  host.innerHTML=`<style>
+    :host {display:block;max-width:580px;color-scheme:light dark} *{box-sizing:border-box}
+    section {--fg:var(--spyde-fg,var(--jp-ui-font-color1,light-dark(#242a33,#d8dee9)));
+      --bg:var(--spyde-panel-bg,var(--jp-layout-color1,light-dark(#f6f7f9,#20242d)));
+      --line:var(--spyde-border,var(--jp-border-color2,light-dark(#ccd0d7,#4c5565)));
+      --accent:var(--spyde-accent,light-dark(#1672b8,#5ba7f7));--cut:light-dark(#a45c17,#e5a05c);
+      border:1px solid var(--line);border-radius:6px;background:var(--bg);color:var(--fg);
+      font:12px var(--jp-ui-font-family,system-ui,sans-serif);overflow:hidden}
+    header,.controls,.detail,.note {padding:9px 12px;line-height:1.5}
+    header {border-bottom:1px solid var(--line)} .controls {display:flex;flex-wrap:wrap;gap:12px}
+    label {display:flex;gap:8px;align-items:center} input {max-width:180px} select {font:inherit;color:inherit;background:var(--bg)}
+    svg {display:block;width:100%;font:12px system-ui} svg text {fill:var(--fg)}
+    .detail {border-top:1px solid var(--line);font-variant-numeric:tabular-nums} .note {font-size:11px}
+  </style><section><header><strong>Depth model · exit statistics and propagation slices</strong></header>
+  <div class="controls"><label>Energy <select aria-label="Depth energy"></select></label>
+  <label>Slice <input aria-label="Depth slice" type="range" min="0" step="1"><output></output></label></div>
+  <svg height="280" role="img" aria-label="Depth slices, exit yield and integration cutoff"></svg>
+  <div class="detail" aria-live="polite"></div><div class="note">Bars show lateral-summed exit yield per incident electron, before absorption correction.
+  Colored slices are retained by the backend's 99% rule (maximum over lateral pixels and lower energies).
+  Depth is normal to the surface, not a ray path length. Selecting a slice only inspects the model.</div></section>`;
+  const svg=host.querySelector('svg'), select=host.querySelector('select'), slider=host.querySelector('input');
+  const energies=model.get('energies_kev');
+  energies.forEach((value,index)=>{const o=document.createElement('option');o.value=index;o.textContent=`${value} keV`;select.append(o);});
+  select.onchange=()=>{model.set('energy_index',Number(select.value));model.save_changes();};
+  slider.oninput=()=>{model.set('slice_index',Number(slider.value));model.save_changes();};
+  const node=(tag,attrs={},value='')=>{
+    const n=document.createElementNS('http://www.w3.org/2000/svg',tag);
+    for(const [key,v] of Object.entries(attrs))n.setAttribute(key,v);n.textContent=value;svg.append(n);return n;
+  };
+  const text=(x,y,value,anchor='start')=>node('text',{x,y,'text-anchor':anchor},value);
+  function draw() {
+    const ei=Math.min(energies.length-1,model.get('energy_index')), p=model.get('profiles')[ei], n=p.length,
+      selected=Math.min(n-1,model.get('slice_index')), count=model.get('integration_bins')[ei], dz=model.get('depth_step');
+    const W=svg.clientWidth||560, top=42, bottom=236, h=bottom-top;
+    svg.setAttribute('viewBox',`0 0 ${W} 280`);svg.replaceChildren();
+    select.value=ei;slider.max=n-1;slider.value=selected;host.querySelector('output').textContent=`${selected+1} / ${n}`;
+    const left=62, slabW=55, barX=150, barW=Math.max(40,W-barX-45), max=Math.max(...p,1e-30),total=p.reduce((a,b)=>a+b,0);
+    text(12,19,`${n} bins × ${dz} nm · modeled window ${n*dz} nm`);
+    text(left,34,'Surface');text(barX,34,'Exit yield / bin');
+    text(W-20,19,`max ${max.toPrecision(3)}`,'end');
+    node('line',{x1:left-8,y1:top,x2:W-20,y2:top,stroke:'var(--fg)'});
+    // Aggregate dense profiles only for painting; selected-bin values stay exact.
+    const stride=Math.max(1,Math.ceil(n/180));
+    for(let start=0;start<n;start+=stride) {
+      const stop=Math.min(start+stride,n),y=top+h*start/n,hh=h*(stop-start)/n;
+      const value=p.slice(start,stop).reduce((a,b)=>a+b,0)/(stop-start);
+      const active=start<count;
+      node('rect',{x:left,y,width:slabW,height:hh,fill:active?'var(--accent)':'var(--line)',
+        'fill-opacity':.15+.55*value/max,stroke:'var(--bg)','stroke-width':.5});
+      const bar=node('rect',{x:barX,y,width:barW*value/max,height:Math.max(.3,hh-.5),
+        fill:active?'var(--accent)':'var(--line)'});
+      const tip=document.createElementNS('http://www.w3.org/2000/svg','title');
+      tip.textContent=`${start*dz}–${stop*dz} nm; mean yield/bin ${value.toPrecision(4)}`;bar.append(tip);
+    }
+    for(const fraction of [0,.5,1]) {
+      const y=top+h*fraction;text(left-9,y+4,`${(n*dz*fraction).toFixed(0)}`,'end');
+    }
+    text(12,260,'z (nm)');
+    const cy=top+h*count/n;
+    node('line',{x1:left-5,y1:cy,x2:W-20,y2:cy,stroke:'var(--cut)','stroke-width':2,'stroke-dasharray':'5 3'});
+    text(W-20,263,`99% window: ${count*dz} nm (${count} slices)`,'end');
+    const sy=top+h*selected/n;
+    node('rect',{x:left-3,y:sy,width:slabW+6,height:Math.max(2,h/n),fill:'none',stroke:'var(--fg)','stroke-width':2});
+    node('line',{x1:barX,y1:sy+h/(2*n),x2:barX+barW,y2:sy+h/(2*n),stroke:'var(--fg)','stroke-width':1});
+    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<count?'Used':'Outside integration window'}. PRISM propagation point: ${(selected+1)*dz} nm.`;
+  }
+  const names=['energy_index','slice_index'];for(const name of names)model.on(`change:${name}`,draw);
+  const observer=new ResizeObserver(draw);observer.observe(host.querySelector('section'));draw();
+  return ()=>{observer.disconnect();for(const name of names)model.off(`change:${name}`,draw);};
+}
+export default {render};