BornSim 0.2.6__py3-none-any.whl

bornsim/green.py

@@ -0,0 +1,161 @@
+"""Outgoing vector Green tensor with open-boundary FFT convolution.
+
+Cubic voxels use an equal-volume spherical self cell, including the
+longitudinal contact term, with time convention exp(-i omega t).
+"""
+
+import numpy as np
+from .units import _refractive_index_values, validate_units, Quantity
+
+
+class GreenOperator:
+    """Apply the outgoing background dyadic Green tensor by FFT convolution.
+
+    Parameters
+    ----------
+    shape : tuple of int
+        Three voxel-grid dimensions, normally supplied by a validated Volume.
+    spacing : Quantity
+        Cubic voxel spacing; length values require explicit units. Must be positive.
+    wavelength : Quantity
+        Positive, finite vacuum wavelength; length values require explicit units.
+    background_refractive_index : float
+        Positive background refractive index; must be dimensionless.
+
+    Attributes
+    ----------
+    shape : tuple of int
+        Unpadded sample dimensions.
+    padded : tuple of int
+        Dimensions doubled along each axis for open-boundary convolution.
+    spectrum : numpy.ndarray
+        Fourier-domain dyadic kernel, shape ``(*padded, 3, 3)``.
+
+    Raises
+    ------
+    ValueError
+        If the wavelength is invalid or a supplied quantity has incompatible units.
+
+    Notes
+    -----
+    This low-level operator assumes a valid grid and background. It evaluates
+    ``k0**2 * integral(G_background(r-r') * source(r'), dV')`` with time
+    convention ``exp(-i*omega*t)``. Off-diagonal cells use midpoint quadrature.
+    The self cell is an equal-volume sphere including the longitudinal contact
+    term. Zero padding prevents periodic propagation across the sample.
+    """
+
+    def __init__(
+        self,
+        *,
+        shape: tuple[int, int, int],
+        spacing: Quantity,
+        wavelength: Quantity,
+        background_refractive_index: float,
+    ) -> None:
+        validate_units(
+            spacing,
+            unit="meter",
+            name="spacing",
+            scalar=True,
+        )
+
+        validate_units(
+            wavelength,
+            unit="meter",
+            name="wavelength",
+            scalar=True,
+        )
+
+        # The FFT kernel uses numeric SI distances and a dimensionless field.
+        voxel_spacing_m = float(spacing.to("meter").magnitude)
+
+        vacuum_wavelength_m = float(wavelength.to("meter").magnitude)
+
+        background_refractive_index = _refractive_index_values(
+            value=background_refractive_index,
+            name="background_refractive_index",
+            scalar=True,
+        )
+
+        if not np.isfinite(vacuum_wavelength_m) or vacuum_wavelength_m <= 0:
+            raise ValueError("wavelength must be finite and positive.")
+
+        self.shape = tuple(shape)
+
+        self.padded = tuple(2 * n for n in shape)
+
+        k0 = 2 * np.pi / vacuum_wavelength_m
+
+        k = k0 * background_refractive_index
+
+        axes = [
+            np.where(np.arange(2 * n) < n, np.arange(2 * n), np.arange(2 * n) - 2 * n) * voxel_spacing_m for n in shape
+        ]
+
+        displacement_between_voxel_centres_m = np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1)
+
+        distance_between_voxel_centres_m = np.linalg.norm(displacement_between_voxel_centres_m, axis=-1)
+
+        nonzero_distance_m = np.where(
+            distance_between_voxel_centres_m == 0, voxel_spacing_m, distance_between_voxel_centres_m
+        )
+
+        direction_between_voxels = displacement_between_voxel_centres_m / nonzero_distance_m[..., None]
+
+        background_phase = k * nonzero_distance_m
+
+        scalar = np.exp(1j * background_phase) / (4 * np.pi * nonzero_distance_m)
+
+        isotropic = 1 + 1j / background_phase - 1 / background_phase**2
+
+        longitudinal = -1 - 3j / background_phase + 3 / background_phase**2
+
+        kernel = scalar[..., None, None] * (
+            isotropic[..., None, None] * np.eye(3)
+            + longitudinal[..., None, None]
+            * direction_between_voxels[..., :, None]
+            * direction_between_voxels[..., None, :]
+        )
+
+        kernel *= k0**2 * voxel_spacing_m**3
+
+        # Integrated Green tensor over an equal-volume sphere, including
+        # -I delta(r)/(3 k^2). Use a series to avoid cancellation at small ka.
+        a = (3 * voxel_spacing_m**3 / (4 * np.pi)) ** (1 / 3)
+
+        ka = k * a
+
+        if abs(ka) < 1e-3:
+            radial = ka**2 / 2 + 1j * ka**3 / 3 - ka**4 / 8 - 1j * ka**5 / 30
+        else:
+            radial = np.exp(1j * ka) * (1 - 1j * ka) - 1
+
+        kernel[0, 0, 0] = np.eye(3) * k0**2 * (2 * radial - 1) / (3 * k**2)
+
+        self.spectrum = np.fft.fftn(kernel, axes=(0, 1, 2))
+
+    def apply(self, *, source: np.ndarray) -> np.ndarray:
+        """Propagate a voxel source field through the background Green tensor.
+
+        Parameters
+        ----------
+        source : numpy.ndarray
+            Numeric source values, shape (nx, ny, nz, polarization, 3).
+            Born iteration supplies linearized dielectric contrast times field.
+
+        Returns
+        -------
+        field : numpy.ndarray
+            Complex propagated field with the same shape and field units as source.
+            The padded convolution is cropped to the original sample grid.
+        """
+
+        # source shape: (nx, ny, nz, polarization, vector component)
+        transformed = np.fft.fftn(source, s=self.padded, axes=(0, 1, 2))
+
+        propagated = np.einsum("...ij,...pj->...pi", self.spectrum, transformed)
+
+        result = np.fft.ifftn(propagated, axes=(0, 1, 2))
+
+        return result[tuple(slice(0, n) for n in self.shape)]

