braggcalculator 0.1.0__py3-none-any.whl

braggcalculator/__init__.py

@@ -0,0 +1,5 @@
+from .core import BraggCalculator
+from .results import ReflectionTable
+from ._version import __version__
+
+__all__ = ["BraggCalculator", "ReflectionTable", "__version__"]

braggcalculator/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

braggcalculator/backends/__init__.py

@@ -0,0 +1,8 @@
+from .numpy_backend import NumpyBackend
+
+try:
+    from .torch_backend import TorchBackend
+except ImportError:  # pragma: no cover
+    TorchBackend = None
+
+__all__ = ["NumpyBackend", "TorchBackend"]

braggcalculator/backends/numpy_backend.py

@@ -0,0 +1,93 @@
+import numpy as np
+
+
+class NumpyBackend:
+    """Small numerical interface shared by the diffraction kernels.
+
+    Double precision is intentional.  Systematic absences are cancellations of
+    complex-valued sums and single precision produces visible ghost peaks for
+    larger cells.
+    """
+
+    complex64 = np.complex64
+    complex128 = np.complex128
+    float32 = np.float32
+    float64 = np.float64
+    int64 = np.int64
+    bool = np.bool_
+    is_torch = False
+
+    def __init__(self, dtype=np.float64):
+        self.dtype = dtype
+
+    def asarray(self, x, dtype=None):
+        return np.asarray(x, dtype=dtype)
+
+    def zeros(self, shape, dtype=None):
+        return np.zeros(shape, dtype=dtype)
+
+    def ones(self, shape, dtype=None):
+        return np.ones(shape, dtype=dtype)
+
+    def exp(self, x):
+        return np.exp(x)
+
+    def pi(self):
+        return np.pi
+
+    def sin(self, x):
+        return np.sin(x)
+
+    def cos(self, x):
+        return np.cos(x)
+
+    def arcsin(self, x):
+        return np.arcsin(x)
+
+    def sqrt(self, x):
+        return np.sqrt(x)
+
+    def clip(self, x, a, b):
+        return np.clip(x, a, b)
+
+    def inverse(self, x):
+        return np.linalg.inv(x)
+
+    def einsum(self, s, *ops):
+        return np.einsum(s, *ops)
+
+    def matmul(self, a, b):
+        return np.matmul(a, b)
+
+    def linspace(self, a, b, n):
+        return np.linspace(a, b, n, dtype=self.dtype)
+
+    def concat(self, xs, axis=0):
+        return np.concatenate(xs, axis=axis)
+
+    def conj(self, x):
+        return np.conj(x)
+
+    def real(self, x):
+        return np.real(x)
+
+    def sum(self, x, axis=None):
+        return np.sum(x, axis=axis)
+
+    def max(self, x):
+        return np.max(x)
+
+    def scatter_sum(self, values, indices, size):
+        result = np.zeros(size, dtype=values.dtype)
+        np.add.at(result, np.asarray(indices, dtype=np.int64), values)
+        return result
+
+    def degrees(self, x):
+        return np.degrees(x)
+
+    def q_from_two_theta(self, two_theta, wavelength):
+        return 4.0 * np.pi * np.sin(two_theta / 2.0) / wavelength
+
+    def two_theta_from_q(self, q, wavelength):
+        theta = np.arcsin(np.clip(q * wavelength / (4.0 * np.pi), -1.0, 1.0))
+        return 2.0 * theta

braggcalculator/backends/torch_backend.py

