lsurf 1.0.0__py3-none-any.whl

lsurf/propagation/propagators/material_propagator.py

@@ -0,0 +1,398 @@
+# 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.
+
+"""
+Material Propagator
+
+Handles in-material physics including:
+- Ray equation integration (Euler/RK4 in gradient media)
+- Beer-Lambert absorption
+- Surface crossing detection (signed distance check each step)
+- Bisection refinement for exact intersection
+- Optical/geometric path length tracking
+
+This is the first component in the propagator architecture:
+MaterialPropagator -> SurfaceInteractionProcessor -> SimulationOrchestrator
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+
+from .surface_propagator import SurfacePropagator, HitData
+
+if TYPE_CHECKING:
+    from ...materials import MaterialField
+    from ...surfaces import Surface
+    from ...utilities.ray_data import RayBatch
+
+
+@runtime_checkable
+class MaterialPropagatorProtocol(Protocol):
+    """
+    Protocol for material propagators.
+
+    Material propagators handle ray propagation through a material medium,
+    including ray equation integration and surface crossing detection.
+    """
+
+    @property
+    def material(self) -> "MaterialField":
+        """The material being propagated through."""
+        ...
+
+    @property
+    def surfaces(self) -> list["Surface"]:
+        """List of surfaces being checked for intersection."""
+        ...
+
+    def propagate_to_surface(
+        self,
+        rays: "RayBatch",
+        step_size: float,
+        max_steps: int,
+        adaptive_stepping: bool = False,
+        min_step_size: float = 3e-4,
+        surface_proximity_factor: float = 0.5,
+        surface_proximity_threshold: float = 10.0,
+    ) -> HitData:
+        """
+        Propagate rays until they hit a surface or reach max_steps.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Ray batch to propagate. Modified in-place.
+        step_size : float
+            Maximum integration step size in meters.
+        max_steps : int
+            Maximum number of propagation steps.
+        adaptive_stepping : bool, optional
+            Whether to use adaptive step sizing near surfaces.
+        min_step_size : float, optional
+            Minimum step size in meters.
+        surface_proximity_factor : float, optional
+            Step = distance * factor when within threshold.
+        surface_proximity_threshold : float, optional
+            Distance within which to start adaptive stepping.
+
+        Returns
+        -------
+        HitData
+            Information about which rays hit which surfaces.
+        """
+        ...
+
+
+@dataclass
+class PropagationResult:
+    """
+    Result from a single propagation leg.
+
+    Attributes
+    ----------
+    hit_data : HitData
+        Information about ray-surface intersections.
+    steps_taken : int
+        Number of steps actually taken.
+    """
+
+    hit_data: HitData
+    steps_taken: int = 0
+
+
+class MaterialPropagator:
+    """
+    GPU-accelerated material propagator with multi-surface detection.
+
+    This class wraps the SurfacePropagator to provide a clean interface
+    for ray propagation through gradient media with surface detection.
+
+    Parameters
+    ----------
+    material : MaterialField
+        The material to propagate through. Must support SimpleInhomogeneousModel
+        GPU interface (i.e., have get_gpu_parameters() and get_gpu_arrays()).
+    surfaces : list of Surface
+        List of surfaces to check for intersections. Maximum of 16 surfaces.
+    use_gpu : bool, optional
+        Whether to use GPU acceleration. Default True.
+    threads_per_block : int, optional
+        CUDA threads per block for GPU execution. Default 256.
+
+    Examples
+    --------
+    >>> from lsurf.materials import LinsleyAtmosphere
+    >>> from lsurf.surfaces import PlaneSurface, SphereSurface, SurfaceRole
+    >>>
+    >>> atmosphere = LinsleyAtmosphere()
+    >>> detector = PlaneSurface(
+    ...     normal=(0, 0, 1),
+    ...     point=(0, 0, 35000),
+    ...     role=SurfaceRole.DETECTOR,
+    ... )
+    >>> ocean = SphereSurface(
+    ...     center=(0, 0, -6.371e6),
+    ...     radius=6.371e6,
+    ...     role=SurfaceRole.OPTICAL,
+    ... )
+    >>>
+    >>> propagator = MaterialPropagator(
+    ...     material=atmosphere,
+    ...     surfaces=[detector, ocean],
+    ... )
+    >>> hit_data = propagator.propagate_to_surface(rays, step_size=100.0, max_steps=1000)
+    """
+
+    def __init__(
+        self,
+        material: "MaterialField",
+        surfaces: list["Surface"],
+        use_gpu: bool = True,
+        threads_per_block: int = 256,
+        apply_absorption: bool = False,
+    ):
+        self._material = material
+        self._surfaces = list(surfaces)
+        self._use_gpu = use_gpu
+        self._threads_per_block = threads_per_block
+        self._apply_absorption = apply_absorption
+
+        # Create underlying SurfacePropagator
+        self._propagator = SurfacePropagator(
+            material=material,
+            surfaces=surfaces,
+            method="euler",
+            threads_per_block=threads_per_block,
+            use_gpu=use_gpu,
+            apply_absorption=apply_absorption,
+        )
+
+    @property
+    def material(self) -> "MaterialField":
+        """The material being propagated through."""
+        return self._material
+
+    @property
+    def surfaces(self) -> list["Surface"]:
+        """List of surfaces being checked for intersection."""
+        return self._surfaces
+
+    @property
+    def num_surfaces(self) -> int:
+        """Number of surfaces."""
+        return len(self._surfaces)
+
+    @property
+    def use_gpu(self) -> bool:
+        """Whether GPU acceleration is enabled."""
+        return self._propagator._use_gpu
+
+    def propagate_to_surface(
+        self,
+        rays: "RayBatch",
+        step_size: float,
+        max_steps: int,
+        adaptive_stepping: bool = False,
+        min_step_size: float = 3e-4,
+        surface_proximity_factor: float = 0.5,
+        surface_proximity_threshold: float = 10.0,
+    ) -> HitData:
+        """
+        Propagate rays until they hit a surface or reach max_steps.
+
+        Each step:
+        1. Compute ray equation step (position, direction update)
+        2. Apply absorption (Beer-Lambert) - integrated in the ray equation
+        3. Check signed distance to all surfaces
+        4. If sign change detected -> bisect to find exact crossing
+        5. Record hit data, deactivate ray
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Ray batch to propagate. Modified in-place with updated positions,
+            directions, path lengths, and active status.
+        step_size : float
+            Maximum integration step size in meters.
+        max_steps : int
+            Maximum number of propagation steps.
+        adaptive_stepping : bool, optional
+            Whether to use adaptive step sizing near surfaces (default False).
+        min_step_size : float, optional
+            Minimum step size in meters (default 3e-4 = 0.3mm → ~1ps resolution).
+        surface_proximity_factor : float, optional
+            Step = distance * factor when within threshold (default 0.5).
+        surface_proximity_threshold : float, optional
+            Distance within which to start adaptive stepping (default 10.0 m).
+
+        Returns
+        -------
+        HitData
+            Information about which rays hit which surfaces:
+            - hit_surface_idx: which surface each ray hit (-1 = no hit)
+            - hit_positions: intersection positions
+            - hit_directions: directions at intersection
+        """
+        return self._propagator.propagate_to_surface(
+            rays=rays,
+            step_size=step_size,
+            max_steps=max_steps,
+            adaptive_stepping=adaptive_stepping,
+            min_step_size=min_step_size,
+            surface_proximity_factor=surface_proximity_factor,
+            surface_proximity_threshold=surface_proximity_threshold,
+        )
+
+    def propagate(
+        self,
+        rays: "RayBatch",
+        step_size: float,
+        max_steps: int,
+    ) -> PropagationResult:
+        """
+        Propagate rays and return full result with metadata.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Ray batch to propagate.
+        step_size : float
+            Integration step size in meters.
+        max_steps : int
+            Maximum number of steps.
+
+        Returns
+        -------
+        PropagationResult
+            Full propagation result including hit data and steps taken.
+        """
+        hit_data = self.propagate_to_surface(rays, step_size, max_steps)
+        return PropagationResult(
+            hit_data=hit_data,
+            steps_taken=max_steps,  # Approximate - actual may be less
+        )
+
+    def get_surface_by_index(self, idx: int) -> "Surface":
+        """Get surface by index."""
+        return self._surfaces[idx]
+
+    def extract_hits_for_surface(
+        self,
+        rays: "RayBatch",
+        hit_data: HitData,
+        surface_idx: int,
+    ) -> "RayBatch":
+        """
+        Extract rays that hit a specific surface as a new RayBatch.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Original ray batch.
+        hit_data : HitData
+            Hit data from propagation.
+        surface_idx : int
+            Index of surface to extract hits for.
+
+        Returns
+        -------
+        RayBatch
+            New batch containing only rays that hit the specified surface.
+        """
+        return self._propagator.extract_hits_for_surface(rays, hit_data, surface_idx)
+
+    def extract_no_hits(
+        self,
+        rays: "RayBatch",
+        hit_data: HitData,
+    ) -> "RayBatch":
+        """
+        Extract rays that didn't hit any surface.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Original ray batch.
+        hit_data : HitData
+            Hit data from propagation.
+
+        Returns
+        -------
+        RayBatch
+            New batch containing only rays that didn't hit any surface.
+        """
+        return self._propagator.extract_no_hits(rays, hit_data)
+
+
+class CPUMaterialPropagator(MaterialPropagator):
+    """
+    CPU-only material propagator.
+
+    Forces CPU execution even if GPU is available. Useful for testing
+    or when GPU resources are limited.
+    """
+
+    def __init__(
+        self,
+        material: "MaterialField",
+        surfaces: list["Surface"],
+    ):
+        super().__init__(
+            material=material,
+            surfaces=surfaces,
+            use_gpu=False,
+        )
+
+
+class GPUMaterialPropagator(MaterialPropagator):
+    """
+    GPU-accelerated material propagator.
+
+    Explicitly requests GPU acceleration. Falls back to CPU if unavailable.
+    """
+
+    def __init__(
+        self,
+        material: "MaterialField",
+        surfaces: list["Surface"],
+        threads_per_block: int = 256,
+    ):
+        super().__init__(
+            material=material,
+            surfaces=surfaces,
+            use_gpu=True,
+            threads_per_block=threads_per_block,
+        )