API Reference
=============

Complete API documentation for all modules in L-SURF.

.. toctree::
   :maxdepth: 2

   geometry
   simulation
   materials
   sources
   surfaces
   detectors
   propagation
   interactions
   visualization
   utilities

Module Overview
---------------

Simulation Framework
~~~~~~~~~~~~~~~~~~~~

:doc:`geometry`
   GeometryBuilder for constructing simulation geometries with named media.

:doc:`simulation`
   Simulation class and SimulationConfig for running ray tracing simulations.

:doc:`propagation`
   Ray propagation engines including GPU-accelerated gradient propagators.

Core Modules
~~~~~~~~~~~~

:doc:`materials`
   Material property definitions including refractive indices, dispersion models,
   and atmospheric profiles.

:doc:`sources`
   Ray generation from various source types (point, collimated, diverging, gaussian).

:doc:`surfaces`
   Surface geometry and ray-surface intersection (planar, spherical, wave surfaces).

:doc:`detectors`
   Detection and analysis of rays at specified locations.

:doc:`interactions`
   High-level functions for processing ray-surface interactions.

:doc:`visualization`
   Plotting and visualization tools for ray paths, detections, and distributions.

:doc:`utilities`
   Supporting utilities for ray data structures and Fresnel calculations.

Quick Reference
---------------

Setting Up a Simulation
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import lsurf as sr
   from lsurf.geometry import GeometryBuilder
   from lsurf.simulation import Simulation, SimulationConfig
   from lsurf.surfaces import SphereSurface, PlaneSurface, SurfaceRole

   # Build geometry
   geometry = (
       GeometryBuilder()
       .register_medium("air", sr.AIR_STP)
       .register_medium("water", sr.WATER)
       .set_background("air")
       .add_surface(ocean_surface, front="air", back="water")
       .add_detector(detector_plane)
       .build()
   )

   # Configure and run
   config = SimulationConfig(step_size=100.0, max_bounces=5)
   sim = Simulation(geometry, config)
   result = sim.run(rays)

Creating Objects
~~~~~~~~~~~~~~~~

.. code-block:: python

   import lsurf as sr
   from lsurf.surfaces import SurfaceRole

   # Materials
   material = sr.WATER
   atmosphere = sr.ExponentialAtmosphere(n_sea_level=1.000293)
   custom = sr.create_sellmeier_material(B1=1.03961212, ...)

   # Sources
   source = sr.CollimatedBeam(center=(0,0,1), direction=(0,0,-1), ...)

   # Surfaces (with roles)
   surface = sr.PlaneSurface(
       point=(0,0,0), normal=(0,0,1),
       role=SurfaceRole.OPTICAL, name="surface"
   )

   # Detectors
   detector = sr.PlaneSurface(
       point=(0,0,10), normal=(0,0,1),
       role=SurfaceRole.DETECTOR, name="detector"
   )

Processing Results
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   result = sim.run(rays)

   # Access detected rays
   detected = result.detected
   print(f"Detected: {detected.num_rays}")
   print(f"Times: {detected.times}")
   print(f"Positions: {detected.positions}")

   # Statistics
   stats = result.statistics
   print(f"Rays detected: {stats.rays_detected}")
   print(f"Rays absorbed: {stats.rays_absorbed}")
   print(f"Bounces completed: {stats.bounces_completed}")

   # Per-detector breakdown
   for name, count in result.detections_per_surface.items():
       print(f"  {name}: {count}")

Simple Surface Interaction
~~~~~~~~~~~~~~~~~~~~~~~~~~

For quick tests without full simulation:

.. code-block:: python

   # Direct surface interaction
   reflected, refracted = sr.process_surface_interaction(
       rays, surface, wavelength=532e-9
   )

Visualization
~~~~~~~~~~~~~

.. code-block:: python

   from lsurf.visualization import (
       plot_ray_paths_projection,
       plot_detection_counts,
       create_detector_scan_figure,
   )

   fig = plot_ray_paths_projection(
       rays=initial_rays,
       reflected_rays=reflected,
       surface=surface,
   )

Logging
~~~~~~~

.. code-block:: python

   import lsurf as sr

   sr.configure_logging("INFO")   # Simulation summaries
   sr.configure_logging("DEBUG")  # Per-bounce details