Local Scale Ocean Wave Simulation =================================== The ``run_local_simulation.py`` script performs ray tracing simulations on ocean wave surfaces with a local recording sphere geometry. This is ideal for studying ray reflection patterns, arrival time distributions, and angular scattering from wave surfaces at moderate scales (tens of kilometers). Overview -------- This simulation features: * **Local coordinate system** - Recording sphere centered at the origin * **Configurable wave surfaces** - Single or multiple Gerstner wave components * **Flexible beam types** - Collimated (parallel) or diverging beams * **Comprehensive visualization** - 8 output figures including statistics and analysis * **High-resolution timing** - Nanosecond-scale arrival time distributions * **Angular analysis** - Ray direction binning with intensity-weighted histograms Key Features ------------ **Wave Surface** - Curved Earth geometry with Gerstner waves - Configurable amplitude, wavelength, and steepness - Single wave or multi-component ocean spectrum **Source Configuration** - **Collimated beam**: Parallel rays with specified radius - **Diverging beam**: Cone of rays with configurable opening angle - Positioned at 2 km altitude, aimed at surface origin - Automatic geometry calculation for grazing angles **Recording Sphere** - Local sphere centered at (0, 0, 0) - Default 33 km radius - Captures all upward-reflected rays - Records position, direction, time, and intensity **Output Products** 1. Overview plot (ray paths and surface interaction) 2. Statistics figure (6-panel analysis) 3. Intensity vs angle (log scale) 4. Intensity vs angle (linear scale) 5. Intensity density (log scale, ns⁻¹) 6. Intensity density (linear scale, ns⁻¹) 7. 3D scatter plot 8. Energy conservation check 9. HDF5 data file with complete ray information Usage ----- Basic usage with default parameters:: python run_local_simulation.py --num-rays 50000 Common configurations: **Small grazing angle (5°) with collimated beam**:: python run_local_simulation.py \ --num-rays 50000 \ --grazing-angle 5 \ --beam-type collimated \ --beam-radius 100 \ --wave-amplitude 1.0 \ --wave-wavelength 50 **Larger grazing angle (85°) with diverging beam**:: python run_local_simulation.py \ --num-rays 500000 \ --grazing-angle 85 \ --beam-type diverging \ --divergence-angle 0.5 \ --wave-amplitude 2.0 \ --wave-wavelength 100 Command-Line Arguments ---------------------- **Wave Parameters** ``--wave-amplitude FLOAT`` Wave amplitude in meters (default: 1.0) ``--wave-wavelength FLOAT`` Wave wavelength in meters (default: 50.0) ``--wave-steepness FLOAT`` Wave steepness parameter 0-1 (default: 0.5) ``--num-wave-components INT`` Number of wave components for realistic ocean (default: 3) ``--wave-time FLOAT`` Time for wave animation in seconds (default: 0.0) **Beam Parameters** ``--num-rays INT`` Number of rays to trace (default: 10,000) ``--beam-radius FLOAT`` Beam radius in meters for collimated beam (default: 100.0) ``--grazing-angle FLOAT`` Grazing angle from horizontal in degrees (default: 10.0) ``--wavelength FLOAT`` Optical wavelength in meters (default: 532e-9 for green) ``--beam-type {collimated,diverging}`` Beam type: parallel rays or diverging cone (default: diverging) ``--divergence-angle FLOAT`` Half-angle for diverging beam in degrees (default: 0.5) **Recording Parameters** ``--recording-altitude FLOAT`` Recording sphere altitude/radius in meters (default: 33,000) **Tracing Parameters** ``--max-bounces INT`` Maximum surface bounces (default: 10) ``--min-intensity FLOAT`` Minimum intensity threshold (default: 1e-10) **Output Parameters** ``--output-dir STR`` Output directory for HDF5 files (default: "data") ``--plot-dir STR`` Output directory for plots (default: "plots") ``--tag STR`` Optional tag for output filenames Output Files ------------ **Data Files** ``data/local_simulation_TIMESTAMP.h5`` HDF5 file containing: - Original ray batch (source) - Reflected ray batch - Refracted ray batch - Recorded rays at detection sphere - Complete ray history with positions, directions, times, intensities **Visualization Plots** ``plots/local_simulation_TIMESTAMP_overview.png`` Two-panel figure showing: - Left: Full-scale ray paths (X-Z plane) with Earth curvature, recording sphere - Right: Zoomed surface interaction with hit points and reflection vectors ``plots/local_simulation_TIMESTAMP_statistics.png`` Six-panel analysis figure: - Ray angle from horizontal distribution - Azimuth angle distribution - Arrival time distribution (log scale) - Intensity distribution - Intensity vs time by angle bin - 2D angular distribution heatmap ``plots/local_simulation_TIMESTAMP_intensity_angle_log.png`` Dedicated plot showing normalized intensity fraction vs arrival time, color-coded by ray angle bins. Logarithmic time scale (10 ps to 10 μs). ``plots/local_simulation_TIMESTAMP_intensity_angle_linear.png`` Same as log version but with linear time scale (1 ns bins). ``plots/local_simulation_TIMESTAMP_intensity_angle_log_density.png`` Intensity density (ns⁻¹) vs arrival time, logarithmic scale. Shows intensity per unit time normalized by incident power. ``plots/local_simulation_TIMESTAMP_intensity_angle_linear_density.png`` Density plot with linear time scale. ``plots/local_simulation_TIMESTAMP_3d.png`` 3D scatter plot of recorded ray positions at the detection sphere, color-coded by intensity. ``plots/local_simulation_TIMESTAMP_energy.png`` Energy conservation check showing: - Bar chart: Input, reflected, refracted, and recorded intensities - Text summary: Ray counts, efficiencies, and simulation parameters Example Output -------------- Running a typical simulation:: $ python run_local_simulation.py --num-rays 50000 --grazing-angle 5 \ --beam-type collimated --beam-radius 100 ====================================================================== Local Scale Ocean Wave Ray Tracing Simulation ====================================================================== Timestamp: 20260104_122100 Configuration: Wave amplitude: 1.00 m Wave wavelength: 50.0 m Wave steepness: 0.50 Wave components: 3 Beam rays: 50,000 Beam radius: 100.0 m Grazing angle: 5.0° Recording altitude: 33.0 km Creating curved wave surface... Single wave mode (amplitude=1.00 m, wavelength=50.0 m) Max wave height: 1.00 m Generating rays... Beam type: Collimated (parallel rays) Generated 50,000 rays Total input intensity: 1.0000 Processing single-bounce reflection/refraction... Reflected rays: 49,995 (intensity: 0.3787) Refracted rays: 49,995 (intensity: 0.6212) Upward-going rays: 49,142 Recording rays at detection sphere... Recorded rays: 49,142 Recorded intensity: 0.3643 Time range: 186.46 to 186.82 μs Creating visualization figures... [8 plots generated] ====================================================================== SIMULATION COMPLETE ====================================================================== Recording efficiency: 36.43% Physics Background ------------------ **Normalization** Intensity plots are normalized by total incident power, giving the fraction of input power in each time/angle bin. This accounts for overall reflection efficiency and allows comparison across different conditions. **Time Binning** - Logarithmic: 100 bins from 10 ps to 10 μs - Linear: 1 ns bins - Per-bin time subtraction: Each angle bin's earliest arrival set to t=0 **Angular Binning** Rays are binned by their direction angle relative to horizontal (z=0 plane) at the origin. Typically 15-20 bins spanning the full elevation range. **Density Normalization** Density plots divide by time bin width to give intensity per nanosecond, useful for comparing bins of different widths (especially in log scale). See Also -------- - :doc:`10_production_simulation` - Production-scale version with extended geometry - :doc:`06_detector_scan` - Detector scanning examples - :doc:`user_guide/physics` - Physical models and validation