Meteorological and Oceanographic Data Fields for Maritime Weather Routing

Environmental forcing parameters used in WindMar's vessel performance prediction and route optimization

Abstract

Maritime weather routing systems depend on accurate environmental forcing data to predict vessel performance under realistic sea conditions. WindMar ingests three categories of geophysical fields — atmospheric winds, ocean surface waves, and ocean currents — from operational numerical weather prediction (NWP) and ocean analysis systems. Wind fields are obtained from the NCEP Global Forecast System (GFS) at 0.25° resolution with ERA5 reanalysis serving as a climatological fallback. Wave fields are sourced from the Copernicus Marine Environment Monitoring Service (CMEMS) global wave analysis and forecast product at 0.083° resolution, providing total sea state parameters along with decomposed swell and wind-wave components. Ocean current fields are drawn from the CMEMS global physics analysis and forecast at the same spatial resolution. This article describes each field, its physical meaning, the data source and resolution, the vector decomposition conventions used, and the ocean masking procedure that filters land pixels from weather grids before they enter the routing engine.

1. Introduction

The performance of an ocean-going vessel is governed by the environmental conditions it encounters along its route. Wind generates aerodynamic resistance on the hull superstructure and cargo (particularly significant for container ships and car carriers with high windage areas). Waves impose added resistance through radiation, diffraction, and motion-induced effects that can increase fuel consumption by 15–30% in heavy weather relative to calm-water conditions. Ocean currents alter the vessel's speed over ground (SOG) without changing its speed through water (STW), directly affecting passage time and, indirectly, fuel consumption through engine load adjustments. Accurate representation of these three forcing categories is therefore essential for any weather routing system that aims to optimize fuel efficiency or minimize voyage duration under realistic conditions. In WindMar, the environmental data feeds into the hydrodynamic resistance models (Blendermann wind resistance, STA-wave added resistance, seakeeping response amplitude operators) and the A* pathfinding algorithm that evaluates candidate route segments.

WindMar organizes environmental data into a unified WeatherData dataclass that encapsulates scalar fields (significant wave height, wave period), vector fields (wind and current as U/V components), and decomposed spectral fields (swell versus wind-wave partitions). Each field carries metadata including its source parameter name, timestamp, geographic extent (latitude and longitude arrays), physical unit, and spatial grid of values. This article documents the complete set of fields, grouped into three categories: atmospheric fields (Section 2), sea state fields (Section 3), and ocean current fields (Section 4). Section 5 describes the ocean mask used to distinguish water from land in the routing grid, and Section 6 discusses data quality considerations and limitations of the forecast products employed.

2. Atmospheric Fields

Wind forcing is the primary atmospheric input to the routing engine. WindMar obtains 10-metre wind fields from two sources: the NCEP Global Forecast System (GFS) for operational forecasts and the ECMWF ERA5 reanalysis for climatological fallback when the forecast horizon is exceeded. Both products provide wind as orthogonal U and V components on a regular latitude-longitude grid, which WindMar converts to scalar speed and meteorological direction for use in the Blendermann wind resistance model.

2.1 GFS Operational Forecast

The GFS model is produced by the National Centers for Environmental Prediction (NCEP) of the U.S. National Oceanic and Atmospheric Administration (NOAA). WindMar accesses GFS data via the NOMADS (NOAA Operational Model Archive and Distribution System) endpoint at https://nomads.ncep.noaa.gov/cgi-bin/filter_gfs_0p25.pl, which provides filtered GRIB2 data for specific parameters and subregions. The GFS runs four times daily at 00, 06, 12, and 18 UTC, with output becoming available approximately 3.5 hours after each run time. WindMar's GFSDataProvider automatically selects the most recent available run, accounting for this production lag. The forecast extends to 120 hours (5 days) at 3-hourly temporal resolution, yielding 41 forecast steps (hours 0, 3, 6, …, 120).

The two parameters retrieved are the U-component (UGRD) and V-component (VGRD) of wind at 10 metres above the surface. The U-component represents the eastward wind velocity and the V-component represents the northward wind velocity, both in metres per second. These are provided on a global 0.25° × 0.25° latitude-longitude grid (1440 × 721 grid points). The GRIB2 format is parsed using the cfgrib and pygrib libraries.

2.2 ERA5 Reanalysis

