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.ALSLidar`	Scanning-mirror topographic lidar sensor model + RIEGL VQ-480 II reference instance; locked public API on nominal-density semantics, contiguity, MTA envelope, inverse solvers, and LVIS-parity terrain-aware methods
`hyplan.instruments.MultiALSLidarRig`	Multi-lidar rig (G-LiHT dual VQ-480i reference); pitch/roll-tilt mount geometry, combined swath/density, multi-angle pair detection
`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:

The old interface is preserved and emits a DeprecationWarning for at least one minor release.
The deprecation message names the replacement.
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.