pycontrails.core.aircraft_performance¶

Abstract interfaces for aircraft performance models.

Module Attributes

DEFAULT_LOAD_FACTOR

Default load factor for aircraft performance models.

Classes

`AircraftPerformance`([met, params])	Support for standardizing aircraft performance methodologies.
`AircraftPerformanceData`(fuel_flow, ...)	Store the computed aircraft performance metrics.
`AircraftPerformanceGrid`([met, params])	Support for standardizing aircraft performance methodologies on a grid.
`AircraftPerformanceGridData`(fuel_flow, ...)	Store the computed aircraft performance metrics for nominal cruise conditions.
`AircraftPerformanceGridParams`([copy_source, ...])	Parameters for `AircraftPerformanceGrid`.
`AircraftPerformanceParams`([copy_source, ...])	Parameters for `AircraftPerformance`.

class pycontrails.core.aircraft_performance.AircraftPerformance(met=None, params=None, **params_kwargs)¶

Bases: Model

Support for standardizing aircraft performance methodologies.

This class provides a simulate_fuel_and_performance() method for iteratively calculating aircraft mass and fuel flow rate.

The implementing class must bring eval() and calculate_aircraft_performance() methods. At runtime, these methods are intended to be chained together as follows:

The eval() method is called with a Flight
The simulate_fuel_and_performance() method is called inside eval() to iteratively calculate aircraft mass and fuel flow rate. If an aircraft mass is provided, the fuel flow rate is calculated once directly with a single call to calculate_aircraft_performance(). If an aircraft mass is not provided, the fuel flow rate is calculated iteratively with multiple calls to calculate_aircraft_performance().

abstract calculate_aircraft_performance(*, aircraft_type, altitude_ft, air_temperature, time, true_airspeed, aircraft_mass, engine_efficiency, fuel_flow, thrust, q_fuel, **kwargs)¶

Calculate aircraft performance along a trajectory.

When time is not None, this method should be used for a single flight trajectory. Waypoints are coupled via the time parameter.

This method computes the rate of climb and descent (ROCD) to determine flight phases: “cruise”, “climb”, and “descent”. Performance metrics depend on this phase.

When time is None, this method can be used to simulate flight performance over an arbitrary sequence of flight waypoints by assuming nominal flight characteristics. In this case, each point is treated independently and all points are assumed to be in a “cruise” phase of the flight.

Parameters:

aircraft_type (str) – Used to query the underlying model database for aircraft engine parameters.
altitude_ft (npt.NDArray[np.float64]) – Altitude at each waypoint, [\(ft\)]
air_temperature (npt.NDArray[np.float64]) – Ambient temperature for each waypoint, [\(K\)]
time (npt.NDArray[np.datetime64] | None) – Waypoint time in np.datetime64 format. If None, only drag force will is used in thrust calculations (ie, no vertical change and constant horizontal change). In addition, aircraft is assumed to be in cruise.
true_airspeed (npt.NDArray[np.float64] | float | None) – True airspeed for each waypoint, [\(m s^{-1}\)]. If None, a nominal value is used.
aircraft_mass (npt.NDArray[np.float64] | float) – Aircraft mass for each waypoint, [\(kg\)].
engine_efficiency (npt.NDArray[np.float64] | float | None) – Override the engine efficiency at each waypoint.
fuel_flow (npt.NDArray[np.float64] | float | None) – Override the fuel flow at each waypoint, [\(kg s^{-1}\)].
thrust (npt.NDArray[np.float64] | float | None) – Override the thrust setting at each waypoint, [:math: N].
q_fuel (float) – Lower calorific value (LCV) of fuel, [\(J \ kg_{fuel}^{-1}\)].
**kwargs (Any) – Additional keyword arguments to pass to the model.

Returns:

AircraftPerformanceData – Derived performance metrics at each waypoint.

ensure_true_airspeed_on_source()¶

Add true_airspeed field to source data if not already present.

Returns:: npt.NDArray[np.float64] – True airspeed, [\(m s^{-1}\)]. If true_airspeed is already present on source, this is returned directly. Otherwise, it is calculated using Flight.segment_true_airspeed().

abstract eval(source=None, **params)¶