For climatological conditions beyond the operational forecast horizon, WindMar falls back to the ERA5 global reanalysis produced by ECMWF. ERA5 provides hourly estimates of atmospheric variables on a 0.25° grid from 1940 to the present, combining model data with observations through 4D-Var data assimilation. WindMar's ClimatologyProvider retrieves ERA5 monthly means from the reanalysis-era5-single-levels dataset for the variables u10 (10-metre U-wind) and v10 (10-metre V-wind). These climatological fields serve as the baseline wind estimate when the voyage extends beyond the 10-day forecast-to-climatology blending window.

2.3 Vector Decomposition

The routing engine requires scalar wind speed and meteorological direction (the direction from which the wind blows, measured clockwise from true north). These are derived from the U and V components using standard meteorological conventions:

The 270° offset and sign convention ensure that a purely westerly wind (u > 0, v = 0) yields a direction of 270°, corresponding to "wind from the west," which is the standard meteorological convention. The WeatherData dataclass stores both the raw u_component and v_component arrays and the derived scalar values (speed) field, allowing downstream consumers to use whichever representation is most convenient.

2.4 Summary of Atmospheric Parameters

3. Sea State Fields

Wave forcing is the dominant contributor to added resistance and speed loss for most commercial vessel types. WindMar obtains wave data from the CMEMS Global Ocean Waves Analysis and Forecast product (cmems_mod_glo_wav_anfc_0.083deg_PT3H-i), which provides spectral wave parameters on a global 0.083° grid (approximately 9 km at the equator) at 3-hourly temporal resolution. The forecast extends to 120 hours (5 days) with output at hours 0, 3, 6, …, 120. This product is based on the MFWAM wave model, forced by ECMWF atmospheric analyses, and assimilates satellite altimetry observations to constrain the significant wave height field.

WindMar retrieves a comprehensive set of wave parameters that describe both the total sea state and its decomposition into swell and locally generated wind-wave components. The total sea state parameters (significant wave height, peak period, mean direction) characterize the aggregate ocean surface conditions, while the decomposed fields enable the seakeeping model to compute vessel motions and added resistance separately for long-period swell and short-crested wind-waves, which produce qualitatively different vessel responses.

3.1 Total Sea State Parameters

The total sea state is described by three primary parameters derived from the two-dimensional wave energy spectrum. The significant wave height (H_s) is defined as four times the square root of the zeroth spectral moment (H_s = 4√m₀) and approximates the average height of the highest one-third of waves, which is the quantity most directly related to wave-induced ship motions and structural loads. The peak wave period (T_p) is the period at which the wave energy spectrum reaches its maximum, and the mean wave direction indicates the direction from which the dominant wave energy propagates.

3.2 Complete Wave Parameter Table

The spectral mean period VTM02 is computed from the ratio of the zeroth and second spectral moments (T_m02 = √(m₀/m₂)) and provides a measure of the average wave period that is less sensitive to spectral shape than the peak period. Both period measures are retained because the peak period is more relevant for resonance calculations (encounter frequency), while the mean period better characterizes the bulk energy content of the sea state.

3.3 Wave Spectrum Decomposition

The ocean wave field at any location is typically composed of multiple wave systems with different origins. Wind-waves (also called wind-sea) are generated locally by the action of wind stress on the sea surface; they are short-crested, have relatively short periods (typically 3–8 seconds), and their direction aligns closely with the local wind direction. Swell, by contrast, consists of waves that have propagated away from their generation area (a distant storm) and can travel thousands of kilometres with minimal energy loss. Swell waves are long-crested, have longer periods (typically 8–20 seconds), and their direction may bear no relationship to the local wind. A vessel transiting the North Atlantic, for example, may simultaneously experience locally generated wind-waves from a northwesterly breeze and long-period swell arriving from a storm system far to the southwest.

The CMEMS wave model partitions the two-dimensional wave spectrum into swell and wind-wave components using the Hasselmann et al. (1994) spectral partitioning algorithm. This decomposition is physically meaningful because the two wave types produce qualitatively different vessel responses. Short-period wind-waves with periods near the vessel's natural roll period (typically 8–15 seconds for cargo ships) can excite resonant rolling motions, while long-period swell primarily causes heaving and pitching. The added resistance mechanisms also differ: wind-waves contribute mainly through radiation stress and wave reflection at the bow, while swell contributes through diffraction effects and hull pressure changes that depend on the ratio of wavelength to ship length.

The total significant wave height is related to the component heights through the energy conservation principle:

The decomposition is critical for WindMar's seakeeping model, which implements SeakeepingModel.calculate_motions_decomposed() to compute vessel response separately for each wave system. For a given vessel heading, the encounter frequency differs between swell (long period, hence low encounter frequency) and wind-waves (short period, higher encounter frequency), leading to different positions on the vessel's Response Amplitude Operator (RAO) curves. Summing the motions from each component provides a more accurate estimate of total vessel response than computing motions from the aggregate sea state parameters alone, particularly in bimodal sea states where swell and wind-waves arrive from different directions. Further details on the hydrodynamic response calculations are provided in the Hydrodynamics & RAO article.

4. Ocean Current Fields

Ocean surface currents affect vessel routing by altering the speed over ground (SOG) relative to the speed through water (STW). A favourable current of 1–2 knots (common in regions such as the Gulf Stream, Kuroshio, or Agulhas Current) can reduce passage time by several hours on a trans-oceanic voyage, while an adverse current of the same magnitude increases both passage time and fuel consumption. WindMar obtains ocean current data from the CMEMS Global Ocean Physics Analysis and Forecast product (cmems_mod_glo_phy_anfc_0.083deg_PT1H-m), which provides surface current vectors on a 0.083° global grid (approximately 9 km) at hourly temporal resolution. Forecast output extends to 120 hours at 3-hourly steps (hours 0, 3, 6, …, 120), consistent with the wave forecast horizon.

The current field is represented as two orthogonal velocity components: uo (eastward velocity, positive eastward) and vo (northward velocity, positive northward), both in metres per second. These are stored in the WeatherData dataclass as u_component and v_component, analogous to the wind field representation. The scalar current speed and direction are derived using the same vector decomposition as for wind:

The effect of currents on vessel ground speed is computed in the voyage calculator (VoyageCalculator._calculate_sog()) by vector addition. The vessel's speed through water (STW) along its heading is combined with the current vector projected onto the vessel's track direction to obtain the effective speed over ground. When the current has a component aligned with the vessel's heading, it increases SOG and reduces passage time; when opposed, it decreases SOG and increases fuel consumption per nautical mile of ground track covered.

4.1 Current Parameter Table

Compared to the atmospheric wind and wave fields, the ocean current analysis product has higher temporal resolution (hourly versus 3-hourly for waves and wind forecasts) but represents an analysis rather than a pure forecast product. The CMEMS physics model assimilates in-situ observations (Argo floats, moored buoys) and satellite altimetry to produce a nowcast, which is then propagated forward as a forecast. The current field is generally more persistent and predictable than wind or waves over the 5-day forecast horizon, particularly for major ocean currents whose positions are determined by large-scale thermohaline and wind-driven circulation patterns.

5. Ocean Mask and Land Filtering

A practical requirement for any maritime weather routing system is the ability to distinguish ocean grid points from land grid points. While the CMEMS and GFS products naturally contain NaN or missing values over land, the routing grid must explicitly exclude land nodes to prevent the A* pathfinding algorithm from generating routes that cross land masses. WindMar implements ocean masking at two levels: server-side during weather data ingestion and client-side during weather grid visualization.

5.1 Server-Side Masking

The backend uses the global_land_mask Python library to generate a boolean ocean mask at 0.05° resolution (approximately 5.5 km at the equator). The _build_ocean_mask() function evaluates every grid point within the requested geographic extent and returns a two-dimensional boolean array where True indicates water and False indicates land. This mask is applied to all weather grids before they are served to the routing engine, ensuring that NaN-filled land pixels from the upstream data sources are explicitly flagged as non-navigable. The 0.05° mask resolution is finer than the coarsest weather data (GFS at 0.25°), which prevents the mask from inadvertently blocking narrow straits or coastal passages that are resolved by the land mask but not by the weather grid.

5.2 Client-Side Masking

On the frontend, the WeatherGridLayer component applies per-pixel ocean masking when rendering weather data on the map. Each grid cell is checked against the land mask before rendering its colour-coded weather value, preventing the display of weather data over land areas. This is purely a visualization concern and does not affect the routing computation, but it provides users with a clear visual representation of where weather data is available and where the routing graph has been constrained to water-only nodes.

5.3 Why Explicit Masking is Necessary

