Metadata-Version: 2.4
Name: dhcp-simulator
Version: 2.9.0
Summary: Educational deterministic drone hub control port simulator
Project-URL: Homepage, https://github.com/lastforkbender/dhcp-simulator
Project-URL: Repository, https://github.com/lastforkbender/dhcp-simulator
Project-URL: Changelog, https://github.com/lastforkbender/dhcp-simulator/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/lastforkbender/dhcp-simulator/issues
License-Expression: MIT
License-File: LICENSE
Keywords: digital-twin,drone,education,simulation,uas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Provides-Extra: database
Requires-Dist: alembic>=1.13; extra == 'database'
Requires-Dist: sqlalchemy>=2.0; extra == 'database'
Provides-Extra: postgres
Requires-Dist: alembic>=1.13; extra == 'postgres'
Requires-Dist: geoalchemy2>=0.15; extra == 'postgres'
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
Requires-Dist: sqlalchemy>=2.0; extra == 'postgres'
Provides-Extra: test
Requires-Dist: hypothesis>=6; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Provides-Extra: ui
Requires-Dist: pyqt6-webengine>=6.7; extra == 'ui'
Requires-Dist: pyqt6>=6.7; extra == 'ui'
Requires-Dist: pyqtgraph>=0.13; extra == 'ui'
Provides-Extra: ui-test
Requires-Dist: pyqt6>=6.7; extra == 'ui-test'
Requires-Dist: pytest-qt>=4.4; extra == 'ui-test'
Description-Content-Type: text/markdown

# Drone Hub Control Port Simulator — v2.9.0-sim

DHCP is a deterministic drone-port hub simulation model for education, research,
software engineering, and supervised training exercises. Its fleet is
**all-unmanned cargo drone/UAS** across the educational `PARCEL`, `LARGE`,
`HEAVY`, and `EXTRA_HEAVY` payload classes. It connects UAS, missions, cargo
custody, batteries, pads, personnel, facilities, weather, maintenance, traffic
coordination, recovery, alarms, replay, analytics, and persistence through one
shared simulation session.

> **SIMULATION / EDUCATIONAL USE ONLY.** DHCP cannot connect to or command a
> live aircraft. It models no manned aircraft and no onboard pilots, crew, or
> passengers; operators remain at the simulated ground-operations center. Its
> maps are not navigational products. Simulated
> authorizations, maintenance releases, airworthiness decisions, and training
> scores are not regulatory approvals, certifications, or evidence that a
> real-world operation is safe.

## v2.9 validation and reproducibility foundation

This candidate extends the v2.8 mixed-class foundation without changing
control authority:

- one deterministic mixed fleet with `PARCEL`, `LARGE`, `HEAVY`, and
  `EXTRA_HEAVY` educational UAS profiles;
- 52 immutable parameter-evidence records—13 for each class—with units, local
  source, derivation, uncertainty, validity range, and a stable model identity;
- 20 pinned vendor-independent reference scenarios and a bounded 972-case
  sensitivity corpus, all packaged locally with no runtime network dependency;
- ten session-integrated phases: `CLIMB`, `CRUISE`, `DESCENT`,
  `HOVER_DWELL`, `RETURN`, `APPROACH`, `GO_AROUND`, `HOLD`, `ALTERNATE`, and
  `COMPLETE`;
- explicit simulation-only landing authorization and model-validity holds for
  route or environmental inputs outside declared ranges, with invalid payload
  or unsupported configuration rejected before commit;
- fail-closed landing defaults, a profile-reserve gate applied to projected
  post-descent battery, and detached disclosure of the required reserve and
  signed projected reserve margin;
- hub recovery only after a non-alternate detailed flight is `COMPLETE` and
  grounded, plus a separate simulated alternate-site descent authorization
  that creates no hub-pad or turnaround handoff;
- incrementally maintained deterministic replay evidence bound to release,
  seed, normalized bounded inputs, model configuration, authoritative state,
  and documented numerical tolerances;
- SQLite schema 12 with normalized model-configuration and replay evidence
  written from detached session/checkpoint data, with checkpoint hash
  verification and reset-generation invalidation of stale asynchronous
  persistence completions;
- class-aware payload, mass, energy, wind, link, speed, altitude, endurance,
  freshness, and status monitoring;
- payload-class compatibility checks in cargo/dispatch workflows;
- distinct code-native map silhouettes for each class, while fill colors remain
  reserved for operational phase and emergency/warning state;
- a dedicated **Heavy Transport Operations** workspace with generic generated
  class illustrations and current simulated read-only telemetry;
- context-aware telemetry in the persistent selected-UAS inspector;
- professional semantic alarm audio: silent initial baseline, cues only for new
  warning/critical alarms and one-time resolutions, cooldown/deduplication,
  replay suppression and live re-baselining, mute/volume controls, and a
  fail-silent asynchronous Qt adapter; and
