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.

• Example 01: Basic Raytracing
  • Overview
  • Key Concepts
  • Expected Output
  • Physics Validation
  • Running the Example
  • Exercises
  • See Also
• Example 06: Detector Scan (Planar Surface)
  • Overview
  • Geometry
  • Key Code Sections
  • Expected Output
  • Physics
  • Running the Example
  • Exercises
  • See Also
• Local Scale Ocean Wave Simulation
  • Overview
  • Key Features
  • Usage
  • Command-Line Arguments
  • Output Files
  • Example Output
  • Physics Background
  • See Also
• Production Ocean Wave Simulation
  • Overview
  • Differences from Local Simulation
  • Usage
  • Command-Line Arguments
  • Output Files
  • Performance Considerations
  • Batch Processing
  • Data Analysis Workflow
  • Combining Multiple Runs
  • Common Production Scenarios
  • Troubleshooting
  • See Also

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:

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