Aircraft¶

Aircraft performance models with speed profiles, climb/descent rates, turn radii, and endurance limits. 22 pre-configured research aircraft are included; custom aircraft can be created by instantiating Aircraft directly. Performance values for the pre-configured fleet live in editable JSON files at hyplan/data/aircraft/<short_name>.json (see the Profile I/O section below).

Fleet overview¶

The table below is auto-generated from the live hyplan.aircraft classes by python -m docs._gen_fleet_tables. Re-run it whenever calibration sortie counts or performance values change.

Class	Airframe	Operator	Tail(s)	Ceiling (ft)	Range (nmi)	Endurance (hr)	Engine	Calibration
`NASA_ER2`	ER-2	NASA AFRC	NASA 806	70,000	5,000	8.0	jet	calibrated
`NASA_GIII`	Gulfstream III	NASA LaRC	NASA 520	45,000	3,767	7.5	jet	calibrated · n=153
`NASA_GIV`	Gulfstream IV	NASA AFRC	NASA 817	45,000	5,130	7.5	jet	brochure only
`NASA_GV`	Gulfstream V	NASA AFRC	NASA 95	51,000	5,500	13.0	jet	calibrated · n=101
`NCAR_GV`	Gulfstream V	NSF/NCAR EOL	N677F	51,000	6,500	14.0	jet	calibrated
`NASA_C20A`	C-20A	NASA AFRC	NASA 502	45,000	3,400	6.0	jet	inferred
`NASA_P3`	P-3 Orion	NASA WFF	NASA 426	27,000	3,800	12.0	turboprop	calibrated · n=252
`NOAA_WP3D`	P-3 Orion (WP-3D)	NOAA AOC	N42RF + N43RF	27,600	3,800	12.0	turboprop	calibrated · n=96
`NOAA_GIV`	Gulfstream IV-SP	NOAA AOC	N49RF	47,500	4,220	8.5	jet	calibrated · n=93
`NASA_WB57`	WB-57	NASA JSC	NASA 926/927	63,000	2,500	6.5	jet	calibrated · n=100
`NASA_B777`	B777	NASA LaRC	Unknown	43,000	9,000	18.0	jet	brochure only
`KingAirA90`	King Air 90	Unknown	Unknown	30,000	1,500	6.0	turboprop	brochure only
`KingAirB200`	King Air 200	NASA (multiple)	multi-tail	30,000	1,632	6.0	turboprop	calibrated
`KingAir350`	King Air 350	Unknown	Unknown	35,000	2,100	5.0	turboprop	brochure only
`NASA_C130`	C-130H Hercules	NASA WFF	NASA 436	28,000	2,500	10.0	turboprop	calibrated · n=91
`NOAA_TwinOtter`	DHC-6 Twin Otter	NOAA	N48RF + N46RF	17,500	800	6.0	turboprop	calibrated · n=164
`BAS_TwinOtter`	DHC-6 Twin Otter	BAS	VP-FBL + VP-FBB	14,600	800	6.0	turboprop	calibrated · n=105
`FAAM_BAe146`	BAe-146-301	FAAM	G-LUXE	34,500	1,800	5.0	jet	calibrated · n=125
`SAFIRE_ATR42`	ATR-42-320	SAFIRE	F-HMTO	24,700	900	5.0	turboprop	calibrated
`NERC_DO228`	Dornier Do228-101	NERC ARSF	D-CALM	22,000	1,400	5.0	turboprop	calibrated
`AWI_BaslerBT67`	Basler BT-67	AWI	Polar 5 + Polar 6	25,000	1,600	6.5	turboprop	calibrated
`DLR_HALO`	Gulfstream G550	DLR	D-ADLR	44,300	6,750	10.0	jet	calibrated · n=18

See docs/calibration.md for the per-aircraft calibration provenance and a breakdown of the underlying data archives.

Base class¶

class Aircraft[source]¶

Bases: object