Evaluate the aircraft performance model.

The implementing model adds the following fields to the source flight:

aircraft_mass: aircraft mass at each waypoint, [\(kg\)]
fuel_flow: fuel mass flow rate at each waypoint, [\(kg s^{-1}\)]
thrust: thrust at each waypoint, [\(N\)]
engine_efficiency: engine efficiency at each waypoint
rocd: rate of climb or descent at each waypoint, [\(ft min^{-1}\)]
fuel_burn: fuel burn at each waypoint, [\(kg\)]

In addition, the following attributes are added to the source flight:

n_engine: number of engines
wingspan: wingspan, [\(m\)]
max_mach: maximum Mach number
max_altitude: maximum altitude, [\(m\)]
total_fuel_burn: total fuel burn, [\(kg\)]

Parameters:

source (Flight) – Flight trajectory to evaluate.
params (Any) – Override params with keyword arguments.

Returns:

Flight – Flight trajectory with aircraft performance data.

met¶: Meteorology data

params¶: Instantiated model parameters, in dictionary form

simulate_fuel_and_performance(*, aircraft_type, altitude_ft, time, true_airspeed, air_temperature, aircraft_mass, thrust, engine_efficiency, fuel_flow, q_fuel, n_iter, amass_oew, amass_mtow, amass_mpl, load_factor, takeoff_mass, **kwargs)¶

Calculate aircraft mass, fuel mass flow rate, and overall propulsion efficiency.

This method performs n_iter iterations, each of which calls calculate_aircraft_performance(). Each successive iteration generates a better estimate for mass fuel flow rate and aircraft mass at each waypoint.

Parameters:

aircraft_type (str) – Aircraft type designator used to query the underlying model database.
altitude_ft (npt.NDArray[np.float64]) – Altitude at each waypoint, [\(ft\)]
time (npt.NDArray[np.datetime64]) – Waypoint time in np.datetime64 format.
true_airspeed (npt.NDArray[np.float64]) – True airspeed for each waypoint, [\(m s^{-1}\)]
air_temperature (npt.NDArray[np.float64]) – Ambient temperature for each waypoint, [\(K\)]
aircraft_mass (npt.NDArray[np.float64] | float | None) – Override the aircraft_mass at each waypoint, [\(kg\)].
thrust (npt.NDArray[np.float64] | float | None) – Override the thrust setting at each waypoint, [:math: N].
engine_efficiency (npt.NDArray[np.float64] | float | None) – Override the engine efficiency at each waypoint.
fuel_flow (npt.NDArray[np.float64] | float | None) – Override the fuel flow at each waypoint, [\(kg s^{-1}\)].
q_fuel (float) – Lower calorific value (LCV) of fuel, [\(J \ kg_{fuel}^{-1}\)].
amass_oew (float) – Aircraft operating empty weight, [\(kg\)]. Used to determine the initial aircraft mass if takeoff_mass is not provided. This quantity is constant for a given aircraft type.
amass_mtow (float) – Aircraft maximum take-off weight, [\(kg\)]. Used to determine the initial aircraft mass if takeoff_mass is not provided. This quantity is constant for a given aircraft type.
amass_mpl (float) – Aircraft maximum payload, [\(kg\)]. Used to determine the initial aircraft mass if takeoff_mass is not provided. This quantity is constant for a given aircraft type.
load_factor (float) – Aircraft load factor assumption (between 0 and 1). If unknown, a value of 0.7 is a reasonable default. Typically, this parameter is between 0.6 and 0.8. During the height of the COVID-19 pandemic, this parameter was often much lower.
takeoff_mass (float | None, optional) – If known, the takeoff mass can be provided to skip the calculation in jet.initial_aircraft_mass(). In this case, the parameters load_factor, amass_oew, amass_mtow, and amass_mpl are ignored.
**kwargs (Any) – Additional keyword arguments are passed to calculate_aircraft_performance().

Returns:

AircraftPerformanceData – Results from the final iteration is returned.

source¶: Data evaluated in model

class pycontrails.core.aircraft_performance.AircraftPerformanceData(fuel_flow, aircraft_mass, true_airspeed, fuel_burn, thrust, engine_efficiency, rocd)¶

