BornSim 0.2.6__py3-none-any.whl

bornsim/rotation.py

@@ -0,0 +1,68 @@
+"""Proper three-dimensional rotations for immutable material shapes."""
+
+from dataclasses import dataclass
+import numpy as np
+from .units import Quantity, validate_units, _dimensionless
+
+
+@dataclass(frozen=True, kw_only=True)
+class Rotation:
+    """Define an active right-handed rotation about a dimensionless axis.
+
+    angle accepts angular quantities; angular values require explicit units. The axis is
+    normalized. matrix maps local column coordinates into global coordinates.
+    No numerical scattering or voxel resampling is performed by this class.
+    """
+
+    axis: tuple[float, float, float]
+    angle: Quantity
+
+    def __post_init__(self) -> None:
+        axis = _dimensionless(value=self.axis, name="axis")
+
+        validate_units(
+            self.angle,
+            unit="radian",
+            name="angle",
+            scalar=True,
+        )
+
+        if axis.shape != (3,) or np.any(~np.isfinite(axis)) or np.linalg.norm(axis) == 0:
+            raise ValueError("axis must be a finite, nonzero three-vector.")
+
+        if not np.isfinite(self.angle):
+            raise ValueError("angle must be finite.")
+
+        object.__setattr__(self, "axis", tuple(axis / np.linalg.norm(axis)))
+
+    @property
+    def matrix(self) -> np.ndarray:
+        """Return Rodrigues' active rotation matrix, shape (3, 3)."""
+
+        axis = np.asarray(self.axis)
+
+        x, y, z = axis
+
+        skew = np.array([[0, -z, y], [z, 0, -x], [-y, x, 0]])
+
+        cosine = float(np.cos(self.angle))
+
+        sine = float(np.sin(self.angle))
+
+        return cosine * np.eye(3) + (1 - cosine) * np.outer(axis, axis) + sine * skew
+
+    @staticmethod
+    def _matrix(*, rotation):
+        matrix = rotation.matrix if isinstance(rotation, Rotation) else _dimensionless(value=rotation, name="rotation")
+
+        invalid = (
+            matrix.shape != (3, 3)
+            or np.any(~np.isfinite(matrix))
+            or not np.allclose(matrix.T @ matrix, np.eye(3), rtol=0, atol=1e-10)
+            or not np.isclose(np.linalg.det(matrix), 1, rtol=0, atol=1e-10)
+        )
+
+        if invalid:
+            raise ValueError("rotation must be a proper orthonormal 3-by-3 matrix or Rotation.")
+
+        return matrix

bornsim/sampling.py

