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