Examples
========

This section walks through the example applications included with L-SURF, demonstrating
key features and usage patterns.

All example scripts are located in the ``scripts/`` directory of the repository.

.. toctree::
   :maxdepth: 2

   01_basic
   06_detector_scan
   09_local_simulation
   10_production_simulation

Example Overview
----------------

+-----+-------------------------------+-----------------------------------------------+
| #   | Example                       | Description                                   |
+=====+===============================+===============================================+
| 01  | Basic Raytracing              | Introduction to core interfaces and workflow  |
+-----+-------------------------------+-----------------------------------------------+
| 02  | Ray Sources                   | Different source types and configurations     |
+-----+-------------------------------+-----------------------------------------------+
| 03  | Visualization                 | Plotting and visualization capabilities       |
+-----+-------------------------------+-----------------------------------------------+
| 04  | Glass Reflection              | Fresnel coefficients at glass interface       |
+-----+-------------------------------+-----------------------------------------------+
| 05  | Brewster Angle                | Validation of Brewster angle for water        |
+-----+-------------------------------+-----------------------------------------------+
| 06  | Detector Scan (Planar)        | Scanning detector positions on flat surface   |
+-----+-------------------------------+-----------------------------------------------+
| 07  | Detector Scan (Waves)         | Detector scanning with wave surface           |
+-----+-------------------------------+-----------------------------------------------+
| 08  | Large-scale Ocean             | Earth-scale ocean wave simulation             |
+-----+-------------------------------+-----------------------------------------------+
| 09  | Full 3D Curved Ocean          | Full 3D ray tracing with curved ocean surface |
+-----+-------------------------------+-----------------------------------------------+
| 10  | Time Spread Estimate          | Geometric time spread estimation              |
+-----+-------------------------------+-----------------------------------------------+
| --  | **run_local_simulation**      | **Local-scale ocean with polarization**       |
+-----+-------------------------------+-----------------------------------------------+
| --  | **run_production_simulation** | **Production ocean simulations at scale**     |
+-----+-------------------------------+-----------------------------------------------+

Running Examples
----------------

All examples can be run directly from the ``scripts/`` directory::

   cd scripts
   python 01_basic.py

Each example:

* Is self-contained and well-documented
* Generates plots in the ``plots/`` directory
* Includes detailed console output
* Can be customized by editing parameters

Output Files
------------

Examples generate various output files:

**Plots:** ``plots/XX_example_name.png``
   - Ray path visualizations
   - Statistical distributions
   - Angular/temporal measurements

**Data:** ``data/simulation_YYYYMMDD_HHMMSS.h5`` (example 08)
   - HDF5 files with complete ray history
   - Can be loaded for post-processing

Performance Notes
-----------------

GPU vs CPU
~~~~~~~~~~

The examples will automatically use GPU acceleration if available. To force CPU mode:

.. code-block:: python

   import os
   os.environ['NUMBA_DISABLE_JIT'] = '1'

Scaling
~~~~~~~

Most examples use small ray counts (100-5000) for quick execution. For production:

* Increase ``num_rays`` by 10-100x
* Enable GPU for best performance
* Monitor memory usage for very large simulations