Winds

Wind field models for per-segment wind correction in flight planning.

Provides a WindField abstraction with implementations for still air, constant wind, NASA MERRA-2 reanalysis, NOAA GFS forecast, and GMAO GEOS-FP near-real-time analysis.

Wind field classes

class WindField

Bases: ABC

Abstract base for wind data providers.

All subclasses must implement wind_at(), which returns eastward (U) and northward (V) wind components as pint.Quantity in m/s.

abstractmethod wind_at(lat, lon, altitude, time)

Return (u, v) wind components at the given point.

Parameters:

• lat (float) – Latitude in decimal degrees.

• lon (float) – Longitude in decimal degrees.

• altitude (Quantity) – Geometric altitude as a pint.Quantity.

• time (datetime) – UTC datetime.

Return type:

Tuple[Quantity, Quantity]

Returns:

Tuple of (u, v) as pint.Quantity in m/s. u is eastward (positive = from west), v is northward (positive = from south).

class StillAirField

Bases: WindField

Zero-wind field — always returns U=0, V=0.

Use this as an explicit “no wind” baseline for comparison or when wind data is unavailable.

wind_at(lat, lon, altitude, time)

Return (u, v) wind components at the given point.

Parameters:

• lat (float) – Latitude in decimal degrees.

• lon (float) – Longitude in decimal degrees.

• altitude (Quantity) – Geometric altitude as a pint.Quantity.

• time (datetime) – UTC datetime.

Return type:

Tuple[Quantity, Quantity]

Returns:

Tuple of (u, v) as pint.Quantity in m/s. u is eastward (positive = from west), v is northward (positive = from south).

class ConstantWindField

Bases: WindField

Constant wind field — same U/V everywhere.

Useful for backward compatibility with the scalar wind_speed / wind_direction parameters.

Parameters:

• wind_speed (Quantity) – Wind speed magnitude.

• wind_from_deg (float) – Direction the wind is blowing from in degrees true (meteorological convention: 0 = from north, 90 = from east).

__init__(wind_speed, wind_from_deg)

Parameters:

• wind_speed (Quantity)

• wind_from_deg (float)

wind_at(lat, lon, altitude, time)

Return (u, v) wind components at the given point.

Parameters:

• lat (float) – Latitude in decimal degrees.

• lon (float) – Longitude in decimal degrees.

• altitude (Quantity) – Geometric altitude as a pint.Quantity.

• time (datetime) – UTC datetime.

Return type:

Tuple[Quantity, Quantity]

Returns:

Tuple of (u, v) as pint.Quantity in m/s. u is eastward (positive = from west), v is northward (positive = from south).

class MERRA2WindField

Bases: _GriddedWindField

MERRA-2 reanalysis wind field for historical planning.

Fetches 3-hourly instantaneous U/V winds on pressure levels from NASA GES DISC via OPeNDAP.

Prerequisites:

1. Install: pip install hyplan[winds]

2. Register at https://urs.earthdata.nasa.gov

3. Authenticate via one of: - Set EARTHDATA_TOKEN environment variable (recommended) - Add to ~/.netrc:

   machine urs.earthdata.nasa.gov login <user> password <pass>
   

Authentication is handled by earthaccess, which tries the EARTHDATA_TOKEN env var first, then ~/.netrc, then an interactive prompt.

Parameters:

• lat_min – Southern latitude bound (degrees).

• lat_max – Northern latitude bound (degrees).

• lon_min – Western longitude bound (degrees).

• lon_max – Eastern longitude bound (degrees).

• time_start – Start of time window (UTC).

• time_end – End of time window (UTC).

• pressure_min_hpa – Top pressure level to fetch (hPa). Default 50.

• pressure_max_hpa – Bottom pressure level to fetch (hPa). Default 1000.

__init__(*args, **kwargs)

class GFSWindField

Bases: _GriddedWindField

NOAA GFS 0.25deg forecast wind field for operational planning.

Fetches U/V winds on pressure levels from the NOMADS GRIB filter, which performs server-side subsetting by variable, pressure level, and geographic region — typically downloading only ~10 KB instead of the full ~500 MB GRIB2 file.

No credentials required. Forecast data available up to 16 days ahead, updated 4 times daily (00Z, 06Z, 12Z, 18Z).

Requires cfgrib (with eccodes) for GRIB2 decoding.

Parameters:

• lat_min – Southern latitude bound (degrees).

• lat_max – Northern latitude bound (degrees).

• lon_min – Western longitude bound (degrees).

• lon_max – Eastern longitude bound (degrees).

• time_start – Start of time window (UTC).

• time_end – End of time window (UTC).

• pressure_min_hpa – Top pressure level to fetch (hPa). Default 50.

• pressure_max_hpa – Bottom pressure level to fetch (hPa). Default 1000.

• cycle_date (Optional[date]) – Override GFS cycle date (default: auto-select).

• cycle_hour (Optional[int]) – Override GFS cycle hour (default: auto-select).

• forecast_hour (Optional[int]) – Specific forecast hour to fetch. If None (default), the hour closest to the midpoint of the time window is chosen automatically.

__init__(*args, cycle_date=None, cycle_hour=None, forecast_hour=None, **kwargs)

Parameters:

• cycle_date (date | None)

• cycle_hour (int | None)

• forecast_hour (int | None)

class GMAOWindField

Bases: _GriddedWindField

GMAO GEOS-FP near-real-time wind field for operational planning.

Fetches 3-hourly instantaneous U/V winds on pressure levels from NCCS OPeNDAP server via the pydap DAP2 protocol. Typically covers the last ~30 days of analysis plus short-range forecasts. No credentials required.

Parameters:

• lat_min – Southern latitude bound (degrees).

• lat_max – Northern latitude bound (degrees).

• lon_min – Western longitude bound (degrees).

• lon_max – Eastern longitude bound (degrees).

• time_start – Start of time window (UTC).

• time_end – End of time window (UTC).

• pressure_min_hpa – Top pressure level to fetch (hPa). Default 50.

• pressure_max_hpa – Bottom pressure level to fetch (hPa). Default 1000.

• url (Optional[str]) – Override the default GEOS-FP OPeNDAP URL.

__init__(*args, url=None, **kwargs)

Parameters:

url (str | None)

Factory function

wind_field_from_plan(source, flight_sequence, takeoff_time, takeoff_airport=None, return_airport=None, flight_altitude=None, margin_deg=2.0, margin_hours=2.0)

Create a wind field pre-fetched for a planned flight.

Computes the geographic and temporal bounding box from the flight sequence, adds margins, and constructs the appropriate WindField with its data slab pre-loaded.

Parameters:

• source (str) – "merra2" for MERRA-2 reanalysis, "gmao" for GEOS-FP near-real-time analysis, "gfs" for NOAA GFS forecast, or "still_air" for zero wind.

• flight_sequence (list) – Ordered list of flight lines and/or waypoints (same format as compute_flight_plan()).

• takeoff_time (datetime) – Mission start time (UTC).

• takeoff_airport – Optional departure airport (extends bounding box).

• return_airport – Optional arrival airport (extends bounding box).

• flight_altitude (Optional[Quantity]) – Representative flight altitude for pressure-level selection. If None, derived from the highest altitude in the flight sequence.

• margin_deg (float) – Spatial margin in degrees added to all sides.

• margin_hours (float) – Temporal margin in hours added before/after.

Return type:

WindField

Returns:

A WindField ready for use with compute_flight_plan().