Relying solely on NaN values in the upstream CMEMS or GFS data for land exclusion is insufficient for several reasons. First, different data products have different land-sea masks: the GFS 0.25° grid treats some coastal grid cells as land that the CMEMS 0.083° grid treats as water, and vice versa. Second, interpolation at grid boundaries can produce non-NaN values over land when nearby ocean grid points are used in the bilinear weighting. Third, the A* routing algorithm requires a consistent binary navigability grid that does not depend on which weather parameter happens to be queried. The global_land_mask at 0.05° provides this consistent reference, derived from high-resolution geographic data rather than from the weather model's own land-sea classification.

6. Data Quality and Limitations

The quality and reliability of the environmental data used in weather routing directly affects the fidelity of vessel performance predictions and route optimization outcomes. Several factors limit the accuracy of the data fields described in this article, and WindMar implements a provenance tracking system to communicate forecast confidence to the user.

6.1 Forecast Accuracy Degradation

All numerical weather prediction products exhibit accuracy degradation with increasing forecast lead time. For GFS 10-metre wind, the root-mean-square error (RMSE) is approximately 1.5 m/s at 24 hours, increasing to approximately 3.5 m/s at 120 hours. CMEMS significant wave height errors follow a similar pattern, with RMSE of approximately 0.2 m at short lead times growing to 0.5–0.8 m at the 5-day horizon. Ocean current forecasts are generally more stable, with RMSE below 0.1 m/s for major current systems, though mesoscale eddies and transient features are poorly predicted beyond 2–3 days.

WindMar communicates forecast confidence through the WeatherProvenance system, which assigns three confidence levels based on data age and forecast lead time:

6.2 Spatial Resolution Limitations

The 0.083° resolution of CMEMS wave and current products corresponds to approximately 9 km at the equator and approximately 5 km at 55°N latitude. While this resolution is adequate for open-ocean routing, it is insufficient for resolving coastal processes such as wave refraction in shallow water, tidal current acceleration in straits, and sheltering effects behind headlands and islands. Port approach routing, where these effects are significant, would require higher-resolution regional models (e.g., 100–500 m coastal wave models) that are outside the scope of WindMar's current data architecture. The GFS wind field at 0.25° (approximately 28 km) is even coarser and cannot resolve local wind effects such as orographic acceleration, land-sea breezes, or gap winds in mountainous coastal terrain.

6.3 Climatological Fallback

When the voyage duration exceeds the operational forecast horizon, WindMar's ClimatologyProvider transitions from forecast data to ERA5 monthly climatological means. The transition is governed by two parameters: FORECAST_HORIZON_DAYS = 10, which defines the outer boundary of the forecast window, and BLEND_WINDOW_DAYS = 2, which defines a linear blending zone between pure forecast and pure climatology. Within the blending window, wind fields are computed as a weighted average of the forecast and climatological values, producing a smooth transition that avoids discontinuities at the forecast boundary. Climatological fields represent long-term average conditions and do not capture individual weather systems; the Monte Carlo simulation is particularly important for quantifying uncertainty in the climatological portion of a long voyage.

6.4 Geographic Coverage

The data sources used by WindMar provide global coverage with latitude bounds of −85° to +85°, excluding extreme polar regions where sea ice prevents commercial navigation and where weather model output is unreliable. Within this domain, the GFS model provides complete global coverage at 0.25°, while the CMEMS wave and current products cover the global ocean at 0.083°. Coverage gaps may occur in semi-enclosed seas or near the coast where the CMEMS model grid does not extend, though such gaps are rare in the open ocean where weather routing is most relevant.

References

1. NCEP/NOAA (2023). “Global Forecast System (GFS) Model Documentation.” National Centers for Environmental Prediction.
2. Hersbach, H. et al. (2020). “The ERA5 Global Reanalysis.” Quarterly Journal of the Royal Meteorological Society, vol. 146, no. 730, pp. 1999–2049. DOI: 10.1002/qj.3803
3. CMEMS (2024). “Global Ocean Waves Analysis and Forecast — Product User Manual.” Copernicus Marine Environment Monitoring Service.
4. CMEMS (2024). “Global Ocean Physics Analysis and Forecast — Product User Manual.” Copernicus Marine Environment Monitoring Service.
5. WMO (1998). “Guide to Wave Analysis and Forecasting.” WMO-No. 702, World Meteorological Organization, 2nd ed.
6. Holthuijsen, L.H. (2007). Waves in Oceanic and Coastal Waters. Cambridge University Press.
7. Komen, G.J. et al. (1994). Dynamics and Modelling of Ocean Waves. Cambridge University Press.