pycontrails.models.ps_model.PSFlight

class pycontrails.models.ps_model.PSFlight(met=None, params=None, **params_kwargs)

Bases: AircraftPerformance

Simulate aircraft performance using Poll-Schumann (PS) model.

References

[Poll and Schumann, 2021] [Poll and Schumann, 2021]

Poll & Schumann (2022). An estimation method for the fuel burn and other performance characteristics of civil transport aircraft. Part 3 Generalisation to cover climb, descent and holding. Aero. J., submitted.

See also

pycontrails.physics.jet.aircraft_load_factor

__init__(met=None, params=None, **params_kwargs)

Methods

__init__([met, params])
calculate_aircraft_performance(*, ...)	Calculate aircraft performance along a trajectory.
check_aircraft_type_availability(aircraft_type)	Check if aircraft type designator is available in the PS model database.
downselect_met()	Downselect met domain to the max/min bounds of source.
ensure_true_airspeed_on_source()	Add true_airspeed field to source data if not already present.
eval([source])	Evaluate the aircraft performance model.
get_source_param(key[, default, set_attr])	Get source data with default set by parameter key.
require_met()	Ensure that met is a MetDataset.
require_source_type(type_)	Ensure that source is type_.
set_source([source])	Attach original or copy of input source to source.
set_source_met(*args, **kwargs)	Ensure or interpolate each required met_variables on source .
simulate_fuel_and_performance(*, ...)	Calculate aircraft mass, fuel mass flow rate, and overall propulsion efficiency.
transfer_met_source_attrs([source])	Transfer met source metadata from met to source.
update_params([params])	Update model parameters on params.

Attributes

met	Meteorology data
params	Instantiated model parameters, in dictionary form
source	Data evaluated in model
hash	Generate a unique hash for model instance.
interp_kwargs	Shortcut to create interpolation arguments from params.
long_name
met_required	Require meteorology is not None on __init__()
met_variables	Required meteorology pressure level variables.
name
optional_met_variables	Optional meteorology variables
aircraft_engine_params
processed_met_variables	Set of required parameters if processing already complete on met input.

aircraft_engine_params

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.

check_aircraft_type_availability(aircraft_type, raise_error=True)

Check if aircraft type designator is available in the PS model database.

Parameters:

• aircraft_type (str) – ICAO aircraft type designator

• raise_error (bool, optional) – Optional flag for raising an error, by default True.

Returns:

bool – Aircraft found in the PS model database.

Raises:

KeyError – raises KeyError if the aircraft type is not covered by database

default_params

alias of PSFlightParams

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.

ensure_true_airspeed_on_source()

Add true_airspeed field to source data if not already present.

Returns:

npt.NDArray[np.floating] – 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().

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.

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:

1. source.data[key]. Returns np.ndarray | xr.DataArray.

2. source.attrs[key]

3. params[key]

4. default

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

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.

See also

-

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.

long_name = 'Poll-Schumann Aircraft Performance Model'

met

Meteorology data

met_required = False

Require meteorology is not None on __init__()

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.'),)

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. Only one variable in the tuple is required.

name = 'PSFlight'

optional_met_variables = (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

-

meth:eval

set_source_met(*args, **kwargs)

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.