Resumo da Metodologia
O Swellwise assenta numa abordagem física e probabilística rigorosa, desenvolvida para dar aos praticantes de surf uma leitura fiel da costa portuguesa. Os nossos quatro princípios fundamentais:
- Valores modelados ao largo (Offshore): As previsões de altura significativa (Hs), período e direção são obtidas de modelos numéricos globais de alta resolução (Open-Meteo). Estes valores representam o estado do mar em águas profundas ao largo e não a face da onda ao quebrar na bancada da praia.
- Combinação de Ondulações (Swell Efetivo - WM-11): O mar raramente é composto por uma única vaga. Quando existem ondulações primárias, secundárias ou terciárias (por exemplo, um swell de fundo de SO com vento de NO), o Swellwise calcula a energia transmitida em função da orientação geográfica e da janela de exposição da praia, combinando as energias (quadrado da altura) de forma fisicamente consistente.
- Concordância entre Modelos e Confiança (WM-13): Em vez de apresentarmos uma certeza artificial, comparamos em tempo real modelos independentes (ECMWF WAM e NCEP GFS-Wave). Quanto maior a dispersão entre eles, menor o índice de confiança, acompanhando o aumento natural da incerteza com a distância no tempo.
- Predição Local de Marés (FES2022 - WM-14): As marés utilizam a solução oceânica harmónica FES2022 com 34 constituintes astronómicos referenciados ao Zero Hidrográfico (ZH) do Instituto Hidrográfico de Portugal. Nas praias situadas em estuários ou lagoas, a predição é devidamente identificada como aproximada.
Princípio de Honestidade Swellwise: Nunca apresentamos valores modelados como se fossem medições reais na praia. Um spot só é identificado como “Ao vivo · Calibrado” quando o multiplicador de altura local foi revisto a partir de observações suficientes. Quando apenas a orientação e a exposição da praia foram revistas, surge como “Ao vivo · Geometria revista”. Sem qualquer revisão local, é claramente identificado como “Ao vivo · Por calibrar”.
Especificação Técnica Completa (Forecast Quantities & Model)
Forecast quantities
Significant wave height
significantHeightM is the model's total significant wave height (Hs): a statistical sea-state measure, roughly associated with the average of the highest third of waves. It combines swell and locally generated wind sea. It is not the height of each wave and is not a breaking-wave-face prediction.
Swell height
A swell partition isolates wave energy travelling with a broadly shared direction and period. Open-Meteo exposes primary, and for some models secondary and tertiary, swell partitions. Their significant heights do not combine by simple addition because wave energies scale with height squared. Missing partitions remain null.
Wave period
wave_period and partition periods describe representative time between waves. Longer-period swell carries more power for the same height and generally feels more energetic at the coast. The implementation uses the available period as an approximation for energy period (Te).
Peak period
Peak period is the period at the strongest spectral-energy peak. It can differ from mean period. It is displayed separately and is not silently substituted when a provider supplies no mean period.
Energy density — kJ/m²
The requested prototype convention is E = ρgHs²/8, with seawater density 1025 kg/m³ and gravity 9.81 m/s². It describes forecast wave energy per horizontal sea-surface area. Some wave-spectrum references use ρgHs²/16; the app follows the supplied product equation deliberately and documents the convention to prevent silent comparison errors.
Wave power — kW/m
Deep-water flux is P = ρg²Hs²Te/(64π). It estimates energy crossing each metre of wave crest per second. Because true energy period is unavailable, the provider's available representative period approximates Te. It is not measured coastal power.
Effective spot energy
Partition power multiplied by spotExposureFactor is the architecture's directional-exposure hook. Milfontes currently uses 1.0 because a defensible break-specific exposure model has not been established. The interface therefore labels it Offshore forecast energy. It does not claim energy at the breaking wave.
Effective swell for the surf score (WM-11)
The surf score no longer reads the primary swell partition alone. effectiveSwell in src/lib/forecast/surfScore.ts combines the primary, secondary and tertiary partitions that have a height:
- Transmission
fi: when the spot has aswellWindoworidealSwellDirectionDeg,fiiscalculateDirectionalTransmissionfromsrc/server/forecast/estimator/directionalDecay.tsfor the partition direction (1 when the direction is unknown). Without directional metadatafi = 1. - Scoring partition: the partition with the most transmitted energy
Hi² · Ti · fi. Its period feeds the period factor and its direction feeds the direction factor. Partitions without a period cannot be chosen unless none has one. - Effective height:
H_eff = sqrt(Σ Hi² · wi)withwi = min(1, fi / f_scoring). Heights combine through energy (height squared), not addition.
Transmission is applied relative to the scoring partition rather than as the raw fi. With raw fi, a lone primary partition at any spot with a swell window would shrink to H · sqrt(f), changing every existing score and counting exposure twice, because the direction factor already scores the scoring partition's exposure. With the relative weight a lone partition keeps its height, so primary-only hours score exactly as before (tests/wm-11-effective-swell.test.ts). A partition that is less exposed than the scoring partition contributes in proportion to its relative transmission.
Example: at a spot open from 180° to 270°, a 1.5 m 7 s NW windswell (315°, f = 0.04) under a 0.8 m 14 s SW groundswell (225°, f = 1.0) scores on the groundswell: period 14 s, direction 225°, H_eff = sqrt(0.8² + 1.5² · 0.04) ≈ 0.85 m.
Locally generated wind sea is not a partition here; the wind factor already scores local wind. The chosen partition, its transmission, each partition's weight and H_eff are returned as surf.effectiveSwell on every forecast hour, and recommendation windows summarise them as evidence.effectiveSwellHeight and evidence.scoringPartition for the evidence drawer. All inputs are modelled offshore values; this is not a nearshore transformation.
Offshore height bands per exposure class (WM-12)
The height factor compares the effective offshore swell height with a band: below idealMinM it rises linearly from zero, inside idealMinM–idealMaxM it is 1, and above idealMaxM it falls linearly to zero at excessiveM. Above idealMaxM the same factor also multiplies the whole score, so long period or light wind cannot rescue oversized swell.
SURF_SCORE_CONFIG.heightBands holds one band per exposure class:
| Exposure class | Ideal offshore height | Zero at |
|---|---|---|
open | 1.2–2.2 m | 4.5 m |
semi-sheltered | 1.6–2.8 m | 5.5 m |
sheltered | 2.0–3.5 m | 6.5 m |
resolveHeightBand in src/lib/forecast/surfScore.ts picks the band from the spot's exposure evidence:
- No reviewed exposure evidence, or no recognised
exposureClass:open,source: "default". This is the band every spot used before WM-12, so unreviewed spots score exactly as before. - Reviewed
exposureClass: that class's band,source: "exposure_class". - Reviewed
heightBandMwith finite0 < idealMinM < idealMaxM < excessiveM ≤ 15: that band,source: "spot_evidence". An invalid band is ignored and the class default applies.
Candidate or unresolved evidence never changes the band. The semi-sheltered and sheltered bands are provisional heuristics: sheltered coasts receive less of the offshore energy, so they need more offshore swell before they work and close out later. Replace them with per-spot bands as local reviews are signed off. Bands describe modelled offshore Hs, not breaking-face height.
The forecast service adds the resolved band to every response as spot.heightBand, and recommendation windows copy it to evidence.heightBand, which the evidence drawer shows with its source.
The local-estimator pilot (ENABLE_LOCAL_WAVE_ESTIMATOR) is separate from these bands. Its shoaling term in src/server/forecast/estimator/shoaling.ts, (T/10)^0.3 with extra dissipation below 6 s, is an empirical period power law. It is not linear-theory shoaling and has no depth term.
Confidence from model spread (WM-13)
Before WM-13, surf.confidence was a data-quality heuristic: field coverage times a horizon decay, capped at 0.8 (surf.confidenceBasis: "data_quality_heuristic"). It said nothing about whether the forecast itself was uncertain.
OpenMeteoMarineProvider now makes one extra request for wave_height and wave_period from two wave models, in parallel with the unchanged best_match request and inside the same provider slot of the forecast service semaphore:
| Model | Run | Resolution |
|---|---|---|
ecmwf_wam025 | ECMWF WAM | 0.25° |
ncep_gfswave025 | NCEP GFS-Wave | 0.25° |
MeteoFrance WAM is deliberately not in the set: at the Portuguese pilot spots Open-Meteo's best_match resolved to meteofrance_wave (identical values in a live probe on 2026-09-15), so including it would count one model twice and fake agreement. Open-Meteo suffixes variables with _<model> when several models are requested; the provider stores them as wave_height@<model> and wave_period@<model> in the marine series and lists the models that returned heights in ensembleModels.
For each hour, computeModelSpread (src/lib/forecast/modelSpread.ts) takes every model with a wave height (best_match plus the ensemble) and reports min, max, mean and spread (max − min) for height and, when at least two models have one, mean period. With at least two models, modelSpreadConfidence replaces the heuristic:
- height disagreement
dH = min(1, (spreadH / max(meanH, 0.5 m)) / 0.6); - period disagreement
dT = min(1, (spreadT / max(meanT, 4 s)) / 0.5); - disagreement
d = 0.7 · dH + 0.3 · dT(height alone when no period spread); - confidence
= 0.95 · (1 − d) · max(0.2, 1 − horizonHours / 240), clamped to [0, 0.95] and rounded to three decimals.
The floors stop half-metre seas and short periods from producing huge relative spreads, and the horizon decay is the same one the heuristic uses. The hour then carries surf.confidenceBasis: "model_spread" and surf.modelSpread (models, height and period summaries) for the evidence drawer. When fewer than two models cover an hour, including when the ensemble request fails (a provider warning is added), the heuristic and data_quality_heuristic basis apply unchanged.
Agreement between wave models is still not a measured probability: all three can share the same wind forcing error, and none of them sees the beach. Recommendation windows keep their contract basis data_quality_heuristic for now.
Cost: a normal refresh is three HTTP calls per spot (weather, marine best_match, marine ensemble). Retries happen only when a request fails. The per-spot cache TTL stays 45 minutes (FORECAST_CACHE_TTL_MS).
Breaking-wave and surf height
Breaking height depends on bathymetry, depth, refraction, shoaling, breaking criterion, tide, currents and local shelter. Offshore Hs cannot provide it alone. “Relative forecast size” currently compares offshore Hs with an editable human height to preserve the prototype's intuitive visual; its wording explicitly avoids calling this wave-face height. A future nearshore transformation model can replace this isolated calculation.
Tide in the score (T2, WM-16)
The tide factor only affects a spot's score when the spot has a reviewed tide rule. A rule is a reviewed tide_suitability evidence row whose value is { "datum": "ZH", "preferredStages": [...], "avoidStages": [...] }, using the stages low, mid_rising, high and mid_falling, with a named source and a reviewer (resolveReviewedTideRule in src/server/forecast/tides/spotTideRules.ts). Legacy { "datum": "MSL", "suitability": ... } rows, candidate rows and rules without a source or reviewer are ignored. The stage for each hour is the predicted astronomical stage from T1, so a rule has no effect at a spot the predictor does not cover.
With a rule and a predicted stage, the tide factor is 1 for a preferred stage, 0 for an avoided stage and 0.5 otherwise, and the weights change from the defaults to TIDE_RULE_WEIGHTS: tide rises from 0.01 to 0.10 and the other four are multiplied by 0.90 / 0.99 so the total stays 1. Without a rule, or without a predicted stage, nothing changes: the factor stays the neutral 0.5 (or null without modelled sea level) at weight 0.01. tests/t2-tide-weight.test.ts checks every bootstrap spot against a score snapshot taken before the change.
Each rule-scored hour carries surf.tideRule (stages, source, reviewer, review time, the hour's stage, factor and weight), and a recommendation window that contains such hours reports evidence.tideRule with hoursApplied instead of the no_tide_rule limitation.
Worked example, Carcavelos with the rule prefer low and mid_rising, avoid high, for one hour with 1.6 m of effective swell at 7 s from 210° and an 18 kn offshore wind (factors: height 1, period 0.2, wind 0.496, direction 0.985):
| Case | Weights (height, period, wind, direction, tide) | Tide factor | Score |
|---|---|---|---|
| No rule | 0.34, 0.25, 0.29, 0.11, 0.01 | null (no modelled sea level) | 0.34 + 0.05 + 0.1438 + 0.1083 + 0 = 0.642 → 6.4 |
Rule, stage low | 0.3091, 0.2273, 0.2636, 0.10, 0.10 | 1 | 0.3091 + 0.0455 + 0.1308 + 0.0985 + 0.10 = 0.684 → 6.8 |
Rule, stage mid_falling | same | 0.5 | 0.634 → 6.3 |
Rule, stage high | same | 0 | 0.584 → 5.8 |
A reviewed rule can therefore move this hour by about one point across the tide cycle. The tide levels behind the stage are astronomical only; surge and river flow are excluded.
Sea level and tide language
Open-Meteo sea_level_height_msl is modelled sea level above global mean sea level. It includes tides and other sea-level effects, has limited coastal accuracy, and does not share official chart datum. The interface does not derive official high/low-water claims from it.
The local wave estimator's tide assessment (T1) uses the local FES2022 harmonic prediction instead, for every spot with tide constants: predictTideAt in src/server/tides/prediction.ts gives the astronomical level on Zero Hidrográfico for the assessed hour, the IH reference port, the surrounding high and low waters, and the time to the next one. Forecast hours without an offset are read in the spot's timezone. The stage comes from those extremes, not from the level alone: within the quarter of the range next to an extreme it is low or high, otherwise mid_rising after a low and mid_falling after a high (stageBetweenExtremes in src/server/forecast/tides/tideStage.ts). The assessment and every tide reason are labelled source: "predicted_astronomical", datum ZH, with the limitation "Astronomical tide only; surge and river flow excluded." (plus the approximate-location note for estuary or extrapolated cells); recommendation windows report tide status predicted_astronomical with the reference port. Only spots without constants fall back to the GAP-05 approximate_msl_offset path, labelled as before. Spring and neap regime is not derived from a single day, so it stays unknown for predictions. Tide still never changes rideability (allowTideRideabilityAdjustment is false) until reviewed tide rules exist (T2). Extremes are searched once per spot per UTC day and cached in the process; for the five pilot spots over sixteen days the first forecast pays about 0.7 s, later ones about 30 ms.