Aircraft performance model.

Holds identity, geometric constraints, phase-specific speed schedules, vertical performance profiles, turn model, and provenance metadata.

Parameters:

aircraft_type (str) – Aircraft model name (e.g. "Gulfstream V").
tail_number (str) – Tail number or "Unknown".
operator (str) – Operating organization.
service_ceiling (Quantity) – Maximum operational altitude.
approach_speed (Quantity) – Landing approach speed.
climb_schedule (CasMachSchedule | TasSchedule) – Speed schedule for climb phase.
cruise_schedule (CasMachSchedule | TasSchedule) – Speed schedule for cruise phase.
descent_schedule (CasMachSchedule | TasSchedule) – Speed schedule for descent phase.
climb_profile (VerticalProfile) – Rate-of-climb vs altitude.
descent_profile (VerticalProfile) – Rate-of-descent vs altitude. When approach_profile is set, this profile is intended to cover the cruise-altitude → top-of-approach (MSL) regime only; the terminal descent below top-of-approach is owned by approach_profile. When approach_profile is None, descent_profile continues to cover the full cruise-to-touchdown range as before (legacy behavior).
turn_model (TurnModel) – Turn performance / bank angles.
engine_type (Literal['jet', 'turboprop', 'piston']) – Propulsion category — "jet", "turboprop", or "piston".
confidence (PerformanceConfidence | None) – Per-submodel confidence ratings.
sources (list[SourceRecord] | None) – List of provenance records.
range (Quantity | None) – Maximum flight range (optional, metadata only).
endurance (Quantity | None) – Maximum flight duration (optional, metadata only).
useful_payload (Quantity | None) – Payload capacity (optional, metadata only).
approach_profile (ApproachProfile | None) – Optional terminal-arrival template covering top-of-approach → touchdown. When set, the planner can estimate terminal-segment timing geometrically from the speed schedule and glideslope. When None, the legacy scalar approach_speed and descent_profile are used for arrival behavior.
descent_path_angle_max_deg (float | None) – Maximum sustainable flight path angle during descent (degrees). When set, _hybrid_path steepens the descent to fit available lateral distance rather than spiralling at end of leg.
climb_path_angle_max_deg (float | None) – Maximum sustainable flight path angle during climb (degrees). When set, _hybrid_path steepens the climb to fit available lateral distance rather than spiralling at departure. When None and typical_climb_out.absorbed_in_climb_profile is True, the spiral-up regime acts as the absorption mechanism for mission-typical level-offs / .delay orbits.
typical_climb_out (ClimbOutPolicy | None) – Optional ClimbOutPolicy documenting the pre-cruise climb-out behaviour the calibrated climb_profile is tuned to absorb. Pure metadata in v1.5 — names the absorption posture so it’s queryable rather than buried in comments.
calibration_status (Literal['calibrated', 'inferred', 'uncalibrated']) –
Provenance label for the performance model. One of:
- "calibrated" — climb / cruise / descent profiles and TAS schedules are fit to in-situ flight data (IWG1 / ICARTT) per docs/calibration.md.
- "inferred" — performance is mirrored from a calibrated cousin airframe of the same type certificate (e.g. NCAR_GV mirrors NASA_GV); not directly measured against the target airframe.
- "uncalibrated" — performance comes from brochures, AFM tables, or rough estimates with no measured-data fit. Timing and reachability output for these aircraft should be treated as a best-effort starting point rather than a calibrated model.
Defaults to "uncalibrated"; calibrated subclasses set this explicitly.

__init__(aircraft_type, tail_number, operator, service_ceiling, approach_speed, climb_schedule, cruise_schedule, descent_schedule, climb_profile, descent_profile, turn_model, engine_type, confidence=None, sources=None, range=None, endurance=None, useful_payload=None, approach_profile=None, descent_path_angle_max_deg=None, climb_path_angle_max_deg=None, typical_climb_out=None, stall_speed_cas=None, calibration_status='uncalibrated')[source]¶