- bounded audio histories/playback, detached-snapshot observation, and no link
  from sound or presentation code to simulation control authority.

The model configuration identity for this candidate is
`de52a82a31642cd8bd6ba4176b05603c76958c0a1426c01582aa64088841862d`.
All 52 parameter records, all reference scenarios, and all sensitivity cases
remain `ESTIMATED`; every parameter is `NOT_CALIBRATED`. No accepted empirical
calibration dataset is included.

The product-facing release identity remains `2.9.0-sim`. The public Python
distribution uses the PEP 440 version `2.9.0`; PyPI does not permit upstream
projects to publish local `+sim` version identifiers.

The default mixed-fleet Phase 29 reference missions use local one-way routes of
1.5 km for `LARGE`, 1.2 km for `HEAVY`, and 4.0 km for `EXTRA_HEAVY`. These
values replace older generic initialization distances that were not feasible
after full climb, delivery dwell, return, approach, and class reserve
accounting. They are deterministic scenario fixtures, not calibrated ranges or
claims of maximum capability.

The class labels are a **DHCP educational taxonomy**. They are not legal,
regulatory, certification, airworthiness, or vendor product categories. The
included performance values are transparent non-certified reference models,
not exact digital twins and not suitable for real loading, route, reserve,
dispatch, or flight planning. Internal Python names such as `Aircraft` are
neutral domain/type names retained for compatibility; every modeled vehicle in
this release is an unmanned cargo UAS.

The detailed evidence, residual risks, and acceptance gates are recorded in
[`documentation/FULL_SWEEP_ENGINEERING_AUDIT.md`](documentation/FULL_SWEEP_ENGINEERING_AUDIT.md).
The mixed-class model, reference attribution, UI semantics, and limitations are
documented in
[`documentation/HEAVY_TRANSPORT_OPERATIONS.md`](documentation/HEAVY_TRANSPORT_OPERATIONS.md).
The evidence schema and current validation status are documented in
[`documentation/MODEL_EVIDENCE_AND_CALIBRATION.md`](documentation/MODEL_EVIDENCE_AND_CALIBRATION.md)
and
[`documentation/PHASE_29_VALIDATION_REPORT.md`](documentation/PHASE_29_VALIDATION_REPORT.md).

The exact final source passed 536/536 tests, the critical Ruff and bytecode
gates, clean-wheel mixed-fleet/evidence/all-phase/schema/artwork/headless smoke,
and a 3,600-tick / 1,800-simulated-second 50-UAS core/authority soak. That soak
recorded 83.319 ms p95, 5.574 MiB retained RSS growth after warm-up, bounded
histories, recovered injected observer/subscriber/persistence/worker/queue
failures, and a separate responsive authority thread. The external handoff
records final archive checksums. Cross-platform replay, Qt/EGL rendering, real
audio-device playback, and empirical calibration/independent validation remain
open. This README does not declare Phase 29 fully closed.

## Modeled hub

Drone Hub Alpha includes an Operations Center; cargo receiving, inspection,
sorting, storage, and staging; four launch/recovery pads; a maintenance hangar;
battery vault and charging bank; weather and RF facilities; and an Emergency
Landing Zone. The shared model covers:

- cargo custody, dispatch assignment, launch readiness, and release holds;
- mixed-class unmanned cargo-UAS route execution, delivery, return, recovery,
  and turnaround;
- maintenance findings, work orders, parts, airworthiness release, and fleet
  reliability projections;
- batteries, staffing, facility occupancy, operating limits, weather, airspace
  intents, conflicts, sequencing, and hub capacity;
- telemetry freshness and fault injection, alarms, operational timeline,
  replay checkpoints, analytics, resilience, and training assessment; and
- explicit SQLite snapshots with hash-chained audit records.

The PyQt6 console provides role-aware navigation, shared UAS focus,
professional custom iconography, dense operational workspaces, and persistent
simulation-boundary labeling. The current Operations Map is a native
simulation-driven situational display. A provider-neutral model and packaged
MapLibre shell exist, but full MapLibre/WebEngine rendering is a future
integration and must not be represented as delivered.

## Architecture in brief

The `SimulationSession` is the only source of running exercise truth.
Automatic ticks are submitted to one bounded simulation authority rather than
executed by the GUI thread. UI pages and observer services consume detached
snapshots; background workers receive isolated payloads and cannot mutate live
domain state. A failed core tick restores its checkpoint and pauses in degraded
mode. A failed observer, page refresh, or persistence task is contained and
reported without becoming a silent safety bypass.

Detailed flight phases run inside that same authority transaction. UI and
persistence receive detached phase/evidence snapshots; neither can authorize
landing, issue a flight directive, or resume an out-of-validity model hold.

