lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/kernels/fresnel/__init__.py

@@ -0,0 +1,64 @@
+# 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.
+
+"""
+Fresnel Kernels
+
+CUDA kernels for GPU-accelerated Fresnel reflection/refraction calculations.
+Computes reflection and transmission coefficients at material interfaces.
+
+This module exports ONLY pure CUDA kernels and device functions.
+GPU memory management is handled by the propagator layer (handlers).
+
+Kernel Types
+------------
+- STANDARD: Standard Fresnel equations for unpolarized light
+- POLARIZED: Polarization-aware Fresnel equations (s and p separately)
+"""
+
+from .protocol import FresnelKernelProtocol
+from .standard import (
+    kernel_fresnel_standard,
+    kernel_fresnel_polarized,
+    HAS_CUDA,
+)
+
+__all__ = [
+    # Protocol
+    "FresnelKernelProtocol",
+    # Kernels (pure CUDA only)
+    "kernel_fresnel_standard",
+    "kernel_fresnel_polarized",
+    # CUDA availability
+    "HAS_CUDA",
+]

lsurf/propagation/kernels/fresnel/protocol.py

@@ -0,0 +1,97 @@
+# 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.
+
+"""
+Fresnel Kernel Protocol
+
+Defines the interface for Fresnel reflection/refraction kernels that
+compute reflection and transmission coefficients at interfaces.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from numba.cuda.devicearray import DeviceNDArray
+
+
+@runtime_checkable
+class FresnelKernelProtocol(Protocol):
+    """
+    Protocol for Fresnel reflection/refraction kernels.
+
+    Fresnel kernels compute reflection and transmission coefficients
+    at material interfaces based on incident angle, refractive indices,
+    and polarization state.
+
+    Common Parameters
+    -----------------
+    cos_theta_i : DeviceNDArray, shape (N,)
+        Cosine of incident angle (dot product of direction and normal)
+    n1 : DeviceNDArray or float
+        Refractive index of incident medium
+    n2 : DeviceNDArray or float
+        Refractive index of transmitted medium
+    reflectance_out : DeviceNDArray, shape (N,)
+        Output: reflection coefficient (0-1)
+    transmittance_out : DeviceNDArray, shape (N,)
+        Output: transmission coefficient (0-1)
+
+    Optional Parameters
+    -------------------
+    polarization : DeviceNDArray, shape (N,), optional
+        Polarization state per ray (0=unpolarized, 1=s, 2=p)
+
+    Notes
+    -----
+    Kernels are registered with the central registry using @register_kernel
+    decorator and FresnelKernelID enum values.
+
+    For unpolarized light, the kernel averages s and p polarizations.
+    Total internal reflection (TIR) is automatically handled when
+    sin(theta_t) > 1.
+    """
+
+    def __call__(
+        self,
+        cos_theta_i: DeviceNDArray,
+        n1: DeviceNDArray | float,
+        n2: DeviceNDArray | float,
+        reflectance_out: DeviceNDArray,
+        transmittance_out: DeviceNDArray,
+        *args,
+        **kwargs,
+    ) -> None:
+        """Execute the Fresnel kernel."""
+        ...

lsurf/propagation/kernels/fresnel/standard.py

@@ -0,0 +1,258 @@
+# 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 Fresnel Equations
+
+Computes reflection and transmission coefficients at interfaces between
+different media using Fresnel equations.
+
+This module contains ONLY pure CUDA kernels and device functions - no GPU memory
+management. The propagator layer is responsible for cuda.to_device() and copy_to_host().
+
+References
+----------
+.. [1] Born, M., & Wolf, E. (1999). Principles of Optics (7th ed.).
+       Cambridge University Press. Chapter 1.5.
+.. [2] Hecht, E. (2017). Optics (5th ed.). Pearson. Chapter 4.
+"""
+
+import math
+
+from ..registry import FresnelKernelID, 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 Device Functions
+# =============================================================================
+
+
+@cuda.jit(device=True)
+def _device_fresnel_rs_rp(
+    cos_theta_i: float,
+    n1: float,
+    n2: float,
+) -> tuple[float, float, float, bool]:
+    """
+    Compute Fresnel amplitude reflection coefficients r_s and r_p.
+
+    Parameters
+    ----------
+    cos_theta_i : float
+        Cosine of incident angle
+    n1 : float
+        Refractive index of incident medium
+    n2 : float
+        Refractive index of transmitted medium
+
+    Returns
+    -------
+    r_s : float
+        s-polarization amplitude reflection coefficient
+    r_p : float
+        p-polarization amplitude reflection coefficient
+    cos_theta_t : float
+        Cosine of transmitted angle
+    tir : bool
+        True if total internal reflection
+    """
+    # Snell's law: n1*sin(theta_i) = n2*sin(theta_t)
+    n_ratio = n1 / n2
+    sin_theta_i_sq = 1.0 - cos_theta_i * cos_theta_i
+    sin_theta_t_sq = n_ratio * n_ratio * sin_theta_i_sq
+
+    # Check for total internal reflection
+    if sin_theta_t_sq > 1.0:
+        return 1.0, 1.0, 0.0, True
+
+    cos_theta_t = math.sqrt(1.0 - sin_theta_t_sq)
+
+    # Fresnel equations for amplitude coefficients
+    # s-polarization (TE)
+    r_s_num = n1 * cos_theta_i - n2 * cos_theta_t
+    r_s_den = n1 * cos_theta_i + n2 * cos_theta_t
+    r_s = r_s_num / (r_s_den + 1e-10)
+
+    # p-polarization (TM)
+    r_p_num = n2 * cos_theta_i - n1 * cos_theta_t
+    r_p_den = n2 * cos_theta_i + n1 * cos_theta_t
+    r_p = r_p_num / (r_p_den + 1e-10)
+
+    return r_s, r_p, cos_theta_t, False
+
+
+# =============================================================================
+# CUDA Kernels
+# =============================================================================
+
+
+@register_kernel(FresnelKernelID.STANDARD)
+@cuda.jit
+def kernel_fresnel_standard(
+    cos_theta_i,  # (N,) cosine of incident angles
+    n1,  # (N,) or scalar: refractive index of incident medium
+    n2,  # (N,) or scalar: refractive index of transmitted medium
+    reflectance_out,  # (N,) output: reflection coefficient
+    transmittance_out,  # (N,) output: transmission coefficient
+    n1_is_scalar,  # bool: whether n1 is scalar
+    n2_is_scalar,  # bool: whether n2 is scalar
+):
+    """
+    CUDA kernel for standard Fresnel equations (unpolarized light).
+
+    Computes reflection and transmission coefficients by averaging
+    s and p polarizations.
+    """
+    idx = cuda.grid(1)
+    if idx >= cos_theta_i.shape[0]:
+        return
+
+    cti = cos_theta_i[idx]
+    if n1_is_scalar:
+        ni1 = n1[0]
+    else:
+        ni1 = n1[idx]
+    if n2_is_scalar:
+        ni2 = n2[0]
+    else:
+        ni2 = n2[idx]
+
+    r_s, r_p, cos_theta_t, tir = _device_fresnel_rs_rp(cti, ni1, ni2)
+
+    if tir:
+        reflectance_out[idx] = 1.0
+        transmittance_out[idx] = 0.0
+    else:
+        # Intensity reflection coefficients
+        R_s = r_s * r_s
+        R_p = r_p * r_p
+
+        # Average for unpolarized light
+        R = 0.5 * (R_s + R_p)
+        T = 1.0 - R
+
+        reflectance_out[idx] = R
+        transmittance_out[idx] = T
+
+
+@register_kernel(FresnelKernelID.POLARIZED)
+@cuda.jit
+def kernel_fresnel_polarized(
+    cos_theta_i,  # (N,) cosine of incident angles
+    n1,  # (N,) or scalar: refractive index of incident medium
+    n2,  # (N,) or scalar: refractive index of transmitted medium
+    polarization,  # (N,) polarization state: 0=unpolarized, 1=s, 2=p
+    reflectance_out,  # (N,) output: reflection coefficient
+    transmittance_out,  # (N,) output: transmission coefficient
+    n1_is_scalar,  # bool: whether n1 is scalar
+    n2_is_scalar,  # bool: whether n2 is scalar
+):
+    """
+    CUDA kernel for polarization-aware Fresnel equations.
+
+    Computes reflection and transmission coefficients based on
+    the specified polarization state per ray.
+    """
+    idx = cuda.grid(1)
+    if idx >= cos_theta_i.shape[0]:
+        return
+
+    cti = cos_theta_i[idx]
+    pol = polarization[idx]
+    if n1_is_scalar:
+        ni1 = n1[0]
+    else:
+        ni1 = n1[idx]
+    if n2_is_scalar:
+        ni2 = n2[0]
+    else:
+        ni2 = n2[idx]
+
+    r_s, r_p, cos_theta_t, tir = _device_fresnel_rs_rp(cti, ni1, ni2)
+
+    if tir:
+        reflectance_out[idx] = 1.0
+        transmittance_out[idx] = 0.0
+    else:
+        # Intensity reflection coefficients
+        R_s = r_s * r_s
+        R_p = r_p * r_p
+
+        # Select based on polarization
+        if pol == 1:  # s-polarization
+            R = R_s
+        elif pol == 2:  # p-polarization
+            R = R_p
+        else:  # unpolarized
+            R = 0.5 * (R_s + R_p)
+
+        T = 1.0 - R
+
+        reflectance_out[idx] = R
+        transmittance_out[idx] = T

