Open-ALAQS

QGIS plugin for airport emissions inventory and dispersion. Builds an annual emissions inventory from runway, taxiway, gate, stationary, engine-test-run, and movement sources, and exports AUSTAL-ready dispersion inputs.

Table of contents

• Open-ALAQS
  • Table of contents
  • Installation
    • Install QGIS
    • Install dependencies
    • Install Open-ALAQS
    • Upgrading from 5.3.x
  • Quick start
    • Example files
    • Training example study
    • Standalone Emissions + AUSTAL Inputs export script
  • Workflow
  • Emission calculation methods
  • Meteorological data
  • GSE Application
  • Development
    • Code style
    • Debugging
    • Updating the Open-ALAQS database templates
    • Unit tests
  • Validation
  • Recent changes
  • Contribute
  • License
  • Contact

Installation

(Back to top)

To use Open-ALAQS you need to install QGIS, plus a few external Python libraries the plugin depends on.

Install QGIS

Download and install QGIS for your operating system following the official QGIS documentation.

If you are running on Windows, install via the OSGeo4W installer following the Advanced Install route.

Note: If not installed using the OSGeo4W Network Installer, please uninstall any old version and install the new version using OSGeo4W or follow the QGIS installation guide. During installation, accept the unmet dependencies and license agreements.

Install dependencies

Open-ALAQS is built on top of QGIS and a few external libraries that require separate installation. The full list is in requirements.txt.

Primary method: Use QPIP (Python Dependency Manager for QGIS Plugins) to check and install the required dependencies directly inside QGIS. See the Install Open-ALAQS section below for details.

Alternative method: Install the libraries manually using pip install in the Python environment used by QGIS:

pip install -r requirements.txt

OSGeo4W manual installation

Find and install these packages from the OSGeo4W shell:

• qgis-ltr-full (3.34.x or newer)
• python3-fiona
• python3-geopandas (2.x.x)

Install Open-ALAQS

Open-ALAQS is published as a QGIS plugin. The plugin is the open_alaqs/ folder of the repository (the folder with metadata.txt), not the repository root.

From a plugin zip (a zip whose top folder is open_alaqs/): in QGIS, Plugins → Manage and Install Plugins → Install from ZIP, select the zip and click Install Plugin.

From a clone of the repository: copy (or link) the repository's open_alaqs/ folder into the QGIS plugin directory for your platform, so that metadata.txt ends up directly in:

• Windows: %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\open_alaqs\
• macOS: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/open_alaqs/
• Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/open_alaqs/

Then enable the plugin in the QGIS Plugin Manager (Plugins → Manage and Install Plugins → Installed → tick "open_alaqs", the name of the plugin folder).

The first time the plugin loads, QPIP will detect missing dependencies and offer to install them in the QGIS Python environment:

After dependencies are installed, restart QGIS once and Open-ALAQS will be available from the menu and toolbar:

Upgrading from 5.3.x

Several results change with this version, and a study made with 5.3.x keeps its own copy of the engine, aircraft and profile tables, which are copied into every new inventory. See Upgrading from 5.3.x in the User Guide for the list of changes, the studies they affect and how to update a study.

Quick start

(Back to top)

Example files

Two example studies ship with the repository:

• example/training/ — a self-contained study used for tutorials and validation, including pre-computed reference values to compare your run against.
• tests/data/AIRPORT_A/ — the same study used by the regression test suite, with full pre-computed emissions tables and APU/CAEP14 comparison spreadsheets. The two spreadsheets (AIRPORT_A_APU_comparison.xlsx, AIRPORT_A_CAEP14_comparison.xlsx) date from the 5.0.0 rebuild and predate the 5.4.0 changes to aircraft SOx, MEEM V1 and runway placement: their numbers are not those of a current run.

Training example study

The training study lives in example/training/ and contains:

• training.alaqs — the unprocessed study database (geometry, sources, study setup)
• training_out.alaqs: the processed inventory database (output of Calculate Emissions Inventory)
• training_movements.csv — aircraft movements input
• training_meteo.csv — hourly meteorological input
• training_ads_b_data.csv: ADS-B tracks, imported into the inventory when it is generated (movement 11 flies 1764584438_PHBBA)
• training_validation_reference.xlsx: reference values for verifying your installation (the plugin's results on training_out.alaqs beside the CAEP14 reference implementation, per movement and method)

For a step-by-step walk-through of opening, configuring, and running a study, see the User Guide.

Standalone Emissions + AUSTAL Inputs export script

Two standalone paths to run Open-ALAQS outside the QGIS plugin are shipped:

QGIS-bound CLIs (scripts/). Use the plugin's libraries directly under an OSGeo4W shell or QGIS Python:

• scripts/emissions_austal/run_emissions_austal.py runs the full emissions calculation against a .alaqs inventory and optionally generates AUSTAL inputs in one pass. See scripts/emissions_austal/README.md.
• scripts/austal_from_csv/run_austal_from_csv.py generates AUSTAL inputs from pre-computed emissions / meteo CSVs (no .alaqs required). See scripts/austal_from_csv/README.md.
• scripts/metar_to_alaqs_meteo.py converts METAR observations into the meteo.csv format (see scripts/README_metar_to_alaqs_meteo.md).
• scripts/migrate_alaqs.py is the schema migration tool for upgrading legacy .alaqs files; scripts/migrate_alaqs_gui.py is the Qt GUI wrapper.

QGIS-free package (openalaqs_standalone/). A Python package that runs the full emission calculation without QGIS, PyQt5, or SpatiaLite at runtime; it imports QGIS-free modules of the plugin tree, so it runs from the repository root (see its USAGE). Uses pyproj + shapely + numpy. Designed for headless / CI / cluster use and for batched validation against the CAEP14 reference.

• Package: openalaqs_standalone/ (see its README)
• AUSTAL writer helpers used by the standalone live in austal_prep/
• Validation: openalaqs_standalone/validation/tools/CAEP14_VALIDATION.md and the bundled training_v3.alaqs fixture.
• Optional Reference A NOx ambient correction: --apply-nox-corrections (default off; preserves bymode bit-identity with the plugin).

See scripts/README.md for the full inventory of QGIS-bound CLIs.

Workflow

(Back to top)

1. Build the airport study (runways, taxiways, gates, stationary sources) in a QGIS project.
2. Open Calculate Emissions Inventory (window Generate Emission Inventory) to bake the study into an inventory database (*_out.alaqs), supplying a movements CSV, a meteorological CSV (see Meteorological data) and, optionally, an ADS-B CSV.
3. Open Visualize Emission Calculation on the inventory to calculate emissions with the selected method; they are calculated when an output (table, time series, vector layer) is requested.
4. For dispersion runs, see documents/AUSTAL/AUSTAL_OPERATION.md.

For engine test runs (run-ups), an extra step between 1 and 2: mark the area source(s) that represent the run-up pad as engine test sites via the QGIS form ("Engine Test Site" checkbox), then load the events via the "Load engine test events CSV..." button on the same form (or, for scripting workflows and multi-source bulk-load, scripts/import_engine_test_events.py). Per-event masses are then included in the inventory automatically; the source's *_kg_unit rate columns are ignored.

Emission calculation methods

(Back to top)

Open-ALAQS ships three aircraft emission methods selectable at run time:

• bymode — multiplies anchor-mode fuel flow × anchor-mode EI × time × engine count. No ambient corrections. Use as a tautological baseline.
• BFFM2 (trajectory) — default BFFM2 path. For each trajectory segment resolves fuel flow from the segment's sub-mode power setting via the twin-quadratic fit, applies SAE AIR-5715 atmospheric corrections for NOx, and snaps CO/HC to the horizontal mean(CL, TO) value above the APP anchor in the standard-intersection case (CAEP14 v14 rule).
• BFFM2 (mode_anchor) — uses the mode anchor fuel flow (IDLE/APP/CL/TO EEDB values) as the BFFM2 input, still applying ambient corrections. Useful when trajectories lack per-segment sub-mode fidelity.
• Helicopters (FOCA 2015) — separate dispatch for movements flagged as helicopters. Four FOCA categories (PISTON, SINGLE_TURBOSHAFT, TWIN_TURBOSHAFT_LIGHT/HEAVY) with per-category trajectories and emission indices. APU and gate emissions are suppressed; airborne emissions only. See documents/USER_GUIDE.md for category derivation and documents/HELICOPTER_TRAJECTORIES.md for the data sources.

PM is via MEEM V1: the certified EEDB nvPM values in the LTO cycle and the MEEM V1 altitude chain above it. MEEM V2 (CAEP14 v12+) is implemented in meem_v2.py for evaluation only and is not used by the calculation. The MDG4 / Staged Combustion update is not implemented.

For BFFM2 implementation details see documents/BFFM2_validation/BFFM2.md.

Engine test runs

A separate calculation path handles engine test runs (run-ups) as stationary sources. An area source flagged as a test site (is_test_site='1') has its emissions computed from per-event rows in the engine_test_events table rather than from the source's *_kg_unit rate columns. Each event carries a start/end datetime, an aircraft type and engine, a per-mode duration (t_TX_s / t_AP_s / t_CL_s / t_TO_s), and a thrust_mode (snap / meem / bffm2).

• snap — plain ICAO EEDB EI for each mode. Default. No ambient corrections.
• meem — nvPM correction (MEEM V1). Numerically identical to snap for engine-test events because engine test modes correspond to ICAO EEDB anchor thrust settings; interpolation at an anchor returns the anchor's own value.
• bffm2 — gas-phase EIs (NOx, CO, HC) corrected with ambient conditions from tbl_InvMeteo at each event's midpoint (SAE AIR-5715 / CAEP14). PM10 and SOx pass through from the EEDB per-mode. If tbl_InvMeteo is empty, bffm2 falls back to ISA defaults with a one-per-run diagnostic.

The default across every event is snap; users opt into meem or bffm2 per-event via a SQL update on engine_test_events.thrust_mode. Both EngineTestSourceModule (plugin) and openalaqs_standalone/compute_engine_test.py (standalone) implement the same math bit-for-bit. See the Engine test sites subsection of documents/USER_GUIDE.md for the setup workflow.

Meteorological data

(Back to top)

Open-ALAQS expects an hourly meteo CSV during output creation. A standalone utility for producing it from a METAR stream ships in scripts/:

• scripts/metar_to_alaqs_meteo.py — parses raw METAR, IEM CSV, or Ogimet observations (--source {auto,iem-csv,ogimet,raw}), computes relative humidity from T/Td, buckets hourly (wind direction averaged on the circle), classifies stability (Pasquill-Gifford with the mid-hour sun and a night-time humidity correction, --night-rule), writes the ALAQS-schema CSV.
• scripts/README_metar_to_alaqs_meteo.md — usage and notes on where to fetch METAR data (NOAA Aviation Weather Center, ogimet.com, metar-taf.com API, python-metar). Fetching is deliberately left to the user; the script focuses on parsing and resampling.

GSE Application

(Back to top)

A separate companion utility for ground support equipment (GSE) emissions lives in gse_application/. Launch with:

python3 gse_application/gse.py

See gse_application/README.md for full documentation.

Development

(Back to top)

Code style

Open-ALAQS uses pre-commit to enforce code style and basic checks (autoflake, isort, black, flake8). Hooks run on every commit if pre-commit is installed in your local clone:

pip install pre-commit
pre-commit install

Debugging

For inspecting plugin state interactively, use QGIS's Python console (Plugins → Python Console). For step debugging, install the QGIS Dev Tools plugin (debugpy backend) and attach from VS Code or PyCharm.

Updating the Open-ALAQS database templates

The plugin's .alaqs files are cloned from two template databases at open_alaqs/core/templates/project.alaqs (the project file users edit in QGIS) and open_alaqs/core/templates/inventory.alaqs (the inventory output file produced by Calculate Emissions Inventory).

Templates are built by tools/template_build/generate_templates.py from three inputs:

• tools/template_build/spatialite_base.alaqs — the bare SpatiaLite scaffold
• tools/template_build/sql/*.sql — table-creation scripts
• open_alaqs/database/data/*.csv — frozen reference-data CSVs

To regenerate the templates after editing source files:

python3 tools/template_build/generate_templates.py

The script needs a working QGIS Python environment; see tools/template_build/README.md for the exact invocation on each platform.

Unit tests

The full test suite runs offscreen and requires no display:

QT_QPA_PLATFORM=offscreen PYTHONPATH=$PWD python3 -m pytest tests/

Most tests need QGIS available on the Python path. CI runs the suite in a QGIS Docker container (3.40 and 3.44 matrix); see .github/workflows/.

Validation

(Back to top)

The BFFM2 emission-index step is pinned to two cases of the CAEP validation (EUROCONTROL's CAEP/14 engine-emissions calculation; test_caep14_sheet_reference_case.py), and MEEM V1 to the MEEM_V1 tab of the CAEP14 calculation sheet v14 (tests/test_meem_v1.py); in the LTO cycle MEEM V1 returns the EEDB nvPM values unchanged. The CAEP validation does not cover how a fuel flow is derived from the profile: for the whole method (bymode, BFFM2 trajectory, BFFM2 mode_anchor, the NOx correction and the helicopters), the plugin, the QGIS-free standalone and the project's own CAEP14 reference implementation (compute_caep14_reference.py, which imports the plugin's BFFM2 index function and FOCA tables) agree movement by movement on the training fixtures. See openalaqs_standalone/validation/tools/CAEP14_VALIDATION.md and documents/VALIDATION_GUIDE.md. The sensitivity options on the trajectory method's fuel flow are described in documents/FUEL_FLOW_OPTIONS.md.

The BFFM2 method itself is described in documents/BFFM2_validation/BFFM2.md.

Recent changes

(Back to top)

See CHANGELOG.md for fixes and behaviour changes in this and previous releases.

Contribute

(Back to top)

Contributions are welcome. Please open an issue to discuss substantive changes before submitting a pull request, so the work is aligned with what the project needs. For small fixes (typos, documentation corrections, missing test cases), a direct pull request is fine.

When opening a pull request:

• Run the test suite locally and confirm it passes.
• Run pre-commit run --all-files and confirm all hooks pass.
• Include a regression test for any behaviour change.
• Reference the issue number in the PR title or body.

License

(Back to top)

This software is published under European Union Public Licence v. 1.2 (LICENCE.md) with certain amendments described in AMENDMENT_TO_EUPL_license.md, reflecting EUROCONTROL's status as an international organisation.

Contact

(Back to top)

For questions, bug reports, or feature requests, contact us by email at open-alaqs@eurocontrol.int.