lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/surface/detection.py

@@ -0,0 +1,402 @@
+# 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 Crossing Detection Kernels
+
+GPU kernels for detecting when rays cross surfaces by monitoring
+sign changes in signed distance values.
+"""
+
+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,
+)
+
+
+# =============================================================================
+# Device Functions
+# =============================================================================
+
+
+@cuda.jit(device=True)
+def _device_signed_distance(
+    x: float, y: float, z: float, geometry_id: int, params, param_offset: int
+) -> float:
+    """
+    Compute signed distance for a surface with parameters at given offset.
+
+    Parameters
+    ----------
+    x, y, z : float
+        Point coordinates
+    geometry_id : int
+        Surface geometry type (1-5)
+    params : device array
+        All surface parameters concatenated
+    param_offset : int
+        Offset into params for this surface (surface_idx * MAX_SURFACE_PARAMS)
+
+    Returns
+    -------
+    float
+        Signed distance to surface
+    """
+    # Create a local view of params for this surface
+    # Note: We pass the full params array and geometry_id handles the layout
+    if geometry_id == 1:  # Plane
+        return _device_plane_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 2:  # Sphere
+        return _device_sphere_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 3:  # Gerstner wave
+        return _device_gerstner_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 4:  # Curved wave
+        return _device_curved_wave_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 5:  # Multi-wave curved
+        return _device_multi_curved_wave_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 6:  # Bounded plane (same SD formula as infinite plane)
+        return _device_plane_sd(x, y, z, params[param_offset:])
+    elif geometry_id == 7:  # Annular plane
+        return _device_annular_plane_sd(x, y, z, params[param_offset:])
+    else:
+        return math.inf
+
+
+# =============================================================================
+# Main Kernels
+# =============================================================================
+
+
+@cuda.jit
+def kernel_save_prev_positions(
+    positions,  # (N, 3) current positions
+    prev_positions,  # (N, 3) output: saved positions
+    active,  # (N,) active mask
+):
+    """
+    Save current positions before propagation step.
+
+    Simple copy kernel for bisection - saves positions so we can
+    interpolate between prev and current to find exact crossing point.
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Current ray positions
+    prev_positions : (N, 3) float32 device array
+        Output array to store previous positions
+    active : (N,) bool device array
+        Active ray mask (only save for active rays)
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0] or not active[idx]:
+        return
+
+    prev_positions[idx, 0] = positions[idx, 0]
+    prev_positions[idx, 1] = positions[idx, 1]
+    prev_positions[idx, 2] = positions[idx, 2]
+
+
+@cuda.jit
+def kernel_detect_crossing(
+    positions,  # (N, 3) current positions
+    prev_sd,  # (N, S) previous signed distances
+    active,  # (N,) active mask
+    geometry_ids,  # (S,) geometry ID per surface
+    surface_params,  # (S * MAX_PARAMS,) all surface parameters
+    num_surfaces,  # int
+    max_params,  # int: MAX_SURFACE_PARAMS
+    crossing_mask,  # (N,) output: rays that crossed
+    hit_surface_idx,  # (N,) output: which surface was hit
+):
+    """
+    Check all surfaces for sign changes in signed distance.
+
+    For each active ray, compute signed distance to all surfaces and
+    check for sign changes (crossings) compared to previous step.
+    First surface crossed wins (in surface order).
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Current ray positions
+    prev_sd : (N, S) float32 device array
+        Previous signed distances per surface
+    active : (N,) bool device array
+        Active ray mask
+    geometry_ids : (S,) int32 device array
+        Geometry ID for each surface
+    surface_params : (S * MAX_PARAMS,) float32 device array
+        Concatenated surface parameters
+    num_surfaces : int
+        Number of surfaces
+    max_params : int
+        MAX_SURFACE_PARAMS constant
+    crossing_mask : (N,) bool device array
+        Output: True for rays that crossed any surface
+    hit_surface_idx : (N,) int32 device array
+        Output: Surface index that was crossed (-1 if none)
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0] or not active[idx]:
+        return
+
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+
+    crossing_mask[idx] = False
+
+    # Check each surface in order
+    for surf in range(num_surfaces):
+        geo_id = geometry_ids[surf]
+        param_offset = surf * max_params
+
+        # Compute current signed distance
+        curr_sd = _device_signed_distance(x, y, z, geo_id, surface_params, param_offset)
+        prev = prev_sd[idx, surf]
+
+        # Check for sign change (crossing)
+        if (prev >= 0 and curr_sd < 0) or (prev < 0 and curr_sd >= 0):
+            crossing_mask[idx] = True
+            hit_surface_idx[idx] = surf
+            return  # First surface crossed wins
+
+        # Save current as prev for next step
+        prev_sd[idx, surf] = curr_sd
+
+
+@cuda.jit
+def kernel_init_signed_distances(
+    positions,  # (N, 3) current positions
+    active,  # (N,) active mask
+    geometry_ids,  # (S,) geometry ID per surface
+    surface_params,  # (S * MAX_PARAMS,) all surface parameters
+    num_surfaces,  # int
+    max_params,  # int: MAX_SURFACE_PARAMS
+    prev_sd,  # (N, S) output: initial signed distances
+):
+    """
+    Initialize signed distances for all surfaces.
+
+    Called once at the start to populate prev_sd before the first
+    propagation step.
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Initial ray positions
+    active : (N,) bool device array
+        Active ray mask
+    geometry_ids : (S,) int32 device array
+        Geometry ID for each surface
+    surface_params : (S * MAX_PARAMS,) float32 device array
+        Concatenated surface parameters
+    num_surfaces : int
+        Number of surfaces
+    max_params : int
+        MAX_SURFACE_PARAMS constant
+    prev_sd : (N, S) float32 device array
+        Output: Initial signed distances per surface
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0] or not active[idx]:
+        return
+
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+
+    for surf in range(num_surfaces):
+        geo_id = geometry_ids[surf]
+        param_offset = surf * max_params
+        prev_sd[idx, surf] = _device_signed_distance(
+            x, y, z, geo_id, surface_params, param_offset
+        )
+
+
+@cuda.jit
+def kernel_compute_min_surface_distance(
+    positions,  # (N, 3) current positions
+    active,  # (N,) active mask
+    geometry_ids,  # (S,) geometry ID per surface
+    surface_params,  # (S * MAX_PARAMS,) all surface parameters
+    num_surfaces,  # int
+    max_params,  # int: MAX_SURFACE_PARAMS
+    min_distances,  # (N,) output: minimum distance to any surface
+):
+    """
+    Compute minimum absolute distance to any surface for each ray.
+
+    Used for adaptive step sizing - rays closer to surfaces use smaller steps.
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Current ray positions
+    active : (N,) bool device array
+        Active ray mask
+    geometry_ids : (S,) int32 device array
+        Geometry ID for each surface
+    surface_params : (S * MAX_PARAMS,) float32 device array
+        Concatenated surface parameters
+    num_surfaces : int
+        Number of surfaces
+    max_params : int
+        MAX_SURFACE_PARAMS constant
+    min_distances : (N,) float32 device array
+        Output: Minimum absolute distance to any surface
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+
+    if not active[idx]:
+        min_distances[idx] = math.inf
+        return
+
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+
+    min_dist = math.inf
+
+    # Check all surfaces and find minimum absolute distance
+    for surf in range(num_surfaces):
+        geo_id = geometry_ids[surf]
+        param_offset = surf * max_params
+
+        sd = _device_signed_distance(x, y, z, geo_id, surface_params, param_offset)
+        abs_sd = abs(sd)
+
+        if abs_sd < min_dist:
+            min_dist = abs_sd
+
+    min_distances[idx] = min_dist
+
+
+@cuda.jit
+def kernel_compute_adaptive_steps(
+    min_distances,  # (N,) minimum surface distances
+    active,  # (N,) active mask
+    max_step_size,  # float: maximum step size
+    min_step_size,  # float: minimum step size
+    proximity_factor,  # float: step = distance * factor
+    proximity_threshold,  # float: threshold for adaptive stepping
+    adaptive_steps,  # (N,) output: per-ray step sizes
+):
+    """
+    Compute adaptive step sizes based on surface proximity.
+
+    For rays within the proximity threshold, step size is proportional to
+    distance from surface. Otherwise, maximum step size is used.
+
+    Parameters
+    ----------
+    min_distances : (N,) float32 device array
+        Minimum distance to any surface per ray
+    active : (N,) bool device array
+        Active ray mask
+    max_step_size : float
+        Maximum step size (far from surfaces)
+    min_step_size : float
+        Minimum step size (very close to surfaces, ~0.3mm for 1ps resolution)
+    proximity_factor : float
+        Step size = distance * factor when within threshold
+    proximity_threshold : float
+        Distance within which to start adaptive stepping
+    adaptive_steps : (N,) float32 device array
+        Output: Per-ray step sizes
+    """
+    idx = cuda.grid(1)
+    if idx >= min_distances.shape[0]:
+        return
+
+    if not active[idx]:
+        adaptive_steps[idx] = max_step_size
+        return
+
+    dist = min_distances[idx]
+
+    if dist < proximity_threshold:
+        # Within threshold: step proportional to distance
+        step = dist * proximity_factor
+        # Clamp to [min_step_size, max_step_size]
+        if step < min_step_size:
+            step = min_step_size
+        elif step > max_step_size:
+            step = max_step_size
+        adaptive_steps[idx] = step
+    else:
+        adaptive_steps[idx] = max_step_size
+
+
+__all__ = [
+    "kernel_save_prev_positions",
+    "kernel_detect_crossing",
+    "kernel_init_signed_distances",
+    "kernel_compute_min_surface_distance",
+    "kernel_compute_adaptive_steps",
+]

lsurf/propagation/kernels/surface/reduction.py

@@ -0,0 +1,166 @@
+# 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.
+
+"""
+Status Reduction Kernel
+
+GPU kernel for counting active rays and detecting crossings.
+Uses parallel reduction to efficiently compute loop termination conditions.
+"""
+
+# 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
+
+        class shared:
+            @staticmethod
+            def array(size, dtype):
+                return None
+
+        class atomic:
+            @staticmethod
+            def add(arr, idx, val):
+                pass
+
+    cuda = _FakeCuda()  # type: ignore[assignment]
+
+
+@cuda.jit
+def kernel_reduce_status(
+    active,  # (N,) active mask
+    crossing_mask,  # (N,) rays that crossed
+    result,  # (2,) output: [num_active, num_crossing]
+):
+    """
+    Count active rays and check for crossings.
+
+    Uses atomic operations for simplicity. For large ray counts,
+    a proper tree reduction would be more efficient.
+
+    Parameters
+    ----------
+    active : (N,) bool device array
+        Active ray mask
+    crossing_mask : (N,) bool device array
+        Rays that crossed a surface
+    result : (2,) int32 device array
+        Output: [num_active, num_crossing]
+        Must be initialized to zeros before calling.
+    """
+    idx = cuda.grid(1)
+    if idx >= active.shape[0]:
+        return
+
+    if active[idx]:
+        cuda.atomic.add(result, 0, 1)
+
+    if crossing_mask[idx]:
+        cuda.atomic.add(result, 1, 1)
+
+
+@cuda.jit
+def kernel_reduce_status_shared(
+    active,  # (N,) active mask
+    crossing_mask,  # (N,) rays that crossed
+    result,  # (2,) output: [num_active, num_crossing]
+    block_size,  # int: threads per block
+):
+    """
+    Count active rays and crossings using shared memory reduction.
+
+    More efficient than atomic-only version for large ray counts.
+    Uses tree reduction within each block, then atomic add for final sum.
+
+    Parameters
+    ----------
+    active : (N,) bool device array
+        Active ray mask
+    crossing_mask : (N,) bool device array
+        Rays that crossed a surface
+    result : (2,) int32 device array
+        Output: [num_active, num_crossing]
+        Must be initialized to zeros before calling.
+    block_size : int
+        Number of threads per block (must match launch config)
+    """
+    # Shared memory for reduction
+    shared_active = cuda.shared.array(256, dtype=cuda.int32)
+    shared_crossing = cuda.shared.array(256, dtype=cuda.int32)
+
+    tid = cuda.threadIdx.x
+    idx = cuda.grid(1)
+
+    # Load data
+    if idx < active.shape[0]:
+        shared_active[tid] = 1 if active[idx] else 0
+        shared_crossing[tid] = 1 if crossing_mask[idx] else 0
+    else:
+        shared_active[tid] = 0
+        shared_crossing[tid] = 0
+
+    cuda.syncthreads()
+
+    # Tree reduction
+    s = cuda.blockDim.x // 2
+    while s > 0:
+        if tid < s:
+            shared_active[tid] += shared_active[tid + s]
+            shared_crossing[tid] += shared_crossing[tid + s]
+        cuda.syncthreads()
+        s //= 2
+
+    # First thread in block adds to global result
+    if tid == 0:
+        cuda.atomic.add(result, 0, shared_active[0])
+        cuda.atomic.add(result, 1, shared_crossing[0])
+
+
+__all__ = ["kernel_reduce_status", "kernel_reduce_status_shared"]