lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/intersection/signed_distance.py

@@ -0,0 +1,742 @@
+# 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 Signed Distance Functions for All Surface Types
+
+Generic dispatch kernel that computes signed distance for any surface type
+based on geometry_id. This allows GPU-accelerated intersection detection
+for all surfaces via bisection on signed distance values.
+
+Device functions compute the signed distance formula for each geometry type.
+The main kernel dispatches to the appropriate device function based on ID.
+
+Geometry IDs:
+    1 = Plane: signed distance to infinite plane
+    2 = Sphere: signed distance to sphere surface
+    3 = Gerstner wave: flat-earth wave surface
+    4 = Curved wave: spherical-earth wave surface (single wave)
+    5 = Multi-wave curved: spherical-earth with up to 8 wave components
+    7 = Annular plane: ring-shaped planar surface (detector)
+
+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
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+GRAVITY = 9.81  # Gravity for deep water dispersion
+
+
+# =============================================================================
+# Device Functions - Signed Distance
+# =============================================================================
+
+
+@cuda.jit(device=True)
+def _device_plane_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to plane.
+
+    Plane: signed_distance = dot(p - point, normal)
+    Positive on normal side, negative on back side.
+
+    Parameters (from PlaneSurface.get_gpu_parameters):
+        p0: normal_x
+        p1: normal_y
+        p2: normal_z
+        p3: point_x
+        p4: point_y
+        p5: point_z
+    """
+    nx, ny, nz = params[0], params[1], params[2]
+    px, py, pz = params[3], params[4], params[5]
+
+    return nx * (x - px) + ny * (y - py) + nz * (z - pz)
+
+
+@cuda.jit(device=True)
+def _device_sphere_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to sphere surface.
+
+    Sphere: signed_distance = |p - center| - radius
+    Positive outside, negative inside.
+
+    Parameters (from SphereSurface.get_gpu_parameters):
+        p0: center_x
+        p1: center_y
+        p2: center_z
+        p3: radius
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    r = params[3]
+
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+
+    dist = math.sqrt(dx * dx + dy * dy + dz * dz)
+    return dist - abs(r)
+
+
+@cuda.jit(device=True)
+def _device_gerstner_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to Gerstner wave surface.
+
+    Wave: z = ref_z + A * cos(k * (dx*x + dy*y) - omega*t + phase)
+    Signed distance: z - wave_height (positive above, negative below)
+
+    Parameters (from GPUGerstnerWaveSurface.get_gpu_parameters):
+        p0: amplitude
+        p1: wave_number (k)
+        p2: dir_x (normalized)
+        p3: dir_y (normalized)
+        p4: reference_z
+        p5: phase
+        p6: time
+    """
+    A = params[0]
+    k = params[1]
+    dir_x, dir_y = params[2], params[3]
+    ref_z = params[4]
+    phase = params[5]
+    time = params[6]
+
+    # Angular frequency from deep water dispersion: omega = sqrt(g*k)
+    omega = math.sqrt(GRAVITY * k)
+
+    # Phase at this position
+    phase_val = k * (dir_x * x + dir_y * y) - omega * time + phase
+
+    # Wave height
+    wave_height = ref_z + A * math.cos(phase_val)
+
+    return z - wave_height
+
+
+@cuda.jit(device=True)
+def _device_curved_wave_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to curved-earth wave surface.
+
+    The surface is Earth's sphere + wave perturbation.
+    Signed distance: |p - center| - (earth_radius + wave_height)
+    Positive outside, negative inside.
+
+    Uses numerically stable formulation to avoid catastrophic cancellation
+    when computing dist - R with large Earth radius values in float32.
+
+    For earth_center = (cx, cy, cz):
+    dist² - R² = (x-cx)² + (y-cy)² + (z-cz)² - R²
+               = x² + y² + z² - 2(x·cx + y·cy + z·cz) + (cx² + cy² + cz²) - R²
+
+    For the typical case center = (0, 0, -R):
+    dist² - R² = x² + y² + z² + 2zR (since cz = -R, so -2z·cz = 2zR, and cx²+cy²+cz²-R² = 0)
+
+    Parameters (from GPUCurvedWaveSurface.get_gpu_parameters):
+        p0: earth_center_x
+        p1: earth_center_y
+        p2: earth_center_z
+        p3: earth_radius
+        p4: amplitude
+        p5: wave_number (k)
+        p6: dir_x (normalized)
+        p7: dir_y (normalized)
+        p8: time
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    earth_radius = params[3]
+    A = params[4]
+    k = params[5]
+    dir_x, dir_y = params[6], params[7]
+    time = params[8]
+
+    # Vector from Earth center to point
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+
+    # Compute dist² and dist
+    dist_sq = dx * dx + dy * dy + dz * dz
+    dist = math.sqrt(dist_sq)
+
+    # Numerically stable computation of dist² - R²
+    # Expand: dist² - R² = x² + y² + z² - 2(x·cx + y·cy + z·cz) + (cx² + cy² + cz²) - R²
+    # For typical case (cx=0, cy=0, cz=-R), this simplifies to x² + y² + z² + 2zR
+    # which avoids subtracting two large ~O(R²) numbers
+    pos_sq = x * x + y * y + z * z
+    dot_pc = x * cx + y * cy + z * cz
+    center_sq = cx * cx + cy * cy + cz * cz
+    R_sq = earth_radius * earth_radius
+
+    # dist² - R² computed stably (small terms when near surface)
+    dist_sq_minus_R_sq = pos_sq - 2.0 * dot_pc + center_sq - R_sq
+
+    # Altitude above Earth: (dist² - R²) / (dist + R) = dist - R
+    altitude = dist_sq_minus_R_sq / (dist + earth_radius)
+
+    # Angular frequency from deep water dispersion
+    omega = math.sqrt(GRAVITY * k)
+
+    # Wave phase using x,y as local tangent coordinates
+    dot_val = dir_x * x + dir_y * y
+    phase_val = k * dot_val - omega * time
+
+    # Wave height
+    wave_height = A * math.cos(phase_val)
+
+    # Signed distance = altitude above Earth - wave_height
+    # Positive when above wave surface, negative when below
+    return altitude - wave_height
+
+
+@cuda.jit(device=True)
+def _device_multi_curved_wave_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to multi-wave curved-earth surface.
+
+    Supports up to 8 superimposed wave components on Earth's sphere.
+    Signed distance: |p - center| - (earth_radius + sum_of_wave_heights)
+    Positive outside, negative inside.
+
+    Uses numerically stable formulation to avoid catastrophic cancellation
+    when computing dist - R with large Earth radius values in float32.
+
+    Parameters (from GPUMultiCurvedWaveSurface.get_gpu_parameters):
+        p0: earth_center_x
+        p1: earth_center_y
+        p2: earth_center_z
+        p3: earth_radius
+        p4: time
+        p5: num_waves
+        p6-p7: reserved
+
+        For each wave i (i=0..7), starting at offset 8 + i*8:
+        - p[offset+0]: amplitude
+        - p[offset+1]: wave_number (k)
+        - p[offset+2]: dir_x (normalized)
+        - p[offset+3]: dir_y (normalized)
+        - p[offset+4]: phase
+        - p[offset+5]: steepness (unused in SD calculation)
+        - p[offset+6-7]: reserved
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    earth_radius = params[3]
+    time = params[4]
+    num_waves = int(params[5])
+
+    # Vector from Earth center to point
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+
+    # Compute dist² and dist
+    dist_sq = dx * dx + dy * dy + dz * dz
+    dist = math.sqrt(dist_sq)
+
+    # Numerically stable computation of dist² - R²
+    # Expand: dist² - R² = x² + y² + z² - 2(x·cx + y·cy + z·cz) + (cx² + cy² + cz²) - R²
+    pos_sq = x * x + y * y + z * z
+    dot_pc = x * cx + y * cy + z * cz
+    center_sq = cx * cx + cy * cy + cz * cz
+    R_sq = earth_radius * earth_radius
+
+    # dist² - R² computed stably (small terms when near surface)
+    dist_sq_minus_R_sq = pos_sq - 2.0 * dot_pc + center_sq - R_sq
+
+    # Altitude above Earth: (dist² - R²) / (dist + R) = dist - R
+    altitude = dist_sq_minus_R_sq / (dist + earth_radius)
+
+    # Sum wave heights from all components
+    total_wave_height = 0.0
+    for i in range(num_waves):
+        offset = 8 + i * 8
+        A = params[offset + 0]
+        k = params[offset + 1]
+        dir_x = params[offset + 2]
+        dir_y = params[offset + 3]
+        phase = params[offset + 4]
+
+        # Angular frequency from deep water dispersion
+        omega = math.sqrt(GRAVITY * k)
+
+        # Wave phase using x,y as local tangent coordinates
+        dot_val = dir_x * x + dir_y * y
+        phase_val = k * dot_val - omega * time + phase
+
+        # Accumulate wave height
+        total_wave_height += A * math.cos(phase_val)
+
+    # Signed distance = altitude above Earth - wave_height
+    # Positive when above wave surface, negative when below
+    return altitude - total_wave_height
+
+
+# =============================================================================
+# Device Functions - Surface Normal
+# =============================================================================
+
+
+@cuda.jit(device=True)
+def _device_plane_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for plane surface.
+
+    For a plane, normal is constant everywhere.
+    Returns (nx, ny, nz) tuple.
+    """
+    # Normal is stored directly in params
+    return params[0], params[1], params[2]
+
+
+@cuda.jit(device=True)
+def _device_sphere_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for sphere surface.
+
+    Normal points radially outward from center.
+    Returns (nx, ny, nz) tuple.
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    r = params[3]
+
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+
+    norm = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if norm < 1e-12:
+        return 0.0, 0.0, 1.0
+
+    nx = dx / norm
+    ny = dy / norm
+    nz = dz / norm
+
+    # For negative radius (concave), flip normals
+    if r < 0:
+        nx, ny, nz = -nx, -ny, -nz
+
+    return nx, ny, nz
+
+
+@cuda.jit(device=True)
+def _device_gerstner_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for Gerstner wave surface.
+
+    Normal is computed from gradient of height field.
+    For z = ref_z + A*cos(theta):
+        dz/dx = -A * k * dir_x * sin(theta)
+        dz/dy = -A * k * dir_y * sin(theta)
+    Normal = (-dz/dx, -dz/dy, 1) normalized
+
+    Returns (nx, ny, nz) tuple.
+    """
+    A = params[0]
+    k = params[1]
+    dir_x, dir_y = params[2], params[3]
+    phase = params[5]
+    time = params[6]
+
+    omega = math.sqrt(GRAVITY * k)
+    phase_val = k * (dir_x * x + dir_y * y) - omega * time + phase
+
+    sin_theta = math.sin(phase_val)
+    dz_dx = -A * k * dir_x * sin_theta
+    dz_dy = -A * k * dir_y * sin_theta
+
+    # Normal = (-dz/dx, -dz/dy, 1) normalized
+    nx = -dz_dx
+    ny = -dz_dy
+    nz = 1.0
+
+    norm = math.sqrt(nx * nx + ny * ny + nz * nz)
+    return nx / norm, ny / norm, nz / norm
+
+
+@cuda.jit(device=True)
+def _device_curved_wave_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for curved-earth wave surface.
+
+    This is a simplified version - for full accuracy, transform to local
+    tangent space. Here we compute radial + wave perturbation.
+
+    Returns (nx, ny, nz) tuple.
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    A = params[4]
+    k = params[5]
+    dir_x, dir_y = params[6], params[7]
+    time = params[8]
+
+    # Radial direction from Earth center
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+    dist = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if dist < 1e-10:
+        return 0.0, 0.0, 1.0
+
+    radial_x = dx / dist
+    radial_y = dy / dist
+    radial_z = dz / dist
+
+    # Wave normal perturbation (simplified)
+    omega = math.sqrt(GRAVITY * k)
+    dot_val = dir_x * x + dir_y * y
+    phase_val = k * dot_val - omega * time
+
+    sin_theta = math.sin(phase_val)
+    WA = k * A
+
+    # Local wave gradient contribution (small perturbation)
+    # This is simplified - full version would transform to tangent space
+    nx_local = dir_x * WA * sin_theta
+    ny_local = dir_y * WA * sin_theta
+    nz_local = 1.0 - 0.5 * WA * sin_theta
+
+    # Combine radial with local perturbation (simplified blend)
+    nx = radial_x + 0.01 * nx_local
+    ny = radial_y + 0.01 * ny_local
+    nz = radial_z + 0.01 * nz_local
+
+    norm = math.sqrt(nx * nx + ny * ny + nz * nz)
+    if norm < 1e-12:
+        return radial_x, radial_y, radial_z
+
+    return nx / norm, ny / norm, nz / norm
+
+
+@cuda.jit(device=True)
+def _device_multi_curved_wave_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for multi-wave curved-earth surface.
+
+    Combines radial direction with wave gradient perturbations from
+    all wave components.
+
+    Returns (nx, ny, nz) tuple.
+    """
+    cx, cy, cz = params[0], params[1], params[2]
+    time = params[4]
+    num_waves = int(params[5])
+
+    # Radial direction from Earth center
+    dx = x - cx
+    dy = y - cy
+    dz = z - cz
+    dist = math.sqrt(dx * dx + dy * dy + dz * dz)
+    if dist < 1e-10:
+        return 0.0, 0.0, 1.0
+
+    radial_x = dx / dist
+    radial_y = dy / dist
+    radial_z = dz / dist
+
+    # Accumulate wave normal perturbations
+    nx_local = 0.0
+    ny_local = 0.0
+    nz_local = 1.0
+
+    for i in range(num_waves):
+        offset = 8 + i * 8
+        A = params[offset + 0]
+        k = params[offset + 1]
+        dir_x = params[offset + 2]
+        dir_y = params[offset + 3]
+        phase = params[offset + 4]
+
+        omega = math.sqrt(GRAVITY * k)
+        dot_val = dir_x * x + dir_y * y
+        phase_val = k * dot_val - omega * time + phase
+
+        sin_theta = math.sin(phase_val)
+        WA = k * A
+
+        # Accumulate gradient contributions
+        nx_local += dir_x * WA * sin_theta
+        ny_local += dir_y * WA * sin_theta
+        nz_local -= 0.5 * WA * sin_theta
+
+    # Normalize local normal
+    local_norm = math.sqrt(
+        nx_local * nx_local + ny_local * ny_local + nz_local * nz_local
+    )
+    if local_norm > 1e-10:
+        nx_local /= local_norm
+        ny_local /= local_norm
+        nz_local /= local_norm
+
+    # Combine radial with local perturbation (simplified blend)
+    nx = radial_x + 0.01 * nx_local
+    ny = radial_y + 0.01 * ny_local
+    nz = radial_z + 0.01 * nz_local
+
+    norm = math.sqrt(nx * nx + ny * ny + nz * nz)
+    if norm < 1e-12:
+        return radial_x, radial_y, radial_z
+
+    return nx / norm, ny / norm, nz / norm
+
+
+@cuda.jit(device=True)
+def _device_annular_plane_sd(x: float, y: float, z: float, params) -> float:
+    """
+    Signed distance from point to annular plane.
+
+    For signed distance, we compute distance to the infinite plane.
+    Bounds checking (inner/outer radius) is done separately in intersection.
+
+    Plane: signed_distance = dot(p - center, normal)
+    Positive on normal side, negative on back side.
+
+    Parameters (from AnnularPlaneSurface.get_gpu_parameters):
+        p0: normal_x
+        p1: normal_y
+        p2: normal_z
+        p3: center_x
+        p4: center_y
+        p5: center_z
+        p6-11: u_axis, v_axis (not needed for signed distance)
+        p12: inner_radius_sq (not used in SD)
+        p13: outer_radius_sq (not used in SD)
+    """
+    nx, ny, nz = params[0], params[1], params[2]
+    cx, cy, cz = params[3], params[4], params[5]
+
+    return nx * (x - cx) + ny * (y - cy) + nz * (z - cz)
+
+
+@cuda.jit(device=True)
+def _device_annular_plane_normal(
+    x: float, y: float, z: float, params, out_nx, out_ny, out_nz
+) -> tuple:
+    """
+    Compute normal for annular plane surface.
+
+    For a plane, normal is constant everywhere.
+    Returns (nx, ny, nz) tuple.
+    """
+    # Normal is stored directly in params
+    return params[0], params[1], params[2]
+
+
+# =============================================================================
+# Main Dispatch Kernels
+# =============================================================================
+
+
+@register_kernel(IntersectionKernelID.SIGNED_DISTANCE_GENERIC)
+@cuda.jit
+def kernel_signed_distance(
+    positions,  # (N, 3) input positions
+    signed_dist_out,  # (N,) output signed distances
+    geometry_id,  # int: 1=plane, 2=sphere, 3=gerstner, 4=curved_wave, 5=multi_curved_wave
+    params,  # (64,) surface parameters from get_gpu_parameters()
+):
+    """
+    CUDA kernel to compute signed distance from points to a surface.
+
+    Dispatches to appropriate device function based on geometry_id.
+    This kernel enables GPU-accelerated intersection detection for all
+    surface types via bisection on signed distance values.
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Points to compute signed distance for
+    signed_dist_out : (N,) float32 device array
+        Output array for signed distances
+    geometry_id : int
+        Surface geometry type:
+        1 = Plane
+        2 = Sphere
+        3 = Gerstner wave (flat earth)
+        4 = Curved wave (spherical earth)
+        5 = Multi-wave curved (up to 8 waves)
+    params : (64,) float32 device array
+        Surface parameters from surface.get_gpu_parameters()
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+
+    if geometry_id == 1:
+        signed_dist_out[idx] = _device_plane_sd(x, y, z, params)
+    elif geometry_id == 2:
+        signed_dist_out[idx] = _device_sphere_sd(x, y, z, params)
+    elif geometry_id == 3:
+        signed_dist_out[idx] = _device_gerstner_sd(x, y, z, params)
+    elif geometry_id == 4:
+        signed_dist_out[idx] = _device_curved_wave_sd(x, y, z, params)
+    elif geometry_id == 5:
+        signed_dist_out[idx] = _device_multi_curved_wave_sd(x, y, z, params)
+    elif geometry_id == 6:
+        # Bounded plane uses same SD formula as infinite plane
+        signed_dist_out[idx] = _device_plane_sd(x, y, z, params)
+    elif geometry_id == 7:
+        signed_dist_out[idx] = _device_annular_plane_sd(x, y, z, params)
+    else:
+        # Unknown geometry - set to inf (no intersection possible)
+        signed_dist_out[idx] = math.inf
+
+
+@register_kernel(IntersectionKernelID.SURFACE_NORMAL_GENERIC)
+@cuda.jit
+def kernel_surface_normal(
+    positions,  # (N, 3) input positions
+    normals_out,  # (N, 3) output normals
+    geometry_id,  # int: 1=plane, 2=sphere, 3=gerstner, 4=curved_wave, 5=multi_curved_wave
+    params,  # (64,) surface parameters
+):
+    """
+    CUDA kernel to compute surface normal at given positions.
+
+    Dispatches to appropriate device function based on geometry_id.
+    Used after intersection detection to compute normals for Fresnel/reflection.
+
+    Parameters
+    ----------
+    positions : (N, 3) float32 device array
+        Points on the surface (or close to it)
+    normals_out : (N, 3) float32 device array
+        Output array for normal vectors
+    geometry_id : int
+        Surface geometry type (1-5)
+    params : (64,) float32 device array
+        Surface parameters from surface.get_gpu_parameters()
+    """
+    idx = cuda.grid(1)
+    if idx >= positions.shape[0]:
+        return
+
+    x = positions[idx, 0]
+    y = positions[idx, 1]
+    z = positions[idx, 2]
+
+    # Placeholder for output (not used by device functions, just for signature)
+    out_nx, out_ny, out_nz = 0.0, 0.0, 0.0
+
+    if geometry_id == 1:
+        nx, ny, nz = _device_plane_normal(x, y, z, params, out_nx, out_ny, out_nz)
+    elif geometry_id == 2:
+        nx, ny, nz = _device_sphere_normal(x, y, z, params, out_nx, out_ny, out_nz)
+    elif geometry_id == 3:
+        nx, ny, nz = _device_gerstner_normal(x, y, z, params, out_nx, out_ny, out_nz)
+    elif geometry_id == 4:
+        nx, ny, nz = _device_curved_wave_normal(x, y, z, params, out_nx, out_ny, out_nz)
+    elif geometry_id == 5:
+        nx, ny, nz = _device_multi_curved_wave_normal(
+            x, y, z, params, out_nx, out_ny, out_nz
+        )
+    elif geometry_id == 6:
+        # Bounded plane uses same normal as infinite plane
+        nx, ny, nz = _device_plane_normal(x, y, z, params, out_nx, out_ny, out_nz)
+    elif geometry_id == 7:
+        nx, ny, nz = _device_annular_plane_normal(
+            x, y, z, params, out_nx, out_ny, out_nz
+        )
+    else:
+        # Unknown geometry - default to +Z normal
+        nx, ny, nz = 0.0, 0.0, 1.0
+
+    normals_out[idx, 0] = nx
+    normals_out[idx, 1] = ny
+    normals_out[idx, 2] = nz
+
+
+__all__ = [
+    "kernel_signed_distance",
+    "kernel_surface_normal",
+    "HAS_CUDA",
+]