Flight Plan

Assemble flight lines and waypoints into a complete mission plan with segment-level timing, distances, and altitude profiles.

Plan computation

compute_flight_plan(aircraft, flight_sequence, takeoff_airport=None, return_airport=None, start_offset=5, end_offset=1, wind_speed=None, wind_direction=None, wind_source=None, takeoff_time=None, climb_plan='auto', wind_sampling='cruise_midpoint', n_samples=20)[source]

Compute a flight plan with segment classifications.

Segment types are determined as follows:

  • “takeoff” for the very first ascending phase,

  • “climb” for any subsequent ascending phase,

  • “transit” for level flight,

  • “descent” for descending flight,

  • “flight_line” for dedicated flight line segments,

  • “approach” for the final descending phase into the return airport.

Parameters:

  • aircraft (Aircraft) – Aircraft performance model used for timing.

  • flight_sequence (List[Union[FlightLine, Waypoint, Pattern]]) – Ordered list of flight lines and/or waypoints.

  • takeoff_airport (Optional[Airport]) – Optional departure airport (prepends a takeoff phase).

  • return_airport (Optional[Airport]) – Optional arrival airport (appends an approach phase).

  • start_offset (float) – Pre-extension of each flight line (nautical miles).

  • end_offset (float) – Post-extension of each flight line (nautical miles).

  • wind_speed (Optional[Quantity]) –

    Optional constant wind speed as a pint.Quantity (e.g. 30 * ureg.knot). When supplied together with wind_direction, the wind is decomposed into a (u_east, v_north) vector and applied two ways:

    1. Horizontal Dubins arcs in the takeoff, inter-line transit, descent, and return phases use trochoidal geometry (see _TrochoidDubins2D), so turn arcs are wind-drift-corrected and segment timing reflects the actual ground track.

    2. Each flight line is solved with a wind-corrected heading (crab angle) and the resulting ground speed from full kinematics, so both headwind/tailwind and crosswind components affect segment time.

    Defaults to no wind (still-air geometry and timing).

  • wind_direction (Optional[float]) – Direction the wind is blowing from, in degrees true (meteorological convention: 0° = wind from north, 90° = from east). Required when wind_speed is set. Ignored when wind_speed is None or zero.

  • wind_source (Optional[WindField]) – A WindField providing per-segment wind. Takes precedence over wind_speed / wind_direction. Cannot be combined with those parameters.

  • takeoff_time (Optional[datetime]) – UTC datetime of takeoff. Required when wind_source is a gridded wind field (MERRA-2, GMAO) so that each segment can be queried at the correct time.

  • climb_plan (Union[ClimbPlan, str, None]) –

    Climb-out hold plan for the takeoff phase. Three forms:

    • "auto" (default) — use the aircraft’s typical_climb_out.explicit_climb_plan if defined, otherwise no holds. Reproduces empirical-typical wall-clock TOC for aircraft whose factory populates the policy (e.g. NASA_ER2 ships with a ~12-min FL356 hold representing the median weight-band .delay orbit observed across 138 IWG1 sorties).

    • None — no holds; pure active-climb integration. Caller is opting out of any typical-mission absorption.

    • ClimbPlan — caller-supplied pauses, used as-is. Each pause renders as a "loiter" segment in the output dataframe (zero forward distance, hold duration only), with the climb split into one row per inter-pause segment.

  • wind_sampling (str) –

    How wind is sampled per phase when wind_source is provided.

    • "cruise_midpoint" (default) — single (u, v) per leg sampled at the leg midpoint at cruise altitude; passed to Aircraft._hybrid_path as wind=(u, v) and used for both 2D Dubins (trochoidal) and the vertical phases. Backward-compatible with v1.5.

    • "phase_midpoint" — climb and descent each get their own wind sample at the phase-mid altitude near the phase-mid distance, projected onto the bearing. Cruise still gets a single midpoint sample at cruise altitude. Captures vertical wind shear (jet streams) that "cruise_midpoint" misses.

    Ignored when wind_source is None (no wind / scalar wind / wind_speed+wind_direction paths).

  • n_samples (int) – Number of points sampled along each Dubins phase sub-linestring (climb / cruise / transit / descent). Defaults to 20. Increase for smoother-looking turns in plotted output (e.g. n_samples=80 removes visible polygonalization on tight Dubins arcs); has no effect on timing, which is computed analytically.

Return type:

GeoDataFrame

Record builders

create_flight_line_record(flight_line, aircraft)[source]

Create a flight line record dictionary for inclusion in a flight plan DataFrame.

Parameters:

  • flight_line (FlightLine) – The flight line to convert.

  • aircraft (Aircraft) – Aircraft used to compute segment timing.

Returns:

Record with geometry, endpoints, altitudes (feet MSL), headings,

time (minutes), segment type, and distance (nautical miles).

Return type:

dict

process_flight_phase(start, end, phase_info, segment_name, override_segment_type=None)[source]

Process a flight phase using the detailed phase_info.

For each sub-phase in phase_info["phases"], this function determines the segment type based on the altitude change:

  • If ascending, the phase is labeled "takeoff" when segment_name is "Departure", otherwise "climb".

  • If descending, the phase is labeled "approach" when segment_name is "Arrival", otherwise "descent".

  • If no altitude change, the phase is labeled "transit".

If override_segment_type is provided (e.g. "pattern" or "sampling" from a flight-pattern waypoint), it replaces the default "transit" label for level segments while climb/descent labels are preserved.

Returns a list of record dictionaries for inclusion in the flight plan.

Return type:

List[dict]

Parameters: