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`([...])	Parameters for `AircraftPerformanceGrid`.
`AircraftPerformanceParams`([...])	Parameters for `AircraftPerformance`.
`CommonAircraftPerformanceParams`([...])	Params for `AircraftPerformanceParams` and `AircraftPerformanceGridParams`.

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.floating]) – Altitude at each waypoint, [\(ft\)]
air_temperature (npt.NDArray[np.floating]) – 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.floating] | float | None) – True airspeed for each waypoint, [\(m s^{-1}\)]. If None, a nominal value is used.
aircraft_mass (npt.NDArray[np.floating] | float) – Aircraft mass for each waypoint, [\(kg\)].
engine_efficiency (npt.NDArray[np.floating] | float | None) – Override the engine efficiency at each waypoint.
fuel_flow (npt.NDArray[np.floating] | float | None) – Override the fuel flow at each waypoint, [\(kg s^{-1}\)].
thrust (npt.NDArray[np.floating] | 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.

default_params¶: alias of AircraftPerformanceParams

downselect_met()¶

Downselect met domain to the max/min bounds of source.

Override this method if special handling is needed in met down-selection.

source must be defined before calling downselect_met().
This method copies and re-assigns met using met.copy() to avoid side-effects.

Raises:

ValueError – Raised if source is not defined. Raised if source is not a GeoVectorDataset.
TypeError – Raised if met is not a MetDataset.

classmethod ecmwf_met_variables()¶

Return an ECMWF-specific list of required meteorology variables.

Returns:: tuple[MetVariable] – List of ECMWF-specific variants of required variables

ensure_air_temperature_on_source()¶

Add air_temperature field to source data if not already present.

This function operates in-place. If air_temperature is not already present on source, it is calculated by interpolation from met data.

ensure_true_airspeed_on_source()¶

Add true_airspeed field to source data if not already present.

This function operates in-place. If true_airspeed is not already present on source, it is calculated using Flight.segment_true_airspeed().

eval(source=None, **params)¶

Evaluate the aircraft performance model.

Parameters:

source (Flight) – Flight trajectory to evaluate. Can be a Flight or Fleet.
params (Any) – Override params with keyword arguments.

Returns:

Flight – Flight trajectory with aircraft performance data.

abstract eval_flight(fl)¶

Evaluate the aircraft performance model on a single flight trajectory.

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\)]

classmethod generic_met_variables()¶

Return a model-agnostic list of required meteorology variables.

Returns:: tuple[MetVariable] – List of model-agnostic variants of required variables

get_data_param(other, key, default=<object object>, *, set_attr=True)¶

Get data from other source-compatible object with default set by model parameter key.

Retrieves data with the following hierarchy:

other.data[key]. Returns np.ndarray | xr.DataArray.
other.attrs[key]
params[key]
default

In case 3., the value of params[key] is attached to other.attrs[key] unless set_attr is set to False.

Parameters:

key (str) – Key to retrieve
default (Any, optional) – Default value if key is not found.
set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in other data, other attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

get_source_param(key, default=<object object>, *, set_attr=True)¶

Get source data with default set by parameter key.

Retrieves data with the following hierarchy:

source.data[key]. Returns np.ndarray | xr.DataArray.
source.attrs[key]
params[key]
default

In case 3., the value of params[key] is attached to source.attrs[key] unless set_attr is set to False.

Parameters:

key (str) – Key to retrieve
default (Any, optional) – Default value if key is not found.
set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in source data, source attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

classmethod gfs_met_variables()¶

Return a GFS-specific list of required meteorology variables.

Returns:: tuple[MetVariable] – List of GFS-specific variants of required variables

property hash¶

Generate a unique hash for model instance.

Returns:: str – Unique hash for model instance (sha1)

property interp_kwargs¶

Shortcut to create interpolation arguments from params.

The output of this is useful for passing to interpolate_met().

Returns:

dict[str, Any] – Dictionary with keys

”method”
”bounds_error”
”fill_value”
”localize”
”use_indices”
”q_method”

as determined by params.

abstract property long_name¶: Get long name descriptor, annotated on xr.DataArray outputs.

met¶: Meteorology data

met_required = False¶: Require meteorology is not None on __init__()

met_variables = ()¶: Required meteorology pressure level variables. Each element in the list is a MetVariable or a tuple[MetVariable]. If element is a tuple[MetVariable], the variable depends on the data source and the tuple must include entries for a model-agnostic variable, an ECMWF-specific variable, and a GFS-specific variable. Only one of the three variable in the tuple is required for model evaluation.

abstract property name¶

class`Flight`.

Type:: Get model name for use as a data key in xr.DataArray or

optional_met_variables = (MetVariable(short_name='t', standard_name='air_temperature', long_name='Air Temperature', level_type='isobaricInhPa', ecmwf_id=130, grib1_id=11, grib2_id=(0, 0, 0), units='K', amip='ta', description='Air temperature is the bulk temperature of the air, not the surface (skin) temperature.'), MetVariable(short_name='u', standard_name='eastward_wind', long_name='Eastward Wind', level_type='isobaricInhPa', ecmwf_id=131, grib1_id=33, grib2_id=(0, 2, 2), units='m s**-1', amip='ua', description='"Eastward" indicates a vector component which is positive when directed eastward (negative westward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'), MetVariable(short_name='v', standard_name='northward_wind', long_name='Northward Wind', level_type='isobaricInhPa', ecmwf_id=132, grib1_id=34, grib2_id=(0, 2, 3), units='m s**-1', amip='va', description='"Northward" indicates a vector component which is positive when directed northward (negative southward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'))¶: Optional meteorology variables

params¶: Instantiated model parameters, in dictionary form

processed_met_variables¶: Set of required parameters if processing already complete on met input.

require_met()¶

Ensure that met is a MetDataset.

Returns:: MetDataset – Returns reference to met. This is helpful for type narrowing met when meteorology is required.
Raises:: ValueError – Raises when met is None.

require_source_type(type_)¶

Ensure that source is type_.

Returns:: _Source – Returns reference to source. This is helpful for type narrowing source to specific type(s).
Raises:: ValueError – Raises when source is not _type_.

set_source(source=None)¶

Attach original or copy of input source to source.

Parameters:: source (MetDataset | GeoVectorDataset | Flight | Iterable[Flight] | None) – Parameter source passed in eval(). If None, an empty MetDataset with coordinates like met is set to source.

See also

eval

set_source_met(optional=False, variable=None)¶

Ensure or interpolate each required met_variables on source .

For each variable in met_variables, check source for data variable with the same name.

For GeoVectorDataset sources, try to interpolate met if variable does not exist.

For MetDataset sources, try to get data from met if variable does not exist.

Parameters:

optional (bool, optional) – Include optional_met_variables
variable (MetVariable | Sequence[MetVariable] | None, optional) – MetVariable to set, from met_variables. If None, set all variables in met_variables and optional_met_variables if optional is True.

Raises:

ValueError – Variable does not exist and source is a MetDataset.
KeyError – Variable not found in source or met.

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.floating]) – Altitude at each waypoint, [\(ft\)]
time (npt.NDArray[np.datetime64]) – Waypoint time in np.datetime64 format.
true_airspeed (npt.NDArray[np.floating]) – True airspeed for each waypoint, [\(m s^{-1}\)]
air_temperature (npt.NDArray[np.floating]) – Ambient temperature for each waypoint, [\(K\)]
aircraft_mass (npt.NDArray[np.floating] | float | None) – Override the aircraft_mass at each waypoint, [\(kg\)].
thrust (npt.NDArray[np.floating] | float | None) – Override the thrust setting at each waypoint, [:math: N].
engine_efficiency (npt.NDArray[np.floating] | float | None) – Override the engine efficiency at each waypoint.
fuel_flow (npt.NDArray[np.floating] | 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

transfer_met_source_attrs(source=None)¶: Transfer met source metadata from met to source.

update_params(params=None, **params_kwargs)¶

Update model parameters on params.

Parameters:

params (dict[str, Any], optional) – Model parameters to update, as dictionary. Defaults to {}
**params_kwargs (Any) – Override keys in params with keyword arguments.

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.floating]) – Fuel mass flow rate for each waypoint, [\(kg s^{-1}\)]
aircraft_mass (npt.NDArray[np.floating]) – Aircraft mass for each waypoint, [\(kg\)]
true_airspeed (npt.NDArray[np.floating]) – True airspeed at each waypoint, [:math: m s^{-1}]
fuel_burn (npt.NDArray[np.floating]) – 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.floating]) – Thrust force, [\(N\)]
engine_efficiency (npt.NDArray[np.floating]) – Overall propulsion efficiency for each waypoint
rocd (npt.NDArray[np.floating]) – 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.

default_params¶: alias of ModelParams

downselect_met()¶

Downselect met domain to the max/min bounds of source.

Override this method if special handling is needed in met down-selection.

source must be defined before calling downselect_met().
This method copies and re-assigns met using met.copy() to avoid side-effects.

Raises:

ValueError – Raised if source is not defined. Raised if source is not a GeoVectorDataset.
TypeError – Raised if met is not a MetDataset.

classmethod ecmwf_met_variables()¶

Return an ECMWF-specific list of required meteorology variables.

Returns:: tuple[MetVariable] – List of ECMWF-specific variants of required variables

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

classmethod generic_met_variables()¶

Return a model-agnostic list of required meteorology variables.

Returns:: tuple[MetVariable] – List of model-agnostic variants of required variables

get_data_param(other, key, default=<object object>, *, set_attr=True)¶

Get data from other source-compatible object with default set by model parameter key.

Retrieves data with the following hierarchy:

other.data[key]. Returns np.ndarray | xr.DataArray.
other.attrs[key]
params[key]
default

In case 3., the value of params[key] is attached to other.attrs[key] unless set_attr is set to False.

Parameters:

key (str) – Key to retrieve
default (Any, optional) – Default value if key is not found.
set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in other data, other attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

get_source_param(key, default=<object object>, *, set_attr=True)¶

Get source data with default set by parameter key.

Retrieves data with the following hierarchy:

source.data[key]. Returns np.ndarray | xr.DataArray.
source.attrs[key]
params[key]
default

In case 3., the value of params[key] is attached to source.attrs[key] unless set_attr is set to False.

Parameters:

key (str) – Key to retrieve
default (Any, optional) – Default value if key is not found.
set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in source data, source attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

classmethod gfs_met_variables()¶

Return a GFS-specific list of required meteorology variables.

Returns:: tuple[MetVariable] – List of GFS-specific variants of required variables

property hash¶

Generate a unique hash for model instance.

Returns:: str – Unique hash for model instance (sha1)

property interp_kwargs¶

Shortcut to create interpolation arguments from params.

The output of this is useful for passing to interpolate_met().

Returns:

dict[str, Any] – Dictionary with keys

”method”
”bounds_error”
”fill_value”
”localize”
”use_indices”
”q_method”

as determined by params.

abstract property long_name¶: Get long name descriptor, annotated on xr.DataArray outputs.

met¶: Meteorology data

met_required = False¶: Require meteorology is not None on __init__()

met_variables¶: Required meteorology pressure level variables. Each element in the list is a MetVariable or a tuple[MetVariable]. If element is a tuple[MetVariable], the variable depends on the data source and the tuple must include entries for a model-agnostic variable, an ECMWF-specific variable, and a GFS-specific variable. Only one of the three variable in the tuple is required for model evaluation.

abstract property name¶

class`Flight`.

Type:: Get model name for use as a data key in xr.DataArray or

optional_met_variables¶: Optional meteorology variables

params¶: Instantiated model parameters, in dictionary form

processed_met_variables¶: Set of required parameters if processing already complete on met input.

require_met()¶

Ensure that met is a MetDataset.

Returns:: MetDataset – Returns reference to met. This is helpful for type narrowing met when meteorology is required.
Raises:: ValueError – Raises when met is None.

require_source_type(type_)¶

Ensure that source is type_.

Returns:: _Source – Returns reference to source. This is helpful for type narrowing source to specific type(s).
Raises:: ValueError – Raises when source is not _type_.

set_source(source=None)¶

Attach original or copy of input source to source.

Parameters:: source (MetDataset | GeoVectorDataset | Flight | Iterable[Flight] | None) – Parameter source passed in eval(). If None, an empty MetDataset with coordinates like met is set to source.

See also

eval

set_source_met(optional=False, variable=None)¶

Ensure or interpolate each required met_variables on source .

For each variable in met_variables, check source for data variable with the same name.

For GeoVectorDataset sources, try to interpolate met if variable does not exist.

For MetDataset sources, try to get data from met if variable does not exist.

Parameters:

optional (bool, optional) – Include optional_met_variables
variable (MetVariable | Sequence[MetVariable] | None, optional) – MetVariable to set, from met_variables. If None, set all variables in met_variables and optional_met_variables if optional is True.

Raises:

ValueError – Variable does not exist and source is a MetDataset.
KeyError – Variable not found in source or met.

source¶: Data evaluated in model

transfer_met_source_attrs(source=None)¶: Transfer met source metadata from met to source.

update_params(params=None, **params_kwargs)¶

Update model parameters on params.

Parameters:

params (dict[str, Any], optional) – Model parameters to update, as dictionary. Defaults to {}
**params_kwargs (Any) – Override keys in params with keyword arguments.

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(engine_deterioration_factor=0.025, 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=(np.timedelta64(0, 'h'), np.timedelta64(0, 'h')), fuel=<factory>, aircraft_type='B737', mach_number=None, aircraft_mass=None)¶

Bases: ModelParams, CommonAircraftPerformanceParams

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

as_dict()¶

Convert object to dictionary.

We use this method instead of dataclasses.asdict to use a shallow/unrecursive copy. This will return values as Any instead of dict.

Returns:: dict[str, Any] – Dictionary version of self.

copy_source = True¶: Copy input source data on eval

downselect_met = True¶: Downselect input MetDataset` to region around source.

