L-SURF Documentation
====================

.. image:: _static/logo.jpg
   :alt: L-SURF Logo
   :align: center
   :width: 400px

**L-SURF** (Light Surface Reflections) is a GPU-accelerated physically-accurate raytracing framework
for simulating light-surface interactions with ocean wave surfaces.

.. image:: https://badge.fury.io/py/lsurf.svg
   :target: https://pypi.org/project/lsurf/
   :alt: PyPI version

.. image:: https://img.shields.io/badge/python-3.13+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python Version

.. image:: https://img.shields.io/badge/License-BSD--3--Clause--Clear-blue.svg
   :target: https://github.com/tobi-h/lsurf/blob/main/LICENSE
   :alt: License

Key Features
------------

* **Fresnel reflection and refraction** - Physically accurate polarization-dependent coefficients
* **Multiple scattering** - Multi-bounce ray tracing with intensity splitting
* **Ocean wave surfaces** - Gerstner wave modeling with curved Earth geometry
* **GPU acceleration** - CUDA-accelerated via Numba for high-performance simulations
* **Wavelength-dependent materials** - Sellmeier and Cauchy dispersion models
* **Polarization tracking** - s and p polarization component handling

Quick Start
-----------

Installation::

   pip install lsurf

Basic usage:

.. code-block:: python

   import lsurf as sr

   # Create a water surface
   surface = sr.PlanarSurface(
       point=(0, 0, 0),
       normal=(0, 0, 1),
       material_front=sr.AIR_STP,
       material_back=sr.WATER,
   )

   # Create a collimated beam
   source = sr.CollimatedBeam(
       center=(0, 0, 0.1),
       direction=(0.707, 0, -0.707),  # 45° incidence
       radius=0.01,
       num_rays=1000,
       wavelength=532e-9,
   )
   rays = source.generate()

   # Process reflection/refraction
   reflected, refracted = sr.process_surface_interaction(
       rays, surface,
       wavelength=532e-9,
       generate_reflected=True,
       generate_refracted=True,
   )

Table of Contents
-----------------

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   installation
   quickstart
   examples/index
   user_guide/index

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/index

.. toctree::
   :maxdepth: 1
   :caption: Development

   contributing
   changelog

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`