bornsim/grid.py

@@ -0,0 +1,98 @@
+"""Reusable centred cubic voxel grids with unit-bearing coordinates."""
+
+from dataclasses import dataclass
+import numpy as np
+import warnings
+from ._validation import _integer
+from .units import Quantity, validate_units
+
+
+@dataclass(frozen=True, kw_only=True)
+class Grid:
+    """Define the spatial discretization once for generation and scattering.
+
+    Parameters
+    ----------
+    shape : tuple of int
+        Three explicitly chosen voxel counts, each from 2 to 32.
+    spacing : Quantity
+        Positive, finite cubic voxel width, with its supplied length units. A spacing must be supplied.
+
+    Notes
+    -----
+    Voxel centres are ``(i - (N - 1)/2) * spacing`` on each axis. The box
+    extends half a voxel beyond its outer centres. It describes the sampled
+    domain, not an additional dielectric boundary. Background refractive index belongs
+    to the medium or volume, rather than the spatial grid.
+    """
+
+    shape: tuple[int, int, int]
+    spacing: Quantity
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.shape, (tuple, list)) or len(self.shape) != 3:
+            raise ValueError("shape must have three axes.")
+
+        shape = tuple(_integer(value=n, name="axis size", low=2, high=32) for n in self.shape)
+
+        validate_units(
+            self.spacing,
+            unit="meter",
+            name="spacing",
+            scalar=True,
+        )
+
+        if not np.isfinite(self.spacing) or self.spacing <= 0:
+            raise ValueError("spacing must be finite and positive.")
+
+        object.__setattr__(self, "shape", shape)
+
+    def __repr__(self) -> str:
+        return f"Grid(shape={self.shape}, spacing={self.spacing:~g})"
+
+    @property
+    def positions(self) -> Quantity:
+        """Unit-bearing voxel-centre coordinates, shape ``(*shape, 3)``."""
+
+        axes = [np.arange(n) - (n - 1) / 2 for n in self.shape]
+
+        return np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1) * self.spacing
+
+    @property
+    def volume(self) -> Quantity:
+        """Physical voxel-box volume in cubic metres."""
+
+        return np.prod(self.shape) * self.spacing**3
+
+    @property
+    def metadata(self) -> dict[str, object]:
+        """Fresh JSON-compatible grid settings in SI units."""
+
+        return {"shape": list(self.shape), "spacing_m": float(self.spacing.to("meter").magnitude)}
+
+    @classmethod
+    def _resolve(
+        cls,
+        *,
+        grid: "Grid | None" = None,
+        shape: tuple[int, int, int] | None = None,
+        spacing: Quantity | None = None,
+    ) -> "Grid":
+        if grid is not None:
+            if not isinstance(grid, cls):
+                raise TypeError("grid must be a Grid.")
+
+            if shape is not None or spacing is not None:
+                raise ValueError("Supply grid or shape/spacing, not both.")
+
+            return grid
+
+        if shape is None or spacing is None:
+            raise ValueError("Supply grid or both shape and spacing; physical grid settings have no defaults.")
+
+        warnings.warn("Use Grid instead of shape/spacing keywords.", DeprecationWarning, stacklevel=3)
+
+        return cls(
+            shape=shape,
+            spacing=spacing,
+        )

