Overview

Rogue is a real-time physics-based rogue-wave predictor built on the mathematics of finite-time blow-up in the supercritical defocusing nonlinear Schrödinger equation (NLS). It replaces heuristic statistical methods with a deterministic symplectic solver.

Three access points — one engine:

• Browser — education dashboard + production forecast at rogue.jesed.dev/education (no install)
• CLI binary — download from GitHub Releases (Linux, macOS, Windows)
• Rust crate — cargo install --path . --root ~/.local

Mathematics

Governing equation

The solver integrates:

i ∂t ψ = −(β₂/2) ∇²ψ + γ |ψ|^(p−1) ψ

with Strang symplectic split-step — half-step dispersion, full-step nonlinearity, half-step dispersion. Unitary by construction, O(dt²) energy conservation.

Invariants

Blow-up detection

Virial evolution + H¹ acceleration tracking. The ETA fit uses y = a + bt = 1/‖∇ψ‖² — extrapolates the singularity time when H¹ → ∞. Works for the supercritical regime p > 5 (Merle–Raphael–Rodnianski–Szeftel 2026).

Benjamin–Feir instability

Rogue waves emerge from side-band instability of a uniform wave train:

γ(ν) = ν √(2A² − ν²)

Unstable for 0 < ν < √2·A. Maximum growth at ν = A. This is the physical mechanism behind Akhmediev breathers and the Peregrine soliton.

Architecture

Crate map

CLI usage

Install

# From GitHub Releases (no Rust needed)
curl -L https://github.com/jesedv/rogue/releases/download/v0.1.0/rogue -o rogue
chmod +x rogue
./rogue help

# From source
cargo install --path . --root ~/.local

Commands

Production mode

Production mode takes real, dimensional sea-state observations and runs the physical NLS forecast bridge. Input is a CSV or TSV with t, hs, tp (optional gamma).

The physical bridge derives:

Carrier frequency:  ω₀ = 2π / Tp
Wave number:       k₀ = ω₀² / g          (deep-water dispersion)
Dispersion:        β  = ω₀ / (8 k₀²)      [m²/s]
Nonlinearity:      γ  = ω₀ k₀² / 2        [/m·s]
Amplitude:         A  = Hs / 4
Steepness:         2A k₀
      

Output

Each observation produces a forecast with:

• Max crest factor — in units of σ (≥ 2.2 = rogue)
• Risk level — normal / elevated / high / severe
• Rogue events — time, position, crest factor, Hs in metres
• Conservation — mass / momentum / energy at final step

Connecting instruments

Any system that produces sea-state data can feed Rogue — wave buoys, shipboard radars, coastal stations, or a helmsman typing observations. All that matters is t, hs, tp.

Supported instrument types

Streaming feed

# Buoy / AIS / bridge writes observations to a rolling CSV
echo "0,4.0,11.0,3.3" > /var/feed/current.csv
rogue predict /var/feed/current.csv --json >> /var/log/rogue-alerts.json

Loop / cron

# Poll every 60 seconds — good for buoys and met stations
watch -n 60 'rogue predict /dev/stdin --json < /var/feed/current.csv'

systemd timer (production-grade)

[Unit]
Description=Rogue rogue-wave forecast

[Service]
Type=oneshot
ExecStart=/usr/local/bin/rogue predict /var/feed/current.csv --json

[Install]
WantedBy=timers.target

WebSocket bridge

socat TCP-LISTEN:8080,fork EXEC:'./rogue predict --json /dev/stdin'

Audit replay

Rogue is deterministic and seeded — replaying historical AIS / S-AIS logs produces identical alerts. Critical for post-voyage review, insurance claims, port-state inspections, and regulatory compliance (SOLAS, MARPOL).

Web dashboard

Education mode

Live interactive NLS simulation at /education. Explore six scenarios:

• Akhmediev breather — periodic modulation that amplifies sidebands
• Peregrine soliton — a single peak that "appears from nowhere and disappears without a trace"
• JONSWAP random sea — realistic ocean spectrum with rogue candidates
• Stokes + sidebands — Benjamin–Feir lab setup
• Soliton walk — stable solitary wave propagation
• Quintic blow-up — supercritical NLS with finite-time singularity

Controls: resolution (256→1024 grid points), speed multiplier (1×–8×), pause/reset. The canvas renders |ψ|² in real time with diagnostics — mass, momentum, energy, H¹ seminorm, kurtosis, and blow-up ETA.

Production mode

At /production, enter a real sea state (Hs, Tp, peak γ) and get a physical, dimensionality-correct forecast running in your browser via WASM. Same engine as the CLI — no server round-trip.

WASM size

The browser bundle is 262 kB (gzipped: ~98 kB). The hard constraint is ≤ 8 MB — verified at every build.

Download

Pre-built binaries for Linux x86-64 are attached to every GitHub Release. macOS and Windows binaries coming via CI.

curl -L https://github.com/jesedv/rogue/releases/download/v0.1.0/rogue -o rogue
chmod +x rogue
sudo mv rogue /usr/local/bin/
rogue predict sea.csv

The crates are published on crates.io — Rust users can also cargo install.

Contributing

Contributions welcome. Fork github.com/jesedv/rogue, branch from main, and send a PR.

Before pushing:

./dev check              # cargo check + cargo test --workspace
./dev regress            # physics regression suite
./dev regress-prod       # production CSV intake regression

Free software (MIT).