⚙️ Prediction Algorithms

The forecast system runs 8 core algorithm modules that transform raw sensor data into actionable session predictions. Each module is documented below with its inputs, logic, and outputs.

1. Wind Prediction

wind-prediction.mjs

The core wind forecast builds a per-hour prediction array by combining synoptic base wind with a thermal boost curve, modulated by cloud cover.

Synoptic Base Estimation

The synoptic base represents the "background" trade wind strength without any thermal effects. Estimated from three independent signals:

• Evening retention — wind speed after 6pm HST when thermals have died (pure synoptic)
• Upolu Airport — 100 miles upwind, no thermal contamination
• Buoy median — median of far-field NDBC buoys (51004, 51002, 51000)

Thermal Boost Model

The isthmus thermal adds wind on top of the synoptic base, following a predictable diurnal curve:

• Peak: 11:00–14:00 HST (maximum solar heating of the isthmus)
• Decay: Linear decline from 14:00 to zero by 19:00 HST
• Cloud modulation: Thermal boost is multiplied by (1 - cloud_cover_pct/100)

Taper Prediction

The output is an array of per-hour wind predictions across the session window. Each hour combines: synoptic_base + thermal_boost(hour) × cloud_modifier(hour). The array is used downstream for equipment sizing and session window scoring.

2. Isthmus Thermal Model

isthmus-thermal.mjs

Models the thermal drive created by differential heating of the Maui isthmus versus the surrounding ocean.

Weighted Heat Index

7 WeatherFlow stations across the isthmus are combined into a single heat index using weighted averaging. Higher-weighted stations (Hansen Rd at 1.5, Kahului Airport at 1.2) are more representative of the thermal core.

Land-Sea Differential

The primary thermal driver is the temperature difference between the isthmus and ocean:

thermal_drive = isthmus_temp_weighted_avg - ocean_SST_pauwela

Larger differential = stronger thermal wind acceleration through the isthmus.

Regime Classification

Venturi Detection

The isthmus acts as a venturi nozzle, compressing trade winds between Haleakala and the West Maui Mountains. Detected when:

Maalaea / Kanaha wind ratio > 0.8  →  venturi active

Active venturi means the isthmus compression is contributing to wind acceleration at Kanaha.

3. Windswell Analysis

windswell-analysis.mjs

Decomposes the wave field into windswell and groundswell components, then rates conditions for downwind foiling.

Swell Decomposition

NE Fetch Model

When wind direction is NE, the fetch along Maui's north shore is maximized, producing well-organized windswell bumps ideal for downwind foiling. The analysis considers:

• Period — longer period windswell (6-8s) = more organized bumps
• Height — 0.5-1.5m windswell = optimal bump size
• Direction — NE direction = long fetch = best bump organization

All three factors combine into a downwind foiling rating.

4. Equipment Recommendation

equipment-rec.mjs

Translates wind predictions and tide data into specific gear recommendations for each session window.

Gust Factor Logic

Mast Selection

Mast length is a safety-critical decision driven by reef depth during the session window:

reef_depth = 0.9m + (tide_ft × 0.3048)
safe_mast  = reef_depth - 0.15m clearance

The system iterates over the tide predictions during the session window and uses the minimum reef depth to select the appropriate mast (72cm, 85cm, 90cm, or 100cm).

Session Windows

Equipment recommendations are generated per 2-hour block within the day's session window. Each block gets its own wind prediction and may get different gear if conditions are expected to change significantly (e.g., early block uses 4.0m kite, later block uses 3.4m as thermal builds).

5. Rain & Precipitation

forecast-nws.mjs + pressure-meteo.mjs + buildPrecipSummary

Dual-source precipitation analysis combining NWS and Open-Meteo, with WMO weathercode shower detection and radar confirmation.

Dual-Source PoP

Probability of precipitation is averaged from both NWS gridpoint data and Open-Meteo forecasts. Neither source alone is reliable enough for Maui's microclimate.

Shower Detection

WMO weathercodes identify shower activity:

• Codes 80–82: Rain showers (slight/moderate/violent)
• Codes 85–86: Snow showers (rare at sea level)
• Codes 95–99: Thunderstorms

Rain Tier Classification

6. North Pacific Swell Propagation

north-pacific-swell.mjs

Physics-based swell propagation model that tracks North Pacific storms and predicts when their energy arrives at Maui's north shore.

Group Velocity

Swell energy travels at the group velocity, which depends on wave period:

Cg = g × T / (4π)   m/s

Longer period swell travels faster — a 16-second swell moves nearly twice as fast as an 8-second swell.

Travel Time

travel_time = distance_nm / (Cg × 1.944 kts)

Height Attenuation

Swell height decreases with distance from the storm as energy spreads radially:

height_at_maui ≈ height_at_source × 1/sqrt(distance_ratio)

Direction Filter

Only swell arriving from the NW-to-NE arc (270°–090° passing through north) activates the north shore. Swell from other directions is shadowed by the island.

Alert Levels

7. 3-Day Outlook

three-day-outlook.mjs

Extends the forecast window to 3 days with coarser granularity, focused on session planning and triage detection.

Per-Day Analysis

• Session window inference — automatically set by day of week (Mon-Thu 12-4pm, Fri 12-5pm, Sat 11-5pm, Sun 11-4pm)
• Rain risk — aggregated precipitation probability per day
• Swell level — predicted groundswell height and period per day

Triage Detection

The 3-day outlook identifies:

• Cancel days — days with heavy rain or pumping+ swell
• Storm duration — how many consecutive days are affected
• Next clear session — first available session after the weather clears

Wave Event Verdict

When a "cancel plans" swell is predicted within the 3-day window, the system issues a WAVE-EVENT verdict. This signals that conditions are exceptional enough to reorganize your schedule around the swell.

8. Gust Ratio Analysis

The gust-to-steady wind ratio is the primary condition quality indicator. It directly affects ride comfort and safety.