ocean-reflectivity-rfi

Satellite passive-sensor RFI analysis over the ocean: an ITU-R sea-surface EM library for Sionna RT, a scan-geometry + ray-tracing framework, and the study scripts that produce our results.

One repo, two installable packages (uv workspace), three doors:

1. ocean_reflectivity — sea-surface EM library (use this from any Sionna project)

ITU-R P.2146-0 sea-surface bistatic scattering as a Sionna RadioMaterialBase BSDF (packages/ocean-reflectivity/): pluggable physics models in the ITU γ convention, Meissner & Wentz 2004 permittivity, ITU-R RS.1813-2 dish patterns. Base install depends on NumPy only; everything DrJit/Sionna sits behind the [sionna] extra and lazy imports.

from ocean_reflectivity import create_sea_water_bistatic_material   # [sionna]
from ocean_reflectivity import rs1813_gain_db                       # pure NumPy
import ocean_reflectivity.antenna.sionna_rs1813                     # registers "itu_rs1813"

Physics conventions and validation: packages/ocean-reflectivity/src/ocean_reflectivity/bistatic/README.md, python -m ocean_reflectivity.validation.p2146_backscatter.

2. satrfi — RFI analysis framework

packages/satrfi/: conical-scan geometry and WGS84/ECEF frames (pure NumPy, satrfi.geometry), the Sionna RT simulation engine and Earth land/sea scenes (satrfi.backends.sionna), and plotting from NetCDF results (satrfi.plotting). Data/figure roots default to ./data and ./figures, overridable via OCEAN_RFI_DATA_DIR / OCEAN_RFI_RESULTS_DIR / OCEAN_RFI_FIG_DIR.

3. Reproduce the studies

git submodule update --init   # sionna-rt
uv sync                       # full dev env (Sionna; CUDA GPU for path tracing)

uv run pytest -q -m "not e2e"                                # fast test tier
uv run python -m satrfi.backends.sionna.simulation --los     # single run
uv run python -m scripts.batch_conical_scan                  # sweep → data/results/*.nc
uv run python -m scripts.batch_plot data/results/conical_scan-v2-*.nc

See CLAUDE.md for the full command and architecture reference.

Data

The public snapshot ships only the small inputs that pin the published orbit and scene; you regenerate everything else locally. Five git-tracked files live under data/: the simple_reflector scene (data/scenes/simple_reflector/, PLY + XML), two Celestrak TLE snapshots (data/tles/*.json), and one Skyfield-propagated trajectory (data/trajectories/GCOM-W1 (SHIZUKU)-*.csv). Together they fix the exact GCOM-W1 ground track and reflector geometry behind our results.

The bulk of data/ is git-ignored and rebuilt by the prep scripts: Earth meshes (data/meshes/, ~13M), simulation results (data/results/, ~88M), Natural Earth shapefiles (data/shapefiles/, ~42M), and the source vector bundle (data/50m_physical.zip, ~7.3M). Run every command from the repo root.

Earth meshes derive from the Natural Earth 1:50m land layer, so download that layer first. The per-layer land zip is the smallest input the mesh pipeline needs; unzip it into data/shapefiles/ne_50m_land/ to produce the exact path the pipeline reads (data/shapefiles/ne_50m_land/ne_50m_land.shp):

mkdir -p data/shapefiles/ne_50m_land
curl -L -o /tmp/ne_50m_land.zip \
  https://naciscdn.org/naturalearth/50m/physical/ne_50m_land.zip
unzip -o /tmp/ne_50m_land.zip -d data/shapefiles/ne_50m_land

Natural Earth data is public domain. The committed data/50m_physical.zip corresponds to the full 1:50m physical vectors bundle from naturalearthdata.com; download and unzip it the same way if you want every physical layer, though the mesh pipeline uses only ne_50m_land.

With the land layer in place, build the meshes at subdivision 7 (the engine's default; the script's own argparse default of 5 is coarser):

uv run python -m scripts.generate_earth_meshes -n 7 --validate

Regenerate the NetCDF results with the batch sweep. It runs Sionna RT path tracing and requires a CUDA-capable GPU:

uv run python -m scripts.batch_conical_scan   # writes data/results/*.nc

Regenerate a trajectory only for new scenarios. scripts.generate_trajectory fetches the current TLE from Celestrak and refuses any TLE older than one day, so re-running yields a different ground track than the shipped CSV. The committed TLE JSONs and trajectory CSV pin the published orbit; keep them to reproduce our results.

uv run python -m scripts.generate_trajectory

Related: the TEMPEST-H8 LoS RFI study (analytical, Sionna-free) lives in the sibling repo ../tempest-h8-rfi.