Skip to main content

AirSpaceSim

Aircraft Simulation and Airspace Visualization

AirSpaceSim is a simulation-first Python library for modeling aircraft movement in structured airspace and visualizing trajectories on map-based interfaces.

Purpose

AirSpaceSim exists to support:

  • trajectory prototyping
  • scenario generation for testing and research
  • visualization-driven debugging
  • repeatable simulation experiments

It is designed to be useful as a standalone simulator.

Scope

Current focus:

  • multi-aircraft movement simulation with both legacy thread-per-aircraft mode and scalable batched scheduler mode
  • waypoint and route processing (DMS and decimal coordinates)
  • map configuration and visualization helpers (Leaflet-compatible)
  • JSON-based aircraft state output for downstream tooling
  • CLI bootstrap with airspacesim init

Non-goals:

  • operational ATM/UTM control
  • certified safety-critical deployment
  • full 4D flight dynamics or weather-integrated ops modeling

Installation

From PyPI:

python3 -m venv .venv
source .venv/bin/activate
pip install airspacesim

From source:

git clone https://github.com/sankarebarri/AirSpaceSim.git
cd AirSpaceSim
pip install -e .

Offline-constrained source install (no index access):

pip install --no-build-isolation --no-deps -e .

If a fresh offline venv lacks setuptools, bootstrap it and install editable:

python3 scripts/offline_editable_install.py --venv .venv-offline

Offline install from local wheel:

python3 setup.py sdist bdist_wheel
pip install --no-index --find-links dist airspacesim

PyPI Release Checklist

From repository root:

# 1) clean old artifacts
rm -rf dist build *.egg-info

# 2) run quality gate
pytest -q
ruff check .

# 3) build distributions
python3 -m build

# 4) verify package metadata/rendering
python3 -m twine check dist/*

# 5) upload (requires PYPI_TOKEN in env)
python3 -m twine upload dist/*

Recommended:

  • publish first to TestPyPI with --repository testpypi before main PyPI.
  • tag release in git after upload.
  • if python3 -m build is unavailable in your environment, fallback build is:
    • python3 setup.py sdist bdist_wheel

Quick Start

Initialize project files in your working directory:

airspacesim init

Then run your simulation script (for example examples/example_simulation.py) and open templates/map.html in a browser.

The default generated data files are:

  • data/map_config.v1.json
  • data/airspace_config.json
  • data/airspace_data.json
  • data/scenario_airspace.v1.json
  • data/scenario.v0.1.json
  • data/scenario_aircraft.v1.json
  • data/inbox_events.v1.json
  • data/render_profile.v1.json
  • data/aircraft_data.json
  • data/aircraft_state.v1.json
  • data/trajectory.v0.1.json
  • data/ui_runtime.v1.json
  • data/aircraft_ingest.json

UI Simulation Test

Run these in separate terminals from your initialized project directory:

python3 examples/example_simulation.py

Optional quick run:

python3 examples/example_simulation.py --max-wait 5
python3 dev_server.py

Then open one of:

  • http://127.0.0.1:8080/templates/map.html
  • http://127.0.0.1:8080/airspacesim-playground/templates/map.html (when running simulation from airspacesim-playground)

Operator controls notes:

  • Use dev_server.py for POST support. Static-only servers (for example Live Server on :5500) may return 405 on /api/events.
  • SET_SPEED.payload.aircraft_id must be the aircraft ID (for example AC800), not callsign (for example OPS800).
  • ADD_AIRCRAFT now skips duplicate aircraft IDs instead of creating duplicate runtime entries.
  • Speed guardrails apply:
    • warning above 700 kt
    • rejection above 1200 kt (default mode)

Simulation Quality Tools

Stress scenario:

python3 -m airspacesim.examples.stress_simulation --aircraft 100 --duration 5 --speed 420

Performance benchmark:

python3 -m airspacesim.examples.benchmark_simulation --aircraft 200 --steps 50 --writes 25

Interoperability export example:

python3 examples/interoperability_export.py

Minimal Runnable Example

from airspacesim.utils.conversions import dms_to_decimal, haversine

wp1 = (16, 15, 0, "N"), (0, 2, 0, "W")
wp2 = (16, 30, 0, "N"), (0, 5, 0, "E")

lat1, lon1 = dms_to_decimal(*wp1[0]), dms_to_decimal(*wp1[1])
lat2, lon2 = dms_to_decimal(*wp2[0]), dms_to_decimal(*wp2[1])

distance_nm = haversine(lat1, lon1, lat2, lon2)
print(round(distance_nm, 2))

Edge-Case Example (Mixed Coordinates)

When creating aircraft routes, a waypoint can already provide decimal coordinates (dec_coords) while another uses DMS (coords). AircraftManager.add_aircraft(...) accepts both patterns and converts DMS waypoints during load.

routes = {
    "MIXED_ROUTE": [
        {"coords": {"lat": [16, 10, 0, "N"], "lon": [0, 3, 0, "W"]}},
        {"dec_coords": [16.45, 0.08]},
    ]
}

Interoperability

AirSpaceSim can act as a scenario and trajectory producer for:

  • conflict modeling pipelines (for example SPECTRA)
  • robustness/invariance audit pipelines (for example AIRE)
  • language + trajectory paired research workflows

Planned output contracts:

  • airspacesim.trajectory.v0.1 for time-stepped aircraft state
  • airspacesim.scenario.v0.1 for route and airspace definitions

Research vs Production Claims

Research claims:

  • suitable for simulation, prototyping, and experimentation workflows
  • useful for generating structured trajectory data for algorithm testing

Production claims:

  • none at this stage; this repo is not positioned as operational ATM software

Safety and Limitations

  • Not an operational separation assurance system
  • No regulatory assurance, certification, or operational safety case
  • Results depend on scenario design and model assumptions
  • Current packaging/docs need consolidation for full out-of-the-box setup

Roadmap

Execution milestones are in new_roadmap.md.

Operational/developer guide is maintained in documentation.md. Hands-on walkthrough is in docs/tutorial.md.

Ecosystem Compatibility

This project is independently usable and developed as a standalone system. It also supports interoperability with related ATC research tools through versioned data contracts and documented interfaces.

Metadata

Release files for AirSpaceSim 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for AirSpaceSim 0.1.3
File Size Uploaded Provenance Actions
airspacesim-0.1.3.tar.gz 67.8 kB Without provenance Details for airspacesim-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for AirSpaceSim 0.1.3
File Interpreter ABI Platform Actions
airspacesim-0.1.3-py3-none-any.whl Python 3 none any Details for airspacesim-0.1.3-py3-none-any.whl

Total release size: 144.1 kB

Release files / airspacesim-0.1.3.tar.gz

Download URL airspacesim-0.1.3.tar.gz
Size 67.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e852df791bc2a55d04bb40559391c78688ab9c25c45a68bb9a0a94377500940e
BLAKE2b-256 checksum
How to use checksums
37ba38820b3d16997f2d2b32cceac19a6f88329886eb4569e281709768a88f9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / airspacesim-0.1.3-py3-none-any.whl

Download URL airspacesim-0.1.3-py3-none-any.whl
Size 76.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ab6885d9043549874219096aeed179524ecc75af3a39c5be9aa269e1dea3227e
BLAKE2b-256 checksum
How to use checksums
649f116d58cb3bde2b32f85ea16f65c0a9d2a6145dd31d66eca96e9ed52fdf25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for AirSpaceSim 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page