Parameters:

aircraft_type (str)
tail_number (str)
operator (str)
service_ceiling (Quantity)
approach_speed (Quantity)
climb_schedule (CasMachSchedule | TasSchedule)
cruise_schedule (CasMachSchedule | TasSchedule)
descent_schedule (CasMachSchedule | TasSchedule)
climb_profile (VerticalProfile)
descent_profile (VerticalProfile)
turn_model (TurnModel)
engine_type (Literal['jet', 'turboprop', 'piston'])
confidence (PerformanceConfidence | None)
sources (list[SourceRecord] | None)
range (Quantity | None)
endurance (Quantity | None)
useful_payload (Quantity | None)
approach_profile (ApproachProfile | None)
descent_path_angle_max_deg (float | None)
climb_path_angle_max_deg (float | None)
typical_climb_out (ClimbOutPolicy | None)
stall_speed_cas (Quantity | None)
calibration_status (Literal['calibrated', 'inferred', 'uncalibrated'])

property speed_model_fidelity: str¶

Describe the fidelity level of the cruise speed model.

Returns one of:

"cas_mach" — CAS/Mach schedule (atmosphere-aware).
"simplified_tas" — piecewise-linear TAS approximation.

property max_bank_angle: float¶: Maximum bank angle in degrees (for Dubins path geometry).

cruise_speed_at(altitude)[source]¶

True airspeed at altitude using the cruise speed schedule.

Return type:: Quantity
Parameters:: altitude (Quantity)

climb_speed_at(altitude)[source]¶

True airspeed during climb at altitude.

Mirrors descent_speed_at() for the climb schedule. Most aircraft factories alias climb_schedule to cruise_schedule, in which case this returns the same value as cruise_speed_at().

Return type:: Quantity
Parameters:: altitude (Quantity)

rate_of_climb(altitude)[source]¶

Rate of climb at altitude from the climb profile.

Return type:: Quantity
Parameters:: altitude (Quantity)

descent_speed_at(altitude)[source]¶

True airspeed during descent at altitude.

Return type:: Quantity
Parameters:: altitude (Quantity)

stall_speed_at(altitude)[source]¶

True airspeed at stall at altitude.

Stall is published as a single stall_speed_cas value (calibrated airspeed at landing config, MLW). TAS at altitude is derived via standard atmosphere — Vs in CAS is approximately invariant with altitude (stall is a fixed-AoA, fixed-q event) but TAS scales as 1/sqrt(density), so TAS at FL400 is roughly twice the SL value.

Raises:: HyPlanValueError – If stall_speed_cas is None for this aircraft.
Return type:: Quantity
Parameters:: altitude (Quantity)

min_safe_speed_at(altitude, *, margin=1.3)[source]¶

Minimum safe true airspeed at altitude, with margin above stall.

margin defaults to 1.3, mirroring the FAR Part 25 rule that V_ref >= 1.3 * Vs0. Pass a tighter margin (e.g., 1.2) for attentive level orbits in benign conditions, or a looser one (1.4-1.5) for night IFR / unstable atmospheres.

Returns margin * stall_speed_at(altitude) — useful for science planners deciding whether a slow-survey speed at a given altitude is acceptable.

Raises:

HyPlanValueError – If stall_speed_cas is None or margin is non-positive.

Return type:

Quantity

Parameters:

altitude (Quantity)
margin (float)

approach_speed_at(altitude_agl)[source]¶

True airspeed at altitude_agl during the terminal approach.

When approach_profile is set, this returns the schedule value at altitude_agl. When it isn’t, this returns the legacy scalar approach_speed for any altitude (the existing single-speed approximation).

Return type:: Quantity
Parameters:: altitude_agl (Quantity)

approach_vertical_rate_at(altitude_agl, groundspeed=None)[source]¶

Approximate vertical rate on the terminal approach.

