Weather Data Cycles

A complete reference for how wind, current, and wave data is downloaded, processed, and activated in FairWinds — from NOAA's servers to your boat.

Overview

There are three data types, each with their own sources, download windows, and go-live logic. The timing flows through two systems: the weather server (downloads and stores files) and the simulator/viewer (decides which file is "active" based on UTC time).

1. Wind (GFS)

1.1 Source & Format

• Model: NOAA GFS (Global Forecast System)
• Resolution: 0.25° (preferred) with 1.00° fallback
• Format: GRIB2, per-step files extracted to wind-only (U/V at 10m)
• Coverage: Up to 240 forecast hours (10 days)
• Storage: Supabase bucket gribs/gfs/0p25/{YYYYMMDD}/{HH}/steps/

1.2 NOAA Release Schedule

GFS runs 4 times per day. Files become available on NOMADS incrementally as steps finish computing:

1.3 Download Schedule (Cron)

The weather server polls NOMADS aggressively around each release window, with fallback sweeps:

All runs call run_getgribs_with_lock.sh — the lock prevents concurrent downloads.

1.4 Simulator Go-Live Logic

The simulator checks for a GRIB update at the top of each hour (when minutesUTC === 0 && secondsUTC === 0). It uses the following UTC-time-based mapping to decide which cycle should be active:

The simulator queries grib_log for the matching (forecast_date, forecast_hour, resolution='0p25') entry and downloads the T3 step files in parallel. If 0.25° is unavailable, it falls back to 1.00°.

1.5 Viewer (Frontend) Go-Live Logic

The viewer (weatherStore.js → windService.checkForUpdates) applies identical cutover logic. It compares the loadedForecastHour stored in windState against the expected forecast hour for the current UTC time. If they differ, it either:

1. Promotes the pre-loaded next-forecast reader (if already downloaded), or
2. Downloads the new cycle fresh from Supabase storage

The viewer also supports:

• Extended forecast (10-day, 1.00°, steps 036–240) — user-initiated, same cycle date/hour as the active base
• Next-forecast preview — loads the upcoming cycle 6h before it goes live, enables "bridging" mode where the reckoning line switches readers at the cutover time

1.6 Router Go-Live Logic

The router service polls POST /api/grib/refresh on its own schedule:

2. Ocean Currents

The simulator checks for current updates every hour (same minutesUTC === 0 check), then currentData.performScheduledUpdate() evaluates each active region independently based on its refreshHours schedule.

2.1 RTOFS (Western Atlantic)

2.2 SFBOFS (San Francisco Bay)

2.3 SSCOFS (Strait of Georgia)

2.4 IBI (English Channel / Copernicus)

2.5 Copernicus Global (Agulhas, East Australia, Kuroshio, Tasman)

3. Waves (GFS-Wave)

The simulator wave update fires at shouldUpdateWaves(currentHour) which returns true only when currentHour === 6. Outside 06Z, it still loads on first boot if no wave data is present.

4. Summary Timeline (Single UTC Day)

UTC    Event
----------------------------------------------------------------------
00:00  Wind: Sim switches → previous day 18Z cycle
00:00  Currents: Sim hourly check (all regions)
02:20  Cleanup: Old GRIB files purged
03:20  Cleanup: Old current files purged
03:31  NOAA: 00Z GFS f000 appears on NOMADS
03:40  Cron: Dense wind download window starts (every 2 min)
04:20  Cron: Dense wind download window ends
04:24  SFBOFS 03Z files land on S3
04:33  NOAA: 00Z GFS f240 (full 240h) typically available
04:45  Cron: SFBOFS 03Z first download attempt
05:00  Cron: SFBOFS 03Z second attempt; waves 00Z first attempt
05:00  Waves: 00Z run first download attempt
05:30  Waves: 00Z run second download attempt (retry)
06:00  Wind: Sim switches → today 00Z cycle  ← MAJOR CUTOVER
06:00  Waves: Sim goes live with today 00Z run
06:00  Currents: Sim switches SFBOFS → 03Z run
06:00  Currents: Sim switches RTOFS/IBI/Global → still yesterday (not 12Z yet)
06:50  SSCOFS 03Z data available on S3
07:05  Cron: SSCOFS download attempt 1
07:29  Cron: IBI + Copernicus Global download window (29/31/33/35/37 past)
08:05  Cron: SSCOFS last attempt
09:31  NOAA: 06Z GFS f000 on NOMADS
09:40  Cron: Dense wind download window starts
10:20  Cron: Dense wind download window ends
12:00  Wind: Sim switches → today 06Z cycle  ← MAJOR CUTOVER
12:00  Currents: Sim switches RTOFS/IBI/Copernicus → today 00Z run
15:31  NOAA: 12Z GFS f000 on NOMADS
15:40  Cron: Dense wind download window starts
16:20  Cron: Dense wind download window ends
16:23  SFBOFS 15Z files land on S3
16:45  Cron: SFBOFS 15Z first download attempt
17:15  Cron: SFBOFS 15Z last attempt
18:00  Wind: Sim switches → today 12Z cycle  ← MAJOR CUTOVER
18:00  Currents: Sim switches SFBOFS → 15Z run
21:31  NOAA: 18Z GFS f000 on NOMADS
21:40  Cron: Dense wind download window starts
22:20  Cron: Dense wind download window ends
24:00  (= 00:00 next day) Wind: Sim switches → today 18Z cycle

5. Discrepancies & Known Issues

Wind: Sim vs Viewer Timing

Both the simulator and viewer use identical UTC-hour-based logic:

• 00–05Z → prev day 18Z
• 06–11Z → today 00Z
• 12–17Z → today 06Z
• 18–23Z → today 12Z

The simulator triggers at exactly 00/06/12/18Z (top of hour). The viewer triggers on a checkForUpdates call from the race update loop, so it may lag by up to one 1-minute simulation cycle.

Forecasts.md Is Outdated

The public-facing forecasts.md page states that the simulator uses steps f006–f012 only. This is no longer accurate. The simulator and viewer now load all available steps from forecastStepMin to forecastStepMax (typically f006–f048 for base, f036–f240 for extended).

Wave Update Window

shouldUpdateWaves() hard-codes currentHour === 6. This means if the server restarts between 07Z and 23Z without wave data loaded, it will load whatever is available rather than waiting for 06Z. This is intentional fallback behavior.

Current Cutover Comment Mismatch

currentData.js line 145 says SFBOFS goes "live at 06Z and 18Z" — this matches the code logic (utcHour < 6 → prev day 15Z, utcHour < 18 → today 03Z, else → today 15Z). ✅ Consistent.

6. Code References