lsurf 1.0.0__py3-none-any.whl

lsurf/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker file - this package supports type checking

lsurf/simulation/__init__.py

@@ -0,0 +1,70 @@
+# 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.
+
+"""
+Simulation Module
+
+Provides the main Simulation class and supporting components for
+ray tracing simulations.
+
+Components:
+- Simulation: Main class that coordinates ray tracing
+- SimulationConfig: Configuration dataclass
+- SimulationOrchestrator: Low-level orchestration (advanced use)
+- SimulationResult: Result dataclass with statistics
+"""
+
+from .config import SimulationConfig
+from .orchestrator import SimulationOrchestrator
+from .result import (
+    SimulationResult,
+    SimulationStatistics,
+    SurfaceHitRecord,
+    SurfaceHitStats,
+    merge_recorded_rays,
+)
+from .simulation import Simulation
+
+__all__ = [
+    # Main classes
+    "Simulation",
+    "SimulationConfig",
+    "SimulationOrchestrator",
+    # Results
+    "SimulationResult",
+    "SimulationStatistics",
+    "SurfaceHitRecord",
+    "SurfaceHitStats",
+    # Utilities
+    "merge_recorded_rays",
+]

lsurf/simulation/config.py

@@ -0,0 +1,164 @@
+# 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.
+
+"""
+Simulation Configuration
+
+Contains the SimulationConfig dataclass for configuring ray tracing simulations.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SimulationConfig:
+    """
+    Configuration for ray tracing simulation.
+
+    Attributes
+    ----------
+    step_size : float
+        Maximum integration step size in meters (default 100.0).
+    min_step_size : float
+        Minimum step size in meters for adaptive stepping (default 3e-4 = 0.3mm).
+        This provides ~1ps time resolution near surfaces.
+    adaptive_stepping : bool
+        Whether to use adaptive step sizing near surfaces (default True).
+        When enabled, steps decrease as rays approach surfaces for precise timing.
+    surface_proximity_factor : float
+        Step size = distance * factor when within proximity threshold (default 0.5).
+    surface_proximity_threshold : float
+        Distance (in meters) within which adaptive stepping activates (default 10.0).
+    max_steps_per_leg : int
+        Maximum steps before forcing surface check (default 10000).
+    max_bounces : int
+        Maximum surface interactions before termination (default 10).
+    min_intensity : float
+        Intensity threshold below which rays are terminated (default 1e-10).
+    bounding_radius : float
+        Radius of bounding sphere in meters (default 500_000.0).
+    bounding_center : tuple[float, float, float]
+        Center of bounding sphere (default (0.0, 0.0, -6.371e6) for Earth center).
+    apply_absorption : bool
+        Whether to apply Beer-Lambert absorption (default True).
+    polarization : str
+        Polarization state: 's', 'p', or 'unpolarized' (default 'unpolarized').
+    track_polarization_vector : bool
+        Whether to track 3D polarization vectors through interactions (default False).
+    track_surface_hits : bool
+        Whether to store intermediate surface hit positions (default False).
+        When enabled, SimulationResult.surface_hits will contain hit positions
+        for all optical surfaces, useful for visualization.
+    track_refracted_rays : bool
+        Whether to continue propagating refracted rays from optical surfaces (default False).
+        When False, only reflected rays continue; refracted rays are discarded.
+        Set to False for simulations where only reflected light is of interest
+        (e.g., ocean surface reflection where underwater propagation is not needed).
+    use_gpu : bool
+        Whether to use GPU acceleration if available (default True).
+
+    Examples
+    --------
+    >>> config = SimulationConfig(step_size=50.0, max_bounces=5)
+    >>> sim = Simulation(geometry, config)
+
+    Notes
+    -----
+    Adaptive stepping provides sub-nanosecond timing precision near surfaces:
+
+    | Distance to Surface | Step Size | Time Resolution |
+    |---------------------|-----------|-----------------|
+    | > 10m               | 100m      | ~333ns          |
+    | 5m                  | 2.5m      | ~8ns            |
+    | 1m                  | 0.5m      | ~1.7ns          |
+    | 0.1m                | 0.05m     | ~167ps          |
+    | < 0.6mm             | 0.3mm     | ~1ps (minimum)  |
+    """
+
+    step_size: float = 100.0
+    min_step_size: float = 3e-4  # 0.3mm → ~1ps time resolution
+    adaptive_stepping: bool = True
+    surface_proximity_factor: float = 0.5  # Step = distance * factor when near
+    surface_proximity_threshold: float = 10.0  # Start adapting within this distance (m)
+    max_steps_per_leg: int = 10000
+    max_bounces: int = 10
+    min_intensity: float = 1e-10
+    bounding_radius: float = 500_000.0
+    bounding_center: tuple[float, float, float] = (0.0, 0.0, -6.371e6)
+    apply_absorption: bool = True
+    polarization: str = "unpolarized"
+    track_polarization_vector: bool = False
+    track_surface_hits: bool = False
+    track_refracted_rays: bool = False
+    use_gpu: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate configuration."""
+        if self.step_size <= 0:
+            raise ValueError(f"step_size must be positive, got {self.step_size}")
+        if self.min_step_size <= 0:
+            raise ValueError(
+                f"min_step_size must be positive, got {self.min_step_size}"
+            )
+        if self.min_step_size > self.step_size:
+            raise ValueError(
+                f"min_step_size ({self.min_step_size}) must be <= step_size ({self.step_size})"
+            )
+        if self.surface_proximity_factor <= 0 or self.surface_proximity_factor > 1:
+            raise ValueError(
+                f"surface_proximity_factor must be in (0, 1], got {self.surface_proximity_factor}"
+            )
+        if self.surface_proximity_threshold <= 0:
+            raise ValueError(
+                f"surface_proximity_threshold must be positive, got {self.surface_proximity_threshold}"
+            )
+        if self.max_steps_per_leg <= 0:
+            raise ValueError(
+                f"max_steps_per_leg must be positive, got {self.max_steps_per_leg}"
+            )
+        if self.max_bounces < 0:
+            raise ValueError(
+                f"max_bounces must be non-negative, got {self.max_bounces}"
+            )
+        if self.min_intensity < 0:
+            raise ValueError(
+                f"min_intensity must be non-negative, got {self.min_intensity}"
+            )
+        if self.bounding_radius <= 0:
+            raise ValueError(
+                f"bounding_radius must be positive, got {self.bounding_radius}"
+            )
+        if self.polarization not in ("s", "p", "unpolarized"):
+            raise ValueError(
+                f"polarization must be 's', 'p', or 'unpolarized', got '{self.polarization}'"
+            )

