lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/detection/spherical.py

@@ -0,0 +1,255 @@
+# 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-Accelerated Detector Operations
+
+This module provides GPU-accelerated ray detection for spherical and planar
+detectors, enabling fast parallel detection of many rays against many detector
+positions simultaneously.
+
+This module contains ONLY pure CUDA kernels - no GPU memory management.
+The propagator layer is responsible for cuda.to_device() and copy_to_host().
+"""
+
+import math
+
+from ..registry import DetectionKernelID, register_kernel
+
+# 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."""
+
+        @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
+
+        class atomic:
+            @staticmethod
+            def add(arr, idx, val):
+                arr[idx] += val
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+# =============================================================================
+# CUDA Kernels for Spherical Detector
+# =============================================================================
+
+
+@register_kernel(DetectionKernelID.SPHERICAL_SINGLE)
+@cuda.jit
+def kernel_spherical_detect_single(
+    ray_positions,  # (N, 3) ray positions
+    ray_directions,  # (N, 3) ray directions
+    ray_active,  # (N,) active mask
+    ray_times,  # (N,) accumulated times
+    ray_wavelengths,  # (N,) wavelengths
+    ray_intensities,  # (N,) intensities
+    detector_center,  # (3,) detector center
+    detector_radius,  # scalar
+    hit_mask_out,  # (N,) output: did ray hit?
+    hit_distances_out,  # (N,) output: distance to hit
+    hit_times_out,  # (N,) output: arrival times
+):
+    """
+    CUDA kernel to detect rays hitting a single spherical detector.
+    """
+    idx = cuda.grid(1)
+    if idx >= ray_positions.shape[0]:
+        return
+
+    # Skip inactive rays
+    if not ray_active[idx]:
+        hit_mask_out[idx] = False
+        return
+
+    # Load ray data
+    ox = ray_positions[idx, 0]
+    oy = ray_positions[idx, 1]
+    oz = ray_positions[idx, 2]
+    dx = ray_directions[idx, 0]
+    dy = ray_directions[idx, 1]
+    dz = ray_directions[idx, 2]
+
+    # Detector center
+    cx = detector_center[0]
+    cy = detector_center[1]
+    cz = detector_center[2]
+
+    # Normalize direction
+    d_len = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if d_len < 1e-10:
+        hit_mask_out[idx] = False
+        return
+    dx /= d_len
+    dy /= d_len
+    dz /= d_len
+
+    # Vector from ray origin to sphere center
+    ocx = cx - ox
+    ocy = cy - oy
+    ocz = cz - oz
+
+    # Project onto ray direction: t_closest = dot(oc, d)
+    t_closest = ocx * dx + ocy * dy + ocz * dz
+
+    # Only forward propagation
+    if t_closest < 0:
+        hit_mask_out[idx] = False
+        return
+
+    # Closest point on ray to center
+    px = ox + t_closest * dx
+    py = oy + t_closest * dy
+    pz = oz + t_closest * dz
+
+    # Distance to center
+    dist_sq = (px - cx) * (px - cx) + (py - cy) * (py - cy) + (pz - cz) * (pz - cz)
+    radius_sq = detector_radius * detector_radius
+
+    if dist_sq <= radius_sq:
+        # Hit!
+        hit_mask_out[idx] = True
+        hit_distances_out[idx] = t_closest
+
+        # Compute arrival time (assume n=1 after reflection)
+        c = 299792458.0  # Speed of light
+        additional_time = t_closest / c
+        hit_times_out[idx] = ray_times[idx] + additional_time
+    else:
+        hit_mask_out[idx] = False
+
+
+@register_kernel(DetectionKernelID.SPHERICAL_MULTI)
+@cuda.jit
+def kernel_spherical_detect_multi(
+    ray_positions,  # (N, 3) ray positions
+    ray_directions,  # (N, 3) ray directions
+    ray_active,  # (N,) active mask
+    ray_times,  # (N,) accumulated times
+    detector_centers,  # (M, 3) detector centers
+    detector_radius,  # scalar (same for all)
+    hit_counts_out,  # (M,) output: count of hits per detector
+    hit_intensity_out,  # (M,) output: sum of intensities per detector
+    ray_intensities,  # (N,) intensities
+):
+    """
+    CUDA kernel to count ray hits across multiple detector positions.
+
+    This is optimized for the detector scan use case where we want to
+    quickly count how many rays hit each detector position.
+    """
+    # 2D grid: (ray_idx, detector_idx)
+    ray_idx = cuda.grid(1)
+
+    if ray_idx >= ray_positions.shape[0]:
+        return
+
+    # Skip inactive rays
+    if not ray_active[ray_idx]:
+        return
+
+    # Load ray data once
+    ox = ray_positions[ray_idx, 0]
+    oy = ray_positions[ray_idx, 1]
+    oz = ray_positions[ray_idx, 2]
+    dx = ray_directions[ray_idx, 0]
+    dy = ray_directions[ray_idx, 1]
+    dz = ray_directions[ray_idx, 2]
+    intensity = ray_intensities[ray_idx]
+
+    # Normalize direction
+    d_len = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if d_len < 1e-10:
+        return
+    dx /= d_len
+    dy /= d_len
+    dz /= d_len
+
+    radius_sq = detector_radius * detector_radius
+
+    # Check against all detectors
+    for det_idx in range(detector_centers.shape[0]):
+        cx = detector_centers[det_idx, 0]
+        cy = detector_centers[det_idx, 1]
+        cz = detector_centers[det_idx, 2]
+
+        # Vector from ray origin to detector center
+        ocx = cx - ox
+        ocy = cy - oy
+        ocz = cz - oz
+
+        # Project onto ray direction
+        t_closest = ocx * dx + ocy * dy + ocz * dz
+
+        # Only forward propagation
+        if t_closest < 0:
+            continue
+
+        # Closest point distance squared
+        px = ox + t_closest * dx
+        py = oy + t_closest * dy
+        pz = oz + t_closest * dz
+
+        dist_sq = (px - cx) ** 2 + (py - cy) ** 2 + (pz - cz) ** 2
+
+        if dist_sq <= radius_sq:
+            # Hit! Atomic add to counters
+            cuda.atomic.add(hit_counts_out, det_idx, 1)
+            cuda.atomic.add(hit_intensity_out, det_idx, intensity)