@@ -0,0 +1,98 @@
+import torch
+
+
+class TorchBackend:
+    """PyTorch backend for BraggCalculator.
+
+    Provides the same API as NumpyBackend but backed by torch tensors,
+    so operations are GPU-accelerated and autograd-compatible.
+    """
+
+    complex64 = torch.complex64
+    complex128 = torch.complex128
+    float32 = torch.float32
+    float64 = torch.float64
+    int64 = torch.int64
+    bool = torch.bool
+    is_torch = True
+
+    def __init__(self, device: str = "cpu", dtype=torch.float64):
+        self.device = torch.device(device)
+        self.dtype = dtype
+
+    def asarray(self, x, dtype=None):
+        if isinstance(x, torch.Tensor):
+            return x.to(device=self.device, dtype=dtype) if dtype else x.to(self.device)
+        return torch.tensor(x, device=self.device, dtype=dtype)
+
+    def zeros(self, shape, dtype=None):
+        return torch.zeros(shape, device=self.device, dtype=dtype)
+
+    def ones(self, shape, dtype=None):
+        return torch.ones(shape, device=self.device, dtype=dtype)
+
+    def exp(self, x):
+        return torch.exp(x)
+
+    def pi(self):
+        return torch.pi
+
+    def sin(self, x):
+        return torch.sin(x)
+
+    def cos(self, x):
+        return torch.cos(x)
+
+    def arcsin(self, x):
+        return torch.arcsin(x)
+
+    def sqrt(self, x):
+        return torch.sqrt(x)
+
+    def clip(self, x, a, b):
+        return torch.clamp(x, a, b)
+
+    def inverse(self, x):
+        return torch.linalg.inv(x)
+
+    def abs(self, x):
+        return torch.abs(x)
+
+    def real(self, x):
+        return torch.real(x)
+
+    def conj(self, x):
+        return torch.conj(x)
+
+    def einsum(self, s, *ops):
+        return torch.einsum(s, *ops)
+
+    def matmul(self, a, b):
+        return torch.matmul(a, b)
+
+    def linspace(self, a, b, n):
+        return torch.linspace(a, b, steps=n, device=self.device)
+
+    def concat(self, xs, axis=0):
+        return torch.cat(xs, dim=axis)
+
+    def sum(self, x, axis=None):
+        return torch.sum(x, dim=axis)
+
+    def max(self, x):
+        return torch.max(x)
+
+    def scatter_sum(self, values, indices, size):
+        index = self.asarray(indices, dtype=torch.int64)
+        result = torch.zeros(size, device=self.device, dtype=values.dtype)
+        return result.scatter_add(0, index, values)
+
+    def degrees(self, x):
+        return torch.rad2deg(x)
+
+    def q_from_two_theta(self, two_theta, wavelength):
+        return 4.0 * torch.pi * torch.sin(two_theta / 2.0) / wavelength
+
+    def two_theta_from_q(self, q, wavelength):
+        theta = torch.arcsin(torch.clamp(q * wavelength / (4.0 * torch.pi), -1.0, 1.0))
+        return 2.0 * theta

braggcalculator/core.py

