Propagation Module
==================

The propagation module provides ray propagation engines for tracing rays
through materials with varying refractive indices.

.. module:: lsurf.propagation

Overview
--------

The propagation system includes:

1. **Propagators** - Engines that advance rays through materials
2. **Kernels** - GPU-accelerated computation kernels
3. **Factory** - ``create_propagator()`` for automatic propagator selection

Propagators
-----------

GradientPropagator (CPU)
~~~~~~~~~~~~~~~~~~~~~~~~

CPU-based propagator for gradient index materials using RK4 integration.

.. autoclass:: lsurf.propagation.GradientPropagator
   :members:
   :undoc-members:

GPUGradientPropagator (GPU)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

GPU-accelerated propagator for gradient index materials.

.. autoclass:: lsurf.propagation.GPUGradientPropagator
   :members:
   :undoc-members:

Propagator Factory
------------------

.. autofunction:: lsurf.propagation.create_propagator

Usage Example
~~~~~~~~~~~~~

.. code-block:: python

   from lsurf.propagation import create_propagator, GPUMaterialID
   from lsurf.materials import ExponentialAtmosphere

   # Create material
   atmosphere = ExponentialAtmosphere(n_sea_level=1.000293)

   # Create propagator (auto-selects GPU if available)
   propagator = create_propagator(atmosphere)

   # Or explicitly request CPU
   from lsurf.propagation.kernels.registry import PropagatorID
   cpu_propagator = create_propagator(
       atmosphere,
       propagator_id=PropagatorID.CPU_GRADIENT
   )

Material IDs
------------

.. autoclass:: lsurf.propagation.GPUMaterialID
   :members:
   :undoc-members:

Kernel Registry
---------------

The kernel registry manages available propagation kernels:

.. automodule:: lsurf.propagation.kernels.registry
   :members: PropagationKernelID, IntersectionKernelID, PropagatorID

Available Kernels
~~~~~~~~~~~~~~~~~

**Propagation Kernels**

- ``SIMPLE_EULER`` - First-order Euler integration
- ``SIMPLE_RK4`` - Fourth-order Runge-Kutta integration
- ``SPECTRAL_EULER`` - Wavelength-dependent Euler
- ``SPECTRAL_RK4`` - Wavelength-dependent RK4
- ``GRID_EULER`` - Grid-based refractive index lookup (Euler)
- ``GRID_RK4`` - Grid-based refractive index lookup (RK4)

**Intersection Kernels**

- ``PLANE_ANALYTICAL`` - Analytical plane intersection
- ``SPHERE_ANALYTICAL`` - Analytical sphere intersection
- ``SDF_BISECTION`` - Signed distance function with bisection refinement

Architecture
------------

The propagation system follows a layered architecture:

1. **Simulation** calls **MaterialPropagator**
2. **MaterialPropagator** uses registered **Kernels** for:

   - Propagation (advancing rays)
   - Intersection (finding surface hits)
   - Detection (recording hits)

3. **Kernels** are GPU-accelerated via Numba CUDA

Device Functions
----------------

Low-level device functions used by GPU kernels:

.. automodule:: lsurf.propagation.kernels.device_functions
   :members:

Integration with Simulation
---------------------------

The ``Simulation`` class automatically creates and manages propagators:

.. code-block:: python

   from lsurf.simulation import Simulation, SimulationConfig

   # Simulation creates propagator internally
   config = SimulationConfig(use_gpu=True)  # Use GPU if available
   sim = Simulation(geometry, config)

   # Or force CPU-only
   config = SimulationConfig(use_gpu=False)
   sim = Simulation(geometry, config)