lsurf/simulation/orchestrator.py

@@ -0,0 +1,462 @@
+# 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.
+
+"""
+Simulation Orchestrator
+
+Coordinates the propagation loop for ray tracing simulations.
+
+Main loop:
+1. MaterialPropagator.propagate_to_surface(rays, max_steps)
+   -> Returns HitData (which rays hit which surfaces)
+2. SurfaceInteractionProcessor.process_hits(rays, hit_data)
+   -> DETECTOR: record hits
+   -> ABSORBER: terminate
+   -> OPTICAL: create reflected/refracted rays
+3. Merge new rays (reflected/refracted) into active batch
+4. Apply termination filters (bounds, min_intensity)
+5. Compact batch (remove inactive rays)
+6. Repeat until no active rays or max_bounces
+
+This is the third component in the propagator architecture:
+MaterialPropagator -> SurfaceInteractionProcessor -> SimulationOrchestrator
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .config import SimulationConfig
+from .result import (
+    SimulationResult,
+    SimulationStatistics,
+    SurfaceHitRecord,
+    merge_recorded_rays,
+)
+
+if TYPE_CHECKING:
+    from ..geometry import Geometry
+    from ..utilities.ray_data import RayBatch
+
+logger = logging.getLogger(__name__)
+
+
+class SimulationOrchestrator:
+    """
+    Coordinates the ray tracing simulation loop.
+
+    Uses MaterialPropagator for GPU-accelerated propagation with surface
+    detection, and SurfaceInteractionProcessor for handling surface
+    interactions (Fresnel, detection, absorption).
+
+    Parameters
+    ----------
+    geometry : Geometry
+        Pre-built geometry from GeometryBuilder.
+    config : SimulationConfig, optional
+        Simulation configuration. Uses defaults if not provided.
+    use_gpu : bool, optional
+        Override GPU setting from config.
+
+    Examples
+    --------
+    >>> from lsurf.geometry import GeometryBuilder
+    >>> from lsurf.simulation import SimulationOrchestrator, SimulationConfig
+    >>>
+    >>> geometry = builder.build()
+    >>> config = SimulationConfig(step_size=100.0, max_bounces=5)
+    >>> orchestrator = SimulationOrchestrator(geometry, config)
+    >>> result = orchestrator.run(rays)
+    """
+
+    def __init__(
+        self,
+        geometry: "Geometry",
+        config: SimulationConfig | None = None,
+        use_gpu: bool | None = None,
+    ):
+        from ..propagation.propagators.material_propagator import MaterialPropagator
+        from ..propagation.propagators.surface_interaction import (
+            SurfaceInteractionProcessor,
+        )
+        from ..utilities.recording_sphere import RecordedRays
+
+        self._geometry = geometry
+        self._config = config if config is not None else SimulationConfig()
+
+        # Override GPU setting if specified
+        effective_use_gpu = use_gpu if use_gpu is not None else self._config.use_gpu
+
+        # Get all surfaces
+        surfaces = geometry.to_surface_list()
+
+        # Create propagator with background material
+        self._propagator = MaterialPropagator(
+            material=geometry.background_material,
+            surfaces=surfaces,
+            use_gpu=effective_use_gpu,
+            apply_absorption=self._config.apply_absorption,
+        )
+
+        # Create interaction processor
+        self._interaction_processor = SurfaceInteractionProcessor(
+            surfaces=surfaces,
+            polarization=self._config.polarization,
+            track_polarization_vector=self._config.track_polarization_vector,
+        )
+
+        # RecordedRays class for creating empty results
+        self._RecordedRays = RecordedRays
+
+    @property
+    def geometry(self) -> "Geometry":
+        """The simulation geometry."""
+        return self._geometry
+
+    @property
+    def config(self) -> SimulationConfig:
+        """The simulation configuration."""
+        return self._config
+
+    def run(self, rays: "RayBatch") -> SimulationResult:
+        """
+        Run the ray tracing simulation.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Initial rays to trace.
+
+        Returns
+        -------
+        SimulationResult
+            Complete simulation results including detected rays and statistics.
+        """
+        from ..utilities.ray_data import merge_ray_batches, create_ray_batch
+
+        # Initialize statistics
+        stats = SimulationStatistics(
+            total_rays_initial=rays.num_rays,
+            total_rays_created=rays.num_rays,
+        )
+
+        logger.info(
+            "Starting simulation: %d rays, max %d bounces, step_size=%.3g m",
+            rays.num_rays,
+            self._config.max_bounces,
+            self._config.step_size,
+        )
+
+        # Clone rays to avoid modifying input
+        active_rays = rays.clone()
+
+        # Storage for collected results
+        all_detector_hits: list = []
+        detector_counts: dict[str, int] = {}
+
+        # Storage for surface hits if tracking enabled
+        surface_hits: dict[str, list[SurfaceHitRecord]] | None = None
+        if self._config.track_surface_hits:
+            surface_hits = {}
+
+        # Parse bounding center
+        bounding_center = np.array(self._config.bounding_center, dtype=np.float64)
+
+        # Main simulation loop
+        for bounce in range(self._config.max_bounces):
+            stats.bounces_completed = bounce + 1
+
+            # Check for active rays
+            if active_rays.num_active == 0:
+                logger.debug("Bounce %d: No active rays remaining", bounce + 1)
+                break
+
+            logger.debug(
+                "Bounce %d/%d: %d active rays",
+                bounce + 1,
+                self._config.max_bounces,
+                active_rays.num_active,
+            )
+
+            # Compact batch if many inactive rays
+            if active_rays.num_active < active_rays.num_rays * 0.5:
+                active_rays = active_rays.compact()
+                logger.debug("  Compacted batch to %d rays", active_rays.num_rays)
+
+            if active_rays.num_rays == 0:
+                break
+
+            # Step 1: Propagate to surface
+            hit_data = self._propagator.propagate_to_surface(
+                rays=active_rays,
+                step_size=self._config.step_size,
+                max_steps=self._config.max_steps_per_leg,
+                adaptive_stepping=self._config.adaptive_stepping,
+                min_step_size=self._config.min_step_size,
+                surface_proximity_factor=self._config.surface_proximity_factor,
+                surface_proximity_threshold=self._config.surface_proximity_threshold,
+            )
+
+            # Step 2: Process surface interactions
+            interaction_result = self._interaction_processor.process_hits(
+                rays=active_rays,
+                hit_data=hit_data,
+                track_surface_hits=self._config.track_surface_hits,
+            )
+
+            # Log interaction results
+            logger.debug(
+                "  Interactions: %d detected, %d absorbed, %d reflected",
+                interaction_result.detected_count,
+                interaction_result.absorbed_count,
+                (
+                    interaction_result.reflected_rays.num_rays
+                    if interaction_result.reflected_rays
+                    else 0
+                ),
+            )
+
+            # Collect detector hits
+            for name, recorded in interaction_result.detector_hits.items():
+                all_detector_hits.append(recorded)
+                detector_counts[name] = detector_counts.get(name, 0) + recorded.num_rays
+
+            # Collect optical surface hits if tracking enabled
+            if surface_hits is not None:
+                for hit in interaction_result.optical_hits:
+                    if hit.surface_name not in surface_hits:
+                        surface_hits[hit.surface_name] = []
+                    surface_hits[hit.surface_name].append(
+                        SurfaceHitRecord(
+                            surface_name=hit.surface_name,
+                            positions=hit.positions,
+                            directions=hit.directions,
+                            intensities=hit.intensities,
+                            wavelengths=hit.wavelengths,
+                            bounce=bounce,
+                        )
+                    )
+
+            # Update statistics
+            stats.rays_detected += interaction_result.detected_count
+            stats.rays_absorbed += interaction_result.absorbed_count
+
+            # Step 3: Collect rays for next iteration
+            next_rays_list = []
+
+            # Rays that didn't hit any surface continue
+            no_hit_rays = self._propagator.extract_no_hits(active_rays, hit_data)
+            if no_hit_rays.num_rays > 0:
+                next_rays_list.append(no_hit_rays)
+
+            # Reflected rays continue
+            if (
+                interaction_result.reflected_rays is not None
+                and interaction_result.reflected_rays.num_rays > 0
+            ):
+                next_rays_list.append(interaction_result.reflected_rays)
+                stats.total_rays_created += interaction_result.reflected_rays.num_rays
+
+            # Refracted rays continue (only if tracking is enabled)
+            if (
+                self._config.track_refracted_rays
+                and interaction_result.refracted_rays is not None
+                and interaction_result.refracted_rays.num_rays > 0
+            ):
+                next_rays_list.append(interaction_result.refracted_rays)
+                stats.total_rays_created += interaction_result.refracted_rays.num_rays
+
+            # Merge all continuing rays
+            if not next_rays_list:
+                active_rays = create_ray_batch(0)
+                break
+
+            active_rays = merge_ray_batches(next_rays_list)
+
+            # Step 4: Apply termination filters
+
+            # Bounding sphere check
+            distances_from_center = np.linalg.norm(
+                active_rays.positions - bounding_center, axis=1
+            )
+            outside_bounds = distances_from_center >= self._config.bounding_radius
+            num_outside = np.sum(outside_bounds & active_rays.active)
+            active_rays.active[outside_bounds] = False
+            stats.rays_terminated_bounds += int(num_outside)
+
+            # Intensity threshold
+            weak_mask = active_rays.active & (
+                active_rays.intensities < self._config.min_intensity
+            )
+            num_weak = np.sum(weak_mask)
+            active_rays.active[weak_mask] = False
+            stats.rays_terminated_intensity += int(num_weak)
+
+            # Log termination counts if any
+            if num_outside > 0 or num_weak > 0:
+                logger.debug(
+                    "  Terminated: %d out-of-bounds, %d below intensity threshold",
+                    num_outside,
+                    num_weak,
+                )
+
+            # Track max depth
+            if active_rays.num_rays > 0:
+                max_gen = np.max(active_rays.generations)
+                stats.max_depth_reached = max(stats.max_depth_reached, int(max_gen))
+
+        # Handle rays remaining after max bounces
+        if active_rays.num_rays > 0:
+            remaining_active = np.sum(active_rays.active)
+            stats.rays_terminated_max_bounces += int(remaining_active)
+
+        # Merge all detector hits
+        detected = merge_recorded_rays(all_detector_hits)
+
+        # Log final summary
+        logger.info(
+            "Simulation complete: %d bounces, %d detected, %d absorbed, %d remaining",
+            stats.bounces_completed,
+            stats.rays_detected,
+            stats.rays_absorbed,
+            active_rays.num_active,
+        )
+        if detector_counts:
+            for name, count in detector_counts.items():
+                logger.info("  Detector '%s': %d hits", name, count)
+
+        # Create final result
+        return SimulationResult(
+            detected=detected,
+            remaining=active_rays,
+            statistics=stats,
+            detections_per_surface=detector_counts,
+            surface_hits=surface_hits,
+        )
+
+    def run_single_bounce(
+        self,
+        rays: "RayBatch",
+    ) -> tuple["RayBatch", "SimulationResult"]:
+        """
+        Run a single propagation + interaction cycle.
+
+        Useful for step-by-step debugging or custom simulation loops.
+
+        Parameters
+        ----------
+        rays : RayBatch
+            Rays to propagate.
+
+        Returns
+        -------
+        continuing_rays : RayBatch
+            Rays that should continue (reflected, refracted, no-hit).
+        result : SimulationResult
+            Results from this single bounce (detections, absorptions).
+        """
+        from ..utilities.ray_data import merge_ray_batches, create_ray_batch
+
+        stats = SimulationStatistics(
+            total_rays_initial=rays.num_rays,
+            total_rays_created=rays.num_rays,
+            bounces_completed=1,
+        )
+
+        # Propagate to surface
+        hit_data = self._propagator.propagate_to_surface(
+            rays=rays,
+            step_size=self._config.step_size,
+            max_steps=self._config.max_steps_per_leg,
+            adaptive_stepping=self._config.adaptive_stepping,
+            min_step_size=self._config.min_step_size,
+            surface_proximity_factor=self._config.surface_proximity_factor,
+            surface_proximity_threshold=self._config.surface_proximity_threshold,
+        )
+
+        # Process interactions
+        interaction_result = self._interaction_processor.process_hits(
+            rays=rays,
+            hit_data=hit_data,
+        )
+
+        # Collect statistics
+        stats.rays_detected = interaction_result.detected_count
+        stats.rays_absorbed = interaction_result.absorbed_count
+
+        # Collect detector hits
+        detector_counts: dict[str, int] = {}
+        for name, recorded in interaction_result.detector_hits.items():
+            detector_counts[name] = recorded.num_rays
+
+        # Merge detector hits
+        detected = merge_recorded_rays(list(interaction_result.detector_hits.values()))
+
+        # Collect continuing rays
+        next_rays_list = []
+
+        no_hit_rays = self._propagator.extract_no_hits(rays, hit_data)
+        if no_hit_rays.num_rays > 0:
+            next_rays_list.append(no_hit_rays)
+
+        if (
+            interaction_result.reflected_rays is not None
+            and interaction_result.reflected_rays.num_rays > 0
+        ):
+            next_rays_list.append(interaction_result.reflected_rays)
+            stats.total_rays_created += interaction_result.reflected_rays.num_rays
+
+        if (
+            self._config.track_refracted_rays
+            and interaction_result.refracted_rays is not None
+            and interaction_result.refracted_rays.num_rays > 0
+        ):
+            next_rays_list.append(interaction_result.refracted_rays)
+            stats.total_rays_created += interaction_result.refracted_rays.num_rays
+
+        if next_rays_list:
+            continuing_rays = merge_ray_batches(next_rays_list)
+        else:
+            continuing_rays = create_ray_batch(0)
+
+        result = SimulationResult(
+            detected=detected,
+            remaining=continuing_rays,
+            statistics=stats,
+            detections_per_surface=detector_counts,
+        )
+
+        return continuing_rays, result