lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/registry.py

@@ -0,0 +1,331 @@
+# 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.
+
+"""
+Kernel and Propagator Registry
+
+Central registry for all kernel types in the ray tracing system:
+- PropagationKernelID: Material propagation kernels
+- IntersectionKernelID: Surface intersection kernels
+- DetectionKernelID: Ray detection kernels
+- FresnelKernelID: Fresnel reflection/refraction kernels
+- PropagatorID: Propagator implementations
+
+This module provides:
+- Kernel ID enums for each category
+- Registration decorator and lookup functions
+- Unified registry for all kernel types
+"""
+
+from enum import Enum, auto
+from typing import Callable
+
+__all__ = [
+    # Enums
+    "PropagationKernelID",
+    "IntersectionKernelID",
+    "DetectionKernelID",
+    "FresnelKernelID",
+    "PropagatorID",
+    "KernelID",
+    # Registration
+    "register_kernel",
+    "get_kernel",
+    "get_registered_kernels",
+    "list_kernels",
+]
+
+
+# =============================================================================
+# Kernel Identifier Enums
+# =============================================================================
+
+
+class PropagationKernelID(Enum):
+    """
+    Identifiers for material propagation kernels.
+
+    Each kernel corresponds to a specific integration method and material type.
+    Materials declare which kernels they support, and propagators use these
+    IDs to select the appropriate CUDA kernel.
+
+    Naming convention: {MATERIAL_TYPE}_{INTEGRATION_METHOD}
+
+    Examples
+    --------
+    >>> from lsurf.propagation.kernels import PropagationKernelID
+    >>> PropagationKernelID.SIMPLE_RK4
+    <PropagationKernelID.SIMPLE_RK4: ...>
+    """
+
+    # Simple inhomogeneous (1D LUT - altitude only)
+    SIMPLE_EULER = auto()
+    SIMPLE_RK4 = auto()
+
+    # Spectral inhomogeneous (2D LUT - altitude × wavelength)
+    SPECTRAL_EULER = auto()
+    SPECTRAL_RK4 = auto()
+    SPECTRAL_EULER_PERRAY = auto()
+    SPECTRAL_RK4_PERRAY = auto()
+
+    # Grid inhomogeneous (3D grid with trilinear interpolation)
+    GRID_EULER = auto()
+    GRID_RK4 = auto()
+
+
+class IntersectionKernelID(Enum):
+    """
+    Identifiers for surface intersection kernels.
+
+    Each kernel corresponds to a specific geometry type and intersection method.
+    Surfaces declare which kernels they support for ray-surface intersection.
+
+    Note: Complex surfaces (waves, curved surfaces) use the generic signed
+    distance kernels which dispatch to device functions based on geometry_id.
+
+    Naming convention: {GEOMETRY_TYPE}_{METHOD}
+
+    Examples
+    --------
+    >>> from lsurf.propagation.kernels import IntersectionKernelID
+    >>> IntersectionKernelID.PLANE_ANALYTICAL
+    <IntersectionKernelID.PLANE_ANALYTICAL: ...>
+    """
+
+    # Analytical (GPU-capable, fast) - specific geometry kernels
+    PLANE_ANALYTICAL = auto()  # Ray-plane intersection
+    SPHERE_ANALYTICAL = auto()  # Ray-sphere intersection
+    BOUNDED_PLANE_ANALYTICAL = auto()  # Ray-bounded-plane intersection
+    ANNULAR_PLANE_ANALYTICAL = auto()  # Ray-annular-plane intersection
+
+    # Generic dispatch kernels (GPU-capable, all geometry types)
+    SIGNED_DISTANCE_GENERIC = auto()  # Signed distance for any surface via geometry_id
+    SURFACE_NORMAL_GENERIC = auto()  # Surface normal for any surface via geometry_id
+
+
+class DetectionKernelID(Enum):
+    """
+    Identifiers for ray detection kernels.
+
+    Each kernel corresponds to a specific detector geometry.
+
+    Naming convention: {GEOMETRY_TYPE}_{VARIANT}
+
+    Examples
+    --------
+    >>> from lsurf.propagation.kernels import DetectionKernelID
+    >>> DetectionKernelID.SPHERICAL_SINGLE
+    <DetectionKernelID.SPHERICAL_SINGLE: ...>
+    """
+
+    SPHERICAL_SINGLE = auto()  # Single spherical detector
+    SPHERICAL_MULTI = auto()  # Multiple spherical detectors (scan mode)
+    PLANAR_SINGLE = auto()  # Single planar detector
+
+
+class FresnelKernelID(Enum):
+    """
+    Identifiers for Fresnel reflection/refraction kernels.
+
+    Each kernel implements a specific approach to computing Fresnel coefficients.
+
+    Examples
+    --------
+    >>> from lsurf.propagation.kernels import FresnelKernelID
+    >>> FresnelKernelID.STANDARD
+    <FresnelKernelID.STANDARD: ...>
+    """
+
+    STANDARD = auto()  # Standard Fresnel equations (unpolarized)
+    POLARIZED = auto()  # Polarization-aware Fresnel equations
+
+
+class PropagatorID(Enum):
+    """
+    Identifiers for available propagator implementations.
+
+    Each propagator ID corresponds to a specific propagator class that handles
+    ray propagation through materials.
+
+    Examples
+    --------
+    >>> from lsurf.propagation.kernels import PropagatorID
+    >>> PropagatorID.GPU_GRADIENT
+    <PropagatorID.GPU_GRADIENT: ...>
+    """
+
+    CPU_GRADIENT = auto()  # GradientPropagator (CPU, any material)
+    GPU_GRADIENT = auto()  # GPUGradientPropagator (GPU, scalar wavelength)
+    GPU_SPECTRAL = auto()  # SpectralGPUGradientPropagator (GPU, per-ray wavelength)
+    GPU_SURFACE = auto()  # SurfacePropagator (GPU, with intersection detection)
+
+
+# =============================================================================
+# Type Aliases
+# =============================================================================
+
+# Union type for any kernel ID
+KernelID = (
+    PropagationKernelID | IntersectionKernelID | DetectionKernelID | FresnelKernelID
+)
+
+
+# =============================================================================
+# Kernel Registration System
+# =============================================================================
+
+# Global registry mapping kernel ID → kernel function
+_KERNEL_REGISTRY: dict[KernelID, Callable] = {}
+
+
+def register_kernel(kernel_id: KernelID):
+    """
+    Decorator to register a kernel function with the global registry.
+
+    Parameters
+    ----------
+    kernel_id : KernelID
+        The unique identifier for this kernel. Can be any kernel ID type:
+        PropagationKernelID, IntersectionKernelID, DetectionKernelID,
+        or FresnelKernelID.
+
+    Returns
+    -------
+    decorator
+        A decorator that registers the function and returns it unchanged.
+
+    Examples
+    --------
+    >>> @register_kernel(PropagationKernelID.SIMPLE_EULER)
+    ... def my_euler_kernel(positions, directions, ...):
+    ...     ...
+
+    >>> @register_kernel(DetectionKernelID.SPHERICAL_SINGLE)
+    ... def my_detection_kernel(positions, directions, ...):
+    ...     ...
+
+    Notes
+    -----
+    Registration happens at import time. The registered function can be
+    retrieved later using get_kernel().
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if kernel_id in _KERNEL_REGISTRY:
+            existing = _KERNEL_REGISTRY[kernel_id]
+            raise ValueError(
+                f"Kernel {kernel_id} already registered by {existing.__name__}. "
+                f"Cannot register {func.__name__}."
+            )
+        _KERNEL_REGISTRY[kernel_id] = func
+        return func
+
+    return decorator
+
+
+def get_kernel(kernel_id: KernelID) -> Callable:
+    """
+    Retrieve a registered kernel function by ID.
+
+    Parameters
+    ----------
+    kernel_id : KernelID
+        The identifier of the kernel to retrieve. Can be any kernel ID type.
+
+    Returns
+    -------
+    Callable
+        The registered kernel function.
+
+    Raises
+    ------
+    KeyError
+        If the kernel ID is not registered.
+
+    Examples
+    --------
+    >>> kernel = get_kernel(PropagationKernelID.SIMPLE_RK4)
+    >>> kernel(positions, directions, ...)
+
+    >>> detect = get_kernel(DetectionKernelID.SPHERICAL_SINGLE)
+    >>> detect(positions, directions, ...)
+    """
+    if kernel_id not in _KERNEL_REGISTRY:
+        registered = list(_KERNEL_REGISTRY.keys())
+        raise KeyError(
+            f"Kernel {kernel_id} not registered. " f"Available kernels: {registered}"
+        )
+    return _KERNEL_REGISTRY[kernel_id]
+
+
+def get_registered_kernels() -> dict[KernelID, Callable]:
+    """
+    Return a copy of all registered kernels.
+
+    Returns
+    -------
+    dict
+        Dictionary mapping kernel IDs to kernel functions.
+    """
+    return _KERNEL_REGISTRY.copy()
+
+
+def list_kernels(kernel_type: type[Enum] | None = None) -> list[KernelID]:
+    """
+    List all registered kernels, optionally filtered by type.
+
+    Parameters
+    ----------
+    kernel_type : type[Enum], optional
+        If provided, only return kernels of this enum type.
+        For example, PropagationKernelID to list only propagation kernels.
+
+    Returns
+    -------
+    list[KernelID]
+        List of registered kernel IDs.
+
+    Examples
+    --------
+    >>> # List all registered kernels
+    >>> all_kernels = list_kernels()
+
+    >>> # List only propagation kernels
+    >>> prop_kernels = list_kernels(PropagationKernelID)
+
+    >>> # List only detection kernels
+    >>> detect_kernels = list_kernels(DetectionKernelID)
+    """
+    if kernel_type is None:
+        return list(_KERNEL_REGISTRY.keys())
+    return [k for k in _KERNEL_REGISTRY.keys() if isinstance(k, kernel_type)]

lsurf/propagation/kernels/surface/__init__.py

@@ -0,0 +1,72 @@
+# 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.
+
+"""
+Surface Detection Kernels
+
+GPU kernels for surface intersection detection, bisection refinement,
+and status reduction. These kernels work with GPUDeviceRays to enable
+GPU-resident surface propagation.
+
+Kernels
+-------
+kernel_save_prev_positions
+    Save current positions before propagation step (for bisection)
+kernel_detect_crossing
+    Check all surfaces for sign changes in signed distance
+kernel_bisect_crossing
+    Bisection refinement for rays that crossed a surface
+kernel_reduce_status
+    Count active rays and check for crossings
+"""
+
+from .detection import (
+    kernel_save_prev_positions,
+    kernel_detect_crossing,
+    kernel_init_signed_distances,
+    kernel_compute_min_surface_distance,
+    kernel_compute_adaptive_steps,
+)
+from .bisection import kernel_bisect_crossing
+from .reduction import kernel_reduce_status, kernel_reduce_status_shared
+
+__all__ = [
+    "kernel_save_prev_positions",
+    "kernel_detect_crossing",
+    "kernel_init_signed_distances",
+    "kernel_compute_min_surface_distance",
+    "kernel_compute_adaptive_steps",
+    "kernel_bisect_crossing",
+    "kernel_reduce_status",
+    "kernel_reduce_status_shared",
+]

lsurf/propagation/kernels/surface/bisection.py

@@ -0,0 +1,232 @@
+# 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.
+
+"""
+Surface Bisection Refinement Kernel
+
+GPU kernel for refining intersection points using bisection method
+after a crossing has been detected.
+"""
+
+import math
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = cuda.is_available()
+except ImportError:
+    HAS_CUDA = False
+
+    class _FakeCuda:
+        @staticmethod
+        def jit(*args, **kwargs):
+            def decorator(func):
+                return func
+
+            if args and callable(args[0]):
+                return args[0]
+            return decorator
+
+        @staticmethod
+        def grid(n):
+            return 0
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+
+
+# Import device functions for signed distance computation
+from ..intersection.signed_distance import (
+    _device_plane_sd,
+    _device_sphere_sd,
+    _device_gerstner_sd,
+    _device_curved_wave_sd,
+    _device_multi_curved_wave_sd,
+    _device_annular_plane_sd,
+)
+
+
+@cuda.jit(device=True)
+def _device_signed_distance_bisect(
+    x: float, y: float, z: float, geometry_id: int, params, param_offset: int
+) -> float:
+    """
+    Compute signed distance for bisection.
+
+    Same as _device_signed_distance but duplicated to avoid circular import.
+    """
+    if geometry_id == 1:
+        return _device_plane_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 2:
+        return _device_sphere_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 3:
+        return _device_gerstner_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 4:
+        return _device_curved_wave_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 5:
+        return _device_multi_curved_wave_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 7:
+        return _device_annular_plane_sd(x, y, z, params[param_offset:])
+    else:
+        return math.inf
+
+
+@cuda.jit
+def kernel_bisect_crossing(
+    prev_positions,  # (N, 3) positions before step
+    curr_positions,  # (N, 3) positions after step
+    crossing_mask,  # (N,) rays that crossed
+    hit_surface_idx,  # (N,) which surface was hit
+    geometry_ids,  # (S,) geometry ID per surface
+    surface_params,  # (S * MAX_PARAMS,) all surface parameters
+    max_params,  # int: MAX_SURFACE_PARAMS
+    hit_positions,  # (N, 3) output: refined hit positions
+    active,  # (N,) in/out: deactivate rays that hit
+    num_iterations,  # int: bisection iterations (default 10)
+    geo_path=None,  # (N,) geometric path length to correct
+    opt_path=None,  # (N,) optical path length to correct
+    acc_time=None,  # (N,) accumulated time to correct
+    step_sizes=None,  # (N,) step size per ray for correction
+    n=1.0,  # refractive index for correction
+    c=299792458.0,  # speed of light for correction
+):
+    """
+    Bisection refinement for rays that crossed a surface.
+
+    For each ray that crossed a surface, use bisection to find
+    the exact intersection point between prev_positions and curr_positions.
+
+    Parameters
+    ----------
+    prev_positions : (N, 3) float32 device array
+        Ray positions before propagation step
+    curr_positions : (N, 3) float32 device array
+        Ray positions after propagation step
+    crossing_mask : (N,) bool device array
+        True for rays that crossed a surface
+    hit_surface_idx : (N,) int32 device array
+        Surface index that was crossed
+    geometry_ids : (S,) int32 device array
+        Geometry ID for each surface
+    surface_params : (S * MAX_PARAMS,) float32 device array
+        Concatenated surface parameters
+    max_params : int
+        MAX_SURFACE_PARAMS constant
+    hit_positions : (N, 3) float32 device array
+        Output: Refined intersection positions
+    active : (N,) bool device array
+        In/out: Rays are deactivated after intersection
+    num_iterations : int
+        Number of bisection iterations (typically 10)
+    """
+    idx = cuda.grid(1)
+    if idx >= curr_positions.shape[0] or not crossing_mask[idx]:
+        return
+
+    surf = hit_surface_idx[idx]
+    geo_id = geometry_ids[surf]
+    param_offset = surf * max_params
+
+    # Load endpoints
+    p0x = prev_positions[idx, 0]
+    p0y = prev_positions[idx, 1]
+    p0z = prev_positions[idx, 2]
+    p1x = curr_positions[idx, 0]
+    p1y = curr_positions[idx, 1]
+    p1z = curr_positions[idx, 2]
+
+    # Get signed distance at p0 to know which side is positive
+    sd_p0 = _device_signed_distance_bisect(
+        p0x, p0y, p0z, geo_id, surface_params, param_offset
+    )
+
+    # Bisection loop
+    for _ in range(num_iterations):
+        midx = (p0x + p1x) * 0.5
+        midy = (p0y + p1y) * 0.5
+        midz = (p0z + p1z) * 0.5
+
+        sd_mid = _device_signed_distance_bisect(
+            midx, midy, midz, geo_id, surface_params, param_offset
+        )
+
+        # Check for convergence
+        if abs(sd_mid) < 1e-6:
+            break
+
+        # Determine which half contains the crossing
+        if (sd_p0 >= 0) != (sd_mid >= 0):
+            # Crossing is in first half
+            p1x, p1y, p1z = midx, midy, midz
+        else:
+            # Crossing is in second half
+            p0x, p0y, p0z = midx, midy, midz
+            sd_p0 = sd_mid
+
+    # Store hit position (midpoint of final interval)
+    hit_x = (p0x + p1x) * 0.5
+    hit_y = (p0y + p1y) * 0.5
+    hit_z = (p0z + p1z) * 0.5
+    hit_positions[idx, 0] = hit_x
+    hit_positions[idx, 1] = hit_y
+    hit_positions[idx, 2] = hit_z
+
+    # Correct accumulated path/time for exact intersection distance
+    # (only if correction arrays are provided)
+    if geo_path is not None and step_sizes is not None:
+        # Compute actual distance traveled (prev_pos to hit_pos)
+        dx = hit_x - prev_positions[idx, 0]
+        dy = hit_y - prev_positions[idx, 1]
+        dz = hit_z - prev_positions[idx, 2]
+        actual_distance = math.sqrt(dx * dx + dy * dy + dz * dz)
+
+        # Compute excess distance (step already accumulated - actual)
+        excess_distance = step_sizes[idx] - actual_distance
+
+        # Remove excess from accumulated values
+        geo_path[idx] -= excess_distance
+        if opt_path is not None:
+            opt_path[idx] -= n * excess_distance
+        if acc_time is not None:
+            acc_time[idx] -= n * excess_distance / c
+
+    # Update current position to hit position
+    curr_positions[idx, 0] = hit_x
+    curr_positions[idx, 1] = hit_y
+    curr_positions[idx, 2] = hit_z
+
+    # Mark ray as inactive
+    active[idx] = False
+
+
+__all__ = ["kernel_bisect_crossing"]