When approach_profile is set, returns the geometric rate from ApproachProfile.approx_vertical_rate_at() (using the optional groundspeed override or scheduled TAS in still air). Returns None when no approach profile is configured — callers should fall back to legacy descent behavior in that case rather than synthesizing from descent_profile, which keeps the regime split crisp.

Return type:

Quantity | None

Parameters:

altitude_agl (Quantity)
groundspeed (Quantity | None)

climb_gradient_at(altitude)[source]¶

Climb gradient at altitude — dimensionless rise/run.

Computed from the integrated climb performance: the climb rate from climb_profile divided by the climb-schedule TAS. Useful for terrain-aware planning (“can the aircraft clear a 10,000 ft ridge in 50 nmi?”) since obstacle clearance is naturally expressed as a horizontal-vs-vertical ratio.

Returns 0.0 if TAS is zero (defensive — physically unreachable).

Return type:: float
Parameters:: altitude (Quantity)

descent_gradient_at(altitude)[source]¶

Descent gradient at altitude — dimensionless drop/run, positive.

Mirror of climb_gradient_at() for descent, returning a positive value (the magnitude of the descent slope).

Return type:: float
Parameters:: altitude (Quantity)

max_bank_under_budget(pitch_deg=0.0)[source]¶

Maximum bank angle (deg) consistent with the load-factor budget.

For a steady banked climb / descent at pitch angle pitch_deg, lift balance gives n = 1 / (cos(bank) · cos(pitch)). Solving for the bank that drives n to turn_model.max_load_factor:

cos(bank_max) = 1 / (n_max · cos(pitch))

Returns 0.0 when the implied pitch alone exceeds the budget (i.e. the aircraft can’t sustain level flight at that pitch — physically unreachable, included as a defensive guard). Returns 90.0 when the budget is unbounded (n_max <= 0 is treated as “no limit”).

The default pitch_deg=0 covers level cruise; callers in the climb / descent paths supply the implicit pitch from the rate-vs-altitude profile.

For the calibrated HyPlan aircraft library this returns large values (60-67° depending on aircraft and pitch) — well above every aircraft’s calibrated bank_by_phase entry — so the budget is effectively a defensive ceiling. It only narrows the chosen bank when callers force unusually aggressive manoeuvres.

Return type:: float
Parameters:: pitch_deg (float)

climb_altitude_profile(start_altitude, end_altitude, n_points=50)[source]¶

Generate altitude-vs-time curve during a climb.

Returns (times, altitudes) as numpy arrays in minutes and feet.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Parameters:

start_altitude (Quantity)
end_altitude (Quantity)
n_points (int)

step_climb(start_altitude, end_altitude, pauses, wind_along_track=None, _allow_above_ceiling=False)[source]¶

Total time and forward distance for a staged climb with pauses.

Real high-altitude aircraft step-climb out of weight-limited ceiling: they climb to an intermediate altitude, level off briefly to burn fuel and reduce gross weight, then continue climbing. For a NASA ER-2 sortie this typically looks like a 25-minute hold at FL611 climbing slowly under reduced weight, before final climb to the FL650 cruise altitude.

Each entry in pauses is (level_off_altitude, hold_duration). At each pause altitude, the aircraft holds (level orbit) for hold_duration adding only to total time — zero forward distance, since the aircraft is presumed to be orbiting at one location during the hold. Climb segments between pauses use the aircraft’s calibrated climb_profile via _climb().

Pauses are applied in altitude order; pauses outside the climb range are silently skipped. In-range means start_altitude < level_off_altitude <= end_altitude — a pause exactly at end_altitude is kept (a hold at top-of-climb), one exactly at start_altitude is not (no climb has happened yet). See ClimbPlan.

Parameters:

start_altitude (Quantity) – Starting altitude (e.g., airport elevation).
end_altitude (Quantity) – Final altitude (e.g., cruise altitude).
pauses (list[tuple[Quantity, Quantity]]) – List of (altitude, hold_duration) tuples. Pass an empty list to recover the no-pause behavior of _climb().
wind_along_track (Quantity | None)
_allow_above_ceiling (bool)