lsurf/propagation/kernels/intersection/__init__.py

@@ -0,0 +1,79 @@
+# 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.
+
+"""
+Intersection Kernels
+
+CUDA kernels for GPU-accelerated ray-surface intersection testing.
+Supports analytical methods for simple geometries (plane, sphere, bounded plane)
+and generic signed distance dispatch for all surface types.
+
+This module exports ONLY pure CUDA kernels and device functions.
+GPU memory management is handled by the propagator layer (handlers).
+
+Kernel Types
+------------
+- Analytical: Fast closed-form solutions for simple geometries
+  - PLANE_ANALYTICAL: Infinite plane intersection
+  - SPHERE_ANALYTICAL: Sphere intersection
+  - BOUNDED_PLANE_ANALYTICAL: Bounded rectangular plane intersection
+
+- Generic dispatch: GPU-accelerated signed distance for any surface
+  - SIGNED_DISTANCE_GENERIC: Signed distance via geometry_id dispatch
+  - SURFACE_NORMAL_GENERIC: Surface normal via geometry_id dispatch
+"""
+
+from .protocol import IntersectionKernelProtocol
+from .plane import kernel_plane_intersect, HAS_CUDA
+from .sphere import kernel_sphere_intersect
+from .bounded_plane import kernel_bounded_plane_intersect
+from .annular_plane import kernel_annular_plane_intersect
+from .signed_distance import kernel_signed_distance, kernel_surface_normal
+
+__all__ = [
+    # Protocol
+    "IntersectionKernelProtocol",
+    # Plane intersection kernel
+    "kernel_plane_intersect",
+    # Sphere intersection kernel
+    "kernel_sphere_intersect",
+    # Bounded plane intersection kernel
+    "kernel_bounded_plane_intersect",
+    # Annular plane intersection kernel
+    "kernel_annular_plane_intersect",
+    # Generic signed distance kernels
+    "kernel_signed_distance",
+    "kernel_surface_normal",
+    # CUDA availability
+    "HAS_CUDA",
+]

