Metadata-Version: 2.5
Name: barograph-met
Version: 0.1.0a2
Summary: Fast weather retrieval along aircraft trajectories: ERA5 model/pressure levels, ARPEGE, Open-Meteo archives
Project-URL: Homepage, https://github.com/eurocontrol-asu/barograph
Project-URL: Documentation, https://eurocontrol-asu.github.io/barograph/met/
Project-URL: Repository, https://github.com/eurocontrol-asu/barograph.git
Project-URL: Issues, https://github.com/eurocontrol-asu/barograph/issues
Author-email: Gabriel Jarry <gabriel.jarry@eurocontrol.int>
License-Expression: EUPL-1.2
License-File: LICENSE
Keywords: ads-b,arpege,aviation,era5,trajectory,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: numcodecs>=0.12
Requires-Dist: numpy>=1.26
Provides-Extra: contrails
Requires-Dist: pycontrails<0.66,>=0.63.3; extra == 'contrails'
Provides-Extra: grib
Requires-Dist: eccodes>=2.38; extra == 'grib'
Requires-Dist: eccodeslib>=2.38; extra == 'grib'
Provides-Extra: openmeteo
Requires-Dist: omfiles>=1.2; extra == 'openmeteo'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://eurocontrol-asu.github.io/barograph/assets/logo.svg" alt="barograph" width="100" />
</p>

<p align="center">
  <strong>barograph-met — wind and temperature at aircraft positions, fast and explicit</strong>
</p>

<p align="center">
  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/eurocontrol-asu/barograph/gh-pages/badges/barograph-met/axm-audit.json" alt="axm-audit"></a>
  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/eurocontrol-asu/barograph/gh-pages/badges/barograph-met/axm-init.json" alt="axm-init"></a>
  <a href="https://pypi.org/project/barograph-met/"><img src="https://img.shields.io/pypi/v/barograph-met" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
  <a href="https://eurocontrol-asu.github.io/barograph/met/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
  <img src="https://img.shields.io/badge/license-EUPL--1.2-blue" alt="EUPL-1.2">
</p>

---

`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](https://eurocontrol-asu.github.io/barograph/met/howto/ifs/) and [AROME aloft](https://eurocontrol-asu.github.io/barograph/met/howto/arome-pressure/).
- **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](https://eurocontrol-asu.github.io/barograph/met/howto/immediate-forecasts/).
- **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](https://eurocontrol-asu.github.io/barograph/met/howto/weather-cubes/) and
  [adaptive evolution](https://eurocontrol-asu.github.io/barograph/met/howto/diffcocip/). Engine dependencies remain optional.
- **Native pycontrails**: [lazy weather datasets](https://eurocontrol-asu.github.io/barograph/met/howto/lazy-pycontrails-weather/)
  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**:

```bash
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:

```bash
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.

```python
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](https://eurocontrol-asu.github.io/barograph/met/tutorials/getting-started/).
- [Data sources and how-to guides](https://eurocontrol-asu.github.io/barograph/met/howto/).
- [Public Python API](https://eurocontrol-asu.github.io/barograph/met/reference/api/).
- [Flags and statistics](https://eurocontrol-asu.github.io/barograph/met/reference/flags/).

## 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.

| Case | Tool | 1 flight: time · download | 1 000 flights: time · download | Disk | Peak RAM | Values vs reference (1 000 flights) |
|---|---|---:|---:|---:|---:|---|
| ERA5, 22 pressure levels | FastMeteo 1.2.0 | 330 s · 3.6 GB | 744 s · 8.1 GB | 4.9 GB | 5.8 GB | reference |
| | **barograph-met** | **15 s · 0.09 GB** | **302 s · 3.6 GB** | **3.6 GB** | **1.5 GB** | identical: 99th pct \|Δ\| < 2e-8 on 548 098 points ¹ |
| ERA5, model levels | pycontrails 0.63.5 | 753 s · 13 GB | 1 893 s · 29.6 GB | 23.7 GB | 39 GB | reference |
| | **barograph-met** (L137) | **34 s · 0.27 GB** | **900 s · 14.6 GB** | **14.6 GB** | **3.8 GB** | RMS 0.037 m/s (u, v), 0.021 K (T); 99th pct 0.15 m/s, 0.08 K on 545 466 points ² |
| ARPEGE 0.25°, official | FastMeteo ³ | 236 s · 2.6 GB | 504 s · 2.6 GB | 2.6 GB | 13 GB | reference |
| | **barograph-met** | **95 s · 0.20 GB** | **211 s · 1.25 GB** | **1.2 GB** | **2.1 GB** | identical with the same 22 levels: \|Δ\| ≤ 3e-8 on 574 673 points ⁴ |

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](https://github.com/open-aviation/fastmeteo/pull/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

| Coverage | FastMeteo | pycontrails | barograph-met |
|---|:---:|:---:|:---:|
| ERA5 pressure levels | 22 of 37 | 37 | 37 |
| ERA5 model levels (L137) | — | via 61 PL | direct, actual surface pressure |
| ARPEGE official (last 14 days) | ✓ | — | ✓ |
| ARPEGE archive (since Dec 2023, Open-Meteo) | — | — | ✓, chained with the official feed |
| Points outside the data | extrapolated | NaN | flagged |

Details in the [benchmark notes](https://eurocontrol-asu.github.io/barograph/met/explanation/benchmarks/).

## FastMeteo

This package builds on [FastMeteo](https://github.com/open-aviation/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](https://github.com/open-aviation/fastmeteo/pull/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.

```bash
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

> [!IMPORTANT]
> **Research use only.** This software is provided for research purposes and
> is not a regulatory or operational tool; EUROCONTROL disclaims any
> responsibility for misuse or operational application.

## 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:

| Source | Licence and attribution |
|---|---|
| ERA5 (Copernicus Climate Change Service, ECMWF) | Copernicus licence: *"Contains modified Copernicus Climate Change Service information [year]. Neither the European Commission nor ECMWF is responsible for any use that may be made of the Copernicus information or data it contains."* Cite Hersbach et al. (2020), [doi:10.1002/qj.3803](https://doi.org/10.1002/qj.3803). |
| ARCO-ERA5 (Google Research, Google Cloud public datasets) | Same ERA5 terms; cite Carver & Merose (2023), [ARCO-ERA5](https://github.com/google-research/arco-era5). |
| Météo-France ARPEGE open data | [Licence Ouverte / Open Licence 2.0 (Etalab)](https://www.etalab.gouv.fr/licence-ouverte-open-licence/): credit *"Source: Météo-France"*. |
| Open-Meteo archive | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): credit *"Weather data by Open-Meteo.com"* and the model's producer (Météo-France for ARPEGE). |
| OpenSky Network (benchmark flights only) | Cite Schäfer et al. (2014), *Bringing up OpenSky*, IPSN; see the [OpenSky terms of use](https://opensky-network.org/about/terms-of-use). |

## License

[EUPL-1.2](https://eupl.eu/1.2/en/) — © 2026 Eurocontrol. The full licence
text is included in the source and wheel distributions.
