barograph-met 0.1.0a2

barograph-met — wind and temperature at aircraft positions, fast and explicit

barograph-met interpolates wind (u, v) and temperature (t) at aircraft positions (time, latitude, longitude, barometric altitude). It also retrieves surface weather at fixed sites or along trajectories using only time, latitude and longitude. For contrail modelling, it can retrieve ERA5 humidity, pressure velocity, cirrus optical depth and radiation, export native grids to pycontrails or diffcocip, and supply weather during checked forward diffcocip evolution.

Features

• Sources: ERA5 from ARCO-ERA5 on its 137 model levels (arco_model_levels) or pressure levels (arco_pressure_levels); Météo-France ARPEGE open data, 0.1° Europe or 0.25° global (ArpegeSource); Open-Meteo archives of ARPEGE, AROME and IFS (OpenMeteoSource). SourceChain combines sources with the same output fields and time step; hourly sources cannot be chained with three-hourly IFS. IFS uses its native 3-hour step; ARPEGE and AROME are hourly. These archives do not retain original forecast runs or leads and are distinct from ERA5 reanalysis. See IFS and AROME aloft.
• Surface weather: 10 m wind and direction, gusts, precipitation and 2 m temperature with SurfaceEnricher. OpenMeteoSurfaceSource reads the stitched archive; AromeSurfaceSource reads an explicit forecast run and preserves its initialization and lead. Precipitation totals and gust maxima retain their native periods. Neither interface requires pressure or altitude.
• Immediate forecasts: authenticated AromePISource (15-minute surface fields) and PiafSource (5-minute precipitation) preserve forecast runs and request only the native grid neighbours needed by each query. See the access and caching guide.
• Selective reads: partial reads of the compressed blocks of ARCO-ERA5 chunks (levels × latitude band), of GRIB2 messages (variables × levels × steps), and of Open-Meteo tiles. Storage block boundaries impose some over-read; shared caches reuse downloaded ranges across flights.
• Exact vertical coordinate: level pressures from each grid column's actual surface pressure, interpolation in ln p.
• Explicit: no silent extrapolation — every missing value has a flag, and points outside a source's period are reported.
• Shared acquisition: download volume grows with the area and hours queried; an on-disk byte-range cache shared by calls and processes reuses immutable data. Per-host concurrency caps and retry with backoff control requests.
• Persistent weather sessions: bounded decoded-cube reuse for successive point queries, with explicit pressure interpolation and field selection.
• Contrail weather: targeted pressure-level windows, separate upper-column cirrus dependencies and ERA5 midpoint radiation. Optional engine exports and a coverage-checked diffcocip forward driver with explicit age cap; see weather grids and adaptive evolution. Engine dependencies remain optional.
• Native pycontrails: lazy weather datasets load fields when the engine requests slices. An optional bounded decoded-run cache avoids repeated decompression across overlapping requests. Cache budgets describe retained data, not total process memory.
• FastMeteo-compatible façade: baro.met.compat.ArcoEra5 and Arpege, same constructors and interpolate(df).

Installation

Requires Python 3.12+ on a POSIX system (Linux or macOS). Native Windows is not supported because the shared disk cache uses POSIX file locks.

With uv:

uv venv --python 3.12
source .venv/bin/activate
uv pip install barograph-met                              # ERA5
uv pip install 'barograph-met[grib,pandas,openmeteo]'       # GRIB, DataFrames and archives
uv pip install 'barograph-met[contrails]'                   # optional pycontrails integration

With pip, in your Python environment:

python -m pip install barograph-met
python -m pip install 'barograph-met[grib,pandas,openmeteo]'
python -m pip install 'barograph-met[contrails]'

In an existing uv-managed project, use uv add barograph-met or uv add 'barograph-met[grib,pandas,openmeteo]'. Extras are independent; choose only the data sources and integrations you need.

Quick start

This example samples a short synthetic flight from the public ERA5 archive. The first run downloads weather; subsequent runs reuse immutable cached data.

