lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/intersection/sphere.py

@@ -0,0 +1,190 @@
+# 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 Sphere Intersection
+
+Analytical ray-sphere intersection using quadratic formula.
+
+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 IntersectionKernelID, 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
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+    HAS_CUDA = False
+
+
+# =============================================================================
+# CUDA Kernels
+# =============================================================================
+
+
+@register_kernel(IntersectionKernelID.SPHERE_ANALYTICAL)
+@cuda.jit
+def kernel_sphere_intersect(
+    origins,  # (N, 3) ray origins
+    directions,  # (N, 3) ray directions
+    distances_out,  # (N,) output distances
+    hit_mask_out,  # (N,) output hit mask
+    normals_out,  # (N, 3) output normals at intersection
+    center_x,  # Sphere center X
+    center_y,  # Sphere center Y
+    center_z,  # Sphere center Z
+    radius,  # Sphere radius
+):
+    """
+    CUDA kernel for ray-sphere intersection.
+
+    Uses analytical solution via quadratic formula:
+    |o + t*d - c|² = r²
+    Expands to: t²(d·d) + 2t(d·(o-c)) + (o-c)·(o-c) - r² = 0
+
+    Returns the nearest positive intersection distance.
+    """
+    idx = cuda.grid(1)
+    if idx >= origins.shape[0]:
+        return
+
+    # Load ray data
+    ox = origins[idx, 0]
+    oy = origins[idx, 1]
+    oz = origins[idx, 2]
+    dx = directions[idx, 0]
+    dy = directions[idx, 1]
+    dz = directions[idx, 2]
+
+    # Normalize direction
+    d_len = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if d_len < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+    dx /= d_len
+    dy /= d_len
+    dz /= d_len
+
+    # Vector from origin to sphere center
+    ocx = ox - center_x
+    ocy = oy - center_y
+    ocz = oz - center_z
+
+    # Quadratic coefficients
+    # a = d·d = 1 (normalized direction)
+    b = 2.0 * (dx * ocx + dy * ocy + dz * ocz)
+    c = ocx * ocx + ocy * ocy + ocz * ocz - radius * radius
+
+    # Discriminant
+    discriminant = b * b - 4.0 * c
+
+    if discriminant < 0:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    sqrt_disc = math.sqrt(discriminant)
+
+    # Two solutions
+    t1 = (-b - sqrt_disc) / 2.0
+    t2 = (-b + sqrt_disc) / 2.0
+
+    # Find nearest positive intersection
+    if t1 > 1e-6:
+        t = t1
+    elif t2 > 1e-6:
+        t = t2
+    else:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Store results
+    hit_mask_out[idx] = True
+    distances_out[idx] = t
+
+    # Compute intersection point and normal
+    px = ox + t * dx
+    py = oy + t * dy
+    pz = oz + t * dz
+
+    # Normal points outward from sphere center
+    nx = px - center_x
+    ny = py - center_y
+    nz = pz - center_z
+
+    # Normalize
+    n_len = math.sqrt(nx * nx + ny * ny + nz * nz)
+    if n_len > 1e-10:
+        normals_out[idx, 0] = nx / n_len
+        normals_out[idx, 1] = ny / n_len
+        normals_out[idx, 2] = nz / n_len
+    else:
+        normals_out[idx, 0] = 0.0
+        normals_out[idx, 1] = 0.0
+        normals_out[idx, 2] = 1.0

lsurf/propagation/kernels/propagation/__init__.py

@@ -0,0 +1,85 @@
+# 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.
+
+"""
+Propagation Kernels for GPU Ray Tracing
+
+CUDA kernels for GPU-accelerated ray propagation through
+various inhomogeneous material models:
+
+- simple: 1D LUT interpolation for radially-symmetric materials
+- spectral: 2D LUT interpolation for wavelength-dependent materials
+- grid: 3D trilinear interpolation for arbitrary 3D fields
+
+Kernel Types
+------------
+- SIMPLE_EULER, SIMPLE_RK4: Simple 1D LUT kernels
+- SPECTRAL_EULER, SPECTRAL_RK4: Spectral 2D LUT kernels
+- SPECTRAL_EULER_PERRAY, SPECTRAL_RK4_PERRAY: Per-ray wavelength kernels
+- GRID_EULER, GRID_RK4: 3D grid-based kernels
+
+Note: Surface intersection during propagation is handled by the propagator
+layer, which calls intersection kernels separately after each propagation step.
+"""
+
+from .protocol import PropagationKernelProtocol
+from .simple import (
+    _kernel_simple_inhomogeneous_euler,
+    _kernel_simple_inhomogeneous_rk4,
+)
+from .spectral import (
+    _kernel_spectral_inhomogeneous_euler,
+    _kernel_spectral_inhomogeneous_rk4,
+    _kernel_spectral_inhomogeneous_euler_perray,
+    _kernel_spectral_inhomogeneous_rk4_perray,
+)
+from .grid import (
+    _kernel_grid_inhomogeneous_euler,
+    _kernel_grid_inhomogeneous_rk4,
+)
+
+__all__ = [
+    # Protocol
+    "PropagationKernelProtocol",
+    # Simple kernels
+    "_kernel_simple_inhomogeneous_euler",
+    "_kernel_simple_inhomogeneous_rk4",
+    # Spectral kernels
+    "_kernel_spectral_inhomogeneous_euler",
+    "_kernel_spectral_inhomogeneous_rk4",
+    "_kernel_spectral_inhomogeneous_euler_perray",
+    "_kernel_spectral_inhomogeneous_rk4_perray",
+    # Grid kernels
+    "_kernel_grid_inhomogeneous_euler",
+    "_kernel_grid_inhomogeneous_rk4",
+]