lsurf 1.0.0__py3-none-any.whl

lsurf/__init__.py

@@ -0,0 +1,471 @@
+# 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.
+
+"""
+L-SURF: Light Surface Reflections
+
+A GPU-accelerated physically-accurate raytracing framework for simulating
+light-surface interactions with spatially-varying material properties.
+
+Note: Numba performance warnings about GPU under-utilization are suppressed
+by default. These warnings occur with small ray counts during testing but
+are not relevant for production simulations with larger ray counts.
+
+This module supports:
+- Inhomogeneous media with gradient refractive indices
+- Multiple scattering and subsurface propagation
+- Fresnel reflection and refraction
+- Wavelength-dependent material properties
+- Polarization tracking (optional)
+
+Main Components
+---------------
+- materials: Material property definitions (refractive index, absorption, etc.)
+- surfaces: Surface geometry and intersection (planar, spherical, waves)
+- sources: Ray generation (point, collimated, diverging, gaussian)
+- detectors: Detection and analysis (spherical, planar, directional)
+- ray_data: Ray batch data structures for GPU processing
+- propagation: Ray propagation engine (straight-line and curved paths)
+- gpu: GPU-accelerated kernels and algorithms
+
+Example Usage
+-------------
+>>> from surface_roughness import materials, ray_data, propagation
+>>>
+>>> # Create material
+>>> material = materials.AIR_STP
+>>>
+>>> # Create ray batch
+>>> rays = ray_data.create_ray_batch(num_rays=10000)
+>>>
+>>> # Initialize rays (would come from source module)
+>>> rays.positions[:] = ...
+>>> rays.directions[:] = ...
+>>> rays.active[:] = True
+>>>
+>>> # Propagate
+>>> propagator = propagation.StraightLinePropagator()
+>>> propagator.propagate_step(rays, step_size=1e-3, material=material)
+
+Refactored Modules (New Structure)
+----------------------------------
+The codebase has been refactored into single-responsibility modules:
+
+>>> # Modular surfaces
+>>> from lsurf.surfaces import CurvedWaveSurface, PlaneSurface
+>>>
+>>> # Modular sources
+>>> from surface_roughness.sources import CollimatedBeam, PointSource
+>>>
+>>> # Modular detectors
+>>> from surface_roughness.detectors import SphericalDetector
+>>>
+>>> # Modular materials
+>>> from surface_roughness.materials import WATER, create_sellmeier_material
+
+References
+----------
+.. [1] Born, M., & Wolf, E. (1999). Principles of Optics (7th ed.).
+       Cambridge University Press.
+.. [2] Ishimaru, A. (1978). Wave Propagation and Scattering in Random Media.
+       Academic Press.
+"""
+
+# =============================================================================
+# Suppress Numba Performance Warnings
+# =============================================================================
+# These warnings about GPU under-utilization are expected for small test cases
+# and are not relevant for production simulations with larger ray counts.
+import warnings
+
+try:
+    from numba.core.errors import NumbaPerformanceWarning
+
+    warnings.filterwarnings("ignore", category=NumbaPerformanceWarning)
+except ImportError:
+    # Numba not installed, no warnings to suppress
+    pass
+
+# =============================================================================
+# Module Imports (Refactored Structure)
+# =============================================================================
+# Refactored modules (new single-responsibility structure)
+from . import detectors, materials, sources, surfaces, utilities
+
+# Backward compatibility aliases for moved modules
+ray_data = utilities.ray_data
+propagation = utilities.propagation
+fresnel = utilities.fresnel
+recording_sphere = utilities.recording_sphere
+
+# Supporting modules
+from . import visualization
+
+# Backward compatibility alias for moved interactions module
+interactions = utilities.interactions
+
+# Key visualization functions
+from .visualization import (
+    create_beam_profile_figure,
+    create_detector_scan_figure,
+    create_ray_overview_figure,
+    create_wavelength_figure,
+    # Detector visualization
+    plot_beam_slice,
+    plot_bounce_points,
+    plot_detection_counts,
+    plot_detection_efficiency,
+    plot_mean_arrival_time,
+    plot_ray_endpoints_histogram,
+    plot_ray_endpoints_scatter,
+    # Ray tracing visualization
+    plot_ray_paths_projection,
+    plot_surface_profile,
+    plot_wavelength_histogram,
+)
+
+# Version info
+__version__ = "0.2.0"  # Refactored modular architecture
+__author__ = "L-SURF Development Team"
+
+# =============================================================================
+# Expose key classes from refactored modules
+# =============================================================================
+
+# Materials module
+# Analysis module
+from . import analysis
+
+# Detectors module
+from .detectors import (
+    DetectionEvent,
+    Detector,
+    DirectionalDetector,
+    LocalRecordingSphere,
+    LocalRecordingSphereDetector,
+    PlanarDetector,
+    RecordingSphere,
+    # Recording sphere detectors
+    RecordingSphereBase,
+    RecordingSphereDetector,
+    SphericalDetector,
+    compute_angular_distribution,
+    compute_intensity_distribution,
+    compute_time_distribution,
+    compute_wavelength_distribution,
+)
+from .detectors import (
+    compute_statistics as compute_detector_statistics,
+)
+
+# Interactions
+from .utilities.interactions import (
+    process_surface_interaction,
+    reflect_rays,
+    refract_rays,
+    trace_rays_multi_bounce,
+    trace_rays_with_splitting,
+)
+from .materials import (
+    AIR_STP,
+    BK7_GLASS,
+    VACUUM,
+    WATER,
+    HomogeneousMaterial,
+    MaterialField,
+    cauchy_refractive_index,
+    create_cauchy_material,
+    create_sellmeier_material,
+    sellmeier_refractive_index,
+    # Atmosphere materials
+    ExponentialAtmosphere,
+    STANDARD_ATMOSPHERE,
+    create_exponential_atmosphere,
+)
+
+# Sources module
+from .sources import (
+    CollimatedBeam,
+    DivergingBeam,
+    GaussianBeam,
+    ParallelBeamFromPositions,
+    PointSource,
+    RaySource,
+)
+
+# Surfaces module
+from .surfaces import (
+    EARTH_RADIUS,
+    CurvedWaveSurface,
+    GerstnerWaveParams,
+    GerstnerWaveSurface,
+    PlaneSurface,
+    SphereSurface,
+    RecordingSphereSurface,
+    LocalRecordingSphereSurface,
+    Surface,
+    SurfaceRole,
+    # Surface type registry
+    SurfaceTypeInfo,
+    register_surface_type,
+    get_surface_type,
+    get_surface_type_id,
+    is_gpu_capable,
+    list_surface_types,
+    # Backwards compatibility
+    GeometryInfo,
+    register_geometry,
+    get_geometry_id,
+)
+
+# Backwards compatibility alias
+PlanarSurface = PlaneSurface
+
+# Propagation
+from .utilities.propagation import (
+    PropagationConfig,
+    PropagationMode,
+    StraightLinePropagator,
+)
+from .propagation import (
+    GPUGradientPropagator,
+    GPUInhomogeneousPropagator,
+    GPUMaterialID,
+    GradientPropagator,
+    create_propagator,
+)
+
+# Ray data structures
+from .utilities.ray_data import (
+    RayBatch,
+    RayStatistics,
+    compute_statistics,
+    create_ray_batch,
+    merge_ray_batches,
+)
+
+# Recording data and I/O from utilities
+from .utilities.recording_sphere import (
+    RecordedRays,
+    load_recorded_rays_hdf5,
+    load_recorded_rays_numpy,
+    save_recorded_rays_hdf5,
+    save_recorded_rays_numpy,
+)
+
+__all__: list[str] = [
+    # ==========================================================================
+    # Refactored Modules
+    # ==========================================================================
+    "materials",
+    "ray_data",
+    "propagation",
+    "sources",
+    "surfaces",
+    "fresnel",
+    "interactions",
+    "visualization",
+    "detectors",
+    "recording_sphere",
+    "analysis",
+    # Material classes
+    "MaterialField",
+    "HomogeneousMaterial",
+    "VACUUM",
+    "AIR_STP",
+    "WATER",
+    "BK7_GLASS",
+    "sellmeier_refractive_index",
+    "cauchy_refractive_index",
+    "create_sellmeier_material",
+    "create_cauchy_material",
+    # Ray data structures
+    "RayBatch",
+    "RayStatistics",
+    "create_ray_batch",
+    "compute_statistics",
+    "merge_ray_batches",
+    # Propagation
+    "PropagationMode",
+    "PropagationConfig",
+    "StraightLinePropagator",
+    "GradientPropagator",
+    "GPUGradientPropagator",
+    "GPUInhomogeneousPropagator",
+    "GPUMaterialID",
+    "create_propagator",
+    # Sources
+    "RaySource",
+    "PointSource",
+    "CollimatedBeam",
+    "DivergingBeam",
+    "GaussianBeam",
+    "ParallelBeamFromPositions",
+    # Surfaces
+    "Surface",
+    "SurfaceRole",
+    "SurfaceTypeInfo",
+    "register_surface_type",
+    "get_surface_type",
+    "get_surface_type_id",
+    "is_gpu_capable",
+    "list_surface_types",
+    # Backwards compatibility
+    "GeometryInfo",
+    "register_geometry",
+    "get_geometry_id",
+    "PlaneSurface",
+    "PlanarSurface",  # Backwards compatibility alias
+    "SphereSurface",
+    "RecordingSphereSurface",
+    "LocalRecordingSphereSurface",
+    "GerstnerWaveSurface",
+    "GerstnerWaveParams",
+    "CurvedWaveSurface",
+    "EARTH_RADIUS",
+    # Interactions
+    "process_surface_interaction",
+    "reflect_rays",
+    "refract_rays",
+    "trace_rays_multi_bounce",
+    "trace_rays_with_splitting",
+    # Detectors
+    "Detector",
+    "SphericalDetector",
+    "PlanarDetector",
+    "DirectionalDetector",
+    "DetectionEvent",
+    "compute_angular_distribution",
+    "compute_time_distribution",
+    "compute_intensity_distribution",
+    "compute_wavelength_distribution",
+    "compute_detector_statistics",
+    # Recording sphere detectors
+    "RecordingSphereBase",
+    "RecordingSphereDetector",
+    "LocalRecordingSphereDetector",
+    "RecordingSphere",
+    "LocalRecordingSphere",
+    "RecordedRays",
+    "save_recorded_rays_hdf5",
+    "load_recorded_rays_hdf5",
+    "save_recorded_rays_numpy",
+    "load_recorded_rays_numpy",
+    # Visualization
+    "plot_ray_paths_projection",
+    "plot_ray_endpoints_scatter",
+    "plot_ray_endpoints_histogram",
+    "plot_surface_profile",
+    "plot_bounce_points",
+    "create_ray_overview_figure",
+    "plot_beam_slice",
+    "plot_wavelength_histogram",
+    "plot_detection_counts",
+    "plot_detection_efficiency",
+    "plot_mean_arrival_time",
+    "create_wavelength_figure",
+    "create_beam_profile_figure",
+    "create_detector_scan_figure",
+    # Logging
+    "configure_logging",
+]
+
+
+# =============================================================================
+# Logging Configuration
+# =============================================================================
+
+
+def configure_logging(
+    level: str = "INFO",
+    format: str = "%(levelname)s - %(message)s",
+    suppress_numba: bool = True,
+) -> None:
+    """
+    Configure logging for lsurf simulations.
+
+    Parameters
+    ----------
+    level : str
+        Logging level: "DEBUG", "INFO", "WARNING", "ERROR".
+        DEBUG shows per-bounce details, INFO shows simulation summaries.
+    format : str
+        Log message format string.
+    suppress_numba : bool
+        If True, suppress verbose numba/CUDA logging and performance warnings
+        (default True). Set to False to see GPU under-utilization warnings
+        which can help optimize ray counts.
+
+    Examples
+    --------
+    >>> import lsurf as sr
+    >>> sr.configure_logging("INFO")  # Show simulation progress
+    >>> sr.configure_logging("DEBUG")  # Show detailed per-bounce info
+    >>> sr.configure_logging("INFO", suppress_numba=False)  # Show GPU warnings
+    """
+    import logging
+    import warnings
+
+    # Configure lsurf logger
+    lsurf_logger = logging.getLogger("lsurf")
+    lsurf_logger.setLevel(getattr(logging, level.upper()))
+
+    # Add handler if none exists
+    if not lsurf_logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(format))
+        lsurf_logger.addHandler(handler)
+    else:
+        # Update existing handler format
+        for handler in lsurf_logger.handlers:
+            handler.setFormatter(logging.Formatter(format))
+
+    # Handle numba loggers and warnings
+    if suppress_numba:
+        for name in ["numba", "numba.cuda"]:
+            logging.getLogger(name).setLevel(logging.WARNING)
+        # Suppress numba performance warnings (already done at import, but ensure)
+        try:
+            from numba.core.errors import NumbaPerformanceWarning
+
+            warnings.filterwarnings("ignore", category=NumbaPerformanceWarning)
+        except ImportError:
+            pass
+    else:
+        # Re-enable numba performance warnings if user wants them
+        try:
+            from numba.core.errors import NumbaPerformanceWarning
+
+            warnings.filterwarnings("default", category=NumbaPerformanceWarning)
+        except ImportError:
+            pass