bornsim/material.py

@@ -0,0 +1,46 @@
+"""Immutable, reusable homogeneous optical materials."""
+
+from dataclasses import dataclass
+import numpy as np
+from .units import _refractive_index_values
+
+
+@dataclass(frozen=True, kw_only=True)
+class Material:
+    """A nondispersive real refractive index shared by any number of shapes.
+
+    ``refractive_index`` is an absolute positive dimensionless refractive index, not a
+    contrast. Supply a plain number; quantities are rejected. Absorption and wavelength dispersion are not implemented.
+    """
+
+    refractive_index: float
+
+    def __post_init__(self) -> None:
+        refractive_index = _refractive_index_values(value=self.refractive_index, name="refractive_index", scalar=True)
+
+        if not np.isfinite(refractive_index) or refractive_index <= 0:
+            raise ValueError("refractive_index must be finite and positive.")
+
+        object.__setattr__(self, "refractive_index", refractive_index)
+
+    @property
+    def metadata(self):
+        """Fresh JSON-compatible material description."""
+
+        return {"refractive_index": self.refractive_index}
+
+    @classmethod
+    def _resolve(cls, *, material=None, refractive_index=None):
+        if material is not None:
+            if not isinstance(material, cls):
+                raise TypeError("material must be a Material.")
+
+            if refractive_index is not None:
+                raise ValueError("Supply material or refractive_index, not both.")
+
+            return material
+
+        if refractive_index is None:
+            raise ValueError("Supply material or refractive_index.")
+
+        return cls(refractive_index=refractive_index)

bornsim/media.py

@@ -0,0 +1,359 @@
+"""Numerical random-medium statistics, independent of analytical solutions."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+import numpy as np
+from .units import _refractive_index_values, Quantity, validate_units, ureg, _dimensionless
+from ._validation import _integer
+from .grid import Grid
+
+if TYPE_CHECKING:
+    from .volume import Volume
+
+
+class Medium(ABC):
+    """Abstract interface for media that can be sampled into a finite volume.
+
+    Instantiate :class:`RandomMedium` or :class:`bornsim.StructuredMedium`,
+    not this base class. Concrete media specify a uniform ``background_refractive_index``
+    and implement :meth:`to_volume` using cubic voxels, SI spacing, and centred
+    coordinates. The resulting field stores ``delta_refractive_index = n(r) - n0``;
+    propagation retains ``epsilon_r = n0**2 + 2*n0*delta_refractive_index``.
+    """
+
+    background_refractive_index: float | None
+
+    @property
+    def is_random(self):
+        """Whether independent generation seeds represent random realizations."""
+
+        return False
+
+    @property
+    def metadata(self):
+        """Return a fresh JSON-compatible description with numeric SI values.
+
+        Concrete media extend this dictionary with their own statistics or
+        geometry. Generation seeds and grids belong to individual volumes.
+        """
+
+        return {"background_refractive_index": self.background_refractive_index}
+
+    def add_background(self, *, refractive_index=None, medium=None, material=None):
+        """Configure a composable medium's background in place.
+
+        StructuredMedium accepts exactly one of a positive uniform ``refractive_index``
+        or a RandomMedium supplied as ``medium``. Statistical media describe
+        homogeneous distributions; use StructuredMedium to compose material.
+        """
+
+        raise TypeError("Use StructuredMedium to compose backgrounds and structures.")
+
+    def add_structures(self, *structures):
+        """Append positional material shapes to a composable medium in place.
+
+        StructuredMedium supports Layer, Sphere, Ellipsoid, Box, and Cylinder.
+        Later structures replace earlier material wherever their masks overlap.
+        """
+
+        raise TypeError("Use StructuredMedium to compose backgrounds and structures.")
+
+    @abstractmethod
+    def to_volume(
+        self,
+        *,
+        grid: Grid | None = None,
+        shape: tuple[int, int, int] | None = None,
+        spacing: Quantity | None = None,
+        seed: int = 0,
+    ) -> "Volume":
+        """Return a finite voxel sample; concrete classes define generation."""
+
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, kw_only=True)
+class RandomMedium(Medium):
+    r"""Define a Gaussian random refractive index field by its isotropic spatial spectrum.
+
+    Parameters
+    ----------
+    background_refractive_index : float
+        Positive uniform background refractive index (required).
+    refractive_index_std : float
+        Nonnegative ensemble standard deviation, not variance (required).
+    correlation_length : Quantity
+        Positive quantity with explicit length units (required).
+    correlation : {'gaussian', 'exponential', 'matern'}
+        Explicitly chosen spatial covariance family. This does not change
+        the Gaussian probability distribution of the refractive index field.
+    smoothness : float or Quantity
+        Positive finite Matérn parameter nu; required for 'matern'.
+        Other covariance families do not require this parameter. Larger values give smoother continuum fields.
+
+    Notes
+    -----
+    With ell = correlation_length and x = sqrt(2*nu)*r/ell, Whittle–Matérn
+    covariance is ``C_n(r) = sigma_n**2 * 2**(1-nu)/Gamma(nu) * x**nu*K_nu(x)``.
+    Its three-dimensional spectrum is proportional to
+    ``(1 + (q*ell)**2/(2*nu))**(-nu-3/2)``. Thus nu = 0.5 reproduces exponential
+    covariance with the same ell. Gaussian covariance uses
+    ``exp(-r**2/(2*ell**2))``; exponential uses ``exp(-r/ell)``.
+
+    :func:`bornsim.random_volume` normalizes the discrete spectrum to preserve
+    expected point variance, retains the DC mode, and crops a doubled synthesis
+    box. Neither individual sample means nor variances are forced to match the
+    ensemble statistics. Grid resolution and box size affect sampled covariance.
+    This class is for numerical generation and ensembles, not analytical solve.
+    """
+
+    background_refractive_index: float
+    refractive_index_std: float
+    correlation_length: Quantity
+    correlation: str
+    smoothness: Quantity | float | None = None
+
+    def __post_init__(self) -> None:
+        validate_units(
+            self.correlation_length,
+            unit="meter",
+            name="correlation_length",
+            scalar=True,
+        )
+
+        if not np.isfinite(self.correlation_length) or self.correlation_length <= 0:
+            raise ValueError("correlation_length must be finite and positive.")
+
+        for name in ("background_refractive_index", "refractive_index_std"):
+            value = _refractive_index_values(
+                value=getattr(self, name),
+                name=name,
+                scalar=True,
+            )
+
+            if not np.isfinite(value) or value < 0 or (name == "background_refractive_index" and value == 0):
+                raise ValueError(
+                    f"{name} must be finite and {'nonnegative' if name == 'refractive_index_std' else 'positive'}."
+                )
+
+        if self.correlation not in ("gaussian", "exponential", "matern"):
+            raise ValueError("correlation must be gaussian, exponential, or matern.")
+
+        if self.smoothness is None:
+            if self.correlation == "matern":
+                raise ValueError("smoothness must be explicitly supplied for matern correlation.")
+        else:
+            smoothness = _dimensionless(
+                value=self.smoothness,
+                name="smoothness",
+                scalar=True,
+            )
+
+            if not np.isfinite(smoothness) or smoothness <= 0:
+                raise ValueError("smoothness must be finite and positive.")
+
+            object.__setattr__(self, "smoothness", smoothness)
+
+    @property
+    def is_random(self):
+        """Statistical media support independent seeded realizations."""
+
+        return True
+
+    @property
+    def metadata(self):
+        """Return independent SI statistics for result provenance.
+
+        Lengths use the ``_m`` suffix. Smoothness is retained for all covariance
+        families, including inherited analytical media, preserving the saved
+        result metadata convention. This describes ensemble statistics rather
+        than a particular seed or a sample's measured mean and variance.
+        """
+
+        return {
+            **super().metadata,
+            "refractive_index_std": self.refractive_index_std,
+            "correlation_length_m": float(self.correlation_length.to("meter").magnitude),
+            "correlation": self.correlation,
+            "smoothness": self.smoothness,
+        }
+
+    def spectral_weight(self, *, q_squared: Quantity) -> np.ndarray:
+        """Return dimensionless spectrum shape at squared wavenumbers in m^-2.
+
+        The zero-wavenumber weight is one. This is not the normalized continuum
+        power spectral density; the synthesis code supplies discrete variance
+        normalization. Inputs must be finite and nonnegative.
+        """
+
+        validate_units(
+            q_squared,
+            unit="1 / meter**2",
+            name="q_squared",
+        )
+
+        if np.any(~np.isfinite(q_squared)) or np.any(q_squared < 0):
+            raise ValueError("q_squared must be finite and nonnegative.")
+
+        scaled = (q_squared * self.correlation_length**2).to("dimensionless").magnitude
+
+        if self.correlation == "gaussian":
+            return np.exp(-scaled / 2)
+
+        if self.correlation == "exponential":
+            return (1 + scaled) ** -2
+
+        assert self.smoothness is not None
+
+        # log1p avoids loss of precision for small q and large smoothness.
+        return np.exp(-(self.smoothness + 1.5) * np.log1p(scaled / (2 * self.smoothness)))
+
+    def to_volume(
+        self,
+        *,
+        grid: Grid | None = None,
+        shape: tuple[int, int, int] | None = None,
+        spacing: Quantity | None = None,
+        seed: int = 0,
+    ) -> "Volume":
+        """Generate a seeded Gaussian random refractive index field with a chosen covariance.
+
+        Parameters
+        ----------
+        grid : Grid, optional
+            Explicit shared spatial configuration. Cannot be
+            combined with the legacy shape and spacing keywords.
+        shape : tuple of int, optional
+            Three sample dimensions, each from 2 to 32. Required with spacing when grid is omitted.
+        spacing : Quantity, optional
+            Positive, finite cubic voxel spacing; length values require explicit units.
+            Must be supplied with shape when grid is omitted.
+        seed : int, optional
+            Reproducible random seed, from 0 to 2**32 - 1. Default is 0.
+
+        Returns
+        -------
+        volume : Volume
+            Cropped fluctuation field with unit-bearing spacing and dimensionless background refractive index.
+
+        Raises
+        ------
+        ValueError
+            If shape, spacing, units, or seed are invalid, or the generated
+            linearized relative permittivity is nonpositive.
+
+        Notes
+        -----
+        The probability distribution is Gaussian for every spatial covariance
+        choice. Spectral synthesis uses a periodic box doubled along every axis,
+        then crops its first half. The discrete spectrum approximates the continuum
+        covariance and normalizes the expected point variance. The DC component is
+        retained; individual samples are never recentered or rescaled. Resolution
+        and finite synthesis-box size can alter the sampled covariance.
+
+        Examples
+        --------
+        >>> from bornsim import RandomMedium
+        ...
+        >>> from bornsim.units import ureg
+        ...
+        >>> 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=(4, 4, 4),
+        ...     seed=42,
+        ...     spacing=50e-9 * ureg.meter,
+        ... )
+        >>> volume.delta_refractive_index.shape
+        (4, 4, 4)
+        """
+
+        from .volume import Volume
+
+        grid = Grid._resolve(
+            grid=grid,
+            shape=shape,
+            spacing=spacing,
+        )
+
+        # FFT frequencies require numeric spacing in a chosen length unit.
+        sample_grid_shape = grid.shape
+
+        voxel_spacing_m = float(grid.spacing.to("meter").magnitude)
+
+        seed = _integer(
+            value=seed,
+            name="seed",
+            low=0,
+            high=2**32 - 1,
+        )
+
+        synthesis_grid_shape = tuple(2 * voxel_count for voxel_count in sample_grid_shape)
+
+        axis_wavenumbers_per_meter = [
+            2 * np.pi * np.fft.fftfreq(voxel_count, voxel_spacing_m) for voxel_count in synthesis_grid_shape
+        ]
+
+        squared_wavenumbers_per_meter_squared = np.zeros(synthesis_grid_shape)
+
+        for wavenumber_component_per_meter in np.meshgrid(*axis_wavenumbers_per_meter, indexing="ij"):
+            squared_wavenumbers_per_meter_squared += wavenumber_component_per_meter**2
+
+        normalized_spectral_weights = self.spectral_weight(
+            q_squared=squared_wavenumbers_per_meter_squared * (1 / ureg.meter**2)
+        )
+
+        # Normalize expected point variance, not each sample's spatial variance.
+        normalized_spectral_weights /= normalized_spectral_weights.mean()
+
+        uncorrelated_gaussian_noise = np.random.default_rng(seed).normal(size=synthesis_grid_shape)
+
+        synthesized_refractive_index_fluctuations = (
+            np.fft.ifftn(np.fft.fftn(uncorrelated_gaussian_noise) * np.sqrt(normalized_spectral_weights)).real
+            * self.refractive_index_std
+        )
+
+        sample_crop = tuple(slice(0, voxel_count) for voxel_count in sample_grid_shape)
+
+        return Volume(
+            delta_refractive_index=synthesized_refractive_index_fluctuations[sample_crop],
+            grid=grid,
+            background_refractive_index=self.background_refractive_index,
+            medium=self,
+            seed=seed,
+        )
+
+
+def random_volume(
+    *,
+    medium: RandomMedium,
+    grid: Grid | None = None,
+    shape: tuple[int, int, int] | None = None,
+    spacing: Quantity | None = None,
+    seed: int = 0,
+) -> "Volume":
+    """Generate a seeded Gaussian refractive index field via :meth:`RandomMedium.to_volume`.
+
+    Medium specifies the covariance and ensemble statistics. Shape contains
+    three integers from 2 to 32; spacing is a positive SI length or quantity.
+    Seed lies in 0 to 2**32-1. Expected point variance is preserved without
+    forcing individual sample means or variances. See the medium method for
+    the spectral synthesis equations and finite-box conventions.
+    """
+
+    if not isinstance(medium, RandomMedium):
+        raise TypeError("medium must be a RandomMedium.")
+
+    return medium.to_volume(
+        grid=grid,
+        shape=shape,
+        spacing=spacing,
+        seed=seed,
+    )