@@ -0,0 +1,231 @@
+"""Full directional output sampling and independent solid-angle quadrature."""
+
+from dataclasses import dataclass
+from typing import cast
+import numpy as np
+import warnings
+from ._validation import _integer
+from .directions import Directions
+from .units import Quantity, validate_units, ureg
+
+
+@dataclass(frozen=True, kw_only=True, init=False)
+class AngularSampling:
+    """Configure directional plots and their solid-angle normalization.
+
+    Parameters
+    ----------
+    angles : array_like or Quantity, optional
+        Output polar angles theta, from 0 to pi, with 1 to 181 entries.
+        Angular values require explicit units. Cannot be combined with start, end or
+        n_points. Omit to generate an evenly spaced range.
+    start, end : Quantity, optional
+        Inclusive range endpoints between 0 and pi. Angular values require explicit units.
+        Defaults are 0 and pi; descending ranges are supported.
+    n_points : int, optional
+        Number of evenly spaced output angles, from 1 to 181. Default is 121.
+        A single point samples start.
+    polar_samples : int, optional
+        Gauss-Legendre integration nodes in cos(theta), from 16 to 128.
+        Default is 32. These are independent of the output angles.
+    azimuth_samples : int, optional
+        Uniform azimuth directions in [0, 2*pi), from 4 to 32. Default is 8.
+        Used for both directional output and solid-angle integration.
+
+    Notes
+    -----
+    Intensities are retained at every output (theta, phi). One-dimensional
+    curves select sampled meridians; azimuth averages require an explicit
+    azimuth_average() call. 3D phase surfaces use directional data.
+    Integration uses ``dOmega = dphi * d(cos(theta))``. Each Born order's
+    phase density is its intensity divided by its integrated coefficient.
+    Refine both quadratures independently of output plot resolution.
+    """
+
+    angles: Quantity
+    polar_samples: int = 32
+    azimuth_samples: int = 8
+
+    def __init__(
+        self,
+        *,
+        angles: Quantity | None = None,
+        start: Quantity | None = None,
+        end: Quantity | None = None,
+        n_points: int | None = None,
+        polar_samples: int = 32,
+        azimuth_samples: int = 8,
+    ) -> None:
+        if angles is not None:
+            if any(value is not None for value in (start, end, n_points)):
+                raise ValueError("Supply angles or start/end/n_points, not both.")
+        else:
+            start = 0 * ureg.radian if start is None else start
+
+            validate_units(
+                start,
+                unit="radian",
+                name="start",
+                scalar=True,
+            )
+
+            end = np.pi * ureg.radian if end is None else end
+
+            validate_units(
+                end,
+                unit="radian",
+                name="end",
+                scalar=True,
+            )
+
+            invalid_endpoints = not (
+                np.isfinite(start)
+                and np.isfinite(end)
+                and 0 <= start <= np.pi * ureg.radian
+                and 0 <= end <= np.pi * ureg.radian
+            )
+
+            if invalid_endpoints:
+                raise ValueError("start and end must be finite angles between 0 and pi.")
+
+            count = _integer(value=121 if n_points is None else n_points, name="n_points", low=1, high=181)
+
+            angles = cast(Quantity, np.linspace(start, end, count))
+
+        validate_units(
+            angles,
+            unit="radian",
+            name="angles",
+        )
+
+        angles = angles.copy()
+
+        invalid_angles = (
+            angles.ndim != 1
+            or not 1 <= angles.size <= 181
+            or np.any(~np.isfinite(angles))
+            or np.any((angles < 0) | (angles > np.pi * ureg.radian))
+        )
+
+        if invalid_angles:
+            raise ValueError("angles must contain 1–181 finite angles between 0 and pi.")
+
+        angles.magnitude.setflags(write=False)
+
+        object.__setattr__(self, "angles", angles)
+
+        for name, value, low, high in (
+            ("polar_samples", polar_samples, 16, 128),
+            ("azimuth_samples", azimuth_samples, 4, 32),
+        ):
+            object.__setattr__(self, name, _integer(value=value, name=name, low=low, high=high))
+
+    def __repr__(self) -> str:
+        angles = self.angles.to("degree").magnitude
+
+        low, high = angles.min(), angles.max()
+
+        return (
+            f"AngularSampling(angles={len(angles)} in [{low:g}, {high:g}] deg, "
+            f"polar_samples={self.polar_samples}, azimuth_samples={self.azimuth_samples})"
+        )
+
+    @property
+    def azimuths(self) -> Quantity:
+        """Uniform output and integration azimuths in radians."""
+
+        return np.arange(self.azimuth_samples) * 2 * np.pi / self.azimuth_samples * ureg.radian
+
+    @property
+    def directions(self) -> Directions:
+        """Unit directions: output grid first, then the integration grid."""
+
+        cosine, _ = np.polynomial.legendre.leggauss(self.polar_samples)
+
+        theta = np.concatenate([self.angles.to("radian").magnitude, np.arccos(cosine)]) * ureg.radian
+
+        return Directions.from_angles(
+            polar_angles=theta[:, None],
+            azimuth_angles=self.azimuths[None, :],
+        )
+
+    @property
+    def metadata(self):
+        """Fresh SI sampling settings for reproducible result archives."""
+
+        return {
+            "angles_rad": self.angles.to("radian").magnitude.tolist(),
+            "polar_samples": self.polar_samples,
+            "azimuth_samples": self.azimuth_samples,
+        }
+
+    def check_work(self, *, grid, order, realizations=1):
+        """Reject synchronous workloads above 100 million voxel-direction-orders."""
+
+        directions = (len(self.angles) + self.polar_samples) * self.azimuth_samples
+
+        if realizations * np.prod(grid.shape) * directions * order > 100_000_000:
+            raise ValueError("Requested scattering is too large; reduce grid, angles, order, or realizations.")
+
+    def summarize(self, *, result):
+        """Reduce numeric Born data while retaining all directional intensities.
+
+        Output amplitudes retain (order, theta, phi, incident polarization,
+        vector component). Integrated coefficients are finite-sample cross
+        sections divided by voxel-box volume, not intrinsic material values.
+        """
+
+        count = len(self.angles)
+
+        order = len(result.differential)
+
+        shape = (order, count + self.polar_samples, self.azimuth_samples)
+
+        directional = result.differential.reshape(shape)
+
+        averaged = directional.mean(axis=-1)
+
+        directional_terms = result.term_differential.reshape(shape)
+
+        terms = directional_terms.mean(axis=-1)
+
+        cosine, weights = np.polynomial.legendre.leggauss(self.polar_samples)
+
+        quadrature = averaged[:, count:]
+
+        mu = 2 * np.pi * np.sum(quadrature * weights, axis=-1)
+
+        moment = 2 * np.pi * np.sum(quadrature * weights * cosine, axis=-1)
+
+        reduced = 2 * np.pi * np.sum(quadrature * weights * (1 - cosine), axis=-1)
+
+        return {
+            "mean": averaged[:, :count],
+            "terms": terms[:, :count],
+            "directional_terms": directional_terms[:, :count],
+            "directional_differential": directional[:, :count],
+            "directional_amplitudes": result.amplitudes.reshape(*shape, 2, 3)[:, :count],
+            "integrals": np.stack([mu, moment, reduced], axis=-1),
+        }
+
+    @classmethod
+    def _resolve(cls, *, sampling=None, angles=None, polar_samples=None, azimuth_samples=None):
+        if sampling is not None:
+            if not isinstance(sampling, cls):
+                raise TypeError("sampling must be an AngularSampling.")
+
+            if any(value is not None for value in (angles, polar_samples, azimuth_samples)):
+                raise ValueError("Supply sampling or individual angular settings, not both.")
+
+            return sampling
+
+        if any(value is not None for value in (angles, polar_samples, azimuth_samples)):
+            warnings.warn(
+                "Use AngularSampling instead of individual angular keywords.", DeprecationWarning, stacklevel=3
+            )
+
+        return cls(
+            angles=angles,
+            polar_samples=32 if polar_samples is None else polar_samples,
+            azimuth_samples=8 if azimuth_samples is None else azimuth_samples,
+        )

