pyneats is an open-source Python library implementing the MRV (Monitoring, Reporting, and Verification) technical requirements for computing non-CO₂ climate impacts of aviation, expressed as GWP (Global Warming Potential) and related metrics.
It integrates multiple established open-source tools to provide a reproducible, end-to-end workflow for estimating aviation's climate effects beyond CO₂ emissions:
- PyContrails – for contrail prediction and atmospheric data processing
- PyBADA – for aircraft performance modelling using EUROCONTROL's BADA datasets
- open-airclim – for integrating climate response functions and GWP calculations
- aCCF estimates are computed inside PyNeats for performance reasons but are based on the ClimAccf library
The library is designed for researchers, airspace operators, regulators, and industry who need a transparent and auditable implementation for MRV purposes.
- Full MRV compliance: Implements the MRV technical requirements for non-CO₂ climate impact assessment
- Multi-library integration: Seamless interoperability between PyContrails, ClimAccf, PyBADA, and open-airclim
- Aircraft- and flight-level analysis: Uses flight trajectory, performance, and meteorological data
- Contrail modelling: Predicts contrail formation and persistence from actual flight and weather data
- Climate metric computation: Outputs Global Warming Potential (GWP) and other climate response metrics
- Reproducible workflows: Built on open-source tools with clear, documented interfaces
- Python 3.11+ (see Python installation)
- uv (fast Python package manager) – Installation guide
- make (build automation tool) – typically pre-installed on Linux/macOS
# Clone the repository
git clone https://github.com/eurocontrol-asu/PyNeats.git
cd PyNeats
# Install all dependencies (including PyBADA and open-airclim)
make installThis runs uv sync and installs PyBADA with the correct flags.
If you prefer not to use make:
# Clone the repository
git clone https://github.com/eurocontrol-asu/PyNeats.git
cd PyNeats
# Install dependencies
uv sync --all-groups
# Install PyBADA (requires special flags due to Python version constraints)
uv run pip install pybada --no-deps --ignore-requires-python
# Install open-airclim
uv run pip install git+https://github.com/dlr-pa/oac.git
# Install PyNeats
uv pip install -e . # triggers hatch-vcs, generates src/pyneats/_version.py# Run unit tests (no external data required)
make test-unit
# Show available make commands
make helpInstall pre-commit hooks for automatic code quality checks:
make pre-commit-installSee CONTRIBUTING.md for development workflow guidelines.
PyNeats tests require external data (BADA aircraft performance data and weather data) for full integration testing.
# Run unit tests only (no external data required)
make test-unit
# Run all tests with BADA data
make test BADA_PATH=/path/to/bada
# Run all tests with BADA and weather data
make test BADA_PATH=/path/to/bada WEATHER_PATH=/path/to/weather
# Run tests without coverage (faster)
make test-fast BADA_PATH=/path/to/badaYou can also set environment variables instead:
export BADA_PATH=/path/to/bada
export WEATHER_PATH=/path/to/weather
make testPyNeats is organized into modular components:
src/pyneats/
├── core/ # Shared types, constants, protocols, step registry
├── runners/ # Fleet and flight-level computation orchestration
├── steps/ # Pipeline stages (parsing, weather, performance, emissions, climate)
│ ├── parsing/ # Trajectory parsing and flight reconstruction
│ ├── weather/ # Meteorological data handling (Zarr-based weather stores)
│ ├── interpolation/ # Trajectory and performance interpolation
│ ├── performance/ # Aircraft performance modeling (PyBADA integration)
│ ├── emissions/ # Fuel burn and emissions calculation
│ ├── climate_functions/ # Climate response functions (CoCiP, CLIMaCCF, local aCCF)
│ └── climate_metrics/ # GWP and climate impact metrics
└── resources/ # Bundled data resources (engine UIDs, base inventories, etc.)
Key Design Principles:
- Modular pipeline: Each step is independent and can be tested/reused separately
- Type safety: mypy type checking for reliability
- Open-source integration: Uses PyContrails, ClimAccf, PyBADA, and open-airclim
- Performance-optimized: Vectorized operations for fleet-level computations with joblib parallelization
Process flight trajectories from a JSON file:
uv run python examples/fleet_computation_from_json.py \
--json-file tests/data/golden/fleet_5_flights_input.json \
--weather-path /path/to/weather/zarr/cache \
--bada-path /path/to/bada/data \
--njobs 4See examples/README.md for more examples and detailed instructions.
Process flight data from a pandas DataFrame:
uv run python examples/fleet_computation_from_dataframe.py \
--weather-path /path/to/weather/zarr/cache \
--bada-path /path/to/bada/data \
--njobs 4Build and cache meteorological data from DWD for reuse:
uv run python examples/weather_cache.py \
--dwd-path /path/to/dwd/icon/data \
--zarr-path /path/to/output/zarr/cache \
--date 2025-07-09 \
--hour 0For additional examples and detailed documentation, see examples/README.md.
make help # Show all available commands
make install # Install all dependencies
make format # Format code with ruff
make lint # Run linting and type checking
make test # Run tests with coverage
make test-fast # Run tests without coverage
make test-unit # Run unit tests only (no external data)
make audit # Run security audit
make check # Run all checks (lint + audit + test)
make pre-commit # Run pre-commit on all files
make clean # Clean build artifacts- Quick Start – Install and run your first computation
- Usage guide – How-to recipes (parse, cache weather, read output)
- Architecture – System design and module overview
- MRV specification – Methodology and formulas
- Example scripts – Runnable example scripts reference
- Contributing – Development setup and contribution guidelines
PyNeats is released under the EUPL 1.2 with an amendment from EUROCONTROL. See LICENSE.md and AMENDMENT_TO_EUPL_license.md for details.
We welcome contributions! Please see CONTRIBUTING.md for:
- How to set up the development environment
- Code style and quality guidelines
- Testing requirements
- Submission process for pull requests
PyNeats integrates with these established open-source projects:
| Library | Purpose | Link |
|---|---|---|
| PyContrails | Contrail prediction and atmospheric data | github.com/contrailcirrus/pycontrails |
| PyBADA | Aircraft performance modeling | github.com/eurocontrol-bada/pybada |
| open-airclim | Climate response functions and GWP | github.com/dlr-pa/oac |
For questions, bug reports, or feature requests, please open an issue on GitHub.