lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/absorption/spectral.py

@@ -0,0 +1,410 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Absorption Kernels for SpectralInhomogeneousModel
+
+GPU kernels for applying Beer-Lambert absorption using 2D altitude×wavelength LUT.
+Supports both scalar wavelength (all rays same λ) and per-ray wavelength modes.
+"""
+
+import math
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = True
+except ImportError:
+
+    class _FakeCuda:
+        """Fake cuda module for when numba is not installed."""
+
+        class devicearray:
+            """Fake devicearray submodule."""
+
+            DeviceNDArray = object
+
+        @staticmethod
+        def jit(*args, **kwargs):
+            """Return a no-op decorator."""
+
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+@cuda.jit(device=True)
+def _device_bilinear_interpolate(
+    val1: float,
+    val2: float,
+    lut: cuda.devicearray.DeviceNDArray,
+    min1: float,
+    delta1: float,
+    n1: int,
+    min2: float,
+    delta2: float,
+    n2: int,
+) -> float:
+    """
+    Bilinear interpolation in 2D LUT.
+
+    Parameters
+    ----------
+    val1 : float
+        Value in first dimension (e.g., altitude)
+    val2 : float
+        Value in second dimension (e.g., wavelength)
+    lut : device array
+        2D lookup table [dim1, dim2]
+    min1 : float
+        Minimum value in first dimension
+    delta1 : float
+        Spacing in first dimension
+    n1 : int
+        Number of entries in first dimension
+    min2 : float
+        Minimum value in second dimension
+    delta2 : float
+        Spacing in second dimension
+    n2 : int
+        Number of entries in second dimension
+
+    Returns
+    -------
+    float
+        Interpolated value
+    """
+    # Normalize coordinates to fractional indices
+    idx1 = (val1 - min1) / delta1
+    idx2 = (val2 - min2) / delta2
+
+    # Clamp to valid bounds
+    if idx1 < 0.0:
+        idx1 = 0.0
+    if idx1 > n1 - 1.001:
+        idx1 = n1 - 1.001
+    if idx2 < 0.0:
+        idx2 = 0.0
+    if idx2 > n2 - 1.001:
+        idx2 = n2 - 1.001
+
+    # Get integer indices
+    i0 = int(idx1)
+    j0 = int(idx2)
+    i1 = i0 + 1
+    j1 = j0 + 1
+
+    # Clamp upper indices
+    if i1 > n1 - 1:
+        i1 = n1 - 1
+    if j1 > n2 - 1:
+        j1 = n2 - 1
+
+    # Fractional parts
+    fi = idx1 - i0
+    fj = idx2 - j0
+
+    # Bilinear interpolation
+    c00 = lut[i0, j0]
+    c01 = lut[i0, j1]
+    c10 = lut[i1, j0]
+    c11 = lut[i1, j1]
+
+    # Interpolate along second dimension first
+    c0 = c00 * (1.0 - fj) + c01 * fj
+    c1 = c10 * (1.0 - fj) + c11 * fj
+
+    # Then interpolate along first dimension
+    return c0 * (1.0 - fi) + c1 * fi
+
+
+@cuda.jit
+def _kernel_absorption_spectral(
+    positions,
+    directions,
+    active,
+    intensities,
+    optical_depth,
+    step_size: float,
+    num_steps: int,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    ref_radius: float,
+    alt_min: float,
+    alt_delta: float,
+    n_alt: int,
+    wl_min: float,
+    wl_delta: float,
+    n_wl: int,
+    lut_alpha,
+    wavelength: float,
+):
+    """
+    Apply Beer-Lambert absorption for SpectralInhomogeneousModel.
+
+    Integrates absorption along the ray path using 2D LUT interpolation
+    for wavelength-dependent absorption. All rays use the same wavelength.
+
+    Parameters
+    ----------
+    positions : device array, shape (N, 3)
+        Ray positions (after propagation)
+    directions : device array, shape (N, 3)
+        Ray directions (unit vectors)
+    active : device array, shape (N,)
+        Boolean mask for active rays
+    intensities : device array, shape (N,)
+        Ray intensities (modified in-place)
+    optical_depth : device array, shape (N,)
+        Accumulated optical depth (modified in-place)
+    step_size : float
+        Integration step size in meters
+    num_steps : int
+        Number of steps taken in propagation
+    center_x, center_y, center_z : float
+        Center of spherical symmetry
+    ref_radius : float
+        Reference radius
+    alt_min : float
+        Minimum altitude in LUT
+    alt_delta : float
+        Altitude spacing in LUT
+    n_alt : int
+        Number of altitude samples
+    wl_min : float
+        Minimum wavelength in LUT
+    wl_delta : float
+        Wavelength spacing in LUT
+    n_wl : int
+        Number of wavelength samples
+    lut_alpha : device array, shape (n_alt, n_wl)
+        2D lookup table for α(altitude, wavelength)
+    wavelength : float
+        Wavelength in meters (same for all rays)
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+    if not active[idx]:
+        return
+
+    # Get current position and direction
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+    dx_dir = directions[idx, 0]
+    dy_dir = directions[idx, 1]
+    dz_dir = directions[idx, 2]
+
+    # Integrate absorption along path by stepping backwards
+    delta_tau = 0.0
+
+    for step in range(num_steps):
+        # Position at this step (walking backwards from current)
+        back_dist = step * step_size
+        px = x - dx_dir * back_dist
+        py = y - dy_dir * back_dist
+        pz = z - dz_dir * back_dist
+
+        # Compute altitude from position
+        rx = px - center_x
+        ry = py - center_y
+        rz = pz - center_z
+        r = math.sqrt(rx * rx + ry * ry + rz * rz)
+        altitude = r - ref_radius
+        if altitude < 0.0:
+            altitude = 0.0
+
+        # Look up absorption coefficient (2D interpolation)
+        alpha = _device_bilinear_interpolate(
+            altitude,
+            wavelength,
+            lut_alpha,
+            alt_min,
+            alt_delta,
+            n_alt,
+            wl_min,
+            wl_delta,
+            n_wl,
+        )
+
+        # Accumulate optical depth for this step
+        delta_tau += alpha * step_size
+
+    # Apply Beer-Lambert decay: I = I₀ * exp(-τ)
+    intensities[idx] *= math.exp(-delta_tau)
+
+    # Accumulate optical depth
+    optical_depth[idx] += delta_tau
+
+
+@cuda.jit
+def _kernel_absorption_spectral_perray(
+    positions,
+    directions,
+    wavelengths,
+    active,
+    intensities,
+    optical_depth,
+    step_size: float,
+    num_steps: int,
+    center_x: float,
+    center_y: float,
+    center_z: float,
+    ref_radius: float,
+    alt_min: float,
+    alt_delta: float,
+    n_alt: int,
+    wl_min: float,
+    wl_delta: float,
+    n_wl: int,
+    lut_alpha,
+):
+    """
+    Apply Beer-Lambert absorption with per-ray wavelengths.
+
+    Integrates absorption along the ray path. Each ray has its own
+    wavelength, enabling chromatic absorption simulation.
+
+    Parameters
+    ----------
+    positions : device array, shape (N, 3)
+        Ray positions (after propagation)
+    directions : device array, shape (N, 3)
+        Ray directions (unit vectors)
+    wavelengths : device array, shape (N,)
+        Per-ray wavelengths in meters
+    active : device array, shape (N,)
+        Boolean mask for active rays
+    intensities : device array, shape (N,)
+        Ray intensities (modified in-place)
+    optical_depth : device array, shape (N,)
+        Accumulated optical depth (modified in-place)
+    step_size : float
+        Integration step size in meters
+    num_steps : int
+        Number of steps taken in propagation
+    center_x, center_y, center_z : float
+        Center of spherical symmetry
+    ref_radius : float
+        Reference radius
+    alt_min : float
+        Minimum altitude in LUT
+    alt_delta : float
+        Altitude spacing in LUT
+    n_alt : int
+        Number of altitude samples
+    wl_min : float
+        Minimum wavelength in LUT
+    wl_delta : float
+        Wavelength spacing in LUT
+    n_wl : int
+        Number of wavelength samples
+    lut_alpha : device array, shape (n_alt, n_wl)
+        2D lookup table for α(altitude, wavelength)
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+    if not active[idx]:
+        return
+
+    # Get current position, direction, and wavelength
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+    dx_dir = directions[idx, 0]
+    dy_dir = directions[idx, 1]
+    dz_dir = directions[idx, 2]
+    wavelength = wavelengths[idx]
+
+    # Integrate absorption along path by stepping backwards
+    delta_tau = 0.0
+
+    for step in range(num_steps):
+        # Position at this step (walking backwards from current)
+        back_dist = step * step_size
+        px = x - dx_dir * back_dist
+        py = y - dy_dir * back_dist
+        pz = z - dz_dir * back_dist
+
+        # Compute altitude from position
+        rx = px - center_x
+        ry = py - center_y
+        rz = pz - center_z
+        r = math.sqrt(rx * rx + ry * ry + rz * rz)
+        altitude = r - ref_radius
+        if altitude < 0.0:
+            altitude = 0.0
+
+        # Look up absorption coefficient (2D interpolation)
+        alpha = _device_bilinear_interpolate(
+            altitude,
+            wavelength,
+            lut_alpha,
+            alt_min,
+            alt_delta,
+            n_alt,
+            wl_min,
+            wl_delta,
+            n_wl,
+        )
+
+        # Accumulate optical depth for this step
+        delta_tau += alpha * step_size
+
+    # Apply Beer-Lambert decay: I = I₀ * exp(-τ)
+    intensities[idx] *= math.exp(-delta_tau)
+
+    # Accumulate optical depth
+    optical_depth[idx] += delta_tau

lsurf/propagation/kernels/detection/__init__.py

@@ -0,0 +1,64 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Detection Kernels
+
+CUDA kernels for GPU-accelerated ray detection.
+
+This module exports ONLY pure CUDA kernels.
+GPU memory management is handled by the propagator layer (handlers).
+
+Kernel Types
+------------
+- SPHERICAL_SINGLE: Single spherical detector
+- SPHERICAL_MULTI: Multiple spherical detectors (scan mode)
+- PLANAR_SINGLE: Single planar detector (TODO)
+"""
+
+from .protocol import DetectionKernelProtocol
+from .spherical import (
+    kernel_spherical_detect_single,
+    kernel_spherical_detect_multi,
+    HAS_CUDA,
+)
+
+__all__ = [
+    # Protocol
+    "DetectionKernelProtocol",
+    # Kernels (pure CUDA only)
+    "kernel_spherical_detect_single",
+    "kernel_spherical_detect_multi",
+    # CUDA availability
+    "HAS_CUDA",
+]

lsurf/propagation/kernels/detection/protocol.py

@@ -0,0 +1,102 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Detection Kernel Protocol
+
+Defines the interface for ray detection kernels that find
+rays hitting detector surfaces.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from numba.cuda.devicearray import DeviceNDArray
+
+
+@runtime_checkable
+class DetectionKernelProtocol(Protocol):
+    """
+    Protocol for ray detection kernels.
+
+    Detection kernels find rays that intersect with detector surfaces
+    and compute detection parameters (hit time, position, intensity).
+
+    Common Parameters
+    -----------------
+    ray_positions : DeviceNDArray, shape (N, 3)
+        Ray positions in meters
+    ray_directions : DeviceNDArray, shape (N, 3)
+        Ray direction unit vectors
+    ray_active : DeviceNDArray, shape (N,)
+        Boolean mask of active rays
+    ray_times : DeviceNDArray, shape (N,)
+        Accumulated ray times in seconds
+    ray_intensities : DeviceNDArray, shape (N,)
+        Ray intensities
+    hit_mask_out : DeviceNDArray, shape (N,)
+        Output: boolean mask of rays that hit detector
+    hit_distances_out : DeviceNDArray, shape (N,)
+        Output: distance to detector
+    hit_times_out : DeviceNDArray, shape (N,)
+        Output: arrival time at detector
+
+    Detector-Specific Parameters
+    ----------------------------
+    Additional parameters depend on the detector type:
+    - Spherical: center position, radius
+    - Planar: normal vector, point on plane
+
+    Notes
+    -----
+    Kernels are registered with the central registry using @register_kernel
+    decorator and DetectionKernelID enum values.
+    """
+
+    def __call__(
+        self,
+        ray_positions: DeviceNDArray,
+        ray_directions: DeviceNDArray,
+        ray_active: DeviceNDArray,
+        ray_times: DeviceNDArray,
+        ray_intensities: DeviceNDArray,
+        hit_mask_out: DeviceNDArray,
+        hit_distances_out: DeviceNDArray,
+        hit_times_out: DeviceNDArray,
+        *args,
+        **kwargs,
+    ) -> None:
+        """Execute the detection kernel."""
+        ...