pycontrails.ext.bada.BADA3

class pycontrails.ext.bada.BADA3(bada_path=None)

Bases: BADA

BADA 3.15 and 3.16 Support.

Base of Aircraft Data (BADA) provides a set of ASCII files containing performance and operating procedure coefficients for 264 different aircraft types (BADA 3.16), or 250 different aircraft types (BADA 3.15). This class implements the “total energy model” as described in BADA User Manual.

Parameters:

bada_path (str | pathlib.Path, optional) – Path to BADA 3.15 or 3.16 Model files. Default path set to /bada/bada3 in the parent directory of the pycontrails repository.

References

  • Eurocontrol. User Manual for the Base of Aircraft Data (BADA) Revision 3.16. Vol EEC Techni. Eurocontrol Experimental Centre; 2022.

  • Eurocontrol. User Manual for the Base of Aircraft Data (BADA) Revision 3.15. Vol EEC Techni. Eurocontrol Experimental Centre; 2019.

__init__(bada_path=None)

Methods

__init__([bada_path])

calculate_aircraft_performance(*, ...)

Calculate aircraft performance along a trajectory.

check_aircraft_type_availability(aircraft_type)

Check if aircraft type designator is available in BADA database.

clip_fuel_flow_by_ptf_bounds(atyp_icao, ...)

Clip array of fuel flow by the BADA PTF-defined thresholds.

correct_fuel_flow(atyp_icao, fuel_flow, ...)

Correct unrealistic fuel mass flow rate by clipping to PTF nominals.

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_aircraft_engine_properties(atyp_icao[, ...])

Extract the aircraft performance and engine properties from the BADA database.

get_aircraft_params(aircraft_type)

Get aircraft params associated to aircraft type.

get_ptf_params(aircraft_type)

Get PTF params associated to aircraft type.

get_source_param(key[, default, set_attr])

Get source data with default set by parameter key.

is_within_thrust_limits(*, atyp_bada, ...)

Determine whether thrust required at each waypoint is within bounds of BADA model.

nominal_cruising_speed(aircraft_type, alt_ft)

Compute nominal cruising speed at altitude by interpolating over PTF data.

nominal_fuel_flow(aircraft_type, alt_ft, phase)

Compute nominal fuel flow depending on phase based on PTF data.

nominal_fuel_flow_from_flight_phase(...)

Call nominal_fuel_flow() for each phase according to flight_phase.

nominal_roc(aircraft_type, alt_ft)

Compute nominal rate of climb at altitude by interpolating over PTF data.

nominal_rod(aircraft_type, alt_ft)

Compute nominal rate of descent at altitude by interpolating over PTF data.

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

path

Path to BADA data directory

synonym_dict

Aircraft type synonyms

aircraft_engine_dataframe

Available/assumed aircraft-engine combinations

ptf_params_dict

aircraft_param_dict

Engine and aircraft properties common to BADA3 and BADA4

default_path

Default path to BADA data directories

version

BADA version.

hash

Generate a unique hash for model instance.

interp_kwargs

Shortcut to create interpolation arguments from params.

long_name

met

Meteorology data

met_required

Require meteorology is not None on __init__()

name

params

Instantiated model parameters, in dictionary form

source

Data evaluated in model

ptf_param_dict

Coefficients and properties extracted from BADA3 and BADA4 PTF files

met_variables

Required meteorology pressure level variables.

processed_met_variables

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

optional_met_variables

Optional meteorology variables

aircraft_engine_dataframe

Available/assumed aircraft-engine combinations

aircraft_param_dict

Engine and aircraft properties common to BADA3 and BADA4

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 BADA database.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

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

Returns:

bool – Aircraft found in BADA database.

Raises:

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

clip_fuel_flow_by_ptf_bounds(atyp_icao, alt_ft, fuel_flow, phase, buffer=0.1)

Clip array of fuel flow by the BADA PTF-defined thresholds.

Often, especially at high altitudes, the BADA “hi” and “lo” values both coincide with the “nom” values. Consequently, it is impossible for a predicted fuel flow to fall within the PTF range. To account for this, values within +/- 10% of nominal are considered in range.

Parameters:
  • atyp_icao (str) – ICAO aircraft type designator.

  • alt_ft (npt.NDArray[np.floating]) – Array of altitude values, [\(ft\)]

  • fuel_flow (npt.NDArray[np.floating]) – Values to clip

  • phase (str, optional) – One of “cruise”, “climb”, or “descent”. By default, “cruise”.

  • buffer (float, optional) – Custom nominal buffer, [:math: 0 - 1] Values within buffer of nominal are considered “within range”. By default, 0.1.

Returns:

npt.NDArray[np.floating] – Clipped fuel flow

correct_fuel_flow(atyp_icao, fuel_flow, altitude_ft, flight_phase)

Correct unrealistic fuel mass flow rate by clipping to PTF nominals.

The BADA PTF files provide “guardrails” for fuel flow values within a specified flight phase (climb, cruise, descent). Specifically, the PTF files provide a nominal, a high, and low value for fuel flows.

The high and low PTF values often fail to provide a sufficiently wide range for fuel flow. To address this, an additional buffer is applied to the nominal values. The adjust PTF ranges take the form

ptf_adjusted_low = minimum(ptf_nom - buffer, ptf_low) ptf_adjusted_high = minimum(ptf_nom + buffer, ptf_high)

This implementation hard codes distinct buffer thresholds for the climb, cruise, and descent phases of flights. These buffers were tuned on real-world flight recorder data to optimize BADA’s predictive quality. These values could be revisited with additional flight recorder data or improved BADA models.

Parameters:
  • atyp_icao (str) – ICAO aircraft type designator.

  • fuel_flow (npt.NDArray[np.floating]) – Uncorrected fuel mass flow rate, [\(kg s^{-1}\)]

  • altitude_ft (npt.NDArray[np.floating]) – Array of altitude values, [\(ft\)]

  • flight_phase (npt.NDArray[np.uint8] | flight.FlightPhase) – Phase state of each waypoint.

Returns:

npt.NDArray[np.floating] – Corrected fuel mass flow rate, [\(kg s^{-1}\)]

default_params

alias of AircraftPerformanceParams

default_path

Default path to BADA data directories

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:
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_aircraft_engine_properties(atyp_icao, engine_uid=None)

Extract the aircraft performance and engine properties from the BADA database.

Parameters:
  • atyp_icao (str) – ICAO aircraft type designator.

  • engine_uid (str) – Engine unique identification number from the ICAO EDB. If None is provided or engine_uid is unidentified, default aircraft-engine combination from BADA will be used. This parameter is unused for BADA3; it is only considered for BADA4.

Returns:

AircraftProperties

get_aircraft_params(aircraft_type)

Get aircraft params associated to aircraft type.

Parameters:

aircraft_type (str) – ICAO aircraft type designator, or BADA-specific aircraft type.

Returns:

AircraftParams – Value from aircraft_param_dict.

get_ptf_params(aircraft_type)

Get PTF params associated to aircraft type.

Parameters:

aircraft_type (str) – ICAO aircraft type designator, or BADA-specific aircraft type.

Returns:

PTFParams – Value from ptf_param_dict.

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.

is_within_thrust_limits(*, atyp_bada, altitude_ft, air_temperature, time, true_airspeed, aircraft_mass, thrust, flight_phase)

Determine whether thrust required at each waypoint is within bounds of BADA model.

If thrust is not provided as input, it will be computed according to BADA standards. Thrust limits are only defined for the BADA3 model. For BADA4, this function will raise a NotImplementedError.

Parameters:
  • atyp_bada (str) – ICAO aircraft type designator (BADA 3), or long aircraft type designator (BADA 4).

  • 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, the nominal BADA cruise value is used.

  • aircraft_mass (npt.NDArray[np.floating] | float | None) – Aircraft mass for each waypoint, [\(kg\)]. If None, the nominal BADA value is used.

  • thrust (npt.NDArray[np.floating] | float | None) – Override the thrust setting at each waypoint, [:math: N].

  • flight_phase (npt.NDArray[np.uint8] | flight.FlightPhase | None) – Flight phase for each waypoint. If None, the flight phase is assumed to be cruise.

Returns:

npt.NDArray[np.bool_] – Boolean array telling whether the thrust at each waypoint is within BADA trust limits

long_name = 'Base of Aircraft Data (BADA) Revision 3.15/3.16'
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. Only one variable in the tuple is required.

name = 'BADA3'
nominal_cruising_speed(aircraft_type, alt_ft)

Compute nominal cruising speed at altitude by interpolating over PTF data.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

  • alt_ft (ArrayOrFloat) – Array of altitude values, [\(ft\)]

Returns:

ArrayOrFloat – Nominal cruising speed according to BADA, [\(m/s\)]

nominal_fuel_flow(aircraft_type, alt_ft, phase, type='nom')

Compute nominal fuel flow depending on phase based on PTF data.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

  • alt_ft (ArrayOrFloat) – Array of altitude values, [\(ft\)]

  • phase (str) – One of “cruise”, “climb”, or “descent”

  • type (str, optional) – One of “nom”, “hi”, or “lo”.

Returns:

ArrayOrFloat – Nominal fuel flow, [\(kg \ s^{-1}\)]

See also

calculate_aircraft_performance(), by, drag, and

nominal_fuel_flow_from_flight_phase(aircraft_type, alt_ft, flight_phase)

Call nominal_fuel_flow() for each phase according to flight_phase.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

  • alt_ft (ArrayOrFloat) – Array of altitude values, [\(ft\)]

  • flight_phase (npt.NDArray[np.uint8] | flight.FlightPhase) – Phase state of each waypoint.

Returns:

npt.NDArray[np.floating] – Nominal PTF fuel flow, [\(kg s^{-1}\)].

nominal_roc(aircraft_type, alt_ft)

Compute nominal rate of climb at altitude by interpolating over PTF data.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

  • alt_ft (ArrayOrFloat) – Array of altitude values, [\(ft\)]

Returns:

ArrayOrFloat – Nominal rate of climb according to BADA, [\(ft \ min^{-1}\)]

nominal_rod(aircraft_type, alt_ft)

Compute nominal rate of descent at altitude by interpolating over PTF data.

Parameters:
  • aircraft_type (str) – ICAO aircraft type designator (BADA 3), or aircraft model (BADA 4)

  • alt_ft (ArrayOrFloat) – Array of altitude values, [\(ft\)]

Returns:

ArrayOrFloat – Nominal rate of descent according to BADA, [\(ft \ min^{-1}\)]

optional_met_variables

Optional meteorology variables

params

Instantiated model parameters, in dictionary form

path

Path to BADA data directory

processed_met_variables

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

ptf_param_dict

Coefficients and properties extracted from BADA3 and BADA4 PTF files

ptf_params_dict
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:
Raises:
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

synonym_dict

Aircraft type synonyms

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.

version

BADA version. Currently only used on BADA3 class.