lsurf 1.0.0__py3-none-any.whl

lsurf/simulation/result.py

@@ -0,0 +1,299 @@
+# 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 Result Data Structures
+
+Contains the result dataclasses returned by the Simulation/Orchestrator classes.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+if TYPE_CHECKING:
+    from ..detectors.results import DetectorResult
+    from ..utilities.ray_data import RayBatch
+
+
+@dataclass
+class SurfaceHitRecord:
+    """
+    Record of ray hits on a surface.
+
+    Stores positions and directions of rays that hit a specific surface,
+    useful for visualization and analysis of intermediate surface interactions.
+
+    Attributes
+    ----------
+    surface_name : str
+        Name of the surface.
+    positions : ndarray, shape (N, 3)
+        Hit positions in world coordinates.
+    directions : ndarray, shape (N, 3)
+        Ray directions at hit points.
+    intensities : ndarray, shape (N,)
+        Ray intensities at hit.
+    wavelengths : ndarray, shape (N,)
+        Ray wavelengths.
+    bounce : int
+        Which bounce iteration this hit occurred on (0-indexed).
+    """
+
+    surface_name: str
+    positions: npt.NDArray[np.float32]
+    directions: npt.NDArray[np.float32]
+    intensities: npt.NDArray[np.float32]
+    wavelengths: npt.NDArray[np.float32]
+    bounce: int
+
+    @property
+    def num_hits(self) -> int:
+        """Number of hits recorded."""
+        return len(self.positions)
+
+    def __repr__(self) -> str:
+        return (
+            f"SurfaceHitRecord(surface_name={self.surface_name!r}, "
+            f"num_hits={self.num_hits}, bounce={self.bounce})"
+        )
+
+
+@dataclass
+class SimulationStatistics:
+    """
+    Statistics from a simulation run.
+
+    Attributes
+    ----------
+    total_rays_initial : int
+        Number of rays at simulation start.
+    total_rays_created : int
+        Total rays including split rays.
+    rays_detected : int
+        Rays that hit detector surfaces.
+    rays_absorbed : int
+        Rays terminated by absorber surfaces.
+    rays_terminated_intensity : int
+        Rays terminated due to low intensity.
+    rays_terminated_bounds : int
+        Rays that exited bounding sphere.
+    rays_terminated_max_bounces : int
+        Rays that reached max bounce limit.
+    bounces_completed : int
+        Number of bounce iterations completed.
+    max_depth_reached : int
+        Maximum tree depth from ray splitting.
+    """
+
+    total_rays_initial: int = 0
+    total_rays_created: int = 0
+    rays_detected: int = 0
+    rays_absorbed: int = 0
+    rays_terminated_intensity: int = 0
+    rays_terminated_bounds: int = 0
+    rays_terminated_max_bounces: int = 0
+    bounces_completed: int = 0
+    max_depth_reached: int = 0
+
+
+@dataclass
+class SimulationResult:
+    """
+    Complete result from a ray tracing simulation.
+
+    Attributes
+    ----------
+    detected : DetectorResult
+        Rays that were recorded by detector surfaces.
+    remaining : RayBatch
+        Rays that are still active after simulation completed
+        (either didn't hit any surface or exceeded max bounces).
+    statistics : SimulationStatistics
+        Detailed simulation statistics.
+    detections_per_surface : dict
+        Number of detections per detector surface name.
+    surface_hits : dict or None
+        If track_surface_hits was enabled, contains SurfaceHitRecord objects
+        for each optical surface, keyed by surface name. Each surface may have
+        multiple records (one per bounce). If disabled, this is None.
+
+    Examples
+    --------
+    >>> result = sim.run(rays)
+    >>> print(f"Detected {result.statistics.rays_detected} rays")
+    >>> print(f"Completed in {result.statistics.bounces_completed} bounces")
+    >>>
+    >>> # Access detection results
+    >>> print(f"Total detected intensity: {result.detected.total_intensity:.3e}")
+    >>> times = result.detected.times
+    >>> positions = result.detected.positions
+    >>>
+    >>> # Access surface hits (if track_surface_hits=True)
+    >>> if result.surface_hits:
+    ...     for name, records in result.surface_hits.items():
+    ...         for rec in records:
+    ...             print(f"{name} bounce {rec.bounce}: {rec.num_hits} hits")
+    """
+
+    detected: "DetectorResult"
+    remaining: "RayBatch"
+    statistics: SimulationStatistics
+    detections_per_surface: dict[str, int] = field(default_factory=dict)
+    surface_hits: dict[str, list[SurfaceHitRecord]] | None = None
+
+    @property
+    def num_detected(self) -> int:
+        """Number of rays that hit detector surfaces."""
+        return self.detected.num_rays
+
+    @property
+    def num_remaining(self) -> int:
+        """Number of rays still active."""
+        return self.remaining.num_rays
+
+    @property
+    def bounces(self) -> int:
+        """Number of bounce iterations performed (backwards compatibility)."""
+        return self.statistics.bounces_completed
+
+    @property
+    def total_rays_processed(self) -> int:
+        """Total rays processed including splits (backwards compatibility)."""
+        return self.statistics.total_rays_created
+
+    def get_surface_hit_positions(self, surface_name: str) -> npt.NDArray[np.float32]:
+        """
+        Get all hit positions for a specific surface across all bounces.
+
+        Parameters
+        ----------
+        surface_name : str
+            Name of the surface.
+
+        Returns
+        -------
+        ndarray, shape (N, 3)
+            Concatenated hit positions from all bounces. Empty array if no hits
+            or if track_surface_hits was not enabled.
+        """
+        if self.surface_hits is None or surface_name not in self.surface_hits:
+            return np.empty((0, 3), dtype=np.float32)
+
+        records = self.surface_hits[surface_name]
+        if not records:
+            return np.empty((0, 3), dtype=np.float32)
+
+        return np.concatenate([r.positions for r in records], axis=0)
+
+
+@dataclass
+class SurfaceHitStats:
+    """
+    Statistics about surface hits during a simulation.
+
+    Attributes
+    ----------
+    surface_name : str
+        Name of the surface.
+    hit_count : int
+        Number of rays that hit this surface.
+    mean_intensity : float
+        Mean intensity of rays hitting this surface.
+    total_intensity : float
+        Sum of intensities of rays hitting this surface.
+    """
+
+    surface_name: str
+    hit_count: int
+    mean_intensity: float
+    total_intensity: float
+
+
+def merge_detector_results(result_list: list) -> "DetectorResult":
+    """
+    Merge multiple DetectorResult objects into a single instance.
+
+    Parameters
+    ----------
+    result_list : list of DetectorResult
+        List of detector results to merge.
+
+    Returns
+    -------
+    DetectorResult
+        Combined detector results.
+    """
+    from ..detectors.results import DetectorResult
+
+    return DetectorResult.merge(result_list)
+
+
+# Backward compatibility: keep merge_recorded_rays as alias
+def merge_recorded_rays(recorded_list: list) -> "DetectorResult":
+    """
+    Merge multiple DetectorResult/RecordedRays into a single instance.
+
+    This function is provided for backward compatibility. New code should
+    use DetectorResult.merge() directly.
+
+    Parameters
+    ----------
+    recorded_list : list
+        List of DetectorResult or RecordedRays to merge.
+
+    Returns
+    -------
+    DetectorResult
+        Combined results.
+    """
+    from ..detectors.results import DetectorResult
+
+    if not recorded_list:
+        return DetectorResult.empty()
+
+    # Check if we have RecordedRays (old format) or DetectorResult (new format)
+    first = recorded_list[0]
+    if hasattr(first, "to_detection_events"):
+        # Already DetectorResult
+        return DetectorResult.merge(recorded_list)
+
+    # Convert RecordedRays to DetectorResult
+    converted = []
+    for r in recorded_list:
+        if r.num_rays > 0:
+            converted.append(DetectorResult.from_recorded_rays(r))
+
+    return DetectorResult.merge(converted)