import numpy as np
from baro.met import Enricher, arco_model_levels, track_components

n = 60
time_utc = np.datetime64("2020-01-01T10:00") + np.arange(n) * np.timedelta64(30, "s")
lat = np.linspace(48.7, 47.5, n)
lon = np.linspace(2.4, 3.2, n)
altitude_ft = np.full(n, 35_000.0)  # barometric (pressure) altitude
track_deg = np.full(n, 150.0)

res = Enricher(arco_model_levels(), cache_dir="~/data/era5-cache").enrich(
    time_utc, lat, lon, altitude_ft=altitude_ft
)
along, cross = track_components(res["u"], res["v"], track_deg)
print(res["t"][:3], res.flags[:3])  # temperature in kelvin; flag 0 means valid
print(res.stats)

Documentation

• First-flight tutorial.
• Data sources and how-to guides.
• Public Python API.
• Flags and statistics.

Benchmarks

Two samples of 1 000 real flights drawn from OpenSky across all ICAO regions (one point every 10 s, surface to FL410): 18 June 2025 for ERA5, 28 September 2026 for ARPEGE (Météo-France keeps its files 14 days). Flights are added to each tool's own cache in steps of 1, 10, 100 and 1 000; costs are cumulative from a cold cache, through a corporate HTTPS proxy; values are compared on every point both tools serve.

In these acquisition benchmarks, at 1 000 flights barograph-met is 2.1–2.5× faster, downloads 2–2.3× less and needs 4–10× less memory; for a single flight it downloads 13–48× less and is 2.5–22× faster (ARPEGE: indexing the files dominates the first call). FastMeteo and the compared pycontrails configuration download whole global fields for every hour they need, so their cost reaches a full day as soon as the flights cover it; barograph-met reads only the latitude bands, levels and messages the flights cross, so its cost grows with the area covered and levels off. Points it cannot interpolate (below the lowest level, invalid altitudes: 0.4–0.8 %) are flagged, never extrapolated. These measurements concern weather retrieval and interpolation; they do not compare CoCiP physics engines or establish the same ratios for other sources, retrieval configurations or cache states.

1. Including the points where FastMeteo 1.2.0 extrapolates across the Greenwich seam, RMS 0.006 m/s and 0.002 K.
2. Different vertical methods: pycontrails interpolates model levels to pressure levels at a reference surface pressure, barograph-met interpolates the model levels directly with each column's actual surface pressure.
3. FastMeteo 1.2.0 cannot reach Météo-France's new data.gouv.fr host; it runs from the branch of fastmeteo#5, in its only full-day mode (00 UTC run, one 000H024H file).
4. By default barograph-met also uses the 275 and 925 hPa levels that FastMeteo drops: 0.23 m/s and 0.12 K RMS from FastMeteo's values.

Benchmarked coverage

Details in the benchmark notes.

FastMeteo

This package builds on FastMeteo (Sun & Roosenbrand, JOAS 2023, doi:10.59490/joas.2023.7264). Fixes found while comparing the two tools were contributed upstream (open-aviation/fastmeteo#5), and this engine is intended to become available to FastMeteo as an optional backend. ERA5 data: Copernicus Climate Change Service (Hersbach et al. 2020, doi:10.1002/qj.3803), via ARCO-ERA5 (Carver & Merose, 2023).

Development

For development, clone the public repository and run these commands from its root. Installing from PyPI does not require a repository checkout.

uv sync --all-packages --all-groups --all-extras --locked
uv run --package barograph-met --directory packages/barograph-met pytest   # offline suite
uv run --package barograph-met --directory packages/barograph-met pytest -m live   # public buckets
make lint

Legal and usage

Data sources and licences

barograph-met redistributes no data: it reads the providers' public stores on your behalf, and what you download stays under their terms. Credit them in work that uses the values:

License

EUPL-1.2 — © 2026 Eurocontrol. The full licence text is included in the source and wheel distributions.