engine_deterioration_factor = 0.025¶: Account for “in-service” engine deterioration between maintenance cycles. Default value is set to +2.5% increase in fuel consumption. Reference: Gurrola Arrieta, M.D.J., Botez, R.M. and Lasne, A., 2024. An Engine Deterioration Model for Predicting Fuel Consumption Impact in a Regional Aircraft. Aerospace, 11(6), p.426.

fuel¶: Fuel type

interpolation_bounds_error = False¶: If True, points lying outside interpolation will raise an error

interpolation_fill_value = nan¶: Used for outside interpolation value if interpolation_bounds_error is False

interpolation_localize = False¶: Experimental. See pycontrails.core.interpolation.

interpolation_method = 'linear'¶: Interpolation method. Supported methods include “linear”, “nearest”, “slinear”, “cubic”, and “quintic”. See scipy.interpolate.RegularGridInterpolator for the description of each method. Not all methods are supported by all met grids. For example, the “cubic” method requires at least 4 points per dimension.

interpolation_q_method = None¶: Experimental. Alternative interpolation method to account for specific humidity lapse rate bias. Must be one of None, "cubic-spline", or "log-q-log-p". If None, no special interpolation is used for specific humidity. The "cubic-spline" method applies a custom stretching of the met interpolation table to account for the specific humidity lapse rate bias. The "log-q-log-p" method interpolates in the log of specific humidity and pressure, then converts back to specific humidity. Only used by models calling to interpolate_met().