Bases: object

Store the computed aircraft performance metrics.

Parameters:

fuel_flow (npt.NDArray[np.float64]) – Fuel mass flow rate for each waypoint, [\(kg s^{-1}\)]
aircraft_mass (npt.NDArray[np.float64]) – Aircraft mass for each waypoint, [\(kg\)]
true_airspeed (npt.NDArray[np.float64]) – True airspeed at each waypoint, [:math: m s^{-1}]
fuel_burn (npt.NDArray[np.float64]) – Fuel consumption for each waypoint, [\(kg\)]. Set to an array of all nan values if it cannot be computed (ie, working with gridpoints).
thrust (npt.NDArray[np.float64]) – Thrust force, [\(N\)]
engine_efficiency (npt.NDArray[np.float64]) – Overall propulsion efficiency for each waypoint
rocd (npt.NDArray[np.float64]) – Rate of climb and descent, [\(ft min^{-1}\)]

aircraft_mass¶

engine_efficiency¶

fuel_burn¶

fuel_flow¶

rocd¶

thrust¶

true_airspeed¶

class pycontrails.core.aircraft_performance.AircraftPerformanceGrid(met=None, params=None, **params_kwargs)¶

Bases: Model

Support for standardizing aircraft performance methodologies on a grid.

Currently just a container until additional models are implemented.

abstract eval(source=None, **params)¶: Evaluate the aircraft performance model.

met¶: Meteorology data

params¶: Instantiated model parameters, in dictionary form

source¶: Data evaluated in model

class pycontrails.core.aircraft_performance.AircraftPerformanceGridData(fuel_flow, engine_efficiency)¶

Bases: Generic[ArrayOrFloat]

Store the computed aircraft performance metrics for nominal cruise conditions.

engine_efficiency¶: Engine efficiency, [\(0-1\)]

fuel_flow¶: Fuel mass flow rate, [\(kg s^{-1}\)]

class pycontrails.core.aircraft_performance.AircraftPerformanceGridParams(copy_source=True, interpolation_method='linear', interpolation_bounds_error=False, interpolation_fill_value=nan, interpolation_localize=False, interpolation_use_indices=False, interpolation_q_method=None, verify_met=True, downselect_met=True, met_longitude_buffer=(0.0, 0.0), met_latitude_buffer=(0.0, 0.0), met_level_buffer=(0.0, 0.0), met_time_buffer=(numpy.timedelta64(0, 'h'), numpy.timedelta64(0, 'h')), fuel=<factory>, aircraft_type='B737', mach_number=None, aircraft_mass=None)¶

Bases: ModelParams

Parameters for AircraftPerformanceGrid.

aircraft_mass = None¶: Aircraft mass, [\(kg\)] If None, a nominal value is determined by the implementation. Can be overridden by including an aircraft_mass key in source data

aircraft_type = 'B737'¶: ICAO code designating simulated aircraft type. Can be overridden by including aircraft_type attribute in source data

fuel¶: Fuel type

mach_number = None¶: Mach number, [\(Ma\)] If None, a nominal cruise value is determined by the implementation. Can be overridden by including a mach_number key in source data

class pycontrails.core.aircraft_performance.AircraftPerformanceParams(copy_source=True, interpolation_method='linear', interpolation_bounds_error=False, interpolation_fill_value=nan, interpolation_localize=False, interpolation_use_indices=False, interpolation_q_method=None, verify_met=True, downselect_met=True, met_longitude_buffer=(0.0, 0.0), met_latitude_buffer=(0.0, 0.0), met_level_buffer=(0.0, 0.0), met_time_buffer=(numpy.timedelta64(0, 'h'), numpy.timedelta64(0, 'h')), correct_fuel_flow=True, n_iter=3)¶

Bases: ModelParams

Parameters for AircraftPerformance.

correct_fuel_flow = True¶: Whether to correct fuel flow to ensure it remains within the operational limits of the aircraft type.

n_iter = 3¶: The number of iterations used to calculate aircraft mass and fuel flow. The default value of 3 is sufficient for most cases.

pycontrails.core.aircraft_performance.DEFAULT_LOAD_FACTOR = 0.7¶: Default load factor for aircraft performance models.