Olus — Airline Disruption Simulation & Recovery Engine
The Problem
Airline operational disruptions — weather, mechanical failures, crew duty limits, and ATC ground stops — cost the global aviation industry an estimated $34 billion per year. When a single hub airport closes for three hours, the ripple effect can ground hundreds of flights, strand thousands of passengers, and cascade crew duty-time violations across an entire network for days.
Traditional airline operations control (AOC) systems rely on manual recovery decisions made under extreme time pressure with incomplete information. Dispatchers juggle spreadsheets, phone calls, and aging terminals to reassign aircraft, reroute crews, and reaccommodate passengers — often optimising one constraint while unknowingly violating another.
Olus gives operations engineers, researchers, and airline strategists a platform to:
- Simulate realistic disruption scenarios across a full flight network
- Predict cascade failures before they propagate
- Optimise recovery plans that satisfy FAR 117 crew-duty regulations and a MILP cost objective simultaneously
- Compare recovery strategies side by side under four competing objectives
It runs on a synthetic carrier — Nimbus Air — and optionally overlays live US flight positions and weather/ATC events pulled from public feeds.
Design Philosophy: a deterministic in-memory simulator
Olus is intentionally stateless and in-memory. On startup the API loads the
Nimbus Air network from YAML and holds the entire world in process — there is no
database, no cache, no message queue, and no auth tier to provision. Every
simulation run is deterministic and reproducible, which makes the engine easy to
reason about, test, and deploy: a single API container plus the web frontend.
Live data (real ADS-B positions, weather alerts, ATC ground stops) is fetched over
HTTPS on demand and cached in memory; the app degrades gracefully to the synthetic
network when those feeds are unavailable.
Architecture
+---------------------------------------------------------------+
| Browser / Client |
| Next.js 15 (App Router, TypeScript) |
| Leaflet | Recharts | Zustand | TanStack Query |
+---------------------------+-----------------------------------+
| REST + WebSocket (/ws/simulation)
+---------------------------v-----------------------------------+
| FastAPI (Python 3.11) |
| in-memory, stateless |
| |
| +------------------+ +----------------+ +--------------+ |
| | Disruption Engine| | FAR 117 Engine | | MILP Solver | |
| | (11 event types) | | (duty limits) | | (OR-Tools) | |
| +------------------+ +----------------+ +--------------+ |
| |
| +------------------+ +----------------+ +--------------+ |
| | Cascade Predictor| | Recovery | | Heuristic | |
| | (physics + | | Explainer + | | Fallback | |
| | optional XGB) | | Cost model | | | |
| +------------------+ +----------------+ +--------------+ |
+----------------+--------------------+-------------------------+
| |
+--------v------+ +--------v--------+
| YAML network | | Live feeds |
| airports / | | OpenSky (ADS-B)|
| aircraft / | | NWS alerts |
| flights /crew | | FAA NAS status |
+---------------+ +-----------------+
Features
Disruption Simulation (11 Event Types)
| Event Type | Description |
|---|
weather_closure | Airport made unavailable by severe weather |
ground_stop | ATC halts departures to/from an airport |
airspace_closure | A polygon of airspace is blocked, forcing reroutes |
security_event | Airport closed for a security incident |
mechanical_aog | A specific aircraft grounded (aircraft-on-ground) |
crew_sickout | N% of crews become unavailable |
runway_closure | Reduced airport capacity |
atc_staffing | Reduced ATC throughput |
volcanic_ash | Ash cloud forces wide-area rerouting |
cyber_incident | Slower aircraft turnarounds network-wide |
drone_incursion | Runway operations suspended — duration unknown at trigger time |
Eleven canned scenarios ship in data/scenarios/ (e.g. chicago_ground_stop,
dfw_runway_closure, volcanic_ash_pacific, atl_security,
tan_son_nhat_drone).
drone_incursion is the one event type whose duration is not known when it
fires. It carries a log-normal closure-length distribution (default: median
45 min, p95 3 h) instead of an end time, its length depends on detection
confidence (pilot report vs. radar), and repeated suspensions of the same
sighting fold into a single incident rather than stacking as independent
events.
MILP Recovery Optimizer (OR-Tools CP-SAT)
- Constraint-programming model minimising weighted delay cost + cancellation penalty + crew-disruption cost
- Hard constraints: FAR 117 rest periods, aircraft availability, turnaround times
- Four competing objectives solved per disruption — Minimize Cost, Minimize Passenger Impact, Protect Tomorrow's Schedule, and Green Recovery — so operators can compare trade-offs
- Configurable solver timeout with an automatic heuristic fallback
- Uncertain horizon (
optimizer/uncertain.py): when a disruption's duration
is a distribution, the same CP-SAT model is solved across sampled closure
lengths. Each plan then reports an expected cost, a cost band, and regret
— how much more it costs than the best recovery available with hindsight
Cascade Predictor
- Predicts which downstream flights are at risk after a disruption (direct → 1st-order → 2nd-order propagation)
- Pure-physics propagation by default; an optional XGBoost model can be trained for sharper estimates
- Outputs counts and a ranked list of affected flights with delay estimates
FAR 117 Duty-Time Engine
- Implements FAR Part 117 rest and duty-limit logic
- Flags crew-legality violations introduced by candidate recovery plans
- Integrated directly into the optimizer's constraint layer
Live Data Overlay (no API keys required)
- OpenSky Network — real US ADS-B flight positions on the live map
- NWS (
api.weather.gov) — active weather alerts, geo-matched to Nimbus airports
- FAA NAS Status (
nasstatus.faa.gov) — live ground stops, GDPs, and departure delays
- METARs are fetched for monitored airports and refreshed on an interval
Quick Start
Option A — Docker Compose (full stack)
Prerequisites: Docker ≥ 24 and Docker Compose ≥ 2.20.
git clone https://github.com/mizuharaa/olus.git olus
cd olus
docker compose up --build
Two services start: olus-api (FastAPI, port 8000) and olus-web
(Next.js, port 3000). No external database or cache is provisioned — the API
loads its network from YAML at startup. Simulation/scenario state (disruption
timeline, recovery plans) is persisted locally to apps/api/state/olus.db
(SQLite) so a restart mid-scenario doesn't lose it; see
apps/api/NONDETERMINISM.md for what replay does and doesn't pin.
Optional: for higher-resolution live ADS-B, create an OpenSky API client at
https://opensky-network.org/my-opensky and set OPENSKY_CLIENT_ID /
OPENSKY_CLIENT_SECRET (or drop a credentials/credentials.json). Without
credentials the app uses anonymous OpenSky access and the synthetic network.
Option B — Local development
Backend (requires Python 3.11 and Poetry):
cd apps/api
poetry install # API runtime only
# poetry install --with train # add XGBoost/sklearn for predictor training
poetry run uvicorn src.main:app --reload --port 8000
Frontend (requires Node 18+):
cd apps/web
npm install
npm run dev # http://localhost:3000
API Reference
All endpoints are prefixed with /api/v1. Full interactive docs at /docs.
Network
| Method | Endpoint | Description |
|---|
| GET | /network | Full Nimbus Air network snapshot |
| GET | /airports · /airports/{id} | Airports |
| GET | /aircraft · /aircraft/{tail} | Aircraft fleet |
| GET | /crews | Crew pairings |
| GET | /schedule | Scheduled flights |
Flights (live + synthetic)
| Method | Endpoint | Description |
|---|
| GET | /flights · /flights/{id} | Scheduled flights |
| GET | /flights/live | Live ADS-B positions (OpenSky) |
| GET | /flights/search | Search flights |
| GET | /flights/status/opensky | OpenSky feed status |
Events / Disruptions
| Method | Endpoint | Description |
|---|
| GET | /events/types | The 11 disruption event types |
| GET | /events/scenarios | Canned scenarios |
| POST | /events/trigger | Inject a disruption |
| GET | /events/active | Active disruptions |
| DELETE | /events/{event_id} | Clear a disruption |
Recovery Optimizer
| Method | Endpoint | Description |
|---|
| POST | /recovery/solve | Solve recovery (returns the 4 objective plans) |
| GET | /recovery/plans | Retrieve computed plans |
| POST | /recovery/apply | Apply a plan to the live schedule |
| POST | /recovery/explain | Plain-language explanation of a plan |
| POST | /recovery/crew-overbooking | Crew-overbooking recovery analysis |
Prediction & Simulation
| Method | Endpoint | Description |
|---|
| POST | /predict/cascade | Predict cascade impact of a disruption |
| GET | /predict/history | Prediction history |
| GET | /simulator/state | Current simulator state |
| POST | /simulator/trigger · /simulator/reset | Drive the simulator |
| GET | /simulator/scenarios · POST /simulator/scenarios/{name}/load | Load a scenario |
| POST | /network/stress-test | Run a network stress test |
| POST | /playtest/cascade | Interactive cascade playtest |
Passengers, Weather & Live Feeds
| Method | Endpoint | Description |
|---|
| GET | /passengers/impact · /passengers/rebooking | Passenger impact & rebooking |
| GET | /passengers/hotels/{airport} · /passengers/compensation-policy | Reaccommodation |
| GET | /weather/metars · /weather/metar/{id} · POST /weather/refresh | METARs |
| GET | /live/faa-status · /live/weather-alerts · /live/national-snapshot | Live US ops feeds |
WebSocket
Connect to ws://localhost:8000/ws/simulation for real-time simulation updates
(simulation_update messages carry the active event, flight states, cascade
summary, and recovery plans; an initial connected message includes a full
state snapshot).
Tech Stack
Backend
| Component | Technology |
|---|
| Language | Python 3.11 |
| Web framework | FastAPI 0.115 + Uvicorn (REST + WebSocket) |
| Validation / config | Pydantic v2 + pydantic-settings |
| Optimiser | Google OR-Tools 9.10 (CP-SAT) |
| Numerics | NumPy |
| Cascade predictor (optional training) | XGBoost + scikit-learn |
| HTTP clients | httpx (OpenSky / NWS / FAA) |
| Logging | structlog |
| Network data | YAML (pyaml) |
Frontend
| Component | Technology |
|---|
| Framework | Next.js 15 (App Router) + React 19 |
| Language | TypeScript 5 |
| Map | Leaflet + react-leaflet (Carto Positron basemap) |
| Charts | Recharts |
| Client state | Zustand |
| Server state | TanStack Query |
| Styling | Tailwind CSS + shadcn/ui (Radix primitives) |
| Forms | React Hook Form + Zod |
| Motion / Icons | Framer Motion · lucide-react |
Infrastructure
| Component | Technology |
|---|
| Containerisation | Docker + Docker Compose (api + web) |
| Deployment | Vercel website; API container on AWS EC2 behind CloudFront |
| Prod IaC | Terraform (infra/aws/); infra/terraform/ is the retired ECS reference |
Project Structure
olus/
├── apps/
│ ├── api/ # FastAPI backend (in-memory)
│ │ ├── Dockerfile
│ │ ├── pyproject.toml
│ │ ├── smoke_test.py # end-to-end engine smoke test
│ │ ├── src/
│ │ │ ├── main.py # app entry point + lifespan
│ │ │ ├── core/ # config + logging
│ │ │ ├── routes/ # API route handlers
│ │ │ ├── events/ # 11 disruption event handlers + registry
│ │ │ ├── optimizer/ # OR-Tools MILP, explainer, crew overbooking
│ │ │ ├── predictor/ # cascade predictor
│ │ │ ├── crew/ # FAR 117 duty-time engine
│ │ │ ├── simulator/ # simulation engine
│ │ │ ├── network/ # stress-test engine
│ │ │ ├── costs/ # cost / carbon models
│ │ │ ├── data/ # OpenSky client
│ │ │ ├── weather/ # METAR / NWS client
│ │ │ └── ws/ # WebSocket handler
│ │ └── tests/ # pytest suite
│ └── web/ # Next.js 15 frontend
│ ├── app/ # App Router pages
│ ├── components/ # UI + simulator components
│ ├── stores/ # Zustand stores
│ └── lib/ # API client + WS hook
├── data/
│ ├── network/ # airports / aircraft / flights / crews YAML
│ └── scenarios/ # 11 canned disruption scenarios
├── scripts/
│ ├── generate_network.py # regenerate the Nimbus Air network
│ └── train_predictor.py # train the optional XGBoost cascade model
├── infra/terraform/ # AWS reference infrastructure
├── packages/schemas/ # shared Pydantic + TypeScript schemas
└── docker-compose.yml
Development
Tests
# Backend
cd apps/api
poetry run pytest -q
poetry run python smoke_test.py # end-to-end engine check
# Frontend
cd apps/web
npm run type-check
npm run build
Linting & Formatting
# Python
cd apps/api
poetry run ruff check src/
poetry run black src/
# TypeScript
cd apps/web
npm run lint
Regenerating the network
cd apps/api # uses repo-root data/ paths
poetry run python ../../scripts/generate_network.py
License
MIT License — Copyright (c) 2026 Olus Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Named after Olus, keeper of the winds in Greek mythology — because in aviation, the wind always has the final say.