lsurf/analysis/__init__.py

@@ -0,0 +1,107 @@
+# 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.
+
+"""
+Analysis Module - Sphere Pattern Analysis and Visualization
+
+This module provides tools for analyzing ray patterns on spherical detection surfaces,
+including HEALPix mapping, intensity distribution analysis, and arrival time statistics.
+
+Available Functions
+-------------------
+rays_to_healpix
+    Convert recorded rays to HEALPix pixel representation
+aggregate_healpix_data
+    Aggregate ray properties per HEALPix pixel
+identify_peak_region
+    Find pixels with highest intensity
+compute_time_statistics
+    Compute arrival time statistics in peak region
+
+plot_mollweide_intensity
+    Visualize intensity distribution on Mollweide projection
+plot_mollweide_time
+    Visualize arrival time distribution on Mollweide projection
+plot_time_distributions
+    Plot arrival time histograms and statistics
+plot_combined_analysis
+    Create comprehensive multi-panel figure
+
+Examples
+--------
+>>> from lsurf import load_recorded_rays_hdf5
+>>> from lsurf.analysis import rays_to_healpix, plot_mollweide_intensity
+>>>
+>>> # Load simulation data
+>>> rays, metadata = load_recorded_rays_hdf5('simulation.h5')
+>>>
+>>> # Convert to HEALPix
+>>> healpix_data = rays_to_healpix(rays, nside=128)
+>>>
+>>> # Visualize
+>>> plot_mollweide_intensity(healpix_data, output='intensity_map.png')
+"""
+
+from .healpix_utils import (
+    aggregate_healpix_data,
+    compute_time_statistics,
+    identify_peak_region,
+    rays_to_healpix,
+)
+from .sphere_viz import (
+    plot_2d_combined,
+    plot_2d_intensity,
+    plot_2d_time,
+    plot_combined_analysis,
+    plot_mollweide_intensity,
+    plot_mollweide_time,
+    plot_ray_direction_intensity,
+    plot_time_distributions,
+    plot_viewing_angle_intensity,
+)
+
+__all__ = [
+    "rays_to_healpix",
+    "aggregate_healpix_data",
+    "identify_peak_region",
+    "compute_time_statistics",
+    "plot_mollweide_intensity",
+    "plot_mollweide_time",
+    "plot_time_distributions",
+    "plot_combined_analysis",
+    "plot_2d_intensity",
+    "plot_2d_time",
+    "plot_2d_combined",
+    "plot_viewing_angle_intensity",
+    "plot_ray_direction_intensity",
+]