lsurf/propagation/kernels/intersection/annular_plane.py

@@ -0,0 +1,207 @@
+# 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 Annular Plane Intersection
+
+Analytical ray-plane intersection with annular (circular) bounds checking.
+
+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.ANNULAR_PLANE_ANALYTICAL)
+@cuda.jit
+def kernel_annular_plane_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
+    # Plane parameters
+    plane_normal_x,  # Plane normal X component
+    plane_normal_y,  # Plane normal Y component
+    plane_normal_z,  # Plane normal Z component
+    # Annulus center
+    center_x,
+    center_y,
+    center_z,
+    # Local U axis for coordinate computation
+    u_axis_x,
+    u_axis_y,
+    u_axis_z,
+    # Local V axis for coordinate computation
+    v_axis_x,
+    v_axis_y,
+    v_axis_z,
+    # Squared radii for annular bounds
+    inner_radius_sq,
+    outer_radius_sq,
+):
+    """
+    CUDA kernel for ray-annular-plane intersection.
+
+    Uses analytical solution for ray-plane intersection, then checks
+    if the intersection point lies within the annular bounds.
+
+    The annular plane is defined by its center point and normal.
+    The annular bounds are checked using the squared radial distance
+    from the center in the local coordinate frame.
+    """
+    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
+
+    # Compute denominator: n . d
+    denom = plane_normal_x * dx + plane_normal_y * dy + plane_normal_z * dz
+
+    # Check if ray is parallel to plane
+    if abs(denom) < 1e-10:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Compute numerator: (center - origin) . n
+    numer = (
+        plane_normal_x * (center_x - ox)
+        + plane_normal_y * (center_y - oy)
+        + plane_normal_z * (center_z - oz)
+    )
+
+    # Compute intersection distance
+    t = numer / denom
+
+    # Only forward intersections
+    if t < 0:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Compute intersection point
+    px = ox + t * dx
+    py = oy + t * dy
+    pz = oz + t * dz
+
+    # Vector from center to intersection
+    rx = px - center_x
+    ry = py - center_y
+    rz = pz - center_z
+
+    # Project onto local axes
+    u_coord = rx * u_axis_x + ry * u_axis_y + rz * u_axis_z
+    v_coord = rx * v_axis_x + ry * v_axis_y + rz * v_axis_z
+
+    # Check annular bounds (circular)
+    r_sq = u_coord * u_coord + v_coord * v_coord
+    if r_sq < inner_radius_sq or r_sq > outer_radius_sq:
+        hit_mask_out[idx] = False
+        distances_out[idx] = math.inf
+        return
+
+    # Valid annular intersection
+    hit_mask_out[idx] = True
+    distances_out[idx] = t
+
+    # Normal points toward ray origin (flip if ray hits from behind)
+    if denom > 0:
+        normals_out[idx, 0] = -plane_normal_x
+        normals_out[idx, 1] = -plane_normal_y
+        normals_out[idx, 2] = -plane_normal_z
+    else:
+        normals_out[idx, 0] = plane_normal_x
+        normals_out[idx, 1] = plane_normal_y
+        normals_out[idx, 2] = plane_normal_z