lsurf/simulation/simulation.py

@@ -0,0 +1,262 @@
+# 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.
+
+"""
+Ray Tracing Simulation
+
+The Simulation class uses a Geometry object built via GeometryBuilder
+as its first step, ensuring:
+- Material consistency across surfaces via named media
+- Validation of surface configurations
+- Immutable geometry during simulation
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from typing import TYPE_CHECKING
+
+from ..geometry import Geometry
+from ..surfaces import SurfaceRole
+
+from .config import SimulationConfig
+from .orchestrator import SimulationOrchestrator
+from .result import SimulationResult
+
+if TYPE_CHECKING:
+    from ..utilities.ray_data import RayBatch
+
+logger = logging.getLogger(__name__)
+
+
+class Simulation:
+    """
+    Ray tracing simulation with geometry-based configuration.
+
+    The simulation takes a pre-built Geometry object which defines:
+    - All optical surfaces with their materials
+    - All detector surfaces
+    - The background propagation medium
+    - Named media for material consistency
+
+    Parameters
+    ----------
+    geometry : Geometry
+        Pre-built geometry from GeometryBuilder containing all surfaces,
+        detectors, and materials.
+    config : SimulationConfig, optional
+        Simulation configuration. Uses defaults if not provided.
+
+    Examples
+    --------
+    >>> from lsurf.geometry import GeometryBuilder
+    >>> from lsurf.materials import LinsleyAtmosphere, WATER
+    >>> from lsurf.surfaces import SphereSurface, PlaneSurface, SurfaceRole
+    >>> from lsurf.simulation import Simulation, SimulationConfig
+    >>>
+    >>> # Build geometry
+    >>> EARTH_RADIUS = 6.371e6
+    >>> atmosphere = LinsleyAtmosphere()
+    >>>
+    >>> ocean = SphereSurface(
+    ...     center=(0, 0, -EARTH_RADIUS),
+    ...     radius=EARTH_RADIUS,
+    ...     role=SurfaceRole.OPTICAL,
+    ...     name="ocean",
+    ... )
+    >>> detector = PlaneSurface(
+    ...     point=(0, 0, 35000),
+    ...     normal=(0, 0, 1),
+    ...     role=SurfaceRole.DETECTOR,
+    ...     name="detector_35km",
+    ... )
+    >>>
+    >>> geometry = (
+    ...     GeometryBuilder()
+    ...     .register_medium("atmosphere", atmosphere)
+    ...     .register_medium("ocean", WATER)
+    ...     .set_background("atmosphere")
+    ...     .add_surface(ocean, front="atmosphere", back="ocean")
+    ...     .add_detector(detector)
+    ...     .build()
+    ... )
+    >>>
+    >>> # Create simulation with geometry
+    >>> config = SimulationConfig(step_size=100.0, max_bounces=5)
+    >>> sim = Simulation(geometry, config)
+    >>> result = sim.run(rays)
+    >>> print(f"Detected: {result.statistics.rays_detected}")
+    """
+
+    def __init__(
+        self,
+        geometry: Geometry,
+        config: SimulationConfig | None = None,
+    ):
+        self._geometry = geometry
+        self._config = config if config is not None else SimulationConfig()
+
+        # Extract surfaces list (surfaces + detectors)
+        self._all_surfaces = geometry.to_surface_list()
+
+        # Build surface indices by role for efficient processing
+        self._detector_indices: list[int] = []
+        self._optical_indices: list[int] = []
+        self._absorber_indices: list[int] = []
+
+        for i, surface in enumerate(self._all_surfaces):
+            if surface.role == SurfaceRole.DETECTOR:
+                self._detector_indices.append(i)
+            elif surface.role == SurfaceRole.OPTICAL:
+                self._optical_indices.append(i)
+            elif surface.role == SurfaceRole.ABSORBER:
+                self._absorber_indices.append(i)
+
+        # Create orchestrator lazily
+        self._orchestrator: SimulationOrchestrator | None = None
+
+        logger.info(
+            "Simulation initialized: %d optical, %d detector, %d absorber surfaces",
+            len(self._optical_indices),
+            len(self._detector_indices),
+            len(self._absorber_indices),
+        )
+
+    @property
+    def geometry(self) -> Geometry:
+        """The simulation geometry."""
+        return self._geometry
+
+    @property
+    def config(self) -> SimulationConfig:
+        """The simulation configuration."""
+        return self._config
+
+    @property
+    def num_surfaces(self) -> int:
+        """Total number of surfaces (optical + absorber + detector)."""
+        return len(self._all_surfaces)
+
+    @property
+    def detector_surfaces(self) -> list:
+        """List of detector surfaces."""
+        return [self._all_surfaces[i] for i in self._detector_indices]
+
+    @property
+    def optical_surfaces(self) -> list:
+        """List of optical surfaces."""
+        return [self._all_surfaces[i] for i in self._optical_indices]
+
+    @property
+    def absorber_surfaces(self) -> list:
+        """List of absorber surfaces."""
+        return [self._all_surfaces[i] for i in self._absorber_indices]
+
+    def _get_orchestrator(self) -> SimulationOrchestrator:
+        """Get or create the simulation orchestrator."""
+        if self._orchestrator is None:
+            self._orchestrator = SimulationOrchestrator(
+                geometry=self._geometry,
+                config=self._config,
+            )
+        return self._orchestrator
+
+    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: RecordedRays from detector surfaces
+            - remaining: RayBatch of rays still active
+            - statistics: SimulationStatistics with counts
+            - detections_per_surface: dict mapping detector names to hit counts
+
+        Examples
+        --------
+        >>> result = sim.run(rays)
+        >>> print(f"Detected {result.statistics.rays_detected} rays")
+        >>> print(f"Absorbed {result.statistics.rays_absorbed} rays")
+        >>> for name, count in result.detections_per_surface.items():
+        ...     print(f"  {name}: {count} hits")
+        """
+        orchestrator = self._get_orchestrator()
+
+        # Suppress Numba GPU under-utilization warnings (common with small batches)
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message=".*Grid size.*GPU under-utilization.*",
+                category=UserWarning,
+            )
+            return orchestrator.run(rays)
+
+    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).
+        """
+        orchestrator = self._get_orchestrator()
+
+        # Suppress Numba GPU under-utilization warnings (common with small batches)
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message=".*Grid size.*GPU under-utilization.*",
+                category=UserWarning,
+            )
+            return orchestrator.run_single_bounce(rays)

lsurf/sources/__init__.py

@@ -0,0 +1,128 @@
+# 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.
+
+"""
+Sources Module - Ray Generation for Raytracing
+
+This module provides ray source classes for generating initial ray conditions.
+Each source type generates rays with specific spatial and angular distributions.
+
+Available Sources
+-----------------
+RaySource : ABC
+    Abstract base class defining the source interface.
+PointSource
+    Isotropic point source emitting in all directions.
+CollimatedBeam
+    Parallel beam with uniform or Gaussian intensity profile.
+DivergingBeam
+    Beam with angular divergence (fiber output, LED).
+UniformDivergingBeam
+    Diverging beam with uniform solid angle distribution.
+GaussianBeam
+    Gaussian beam following paraxial optics.
+ParallelBeamFromPositions
+    Parallel rays from explicit position array (atmospheric studies).
+CustomRaySource
+    Fully customizable rays with per-ray position, direction,
+    wavelength, and intensity (chromatic dispersion, custom setups).
+
+Interface
+---------
+All sources implement the generate() method:
+
+>>> rays = source.generate()
+
+Returns a RayBatch with initialized positions, directions, wavelengths,
+and intensities.
+
+Examples
+--------
+>>> from surface_roughness.sources import CollimatedBeam, PointSource
+>>>
+>>> # Create a collimated laser beam
+>>> beam = CollimatedBeam(
+...     center=(0, 0, -10),
+...     direction=(0, 0, 1),
+...     radius=0.001,
+...     num_rays=10000,
+...     wavelength=633e-9,
+...     power=5e-3
+... )
+>>> rays = beam.generate()
+>>>
+>>> # Create an isotropic point source
+>>> point = PointSource(
+...     position=(0, 0, 0),
+...     num_rays=5000,
+...     wavelength=532e-9,
+...     power=1e-3
+... )
+>>> rays = point.generate()
+>>>
+>>> # Create parallel rays from explicit positions (for atmospheric studies)
+>>> import numpy as np
+>>> positions = np.array([
+...     [-1000, 0, 100],
+...     [-1000, 0, 200],
+...     [-1000, 0, 300],
+... ])
+>>> source = ParallelBeamFromPositions(
+...     positions=positions,
+...     direction=(1, 0, 0),
+...     wavelength=532e-9,
+... )
+>>> rays = source.generate()
+"""
+
+from .base import RaySource
+from .collimated import CollimatedBeam
+from .custom import CustomRaySource
+from .diverging import DivergingBeam
+from .gaussian import GaussianBeam
+from .parallel_from_positions import ParallelBeamFromPositions
+from .point import PointSource
+from .uniform_diverging import UniformDivergingBeam
+
+__all__ = [
+    # Base class
+    "RaySource",
+    # Concrete implementations
+    "PointSource",
+    "CollimatedBeam",
+    "DivergingBeam",
+    "UniformDivergingBeam",
+    "GaussianBeam",
+    "ParallelBeamFromPositions",
+    "CustomRaySource",
+]