@@ -0,0 +1,341 @@
+"""Public Bragg diffraction calculator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Literal, Mapping
+
+import numpy as np
+
+from .backends.numpy_backend import NumpyBackend
+from .factors import resolve_wavelength
+from .hkl import HKLEnumerator
+from .io import to_pmg_structure
+from .profiles import GaussianProfile, GaussianProfileQ
+from .results import ReflectionTable
+from .renderer import apply_lp_and_multiplicity, render_profile, render_profile_q
+from .structure_factor import compute_F2, reflection_geometry
+from .symmetry import SymmetryEngine
+
+
+ParameterDict = Mapping[str, Any]
+
+
+@dataclass
+class BraggCalculator:
+    """Calculate ideal kinematic X-ray or neutron powder diffraction.
+
+    Symmetry detection and HKL enumeration happen in :meth:`load` and form a
+    fixed, discrete topology.  With a Torch backend, tensors supplied through
+    ``parameters=`` remain differentiable inside that topology.
+    """
+
+    mode: Literal["xray", "neutron"] = "xray"
+    wavelength: float | str = 1.5406
+    two_theta_range: tuple[float, float] = (10.0, 80.0)
+    two_theta_step: float = 0.01
+    q_range: tuple[float, float] = (0.0, 10.0)
+    q_step: float = 0.005
+    qmax: float | None = None
+    profile: Any = field(default_factory=GaussianProfile)
+    profile_q: Any = field(default_factory=GaussianProfileQ)
+    backend: Any = field(default_factory=NumpyBackend)
+    symprec: float = 1e-3
+    angle_tolerance: float = 5.0
+    primitive: bool = True
+    debye_waller_factors: Mapping[str, float] = field(default_factory=dict)
+    neutron_scattering_lengths: Mapping[str | int, float | str] = field(default_factory=dict)
+    intensity_tolerance: float = 1e-5
+    phase_chunk_entries: int = 4_194_304
+
+    _pmg_structure: Any = field(default=None, init=False, repr=False)
+    _symm: dict[str, Any] = field(default_factory=dict, init=False, repr=False)
+    _hkl: dict[str, Any] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self):
+        if self.mode not in {"xray", "neutron"}:
+            raise ValueError("mode must be 'xray' or 'neutron'")
+        self.wavelength = resolve_wavelength(self.wavelength)
+        self._validate_range("two_theta_range", self.two_theta_range, lower=0.0, upper=180.0)
+        self._validate_range("q_range", self.q_range, lower=0.0)
+        for name, value in (
+            ("two_theta_step", self.two_theta_step),
+            ("q_step", self.q_step),
+            ("phase_chunk_entries", self.phase_chunk_entries),
+        ):
+            if not np.isfinite(value) or value <= 0:
+                raise ValueError(f"{name} must be positive and finite")
+        if self.intensity_tolerance < 0 or not np.isfinite(self.intensity_tolerance):
+            raise ValueError("intensity_tolerance must be non-negative and finite")
+        if not np.isfinite(self.symprec) or self.symprec <= 0:
+            raise ValueError("symprec must be positive and finite")
+        if not np.isfinite(self.angle_tolerance) or self.angle_tolerance <= 0:
+            raise ValueError("angle_tolerance must be positive and finite")
+        if int(self.phase_chunk_entries) != self.phase_chunk_entries:
+            raise ValueError("phase_chunk_entries must be an integer")
+        self.phase_chunk_entries = int(self.phase_chunk_entries)
+
+        physical_qmax = np.nextafter(4.0 * np.pi / self.wavelength, 0.0)
+        angle_qmax = (
+            4.0 * np.pi * np.sin(np.radians(self.two_theta_range[1]) / 2.0) / self.wavelength
+        )
+        required_qmax = min(
+            max(angle_qmax, float(self.q_range[1])),
+            physical_qmax,
+        )
+        if self.qmax is None:
+            self.qmax = required_qmax
+        elif not np.isfinite(self.qmax) or self.qmax <= 0:
+            raise ValueError("qmax must be positive and finite")
+        elif self.qmax < required_qmax - 64 * np.finfo(float).eps:
+            raise ValueError(
+                f"qmax={self.qmax} does not cover the configured output ranges; "
+                f"use at least {required_qmax:.8g} inverse angstroms"
+            )
+
+    @staticmethod
+    def _validate_range(name, values, *, lower=None, upper=None):
+        if len(values) != 2:
+            raise ValueError(f"{name} must contain two values")
+        start, stop = map(float, values)
+        if not np.isfinite(start) or not np.isfinite(stop) or start >= stop:
+            raise ValueError(f"{name} must be a finite increasing pair")
+        if lower is not None and start < lower:
+            raise ValueError(f"{name} cannot start below {lower}")
+        if upper is not None and stop > upper:
+            raise ValueError(f"{name} cannot end above {upper}")
+
+    def load(self, structure_like: Any) -> "BraggCalculator":
+        """Load a CIF path, pymatgen Structure, or optional ASE Atoms object."""
+        self._pmg_structure = to_pmg_structure(structure_like)
+        engine = SymmetryEngine(
+            symprec=self.symprec,
+            angle_tolerance=self.angle_tolerance,
+            primitive=self.primitive,
+        )
+        self._symm = engine.reduce(self._pmg_structure)
+
+        if self.debye_waller_factors:
+            b_values = self._symm["B"].copy()
+            for index, symbol in enumerate(self._symm["symbols"]):
+                if symbol in self.debye_waller_factors:
+                    value = float(self.debye_waller_factors[symbol])
+                    if value < 0 or not np.isfinite(value):
+                        raise ValueError(f"invalid Debye-Waller B value for {symbol}: {value}")
+                    b_values[index] = value
+            self._symm["B"] = b_values
+
+        self._hkl = HKLEnumerator(self.wavelength, self.qmax).enumerate(
+            self._symm["lattice"], self._symm["pointgroup_symbol"]
+        )
+        return self
+
+    def _ensure_loaded(self):
+        if not self._hkl:
+            raise RuntimeError("load a structure before calculating diffraction")
+
+    def tensor_parameters(
+        self,
+        requires_grad: bool | Iterable[str] = False,
+    ) -> dict[str, Any]:
+        """Return backend arrays suitable for the ``parameters=`` argument.
+
+        Valid differentiable names are ``lattice``, ``frac_coords``,
+        ``occupancies`` and ``b_iso``.  Species and the HKL list are discrete.
+        """
+        self._ensure_loaded()
+        names = {"lattice", "frac_coords", "occupancies", "b_iso"}
+        if isinstance(requires_grad, bool):
+            grad_names = names if requires_grad else set()
+        else:
+            grad_names = set(requires_grad)
+            unknown = grad_names - names
+            if unknown:
+                raise ValueError(f"unknown differentiable parameters: {sorted(unknown)}")
+
+        values = {
+            "lattice": self._symm["lattice"],
+            "frac_coords": self._symm["frac_coords"],
+            "occupancies": self._symm["occ"],
+            "b_iso": self._symm["B"],
+        }
+        result = {}
+        for name, value in values.items():
+            array = self.backend.asarray(value, dtype=self.backend.dtype)
+            if getattr(self.backend, "is_torch", False):
+                array = array.clone().detach().requires_grad_(name in grad_names)
+            result[name] = array
+        return result
+
+    def _parameter_values(self, parameters: ParameterDict | None):
+        parameters = {} if parameters is None else parameters
+        allowed = {"lattice", "frac_coords", "occupancies", "b_iso"}
+        unknown = set(parameters) - allowed
+        if unknown:
+            raise ValueError(f"unknown parameters: {sorted(unknown)}")
+        values = (
+            parameters.get("lattice", self._symm["lattice"]),
+            parameters.get("frac_coords", self._symm["frac_coords"]),
+            parameters.get("occupancies", self._symm["occ"]),
+            parameters.get("b_iso", self._symm["B"]),
+        )
+        lattice, frac, occ, b_iso = values
+        atom_count = len(self._symm["Z"])
+        expected = ((3, 3), (atom_count, 3), (atom_count,), (atom_count,))
+        names = ("lattice", "frac_coords", "occupancies", "b_iso")
+        for name, value, shape in zip(names, values, expected):
+            if tuple(value.shape) != shape:
+                raise ValueError(f"{name} must have shape {shape}, got {tuple(value.shape)}")
+        return lattice, frac, occ, b_iso
+
+    def _domain_indices(self, domain: Literal["two_theta", "q"]):
+        if domain == "two_theta":
+            nominal = np.degrees(self._hkl["two_theta"])
+            lower, upper = self.two_theta_range
+        elif domain == "q":
+            nominal = self._hkl["q"]
+            lower, upper = self.q_range
+        else:
+            raise ValueError("domain must be 'two_theta' or 'q'")
+        return np.flatnonzero((nominal >= lower) & (nominal <= upper))
+
+    def _geometry(self, lattice, indices=None):
+        hkl = self._hkl["hkl"] if indices is None else self._hkl["hkl"][indices]
+        return reflection_geometry(self.backend, hkl, lattice, self.wavelength)
+
+    def fq(self, parameters: ParameterDict | None = None, *, indices=None):
+        """Return per-reciprocal-point ``|F|^2`` without powder corrections."""
+        self._ensure_loaded()
+        lattice, frac, occ, b_iso = self._parameter_values(parameters)
+        hkl = self._hkl["hkl"] if indices is None else self._hkl["hkl"][indices]
+        _, two_theta = self._geometry(lattice, indices)
+        return self._compute_f2(hkl, two_theta, frac, occ, b_iso)
+
+    def _compute_f2(self, hkl, two_theta, frac, occ, b_iso):
+        return compute_F2(
+            mode=self.mode,
+            backend=self.backend,
+            hkl=hkl,
+            two_theta=two_theta,
+            wavelength=self.wavelength,
+            Z=self._symm["Z"],
+            frac=frac,
+            occ=occ,
+            B=b_iso,
+            neutron_scattering_lengths=self.neutron_scattering_lengths,
+            phase_chunk_entries=self.phase_chunk_entries,
+        )
+
+    def iq(
+        self,
+        domain: Literal["two_theta", "q"] = "two_theta",
+        parameters: ParameterDict | None = None,
+    ):
+        """Return individual reciprocal-point positions and corrected intensities."""
+        indices, g, two_theta, _, intensity = self._individual_data(domain, parameters)
+        del indices
+        if domain == "two_theta":
+            positions = self.backend.degrees(two_theta)
+        else:
+            positions = 2.0 * self.backend.pi() * g
+        return positions, intensity
+
+    def _individual_data(self, domain, parameters):
+        self._ensure_loaded()
+        indices = self._domain_indices(domain)
+        lattice, frac, occ, b_iso = self._parameter_values(parameters)
+        g, two_theta = self._geometry(lattice, indices)
+        f2 = self._compute_f2(self._hkl["hkl"][indices], two_theta, frac, occ, b_iso)
+        intensity = apply_lp_and_multiplicity(
+            self.mode, self.backend, f2, two_theta, multiplicity=None
+        )
+        return indices, g, two_theta, f2, intensity
+
+    def reflection_table(
+        self,
+        domain: Literal["two_theta", "q"] = "two_theta",
+        parameters: ParameterDict | None = None,
+    ) -> ReflectionTable:
+        """Return indexed per-reflection geometry and intensities."""
+        indices, g, two_theta, f2, intensity = self._individual_data(domain, parameters)
+        return ReflectionTable(
+            hkl=self._hkl["hkl"][indices].copy(),
+            d_spacing=1.0 / g,
+            q=2.0 * self.backend.pi() * g,
+            two_theta=self.backend.degrees(two_theta),
+            f_squared=f2,
+            intensity=intensity,
+        )
+
+    def line_pattern(
+        self,
+        domain: Literal["two_theta", "q"] = "two_theta",
+        parameters: ParameterDict | None = None,
+        *,
+        scaled: bool = False,
+    ):
+        """Return coincident reciprocal points merged into powder lines.
+
+        Lattice parameters must preserve the prepared metric degeneracies when
+        using this reporting method. :meth:`pattern` keeps reciprocal points
+        separate and is the appropriate differentiable path for symmetry-
+        breaking lattice changes.
+        """
+        positions, intensities = self.iq(domain=domain, parameters=parameters)
+        indices = self._domain_indices(domain)
+        nominal = (
+            np.degrees(self._hkl["two_theta"][indices])
+            if domain == "two_theta"
+            else self._hkl["q"][indices]
+        )
+        tolerance = 1e-5 if domain == "two_theta" else 1e-7
+        if len(nominal) == 0:
+            return positions, intensities
+        starts = np.r_[0, np.flatnonzero(np.diff(nominal) > tolerance) + 1]
+        group_ids = np.cumsum(np.r_[0, (np.diff(nominal) > tolerance).astype(np.int64)])
+        backend_starts = self.backend.asarray(starts, dtype=self.backend.int64)
+        merged_positions = positions[backend_starts]
+        merged_intensities = self.backend.scatter_sum(intensities, group_ids, len(starts))
+
+        # Match the conventional powder-line reporting threshold.  The mask is
+        # based on nominal output and is intentionally not part of the smooth
+        # profile-rendering path.
+        if len(starts):
+            if getattr(self.backend, "is_torch", False):
+                mask = (
+                    merged_intensities.detach().cpu().numpy()
+                    > float(merged_intensities.detach().max().cpu()) * self.intensity_tolerance
+                )
+            else:
+                mask = merged_intensities > np.max(merged_intensities) * self.intensity_tolerance
+            backend_mask = self.backend.asarray(mask, dtype=self.backend.bool)
+            merged_positions = merged_positions[backend_mask]
+            merged_intensities = merged_intensities[backend_mask]
+
+        if scaled and int(merged_intensities.shape[0]):
+            merged_intensities = 100.0 * merged_intensities / self.backend.max(merged_intensities)
+        return merged_positions, merged_intensities
+
+    def pattern(
+        self,
+        domain: Literal["two_theta", "q"] = "two_theta",
+        parameters: ParameterDict | None = None,
+    ):
+        """Return an area-normalized, gridded powder profile."""
+        positions, intensities = self.iq(domain=domain, parameters=parameters)
+        if domain == "two_theta":
+            lower, upper = self.two_theta_range
+            grid = self._regular_grid(lower, upper, self.two_theta_step)
+            values = render_profile(self.profile, self.backend, grid, positions, intensities)
+        elif domain == "q":
+            lower, upper = self.q_range
+            grid = self._regular_grid(lower, upper, self.q_step)
+            values = render_profile_q(self.profile_q, self.backend, grid, positions, intensities)
+        else:
+            raise ValueError("domain must be 'two_theta' or 'q'")
+        return grid, values
+
+    def _regular_grid(self, lower: float, upper: float, step: float):
+        intervals = int(np.floor((upper - lower) / step + 8 * np.finfo(float).eps))
+        last = lower + intervals * step
+        return self.backend.linspace(lower, last, intervals + 1)

braggcalculator/factors.py

@@ -0,0 +1,124 @@
+"""Tabulated X-ray and neutron scattering amplitudes.
+
+The numerical tables are maintained by pymatgen, a required dependency.  The
+X-ray expression is the Doyle-Turner/International Tables parameterization used by
+``pymatgen.analysis.diffraction.xrd``; neutron values are coherent bound
+scattering lengths in femtometres from the same package.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any, Mapping
+
+import numpy as np
+from pymatgen.analysis.diffraction.neutron import ATOMIC_SCATTERING_LEN
+from pymatgen.analysis.diffraction.xrd import ATOMIC_SCATTERING_PARAMS, WAVELENGTHS
+from pymatgen.core import Element
+
+
+_XRAY_FORM_FACTOR_SCALE = 41.78214
+
+
+def resolve_wavelength(value: float | str) -> float:
+    """Return a wavelength in angstroms from a number or radiation name."""
+    if isinstance(value, str):
+        try:
+            return float(WAVELENGTHS[value])
+        except KeyError as exc:
+            choices = ", ".join(sorted(WAVELENGTHS))
+            raise ValueError(f"Unknown radiation {value!r}; choose one of {choices}") from exc
+    wavelength = float(value)
+    if not np.isfinite(wavelength) or wavelength <= 0:
+        raise ValueError("wavelength must be a positive finite value in angstroms")
+    return wavelength
+
+
+def _numpy_atomic_numbers(values) -> np.ndarray:
+    if hasattr(values, "detach"):
+        values = values.detach().cpu().numpy()
+    return np.asarray(values, dtype=np.int64)
+
+
+@lru_cache(maxsize=None)
+def _xray_coefficients(numbers: tuple[int, ...]) -> tuple[np.ndarray, np.ndarray]:
+    coeffs = []
+    for z in numbers:
+        symbol = Element.from_Z(z).symbol
+        try:
+            coeffs.append(ATOMIC_SCATTERING_PARAMS[symbol])
+        except KeyError as exc:
+            raise ValueError(f"No X-ray scattering coefficients for {symbol}") from exc
+    return np.asarray(numbers, dtype=float), np.asarray(coeffs, dtype=float)
+
+
+def xray_form_factors(Z, s, backend) -> Any:
+    """Evaluate neutral-atom X-ray form factors.
+
+    Args:
+        Z: Atomic numbers, shape ``(N,)``.
+        s: ``sin(theta) / wavelength`` in inverse angstroms, shape ``(H,)``.
+        backend: NumPy or Torch backend.
+
+    Returns:
+        Form factors with shape ``(H, N)``.
+    """
+    numbers_array = _numpy_atomic_numbers(Z)
+    unique_numbers, inverse = np.unique(numbers_array, return_inverse=True)
+    numbers = tuple(int(z) for z in unique_numbers.tolist())
+    zs_np, coeff_np = _xray_coefficients(numbers)
+    dtype = getattr(s, "dtype", backend.dtype)
+    zs = backend.asarray(zs_np, dtype=dtype)
+    coeff = backend.asarray(coeff_np, dtype=dtype)
+    s2 = s * s
+    a = coeff[:, :, 0]
+    b = coeff[:, :, 1]
+    terms = a[None, :, :] * backend.exp(-s2[:, None, None] * b[None, :, :])
+    unique_factors = zs[None, :] - _XRAY_FORM_FACTOR_SCALE * s2[:, None] * backend.sum(
+        terms, axis=2
+    )
+    backend_inverse = backend.asarray(inverse, dtype=backend.int64)
+    return unique_factors[:, backend_inverse]
+
+
+@lru_cache(maxsize=None)
+def _neutron_lengths(numbers: tuple[int, ...]) -> np.ndarray:
+    values = []
+    for z in numbers:
+        symbol = Element.from_Z(z).symbol
+        try:
+            values.append(ATOMIC_SCATTERING_LEN[symbol])
+        except KeyError as exc:
+            raise ValueError(f"No coherent neutron scattering length for {symbol}") from exc
+    return np.asarray(values, dtype=float)
+
+
+def neutron_b_coherent(
+    Z,
+    backend,
+    overrides: Mapping[str | int, float | str] | None = None,
+) -> Any:
+    """Return coherent neutron scattering lengths in femtometres.
+
+    ``overrides`` supports element symbols or atomic numbers. Values can be an
+    exact length or a tabulated isotope key such as ``"2H"``. This is the
+    explicit route for isotope-specific samples, which pymatgen ``Structure``
+    objects do not encode unambiguously.
+    """
+    numbers = tuple(int(z) for z in _numpy_atomic_numbers(Z).tolist())
+    values = _neutron_lengths(numbers).copy()
+    if overrides:
+        for idx, z in enumerate(numbers):
+            symbol = Element.from_Z(z).symbol
+            override = overrides.get(symbol, overrides.get(z))
+            if override is not None:
+                if isinstance(override, str):
+                    try:
+                        values[idx] = ATOMIC_SCATTERING_LEN[override]
+                    except KeyError as exc:
+                        raise ValueError(
+                            f"No coherent neutron scattering length for isotope {override!r}"
+                        ) from exc
+                else:
+                    values[idx] = float(override)
+    return backend.asarray(values, dtype=backend.dtype)