interpolation_use_indices = False¶: Experimental. See pycontrails.core.interpolation.

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

met_latitude_buffer = (0.0, 0.0)¶: Met latitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_level_buffer = (0.0, 0.0)¶: Met level buffer for input to Flight.downselect_met(), in [\(hPa\)]. Only applies when downselect_met is True.

met_longitude_buffer = (0.0, 0.0)¶: Met longitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_time_buffer = (np.timedelta64(0,'h'), np.timedelta64(0,'h'))¶: Met time buffer for input to Flight.downselect_met() Only applies when downselect_met is True.

verify_met = True¶: Call _verify_met() on model instantiation.

class pycontrails.core.aircraft_performance.AircraftPerformanceParams(engine_deterioration_factor=0.025, 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=(np.timedelta64(0, 'h'), np.timedelta64(0, 'h')), correct_fuel_flow=True, n_iter=3, fill_low_altitude_with_isa_temperature=False, fill_low_altitude_with_zero_wind=False)¶

Bases: ModelParams, CommonAircraftPerformanceParams

Parameters for AircraftPerformance.

as_dict()¶

Convert object to dictionary.

We use this method instead of dataclasses.asdict to use a shallow/unrecursive copy. This will return values as Any instead of dict.

Returns:: dict[str, Any] – Dictionary version of self.