bornsim/series.py

@@ -0,0 +1,300 @@
+"""Reusable finite-volume vector Born-series engine.
+
+Time convention exp(-i omega t). Relative dielectric contrast is linearized
+as 2 n0 delta_n at every order. Amplitudes interfere coherently before the
+unpolarized intensity is evaluated.
+"""
+
+from dataclasses import dataclass, field
+import numpy as np
+from ._validation import _integer
+from .green import GreenOperator
+from .grid import Grid
+from .directions import Directions
+from .results import BornResult
+from .units import Quantity, validate_units
+from .volume import Volume
+
+
+@dataclass(frozen=True, kw_only=True, eq=False)
+class BornSeries:
+    """Own the fixed geometry and propagation operator for numerical Born orders.
+
+    Parameters
+    ----------
+    grid : Grid, optional
+        Shared spatial configuration, also used by the input Volume.
+        Cannot be combined with legacy shape or spacing keywords.
+    shape : tuple of int, optional
+        Three grid dimensions, each from 2 to 32.
+    spacing : Quantity, optional
+        Positive cubic voxel width; explicit length units are required.
+    background_refractive_index : float
+        Positive uniform background refractive index, dimensionless.
+    wavelength : Quantity
+        Positive vacuum wavelength; explicit length units are required.
+    directions : Directions
+        Validated, immutable Cartesian unit observation vectors.
+    order : int, optional
+        Highest cumulative Born order, from 1 to 12; default 3.
+
+    Attributes
+    ----------
+    operator : bornsim.green.GreenOperator
+        One open-boundary FFT Green operator reused for every compatible volume.
+
+    Notes
+    -----
+    The cached incident plane wave travels along +z with x and y polarizations.
+    For each call, ``E[0] = E_inc`` and ``E[m] = K(chi*E[m-1])``, where
+    ``chi = 2*n0*delta_refractive_index`` and K integrates the background dyadic Green tensor
+    multiplied by ``k0**2``. Order-m far-field amplitude is computed from
+    ``chi*E[m-1]``. Cumulative intensity is ``|sum_m f[m]|**2``, averaged over the two
+    polarizations and divided by the entire voxel-box volume.
+
+    Geometry, incident field, and the Green tensor are reused; contrast,
+    propagated fields, amplitudes, and diagnostics are local to each solve.
+    Compatible volumes must have exactly the configured grid and background.
+    Configuration is frozen to prevent stale propagation settings. Decreasing
+    field terms do not establish universal convergence; the dielectric
+    linearization is unchanged at higher orders.
+    """
+
+    shape: tuple | None = None
+    spacing: Quantity = None
+    grid: Grid | None = None
+    background_refractive_index: float
+    wavelength: Quantity
+    directions: Directions
+    order: int = 3
+    operator: GreenOperator = field(init=False, repr=False)
+    _positions: Quantity = field(init=False, repr=False)
+    _incident_field: np.ndarray = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        grid = Grid._resolve(
+            grid=self.grid,
+            shape=self.shape,
+            spacing=self.spacing,
+        )
+
+        object.__setattr__(self, "grid", grid)
+
+        object.__setattr__(self, "shape", grid.shape)
+
+        object.__setattr__(self, "spacing", grid.spacing)
+
+        volume = Volume(
+            delta_refractive_index=np.zeros(grid.shape),
+            grid=grid,
+            background_refractive_index=self.background_refractive_index,
+        )
+
+        shape = grid.shape
+
+        wavelength = self.wavelength
+
+        validate_units(
+            self.wavelength,
+            unit="meter",
+            name="wavelength",
+            scalar=True,
+        )
+
+        if not np.isfinite(wavelength) or wavelength <= 0:
+            raise ValueError("wavelength must be finite and positive.")
+
+        order = _integer(
+            value=self.order,
+            name="order",
+            low=1,
+            high=12,
+        )
+
+        if not isinstance(self.directions, Directions):
+            raise TypeError("directions must be a Directions instance.")
+
+        directions = self.directions
+
+        positions = grid.positions
+
+        positions.magnitude.setflags(write=False)
+
+        phase = np.exp(1j * 2 * np.pi / wavelength * volume.background_refractive_index * positions[..., 2])
+
+        incident = phase.to("dimensionless").magnitude[..., None, None] * np.eye(3)[:2]
+
+        incident.setflags(write=False)
+
+        operator = GreenOperator(
+            shape=shape,
+            spacing=grid.spacing,
+            wavelength=wavelength,
+            background_refractive_index=volume.background_refractive_index,
+        )
+
+        for name, value in (
+            ("shape", shape),
+            ("spacing", grid.spacing),
+            ("background_refractive_index", volume.background_refractive_index),
+            ("wavelength", wavelength.copy()),
+            ("directions", directions),
+            ("order", order),
+            ("operator", operator),
+            ("_positions", positions),
+            ("_incident_field", incident),
+        ):
+            object.__setattr__(self, name, value)
+
+    def _far_field(self, *, source: np.ndarray) -> np.ndarray:
+        """Project the voxel source onto transverse outgoing amplitudes in metres."""
+
+        # Fourier projection uses numeric SI coordinates and amplitudes in metres.
+        k0 = 2 * np.pi / float(self.wavelength.to("meter").magnitude)
+
+        k = k0 * self.background_refractive_index
+
+        positions = self._positions.to("meter").magnitude.reshape(-1, 3)
+
+        voxel_spacing_m = float(self.spacing.to("meter").magnitude)
+
+        values = source.reshape(-1, 2, 3)
+
+        amplitude = np.empty((len(self.directions), 2, 3), dtype=complex)
+
+        for start in range(0, len(self.directions), 64):
+            direction = self.directions.vectors[start : start + 64]
+
+            phase = np.exp(-1j * k * (direction @ positions.T))
+
+            integral = np.einsum("dn,npv->dpv", phase, values) * k0**2 * voxel_spacing_m**3 / (4 * np.pi)
+
+            amplitude[start : start + 64] = (
+                integral - direction[:, None, :] * np.einsum("dv,dpv->dp", direction, integral)[..., None]
+            )
+
+        return amplitude
+
+    def solve(self, *, volume: Volume) -> BornResult:
+        """Compute coherent scattering from one compatible finite refractive index volume.
+
+        Parameters
+        ----------
+        volume : Volume
+            Fixed fluctuation field with positive linearized permittivity,
+            matching this engine's grid spacing, dimensions and background.
+
+        Returns
+        -------
+        result : bornsim.results.BornResult
+            Fresh numeric SI amplitudes, cumulative and isolated intensities,
+            relative field norms, and diagnostic messages.
+
+        Raises
+        ------
+        TypeError
+            If volume is not a Volume.
+        ValueError
+            If grid or background differs from the engine configuration, or
+            iteration produces nonfinite fields.
+
+        Notes
+        -----
+        Each solve starts with the incident field. Amplitudes are summed
+        before squaring, preserving interference. Intensities are finite-sample
+        cross sections divided by the entire voxel-box volume, not intrinsic
+        infinite-medium transport coefficients. The dielectric contrast is
+        ``2*n0*delta_refractive_index`` at every order. Growing field terms generate a
+        diagnostic; decreasing terms do not certify convergence.
+
+        Examples
+        --------
+        >>> from bornsim.units import ureg
+        >>> from bornsim import BornSeries, RandomMedium
+        ...
+        ...
+        >>> medium = RandomMedium(
+        ...     correlation="gaussian",
+        ...     background_refractive_index=1.33,
+        ...     refractive_index_std=0.01,
+        ...     correlation_length=100e-9 * ureg.meter,
+        ... )
+
+        ...
+        >>> volume = medium.to_volume(
+        ...     shape=(2, 2, 2),
+        ...     seed=42,
+        ...     spacing=50e-9 * ureg.meter,
+        ... )
+        >>> directions = Directions(vectors=[[0.0, 0.0, 1.0]])
+        >>> engine = BornSeries(
+        ...     shape=volume.delta_refractive_index.shape,
+        ...     spacing=volume.spacing,
+        ...     background_refractive_index=volume.background_refractive_index,
+        ...     wavelength=633 * ureg.nanometer,
+        ...     directions=directions,
+        ...     order=2,
+        ... )
+        >>> result = engine.solve(volume=volume)
+        >>> result.amplitudes.shape
+        (2, 1, 2, 3)
+        """
+
+        if not isinstance(volume, Volume):
+            raise TypeError("volume must be a Volume.")
+
+        incompatible_volume = (
+            volume.delta_refractive_index.shape != self.shape
+            or volume.spacing != self.spacing
+            or volume.background_refractive_index != self.background_refractive_index
+        )
+
+        if incompatible_volume:
+            raise ValueError("volume grid and background_refractive_index must match the BornSeries configuration.")
+
+        field = self._incident_field
+
+        incident_norm = np.linalg.norm(field)
+
+        contrast = 2 * volume.background_refractive_index * volume.delta_refractive_index
+
+        amplitude_terms, norms = [], []
+
+        for _ in range(self.order):
+            source = contrast[..., None, None] * field
+
+            amplitude_terms.append(self._far_field(source=source))
+
+            field = self.operator.apply(source=source)
+
+            if not np.all(np.isfinite(field)):
+                raise ValueError("Born terms overflowed; reduce contrast or order.")
+
+            norms.append(float(np.linalg.norm(field) / incident_norm))
+
+        amplitudes = np.asarray(amplitude_terms)
+
+        cumulative = np.cumsum(amplitudes, axis=0)
+
+        differential = np.sum(np.abs(cumulative) ** 2, axis=(-1, -2)) / (
+            2 * float(volume.volume.to("meter**3").magnitude)
+        )
+
+        separate = np.sum(np.abs(amplitudes) ** 2, axis=(-1, -2)) / (2 * float(volume.volume.to("meter**3").magnitude))
+
+        warnings = []
+
+        if volume.spacing > self.wavelength / volume.background_refractive_index / 10:
+            warnings.append("Voxel spacing exceeds one tenth of the background wavelength; refine the grid.")
+
+        if len(norms) > 1 and any(b >= a and b > 0 for a, b in zip(norms, norms[1:])):
+            warnings.append("Successive field terms are not decreasing; Born convergence is not established.")
+
+        return BornResult(
+            directions=self.directions.vectors.copy(),
+            amplitudes=amplitudes,
+            differential=differential,
+            term_differential=separate,
+            field_norms=np.array(norms),
+            warnings=tuple(warnings),
+        )