lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/gpu_device_rays.py

@@ -0,0 +1,294 @@
+# 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.
+
+"""
+GPU Device Rays - Unified GPU Ray Data Structure
+
+Provides a single data class holding device arrays for ALL GPU operations.
+Both material propagation kernels and surface detection kernels operate on
+these same device arrays - no duplication.
+
+This minimizes CPU-GPU transfers by keeping ray data GPU-resident throughout
+the entire propagation loop.
+
+Memory Layout
+-------------
+GPUDeviceRays contains:
+- Core ray state (positions, directions, active, paths) - used by propagation
+- Surface detection state (prev_positions, signed_dist, crossings) - used by detection
+- Reduction output (tiny, single copy per step for loop termination)
+
+Usage
+-----
+    # One-time upload at start
+    gpu_rays = GPUDeviceRays.from_ray_batch(rays, num_surfaces)
+
+    # GPU-resident loop
+    for step in range(max_steps):
+        # Kernels operate on same device arrays
+        propagation_kernel[...](gpu_rays.d_positions, gpu_rays.d_directions, ...)
+        detection_kernel[...](gpu_rays.d_positions, gpu_rays.d_prev_signed_dist, ...)
+
+    # One-time download at end
+    gpu_rays.to_ray_batch(rays)
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+# GPU support is optional
+try:
+    from numba import cuda
+
+    HAS_CUDA = cuda.is_available()
+except ImportError:
+    HAS_CUDA = False
+
+    class _FakeCuda:
+        @staticmethod
+        def is_available():
+            return False
+
+        @staticmethod
+        def to_device(arr):
+            return arr
+
+        @staticmethod
+        def device_array(shape, dtype=np.float32):
+            return np.zeros(shape, dtype=dtype)
+
+        @staticmethod
+        def synchronize():
+            pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+
+
+if TYPE_CHECKING:
+    from ..utilities.ray_data import RayBatch
+
+
+@dataclass
+class GPUDeviceRays:
+    """
+    Unified GPU ray storage shared by propagation and surface detection.
+
+    Both GPUGradientPropagator kernels and surface detection kernels
+    operate on these same device arrays - no duplication.
+
+    Attributes
+    ----------
+    d_positions : device array, shape (N, 3)
+        Ray positions (float32)
+    d_directions : device array, shape (N, 3)
+        Ray directions (float32)
+    d_active : device array, shape (N,)
+        Active mask (bool)
+    d_geo_path : device array, shape (N,)
+        Geometric path lengths (float32)
+    d_opt_path : device array, shape (N,)
+        Optical path lengths (float32)
+    d_acc_time : device array, shape (N,)
+        Accumulated time (float32)
+    d_wavelengths : device array, shape (N,)
+        Ray wavelengths (float32)
+    d_intensities : device array, shape (N,)
+        Ray intensities (float32)
+    d_optical_depth : device array, shape (N,)
+        Accumulated optical depth τ = ∫α·ds (float32)
+    d_prev_positions : device array, shape (N, 3)
+        Previous positions for bisection (float32)
+    d_prev_signed_dist : device array, shape (N, S)
+        Previous signed distances per surface (float32)
+    d_hit_surface_idx : device array, shape (N,)
+        Surface index for each hit (-1 = no hit) (int32)
+    d_hit_positions : device array, shape (N, 3)
+        Hit positions (float32)
+    d_crossing_mask : device array, shape (N,)
+        Rays that crossed a surface this step (bool)
+    d_reduction_result : device array, shape (2,)
+        [num_active, num_crossing] for loop termination (int32)
+    num_rays : int
+        Total number of rays
+    num_surfaces : int
+        Number of surfaces being tracked
+    """
+
+    d_positions: npt.NDArray
+    d_directions: npt.NDArray
+    d_active: npt.NDArray
+    d_geo_path: npt.NDArray
+    d_opt_path: npt.NDArray
+    d_acc_time: npt.NDArray
+    d_wavelengths: npt.NDArray
+    d_intensities: npt.NDArray
+    d_optical_depth: npt.NDArray
+    d_prev_positions: npt.NDArray
+    d_prev_signed_dist: npt.NDArray
+    d_hit_surface_idx: npt.NDArray
+    d_hit_positions: npt.NDArray
+    d_crossing_mask: npt.NDArray
+    d_reduction_result: npt.NDArray
+    num_rays: int
+    num_surfaces: int
+
+    @classmethod
+    def from_ray_batch(
+        cls,
+        rays: "RayBatch",
+        num_surfaces: int,
+    ) -> "GPUDeviceRays":
+        """
+        Upload RayBatch to GPU (one-time at start).
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Source ray batch to upload
+        num_surfaces : int
+            Number of surfaces to track for detection
+
+        Returns
+        -------
+        GPUDeviceRays
+            GPU-resident ray data
+        """
+        n = rays.num_rays
+
+        # Initialize optical depth from rays if present, otherwise zeros
+        if rays.optical_depth is not None:
+            optical_depth_arr = cuda.to_device(rays.optical_depth.astype(np.float32))
+        else:
+            optical_depth_arr = cuda.to_device(np.zeros(n, dtype=np.float32))
+
+        return cls(
+            d_positions=cuda.to_device(rays.positions.astype(np.float32)),
+            d_directions=cuda.to_device(rays.directions.astype(np.float32)),
+            d_active=cuda.to_device(rays.active.astype(np.bool_)),
+            d_geo_path=cuda.to_device(rays.geometric_path_lengths.astype(np.float32)),
+            d_opt_path=cuda.to_device(rays.optical_path_lengths.astype(np.float32)),
+            d_acc_time=cuda.to_device(rays.accumulated_time.astype(np.float32)),
+            d_wavelengths=cuda.to_device(rays.wavelengths.astype(np.float32)),
+            d_intensities=cuda.to_device(rays.intensities.astype(np.float32)),
+            d_optical_depth=optical_depth_arr,
+            d_prev_positions=cuda.device_array((n, 3), dtype=np.float32),
+            d_prev_signed_dist=cuda.device_array((n, num_surfaces), dtype=np.float32),
+            d_hit_surface_idx=cuda.to_device(np.full(n, -1, dtype=np.int32)),
+            d_hit_positions=cuda.device_array((n, 3), dtype=np.float32),
+            d_crossing_mask=cuda.device_array(n, dtype=np.bool_),
+            d_reduction_result=cuda.device_array(2, dtype=np.int32),
+            num_rays=n,
+            num_surfaces=num_surfaces,
+        )
+
+    def to_ray_batch(self, rays: "RayBatch") -> None:
+        """
+        Download final state back to RayBatch (one-time at end).
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Target ray batch to update in-place
+        """
+        if HAS_CUDA:
+            cuda.synchronize()
+
+        rays.positions[:] = self.d_positions.copy_to_host()
+        rays.directions[:] = self.d_directions.copy_to_host()
+        rays.active[:] = self.d_active.copy_to_host()
+        rays.geometric_path_lengths[:] = self.d_geo_path.copy_to_host()
+        rays.optical_path_lengths[:] = self.d_opt_path.copy_to_host()
+        rays.accumulated_time[:] = self.d_acc_time.copy_to_host()
+        rays.intensities[:] = self.d_intensities.copy_to_host()
+        if rays.optical_depth is not None:
+            rays.optical_depth[:] = self.d_optical_depth.copy_to_host()
+
+    def get_hit_data(self) -> tuple[npt.NDArray, npt.NDArray, npt.NDArray]:
+        """
+        Download hit data from GPU.
+
+        Returns
+        -------
+        hit_surface_idx : ndarray, shape (N,)
+            Surface index for each hit (-1 = no hit)
+        hit_positions : ndarray, shape (N, 3)
+            Hit positions
+        hit_mask : ndarray, shape (N,)
+            True for rays that hit any surface
+        """
+        if HAS_CUDA:
+            cuda.synchronize()
+
+        hit_surface_idx = self.d_hit_surface_idx.copy_to_host()
+        hit_positions = self.d_hit_positions.copy_to_host()
+        hit_mask = hit_surface_idx >= 0
+
+        return hit_surface_idx, hit_positions, hit_mask
+
+    def reset_crossing_state(self) -> None:
+        """
+        Reset crossing detection state for next iteration.
+
+        Called at the start of each propagation step to clear
+        the crossing mask and reset reduction counters.
+        """
+        # Reset crossing mask to False
+        zeros_bool = np.zeros(self.num_rays, dtype=np.bool_)
+        self.d_crossing_mask.copy_to_device(zeros_bool)
+
+        # Reset reduction result
+        zeros_int = np.zeros(2, dtype=np.int32)
+        self.d_reduction_result.copy_to_device(zeros_int)
+
+    def get_reduction_result(self) -> tuple[int, int]:
+        """
+        Download reduction result (small transfer).
+
+        Returns
+        -------
+        num_active : int
+            Number of active rays
+        num_crossing : int
+            Number of rays that crossed a surface
+        """
+        if HAS_CUDA:
+            cuda.synchronize()
+
+        result = self.d_reduction_result.copy_to_host()
+        return int(result[0]), int(result[1])
+
+
+__all__ = ["GPUDeviceRays", "HAS_CUDA"]

lsurf/propagation/kernels/__init__.py

@@ -0,0 +1,175 @@
+# 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.
+
+"""
+GPU Kernels for Ray Tracing
+
+This package contains all CUDA kernels organized by function:
+
+- propagation/: Material propagation kernels (simple, spectral, grid)
+- intersection/: Surface intersection kernels (plane, sphere, signed distance)
+- fresnel/: Fresnel reflection/refraction kernels
+- detection/: Ray detection kernels (spherical)
+- device_functions: Shared device functions (integration, dispersion)
+- registry: Kernel ID enums and registration system
+
+All kernels support optional CUDA - they gracefully fall back to
+no-op decorators when numba.cuda is not available.
+
+Kernel Types
+------------
+- PropagationKernelID: Material propagation (SIMPLE_*, SPECTRAL_*, GRID_*)
+- IntersectionKernelID: Surface intersection (PLANE_*, SPHERE_*, SIGNED_DISTANCE_*, SURFACE_NORMAL_*)
+- DetectionKernelID: Ray detection (SPHERICAL_*, PLANAR_*)
+- FresnelKernelID: Fresnel equations (STANDARD, POLARIZED)
+"""
+
+# Re-export kernel registry (enums and registration)
+from .registry import (
+    PropagationKernelID,
+    IntersectionKernelID,
+    DetectionKernelID,
+    FresnelKernelID,
+    PropagatorID,
+    KernelID,
+    register_kernel,
+    get_kernel,
+    get_registered_kernels,
+    list_kernels,
+)
+
+# Re-export protocols
+from .propagation.protocol import PropagationKernelProtocol
+from .intersection.protocol import IntersectionKernelProtocol
+from .fresnel.protocol import FresnelKernelProtocol
+from .detection.protocol import DetectionKernelProtocol
+
+# Re-export device functions
+from .device_functions import (
+    device_euler_step,
+    device_rk4_step,
+    device_adaptive_step_size,
+    device_sellmeier_equation,
+    device_cauchy_equation,
+    euler_step,
+    rk4_step,
+    compute_adaptive_step_size,
+    normalize_directions,
+    euler_step_batch,
+    rk4_step_batch,
+    HAS_CUDA,
+)
+
+# Re-export propagation kernels
+from .propagation import (
+    _kernel_simple_inhomogeneous_euler,
+    _kernel_simple_inhomogeneous_rk4,
+    _kernel_spectral_inhomogeneous_euler,
+    _kernel_spectral_inhomogeneous_rk4,
+    _kernel_spectral_inhomogeneous_euler_perray,
+    _kernel_spectral_inhomogeneous_rk4_perray,
+    _kernel_grid_inhomogeneous_euler,
+    _kernel_grid_inhomogeneous_rk4,
+)
+
+# Re-export intersection kernels (pure CUDA only)
+from .intersection import (
+    kernel_plane_intersect,
+    kernel_sphere_intersect,
+    kernel_signed_distance,
+    kernel_surface_normal,
+)
+
+# Re-export fresnel kernels (pure CUDA only)
+from .fresnel import (
+    kernel_fresnel_standard,
+    kernel_fresnel_polarized,
+)
+
+# Re-export detection kernels (pure CUDA only)
+from .detection import (
+    kernel_spherical_detect_single,
+    kernel_spherical_detect_multi,
+)
+
+__all__ = [
+    # Kernel registry
+    "PropagationKernelID",
+    "IntersectionKernelID",
+    "DetectionKernelID",
+    "FresnelKernelID",
+    "PropagatorID",
+    "KernelID",
+    "register_kernel",
+    "get_kernel",
+    "get_registered_kernels",
+    "list_kernels",
+    # Protocols
+    "PropagationKernelProtocol",
+    "IntersectionKernelProtocol",
+    "FresnelKernelProtocol",
+    "DetectionKernelProtocol",
+    # Device functions
+    "device_euler_step",
+    "device_rk4_step",
+    "device_adaptive_step_size",
+    "device_sellmeier_equation",
+    "device_cauchy_equation",
+    "euler_step",
+    "rk4_step",
+    "compute_adaptive_step_size",
+    "normalize_directions",
+    "euler_step_batch",
+    "rk4_step_batch",
+    "HAS_CUDA",
+    # Propagation kernels
+    "_kernel_simple_inhomogeneous_euler",
+    "_kernel_simple_inhomogeneous_rk4",
+    "_kernel_spectral_inhomogeneous_euler",
+    "_kernel_spectral_inhomogeneous_rk4",
+    "_kernel_spectral_inhomogeneous_euler_perray",
+    "_kernel_spectral_inhomogeneous_rk4_perray",
+    "_kernel_grid_inhomogeneous_euler",
+    "_kernel_grid_inhomogeneous_rk4",
+    # Intersection kernels (pure CUDA only)
+    "kernel_plane_intersect",
+    "kernel_sphere_intersect",
+    "kernel_signed_distance",
+    "kernel_surface_normal",
+    # Fresnel kernels (pure CUDA only)
+    "kernel_fresnel_standard",
+    "kernel_fresnel_polarized",
+    # Detection kernels (pure CUDA only)
+    "kernel_spherical_detect_single",
+    "kernel_spherical_detect_multi",
+]

lsurf/propagation/kernels/absorption/__init__.py

@@ -0,0 +1,61 @@
+# 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
+
+GPU kernels for applying Beer-Lambert absorption after propagation.
+These kernels are separate from propagation kernels to maintain modularity.
+
+The kernels update:
+- intensities: I *= exp(-α·ds) for each step
+- optical_depth: τ += α·ds (accumulated optical depth)
+"""
+
+from .simple import (
+    _kernel_absorption_simple,
+)
+from .spectral import (
+    _kernel_absorption_spectral,
+    _kernel_absorption_spectral_perray,
+)
+from .grid import (
+    _kernel_absorption_grid,
+)
+
+__all__ = [
+    "_kernel_absorption_simple",
+    "_kernel_absorption_spectral",
+    "_kernel_absorption_spectral_perray",
+    "_kernel_absorption_grid",
+]