This is fault containment, not a promise to survive every interpreter,
operating-system, hardware, or out-of-memory failure.

## Requirements

- Python 3.11 or newer
- PyQt6 6.7 or newer for the operations console
- PyQt6-WebEngine for future/experimental WebEngine map surfaces
- SQLite through the Python standard library for local persistence

SQLAlchemy/Alembic and PostgreSQL/PostGIS remain optional future repository
paths; the shipped repository is SQLite.

## Install and verify

Core simulation and tests:

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
pip install -e '.[test]'
python -m pytest
```

Operations console:

```bash
pip install -e '.[ui]'
python -m dhcp.apps.operations_console
```

Headless command-path demonstration:

```bash
python -m dhcp.apps.simulation_console
```

Some Linux hosts require the platform packages used by Qt for EGL/OpenGL and
X11/Wayland integration. Headless CI should install those libraries before
running Qt offscreen smoke tests.

## Persistence

Persistence is explicit. Constructing or advancing a session does not silently
write an operational database.

```python
from dhcp.simulation.session import SimulationSession

session = SimulationSession(database_path="drone_hub_alpha.sqlite3")
report = session.persist_operational_state()
print(report.saved_entities, report.database_path)
```

Each worker uses its own SQLite connection. The repository enables foreign
keys, WAL mode, versioned schema metadata, transactional commits, integrity
checks, and bounded retry for transient lock contention. SQLite remains a
single-host training default, not a multi-user operational service.
Schema 12 stores the 52 normalized parameter-evidence rows, current replay
identity, and detached checkpoint replay identities with the matching session
snapshot.

## Training use

A credible exercise should establish a scenario objective and expected
decisions, capture operator and system events, inject faults through simulation
controls, distinguish alarm acknowledgement from hazard resolution, and finish
with timeline/replay and an instructor-led after-action review. Automated
scores are evidence for discussion, not an autonomous pass/fail authority.
Alarm sounds are monitoring aids only: visual alarm state remains authoritative,
muting audio does not acknowledge or resolve anything, and an unavailable audio
device must not alter or halt the exercise.

## Known limits

- Flight, battery, weather, RF, conflict, and capacity models are deterministic
  abstractions. Phase 29 publishes estimated uncertainty and validity
  boundaries, but the models are not empirically calibrated or validated UAS
  or site performance models.
- `PARCEL`, `LARGE`, `HEAVY`, and `EXTRA_HEAVY` are project-local educational
  labels, not legal or certification classes; vendor figures are only industry
  payload reference points.
- Cargo center of gravity, detailed volume/geometry, dangerous-goods handling,
  class-specific pad/vertiport compatibility, battery thermal/degradation
  dynamics, terrain, and noise propagation require further modeling.
- Full MapLibre GL JS rendering is not yet integrated into the active console.
- There is no live vehicle, navigation, authorization, weather, or regulatory
  service adapter.
- Multi-user database coordination, distributed eventing, full human-factors
  validation, and certified training curricula remain roadmap work.
- Qt workspace rendering on a supported EGL/OpenGL host, real audio-device
  playback, final package verification, cross-platform replay, and the formal
  30-minute 50-UAS soak remain open validation gates.
- DHCP must not be used for real-world operations. Any real system must be
  independently engineered, authorized, secured, and validated outside this
  project.

## Governing documents

- [`documentation/ROADMAP_SOURCE.txt`](documentation/ROADMAP_SOURCE.txt)
- [`documentation/FULL_SWEEP_ENGINEERING_AUDIT.md`](documentation/FULL_SWEEP_ENGINEERING_AUDIT.md)
- [`documentation/MODEL_EVIDENCE_AND_CALIBRATION.md`](documentation/MODEL_EVIDENCE_AND_CALIBRATION.md)
- [`documentation/PHASE_29_VALIDATION_REPORT.md`](documentation/PHASE_29_VALIDATION_REPORT.md)
- [`documentation/HEAVY_TRANSPORT_OPERATIONS.md`](documentation/HEAVY_TRANSPORT_OPERATIONS.md)
- [`documentation/ARCHITECTURE.md`](documentation/ARCHITECTURE.md)
- [`documentation/RUNTIME_RELIABILITY_AND_CONCURRENCY.md`](documentation/RUNTIME_RELIABILITY_AND_CONCURRENCY.md)
- [`documentation/INDUSTRY_BENCHMARKS.md`](documentation/INDUSTRY_BENCHMARKS.md)
- [`documentation/UI_DESIGN_SYSTEM.md`](documentation/UI_DESIGN_SYSTEM.md)
- [`SECURITY.md`](SECURITY.md)
- [`CHANGELOG.md`](CHANGELOG.md)