Return type:

tuple[Quantity, Quantity]

Returns:

Tuple of (total_time, total_forward_distance) as pint.Quantity.

Example

ER-2 NM17 B planned climb-out: 25-min hold at FL611 climbing to FL650.

>>> ac = NASA_ER2()
>>> t, d = ac.step_climb(
...     start_altitude=6_187 * ureg.foot,
...     end_altitude=65_000 * ureg.foot,
...     pauses=[(35_600 * ureg.foot, 25 * ureg.minute)],
... )

time_to_takeoff(airport, waypoint, wind=None, wind_source=None, t_anchor=None, climb_plan='auto', n_samples=20)[source]¶

Calculate time from takeoff to the first waypoint.

Builds the path via _hybrid_path() with phase="climb" — 2D Dubins horizontally, integrated climb_profile vertically — so the climb-out timing reflects the aircraft’s calibrated rate-vs-altitude curve, not a constant pitch.

climb_plan controls the pre-cruise hold model:

"auto" (default): use this aircraft’s typical_climb_out.explicit_climb_plan if defined, otherwise no holds.
ClimbPlan: caller-supplied pauses, used as-is.
None: no holds; pure active-climb integration.

Return type:

dict[str, Any]

Parameters:

airport (Airport)
waypoint (Waypoint)
wind (tuple[float, float] | None)
wind_source (WindField | None)
t_anchor (datetime | None)
climb_plan (ClimbPlan | str | None)
n_samples (int)

time_to_return(waypoint, airport, wind=None, wind_source=None, t_anchor=None, n_samples=20)[source]¶

Calculate time from the last waypoint back to the airport.

Builds the path via _hybrid_path() with phase="descent" — 2D Dubins horizontally, integrated descent_profile vertically.

When approach_profile is set, the descent is targeted at top-of-approach MSL (= airport.elevation + approach_profile.top_of_approach_agl) and a terminal "approach" segment is appended using ApproachProfile.time_to_touchdown(). When no profile is set, the legacy single-leg-to-runway behavior is preserved.

Return type:

dict[str, Any]

Parameters:

waypoint (Waypoint)
airport (Airport)
wind (tuple[float, float] | None)
wind_source (WindField | None)
t_anchor (datetime | None)
n_samples (int)

time_to_cruise(start_waypoint, end_waypoint, true_air_speed=None, wind=None, wind_source=None, t_anchor=None, phase='cruise', climb_plan=None, n_samples=20)[source]¶

Calculate time to fly between two waypoints.

Hybrid 2D Dubins (horizontal layout) + integrated vertical profile. Returns a dict with total_time, phases, and dubins_path (the 2D path; legacy key name kept for backward compatibility — use horizontal_path in new code).

Parameters:

wind (tuple[float, float] | None) – Optional (u_east, v_north) wind vector in m/s. When provided, horizontal turning arcs become trochoids, the 2D path length and timing account for wind drift, and the vertical phases project the wind onto the great-circle bearing for ground-speed-corrected forward distance.
phase (str) – Which entry of PhaseBankAngles drives the horizontal Dubins turn radius — see _hybrid_path(). Defaults to "cruise".
climb_plan (ClimbPlan | None) – Optional ClimbPlan with level-off pauses to insert during the climb. Only takes effect when phase == "climb" and the leg actually climbs.
start_waypoint (Waypoint)
end_waypoint (Waypoint)
true_air_speed (Quantity | None)
wind_source (WindField | None)
t_anchor (datetime | None)
n_samples (int)

Return type:

dict[str, Any]

Pre-configured aircraft¶

class NASA_ER2[source]¶

Aircraft¶

Fleet overview¶

Base class¶

Pre-configured aircraft¶

Profile I/O¶