copy_source = True¶: Copy input source data on eval

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

downselect_met = True¶: Downselect input MetDataset` to region around source.

engine_deterioration_factor = 0.025¶: Account for “in-service” engine deterioration between maintenance cycles. Default value is set to +2.5% increase in fuel consumption. Reference: Gurrola Arrieta, M.D.J., Botez, R.M. and Lasne, A., 2024. An Engine Deterioration Model for Predicting Fuel Consumption Impact in a Regional Aircraft. Aerospace, 11(6), p.426.

fill_low_altitude_with_isa_temperature = False¶: Experimental. If True, fill waypoints below the lowest altitude met level with ISA temperature when interpolating “air_temperature” or “t”. If the met data is not provided, the entire air temperature array is approximated with the ISA temperature. Enabling this does NOT remove any NaN values in the met data itself.

fill_low_altitude_with_zero_wind = False¶: Experimental. If True, fill waypoints below the lowest altitude met level with zero wind when computing true airspeed. In other words, approximate low-altitude true airspeed with the ground speed. Enabling this does NOT remove any NaN values in the met data itself. In the case that met is not provided, any missing values are filled with zero wind.

interpolation_bounds_error = False¶: If True, points lying outside interpolation will raise an error

interpolation_fill_value = nan¶: Used for outside interpolation value if interpolation_bounds_error is False

interpolation_localize = False¶: Experimental. See pycontrails.core.interpolation.

interpolation_method = 'linear'¶: Interpolation method. Supported methods include “linear”, “nearest”, “slinear”, “cubic”, and “quintic”. See scipy.interpolate.RegularGridInterpolator for the description of each method. Not all methods are supported by all met grids. For example, the “cubic” method requires at least 4 points per dimension.

interpolation_q_method = None¶: Experimental. Alternative interpolation method to account for specific humidity lapse rate bias. Must be one of None, "cubic-spline", or "log-q-log-p". If None, no special interpolation is used for specific humidity. The "cubic-spline" method applies a custom stretching of the met interpolation table to account for the specific humidity lapse rate bias. The "log-q-log-p" method interpolates in the log of specific humidity and pressure, then converts back to specific humidity. Only used by models calling to interpolate_met().

interpolation_use_indices = False¶: Experimental. See pycontrails.core.interpolation.

met_latitude_buffer = (0.0, 0.0)¶: Met latitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_level_buffer = (0.0, 0.0)¶: Met level buffer for input to Flight.downselect_met(), in [\(hPa\)]. Only applies when downselect_met is True.

met_longitude_buffer = (0.0, 0.0)¶: Met longitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_time_buffer = (np.timedelta64(0,'h'), np.timedelta64(0,'h'))¶: Met time buffer for input to Flight.downselect_met() Only applies when downselect_met is True.

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.

verify_met = True¶: Call _verify_met() on model instantiation.

class pycontrails.core.aircraft_performance.CommonAircraftPerformanceParams(engine_deterioration_factor=0.025)¶

Bases: object

Params for AircraftPerformanceParams and AircraftPerformanceGridParams.

engine_deterioration_factor = 0.025¶: Account for “in-service” engine deterioration between maintenance cycles. Default value is set to +2.5% increase in fuel consumption. Reference: Gurrola Arrieta, M.D.J., Botez, R.M. and Lasne, A., 2024. An Engine Deterioration Model for Predicting Fuel Consumption Impact in a Regional Aircraft. Aerospace, 11(6), p.426.

pycontrails.core.aircraft_performance.DEFAULT_LOAD_FACTOR = 0.83¶: Default load factor for aircraft performance models. See pycontrails.physics.jet.aircraft_load_factor() for a higher precision approach to estimating the load factor.