Highrise-fire-uav-response-demo

Simulation demo: coordinating a small fleet of UAVs to suppress fires on upper floors of a 130-floor building (facade operations only).
Goal: a clean, auditable baseline for planning, allocation, safety logic, and simple performance metrics.
Python 3.10+

Educational simulator — not an engineering guarantee. No indoor flight, no CFD, no certified safety.

---

Repository structure

highrise-fire-uav-response-demo/
├─ configs/
│  ├─ default.yaml
│  └─ tethered_case.yaml
├─ data/
│  ├─ building_130f.json
│  ├─ wind_profiles.yaml
│  └─ scenarios/
│     ├─ case_small.yaml
│     └─ case_multi.yaml
├─ reports/
│  ├─ .gitkeep
│  ├─ paths_demo.png
│  └─ summary_demo.json
├─ src/
│  ├─ __init__.py
│  ├─ env.py
│  ├─ dynamics.py
│  ├─ safety.py
│  ├─ sensing.py
│  ├─ allocation.py
│  ├─ planner.py
│  ├─ controller.py
│  ├─ agents.py
│  ├─ suppression.py
│  ├─ sim_loop.py
│  ├─ eval_metrics.py
│  ├─ visualize.py
│  ├─ plan_tethered.py
│  └─ run_scenario.py
├─ tests/
│  ├─ __init__.py
│  ├─ test_allocation.py
│  ├─ test_planner.py
│  ├─ test_safety.py
│  ├─ test_tethered.py
│  └─ test_run_tethered_smoke.py
├─ .gitignore
├─ Makefile
├─ CHANGELOG.md
├─ LICENSE
├─ README.md
├─ requirements.txt
└─ requirements-dev.txt


## Quick start

```bash
# 1) Install runtime deps
pip install -r requirements.txt

# 2) (optional) Dev/test tools
pip install -r requirements-dev.txt

# 3) Run default scenario
python -m src.run_scenario --config configs/default.yaml

# Artifacts (written to ./reports)
# - reports/mission_log.csv   (per-step events)
# - reports/summary.json      (aggregated metrics)
# - reports/paths.png         (paths + fire locations)


Run a Specific Scenario (paste as code)

python -m src.run_scenario \
  --config configs/default.yaml \
  --scenario data/scenarios/case_small.yaml


Tests (paste as code)

pytest -q


Artifacts (Example)

Paths plot
Use reports/paths.png (generated) or the demo image reports/paths_demo.png.


Summary (JSON)

{
  "response_time_s": 142.5,
  "coverage_pct": 1.0,
  "temp_drop_proxy": 12.8,
  "safety_score": 0.05,
  "mission_score": 0.6029999999999999
}


Makefile shortcuts

make setup     # pip install -r requirements.txt
make run       # run default scenario
make run-small # run case_small scenario
make test      # pytest -q
make clean     # remove reports/*.csv|*.json|*.png



Inputs

Building: data/building_130f.json — discrete facade grid (130 floors), cell size, access points, no-fly zones.

Wind profile: data/wind_profiles.yaml — piecewise-linear wind magnitude (m/s) vs altitude (m).

Scenarios: data/scenarios/*.yaml — fire cells (id, x, y, intensity) and UAV starting points.



What the Simulator Does

Environment: 2.5D facade; altitude-dependent wind; no-fly masks.

Allocation: Hungarian algorithm over ETA matrix (min arrival time).

Planning: A* (4-neighbors) with wind penalty in edge cost.

Control: waypoint tracking (PID-like), speed clamp.

Safety: geofence margin, gust limit (stub), RTL at low battery.

Suppression: flow-based temperature-drop proxy (intensity ↓).

Metrics:

response_time_s — time to first arrival,

coverage_pct — fraction of fires extinguished,

temp_drop_proxy — accumulated cooling proxy,

safety_score — normalized penalty for violations,

mission_score — 0.4*coverage + 0.3*temp − 0.3*penalty.

Reports: CSV log, JSON summary, PNG path plot.


Example console output

=== Highrise UAV fire response demo complete ===
Logs:     reports/mission_log.csv
Summary:  reports/summary.json
Plot:     reports/paths.png


Limitations

Facade-only; simplified wind/physics; no CFD/smoke occlusion.
Constant UAV parameters; single-shot planning (demo); no refills/multi-goal routing.
For research/education only.

Note: The repo includes example artifacts:

reports/paths.png — generated by running the simulator,

reports/paths_demo.png, reports/summary_demo.json — illustrative samples.



Tethered Nozzle Mode (roof-fed hose)

New scenario: configs/tethered_case.yaml.

Adds quasi-static hose (gravity + wind drag), suspended nozzle, and gentle safety nudges.

New metrics in reports/summary.json:
time_on_target_s, ir_over_limit_s, tension_N_peak, min_bend_radius_m.


Quick run (tethered):

python -m src.run_scenario --config configs/tethered_case.yaml

(tests use fires/starts from data/scenarios/case_small.yaml)


Roadmap

Hex grid + corridor channels; refills and multi-goal routes.

Stronger wind/smoke models; basic CV (thermal/video) detector stub.

Multi-agent policies (task re-allocation, comms loss); ROS2/Gazebo bridge.

Richer safety taxonomy and per-event dashboards.


Versioning
This project follows Semantic Versioning. See CHANGELOG.md for releases and notes.

## [0.2.0-pre] - 2025-11-17
### Added
- Tethered nozzle (roof-fed hose) mode + hose model & safety checks.
- Scenario `configs/tethered_case.yaml`.
- Online/time-weighted metrics: `time_on_target_s`, `ir_over_limit_s`, `tension_N_peak`, `min_bend_radius_m`.

### Changed
- README: scenarios and quick run for tethered mode.

---
## [0.1.0] - 2025-11-16
### Added
- Initial public release: baseline simulator, smoke tests, CI.


License

See LICENSE for details (MIT recommended).
If you need a different license for integration/teaching, open an Issue.


Contributing

Issues and PRs are welcome. Please keep changes small and focused (one feature or fix per PR) and include tests where applicable.