lsurf 1.0.0__py3-none-any.whl

lsurf/surfaces/gpu/sphere.py

@@ -0,0 +1,311 @@
+# 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.
+
+"""
+Sphere Surface (GPU-Capable)
+
+Implements a spherical surface with GPU acceleration support.
+Can be used as DETECTOR, OPTICAL, or ABSORBER.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import numpy.typing as npt
+
+from ..protocol import Surface, SurfaceRole
+from ..registry import register_surface_type
+
+if TYPE_CHECKING:
+    from ...propagation.kernels.registry import IntersectionKernelID
+
+
+@dataclass
+class SphereSurface(Surface):
+    """
+    Sphere surface with GPU acceleration.
+
+    The sphere is defined by center and radius.
+    Signed distance from point p: |p - center| - radius
+    (positive outside, negative inside)
+
+    Parameters
+    ----------
+    center : tuple of float
+        Center point (cx, cy, cz).
+    radius : float
+        Sphere radius (positive for convex, negative for concave).
+    role : SurfaceRole
+        What happens when a ray hits (DETECTOR, OPTICAL, or ABSORBER).
+    name : str
+        Human-readable name.
+    material_front : MaterialField, optional
+        Material outside the sphere. Required for OPTICAL.
+    material_back : MaterialField, optional
+        Material inside the sphere. Required for OPTICAL.
+
+    Examples
+    --------
+    >>> # Earth's surface as ocean
+    >>> EARTH_RADIUS = 6.371e6
+    >>> ocean = SphereSurface(
+    ...     center=(0, 0, -EARTH_RADIUS),
+    ...     radius=EARTH_RADIUS,
+    ...     role=SurfaceRole.OPTICAL,
+    ...     material_front=atmosphere,
+    ...     material_back=seawater,
+    ...     name="ocean_surface",
+    ... )
+    >>>
+    >>> # Spherical detector
+    >>> detector = SphereSurface(
+    ...     center=(0, 0, 0),
+    ...     radius=1000.0,
+    ...     role=SurfaceRole.DETECTOR,
+    ...     name="spherical_detector",
+    ... )
+    """
+
+    center: tuple[float, float, float]
+    radius: float
+    role: SurfaceRole
+    name: str = "sphere"
+    material_front: Any = None
+    material_back: Any = None
+
+    # GPU capability
+    _gpu_capable: bool = field(default=True, init=False, repr=False)
+    _geometry_id: int = field(default=2, init=False, repr=False)  # sphere = 2
+
+    # Kernel ID for this instance (set in __post_init__)
+    _kernel_id: IntersectionKernelID | None = field(
+        default=None, init=False, repr=False
+    )
+
+    @classmethod
+    def _get_supported_kernels(cls) -> list[IntersectionKernelID]:
+        """Get supported intersection kernels (lazy initialization)."""
+        from ...propagation.kernels.registry import IntersectionKernelID
+
+        return [IntersectionKernelID.SPHERE_ANALYTICAL]
+
+    @classmethod
+    def _get_default_kernel(cls) -> IntersectionKernelID:
+        """Get default intersection kernel."""
+        from ...propagation.kernels.registry import IntersectionKernelID
+
+        return IntersectionKernelID.SPHERE_ANALYTICAL
+
+    @classmethod
+    def supported_kernels(cls) -> list[IntersectionKernelID]:
+        """Return list of intersection kernels supported by this surface type."""
+        return cls._get_supported_kernels()
+
+    @classmethod
+    def default_kernel(cls) -> IntersectionKernelID:
+        """Return the default intersection kernel for this surface type."""
+        return cls._get_default_kernel()
+
+    def __post_init__(self) -> None:
+        if self.radius == 0:
+            raise ValueError("Radius cannot be zero")
+
+        # Set default kernel
+        self._kernel_id = self._get_default_kernel()
+
+    @property
+    def gpu_capable(self) -> bool:
+        """This surface supports GPU acceleration."""
+        return True
+
+    @property
+    def geometry_id(self) -> int:
+        """GPU geometry type ID (sphere = 2)."""
+        return 2
+
+    def get_gpu_parameters(self) -> tuple:
+        """
+        Return parameters for GPU kernel.
+
+        Returns
+        -------
+        tuple
+            (center_x, center_y, center_z, radius)
+        """
+        return (
+            self.center[0],
+            self.center[1],
+            self.center[2],
+            self.radius,
+        )
+
+    def get_materials(self) -> tuple | None:
+        """
+        Return (material_front, material_back) for Fresnel calculation.
+
+        Returns
+        -------
+        tuple or None
+            (material_front, material_back) or None if not OPTICAL
+        """
+        if self.role == SurfaceRole.OPTICAL:
+            return (self.material_front, self.material_back)
+        return None
+
+    def signed_distance(
+        self,
+        positions: npt.NDArray[np.float32],
+    ) -> npt.NDArray[np.float32]:
+        """
+        Compute signed distance from positions to sphere surface.
+
+        Parameters
+        ----------
+        positions : ndarray, shape (N, 3)
+            Points to compute distance for
+
+        Returns
+        -------
+        ndarray, shape (N,)
+            Signed distance (positive outside, negative inside)
+        """
+        center = np.array(self.center, dtype=np.float32)
+        diff = positions - center
+        dist = np.linalg.norm(diff, axis=1)
+        return (dist - abs(self.radius)).astype(np.float32)
+
+    def intersect(
+        self,
+        origins: npt.NDArray[np.float32],
+        directions: npt.NDArray[np.float32],
+        min_distance: float = 1e-6,
+    ) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.bool_]]:
+        """
+        Compute ray-sphere intersection.
+
+        Parameters
+        ----------
+        origins : ndarray, shape (N, 3)
+            Ray origins
+        directions : ndarray, shape (N, 3)
+            Ray directions (normalized)
+        min_distance : float
+            Minimum valid intersection distance
+
+        Returns
+        -------
+        distances : ndarray, shape (N,)
+            Distance to intersection (inf if no hit)
+        hit_mask : ndarray, shape (N,)
+            Boolean mask of valid intersections
+        """
+        center = np.array(self.center, dtype=np.float32)
+        r = abs(self.radius)
+
+        # Ray-sphere intersection:
+        # |origin + t*direction - center|^2 = r^2
+        oc = origins - center
+
+        a = np.sum(directions * directions, axis=1)
+        b = 2.0 * np.sum(oc * directions, axis=1)
+        c = np.sum(oc * oc, axis=1) - r * r
+
+        discriminant = b * b - 4 * a * c
+
+        # No intersection if discriminant < 0
+        no_hit = discriminant < 0
+
+        # Compute both roots
+        sqrt_disc = np.sqrt(np.maximum(discriminant, 0))
+        t1 = (-b - sqrt_disc) / (2 * a)
+        t2 = (-b + sqrt_disc) / (2 * a)
+
+        # Choose closest positive intersection >= min_distance
+        t1_valid = t1 >= min_distance
+        t2_valid = t2 >= min_distance
+
+        # Prefer t1 (closer) if valid, else t2
+        t = np.where(t1_valid, t1, np.where(t2_valid, t2, np.inf))
+
+        hit_mask = (~no_hit) & (t1_valid | t2_valid)
+        distances = np.where(hit_mask, t, np.inf)
+
+        return distances.astype(np.float32), hit_mask
+
+    def normal_at(
+        self,
+        positions: npt.NDArray[np.float32],
+        incoming_directions: npt.NDArray[np.float32] | None = None,
+    ) -> npt.NDArray[np.float32]:
+        """
+        Compute surface normal at positions.
+
+        For a sphere, normal points radially outward from center.
+
+        Parameters
+        ----------
+        positions : ndarray, shape (N, 3)
+            Points on the surface
+        incoming_directions : ndarray, shape (N, 3), optional
+            Ray directions (used to flip normal if needed)
+
+        Returns
+        -------
+        ndarray, shape (N, 3)
+            Normal vectors at each position
+        """
+        center = np.array(self.center, dtype=np.float32)
+        diff = positions - center
+
+        # Normalize
+        norms = np.linalg.norm(diff, axis=1, keepdims=True)
+        normals = diff / np.maximum(norms, 1e-12)
+
+        # For negative radius (concave), flip normals
+        if self.radius < 0:
+            normals = -normals
+
+        # Optionally flip normals to face incoming rays
+        if incoming_directions is not None:
+            dot = np.sum(normals * incoming_directions, axis=1)
+            flip_mask = dot > 0
+            normals[flip_mask] = -normals[flip_mask]
+
+        return normals.astype(np.float32)
+
+
+# Register class with registry
+register_surface_type("sphere", "gpu", 2, SphereSurface)

lsurf/surfaces/protocol.py

@@ -0,0 +1,336 @@
+# 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.
+
+"""
+Unified Surface Protocol
+
+Defines the base class and enums for all surfaces in the ray tracing framework.
+All surfaces follow this protocol regardless of GPU capability.
+
+GPU-capable surfaces additionally provide signed_distance() and get_gpu_parameters()
+for accelerated computation. CPU fallback (intersect, normal_at) is always available.
+
+See registry.py for the geometry type registry.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import IntEnum
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from ..materials import MaterialField
+    from ..propagation.kernels.registry import IntersectionKernelID
+
+
+class SurfaceRole(IntEnum):
+    """What happens when a ray hits this surface."""
+
+    DETECTOR = 1  # Record ray data and deactivate
+    OPTICAL = 2  # Reflect/refract based on Fresnel equations
+    ABSORBER = 3  # Apply absorption coefficient, possibly deactivate
+
+
+class Surface(ABC):
+    """
+    Abstract base class for all surfaces.
+
+    All surfaces provide CPU-based ray intersection and normal computation.
+    GPU-capable surfaces additionally provide signed_distance() and
+    get_gpu_parameters() for accelerated GPU computation.
+
+    Parameters
+    ----------
+    role : SurfaceRole
+        What happens when a ray hits (DETECTOR, OPTICAL, ABSORBER).
+    name : str
+        Human-readable identifier for the surface.
+    material_front : MaterialField, optional
+        Material on the front side (direction of normal). Required for OPTICAL.
+    material_back : MaterialField, optional
+        Material on the back side. Required for OPTICAL.
+
+    Attributes
+    ----------
+    role : SurfaceRole
+        Surface role.
+    name : str
+        Surface identifier.
+    material_front : MaterialField or None
+        Front-side material.
+    material_back : MaterialField or None
+        Back-side material.
+    gpu_capable : bool
+        Whether this surface supports GPU acceleration.
+    geometry_id : int
+        GPU geometry type ID (0 for CPU-only surfaces).
+
+    Examples
+    --------
+    >>> # Check if surface can use GPU
+    >>> if surface.gpu_capable:
+    ...     params = surface.get_gpu_parameters()
+    ...     sd = surface.signed_distance(positions)
+    >>> else:
+    ...     distances, hits = surface.intersect(origins, directions)
+    """
+
+    # Subclasses should override these class attributes
+    _gpu_capable: bool = False
+    _geometry_id: int = 0  # 0 = CPU-only, no GPU geometry
+
+    # Intersection kernel compatibility declarations
+    _supported_kernels: list[IntersectionKernelID] = []
+    _default_kernel: IntersectionKernelID | None = None
+
+    def __init__(
+        self,
+        role: SurfaceRole,
+        name: str,
+        material_front: "MaterialField | None" = None,
+        material_back: "MaterialField | None" = None,
+        kernel: "IntersectionKernelID | None" = None,
+    ):
+        self.role = role
+        self.name = name
+        self.material_front = material_front
+        self.material_back = material_back
+
+        # Validate kernel selection
+        if kernel is None:
+            self._kernel_id = self._default_kernel
+        else:
+            if self._supported_kernels and kernel not in self._supported_kernels:
+                raise ValueError(
+                    f"{self.__class__.__name__} does not support kernel {kernel}. "
+                    f"Supported: {self._supported_kernels}"
+                )
+            self._kernel_id = kernel
+
+    @property
+    def gpu_capable(self) -> bool:
+        """Whether this surface supports GPU acceleration."""
+        return self._gpu_capable
+
+    @property
+    def geometry_id(self) -> int:
+        """
+        GPU geometry type ID.
+
+        Returns 0 for CPU-only surfaces. GPU-capable surfaces return
+        a positive integer registered in the geometry registry.
+        """
+        return self._geometry_id
+
+    # Backwards compatibility alias
+    @property
+    def geometry(self) -> int:
+        """Deprecated: use geometry_id instead."""
+        return self._geometry_id
+
+    # =========================================================================
+    # COMPATIBILITY QUERY METHODS
+    # =========================================================================
+
+    @classmethod
+    def supported_kernels(cls) -> list[IntersectionKernelID]:
+        """
+        Return list of intersection kernels supported by this surface type.
+
+        Returns
+        -------
+        list[IntersectionKernelID]
+            List of kernel IDs this surface supports.
+
+        Examples
+        --------
+        >>> from lsurf.surfaces import PlaneSurface
+        >>> PlaneSurface.supported_kernels()
+        [<IntersectionKernelID.PLANE_ANALYTICAL: ...>]
+        """
+
+        return list(cls._supported_kernels)
+
+    @classmethod
+    def default_kernel(cls) -> IntersectionKernelID | None:
+        """
+        Return the default intersection kernel for this surface type.
+
+        Returns
+        -------
+        IntersectionKernelID or None
+            The default kernel ID, or None if no GPU kernels are supported.
+        """
+        return cls._default_kernel
+
+    @property
+    def kernel_id(self) -> IntersectionKernelID | None:
+        """
+        Return the kernel ID configured for this surface instance.
+
+        Returns
+        -------
+        IntersectionKernelID or None
+            The kernel ID selected for this instance.
+        """
+        return self._kernel_id
+
+    @abstractmethod
+    def intersect(
+        self,
+        origins: NDArray[np.float32],
+        directions: NDArray[np.float32],
+        min_distance: float = 1e-6,
+    ) -> tuple[NDArray[np.float32], NDArray[np.bool_]]:
+        """
+        Compute ray-surface intersections (CPU).
+
+        Parameters
+        ----------
+        origins : ndarray, shape (N, 3)
+            Ray origin positions.
+        directions : ndarray, shape (N, 3)
+            Ray direction unit vectors.
+        min_distance : float, optional
+            Minimum valid intersection distance. Default is 1e-6.
+
+        Returns
+        -------
+        distances : ndarray, shape (N,)
+            Distance to intersection (inf if no hit).
+        hit_mask : ndarray, shape (N,), dtype=bool
+            True for rays that hit the surface.
+        """
+        ...
+
+    @abstractmethod
+    def normal_at(
+        self,
+        positions: NDArray[np.float32],
+        incoming_directions: NDArray[np.float32] | None = None,
+    ) -> NDArray[np.float32]:
+        """
+        Compute surface normal at given positions.
+
+        Parameters
+        ----------
+        positions : ndarray, shape (N, 3)
+            Points on the surface.
+        incoming_directions : ndarray, shape (N, 3), optional
+            Incoming ray directions (for orienting normals).
+
+        Returns
+        -------
+        normals : ndarray, shape (N, 3)
+            Unit normal vectors.
+        """
+        ...
+
+    def get_materials(self) -> tuple[Any, Any] | None:
+        """
+        Return (material_front, material_back) for Fresnel calculation.
+
+        Returns
+        -------
+        tuple or None
+            (material_front, material_back) for OPTICAL surfaces, None otherwise.
+        """
+        if self.role == SurfaceRole.OPTICAL:
+            return (self.material_front, self.material_back)
+        return None
+
+    # --- GPU-specific methods (override in GPU-capable surfaces) ---
+
+    def signed_distance(
+        self,
+        positions: NDArray[np.float32],
+    ) -> NDArray[np.float32]:
+        """
+        Compute signed distance from positions to surface.
+
+        Only available for GPU-capable surfaces. Raises NotImplementedError
+        for CPU-only surfaces.
+
+        Parameters
+        ----------
+        positions : ndarray, shape (N, 3)
+            Points to compute distance for.
+
+        Returns
+        -------
+        ndarray, shape (N,)
+            Signed distance (positive on front side, negative on back side).
+
+        Raises
+        ------
+        NotImplementedError
+            If surface is not GPU-capable.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support GPU acceleration. "
+            "Use intersect() for CPU-based ray tracing."
+        )
+
+    def get_gpu_parameters(self) -> tuple:
+        """
+        Return parameters for GPU kernel.
+
+        Only available for GPU-capable surfaces. Raises NotImplementedError
+        for CPU-only surfaces.
+
+        Returns
+        -------
+        tuple
+            Geometry-dependent parameters for GPU signed distance calculation.
+
+        Raises
+        ------
+        NotImplementedError
+            If surface is not GPU-capable.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support GPU acceleration."
+        )
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        gpu_str = "GPU" if self.gpu_capable else "CPU"
+        return f"{self.__class__.__name__}(name='{self.name}', role={self.role.name}, {gpu_str})"
+
+
+# For backwards compatibility, also export as GPUSurface
+GPUSurface = Surface