# API Stability

HyPlan uses stability levels to set expectations about which modules
have settled APIs and which may still change.

## What the levels mean

**Stable** — The public API (function signatures, return types, class
constructors) will not change in backward-incompatible ways within a
major version (1.x).  Bug fixes and new optional parameters are
permitted.  If a breaking change becomes necessary, the old interface
will be deprecated for at least one minor release before removal.

**Experimental** — The module works and is tested, but the API may
change between minor releases based on user feedback.  Pin to a
specific version if you depend on exact signatures.

## Module stability levels

### Stable

| Module | Description |
|--------|-------------|
| `hyplan.FlightLine` | Flight line creation, splitting, clipping, offsetting |
| `hyplan.Waypoint` | Navigation waypoints with heading, altitude, speed |
| `hyplan.planning` | `compute_flight_plan` and segment record builders |
| `hyplan.planning.isochrone` | Wind-aware reachability boundaries (`compute_isochrone`, `compute_concentric_isochrones`, `compute_refuel_isochrone`, `evaluate_target_reachability`) — `wind_sampling="segmented_cruise"` is experimental |
| `hyplan.terrain` | DEM download, elevation lookup, ray-terrain intersection |
| `hyplan.swath` | Swath polygon generation and gap/overlap analysis |
| `hyplan.winds` | Wind field abstractions, MERRA-2, GMAO, GFS providers |
| `hyplan.aircraft` | Aircraft base class and pre-configured models |
| `hyplan.atmosphere` | ISA model and airspeed conversions (CAS/TAS/Mach) |
| `hyplan.exports` | Flight plan output formats (Excel, CSV, KML, GPX, FMS, ICARTT) |
| `hyplan.airports` | Airport database lookup and nearest-airport search |
| `hyplan.flight_box` | Flight box generation from center lines and polygons |
| `hyplan.flight_optimizer` | Graph-based flight line ordering |
| `hyplan.sun` | Solar position and illumination windows |
| `hyplan.glint` | Specular reflection (sun glint) prediction |
| `hyplan.clouds` | Cloud fraction climatology and forecasts |
| `hyplan.phenology` | Vegetation phenology from MODIS |
| `hyplan.satellites` | Satellite overpass prediction |
| `hyplan.airspace` | Airspace conflict detection (OpenAIP, FAA TFR/NASR) |
| `hyplan.dubins3d` | 3D minimum-turn path planning |
| `hyplan.flight_patterns` | Pattern generators (racetrack, rosette, spiral, etc.) |
| `hyplan.plotting` | Folium maps, altitude profiles, terrain cross-sections |
| `hyplan.geometry` | Geodesic math and coordinate utilities |
| `hyplan.units` | Pint unit registry and conversion helpers |

```{note}
Stable means the public API will not break within 1.x. Algorithms,
defaults, datasets, and edge-case behavior may still be improved.
Aircraft parameters (cruise speed, climb rate, endurance) will
continue to be refined as ADS-B calibration data becomes available.
```

### Experimental

| Module | Description |
|--------|-------------|
| `hyplan.instruments.LVIS` | Full-waveform lidar sensor model |
| `hyplan.instruments.SidelookingRadar` | SAR sensor model (UAVSAR variants) |
| `hyplan.instruments.FrameCamera` | Frame camera and multi-camera rig |
| `hyplan.campaign` | Campaign management and airspace conflict detection |
| `hyplan.aircraft.NASA_C20A` | NASA C-20A class — `calibration_status="inferred"` from `NASA_GIII`; type-certificate equivalence assumed |
| `hyplan.aircraft.NASA_GIV` | NASA G-IV — `calibration_status="uncalibrated"` (manufacturer brochure only) |
| `hyplan.aircraft.NASA_B777` | NASA B-777 — `calibration_status="uncalibrated"` (manufacturer brochure only) |
| `hyplan.aircraft.KingAirA90` | King Air A-90 — `calibration_status="uncalibrated"`; no public IWG1-grade A-90 data |
| `hyplan.aircraft.KingAir350` | King Air 350 / 350i — `calibration_status="uncalibrated"`; calibration deferred pending UW UWKA-2 ICARTT data access (`flights.uwyo.edu` and NCAR EOL) |
| `hyplan.aircraft.FAAM_BAe146` | FAAM BAe-146-301 (G-LUXE) — `calibration_status="calibrated"` from 125 CEDA core_processed sorties |
| `hyplan.aircraft.SAFIRE_ATR42` | SAFIRE ATR-42-320 (F-HMTO) — `calibration_status="calibrated"` from 44 sorties (CEDA EUFAR + AERIS EUREC4A) |
| `hyplan.aircraft.DLR_HALO` | DLR HALO Gulfstream G550 (D-ADLR) — `calibration_status="calibrated"` from 18 HALO-AC3 BAHAMAS sorties (single-campaign, confidence 0.7) |
| `hyplan.aircraft.BAS_TwinOtter` | BAS DHC-6 Twin Otter (MASIN) — `calibration_status="calibrated"` from 105 sorties across 5 CEDA archives (OFCAP, ACCACIA, ORCHESTRA, IGP, ArcticCyclones) |
| `hyplan.aircraft.NERC_DO228` | NERC ARSF Dornier 228 (D-CALM) — `calibration_status="calibrated"` from 32 sorties (CEDA ACTIVE 2005-2006 + Eyjafjallajökull 2010, TAS reconstructed via wind triangle) |

## Deprecation policy

When a stable API must change:

1. The old interface is preserved and emits a `DeprecationWarning` for
   at least one minor release.
2. The deprecation message names the replacement.
3. The old interface is removed in the next major version.

Experimental modules may change without a deprecation cycle, but
changes will be documented in the release notes.
