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.
Add
true_airspeed
field tosource
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.
Call
nominal_fuel_flow()
for each phase according toflight_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.
Ensure that
met
is a MetDataset.require_source_type
(type_)Ensure that
source
istype_
.set_source
([source])Attach original or copy of input
source
tosource
.set_source_met
(*args, **kwargs)Ensure or interpolate each required
met_variables
onsource
.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
tosource
.update_params
([params])Update model parameters on
params
.Attributes
Path to BADA data directory
Aircraft type synonyms
Available/assumed aircraft-engine combinations
Engine and aircraft properties common to BADA3 and BADA4
Default path to BADA data directories
BADA version.
Generate a unique hash for model instance.
Shortcut to create interpolation arguments from
params
.Meteorology data
Require meteorology is not None on __init__()
Instantiated model parameters, in dictionary form
Data evaluated in model
Coefficients and properties extracted from BADA3 and BADA4 PTF files
Required meteorology pressure level variables.
Set of required parameters if processing already complete on
met
input.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 thetime
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 innp.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.
- 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 clipphase (
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 ofsource
.Override this method if special handling is needed in met down-selection.
source
must be defined before callingdownselect_met()
.This method copies and re-assigns
met
usingmet.copy()
to avoid side-effects.
- Raises:
ValueError – Raised if
source
is not defined. Raised ifsource
is not aGeoVectorDataset
.
- ensure_true_airspeed_on_source()¶
Add
true_airspeed
field tosource
data if not already present.- Returns:
npt.NDArray[np.floating]
– True airspeed, [\(m s^{-1}\)]. Iftrue_airspeed
is already present onsource
, this is returned directly. Otherwise, it is calculated usingFlight.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 waypointrocd
: 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 engineswingspan
: wingspan, [\(m\)]max_mach
: maximum Mach numbermax_altitude
: maximum altitude, [\(m\)]total_fuel_burn
: total fuel burn, [\(kg\)]
- 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 forBADA3
; it is only considered forBADA4
.
- 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 fromaircraft_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 fromptf_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:
source.data[key]
. Returnsnp.ndarray | xr.DataArray
.source.attrs[key]
params[key]
default
In case 3., the value of
params[key]
is attached tosource.attrs[key]
.- Parameters:
- 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 atuple[MetVariable]
. If element is atuple[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:
- 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 toflight_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 tomet
. This is helpful for type narrowingmet
when meteorology is required.- Raises:
ValueError – Raises when
met
is None.
- require_source_type(type_)¶
Ensure that
source
istype_
.- Returns:
_Source
– Returns reference tosource
. This is helpful for type narrowingsource
to specific type(s).- Raises:
ValueError – Raises when
source
is not_type_
.
- set_source(source=None)¶
Attach original or copy of input
source
tosource
.- Parameters:
source (
MetDataset | GeoVectorDataset | Flight | Iterable[Flight] | None
) – Parametersource
passed ineval()
. If None, an empty MetDataset with coordinates likemet
is set tosource
.
See also
-
meth:eval
- set_source_met(*args, **kwargs)¶
Ensure or interpolate each required
met_variables
onsource
.For each variable in
met_variables
, checksource
for data variable with the same name.For
GeoVectorDataset
sources, try to interpolatemet
if variable does not exist.For
MetDataset
sources, try to get data frommet
if variable does not exist.- Parameters:
optional (
bool
, optional) – Includeoptional_met_variables
variable (
MetVariable | Sequence[MetVariable] | None
, optional) – MetVariable to set, frommet_variables
. If None, set all variables inmet_variables
andoptional_met_variables
ifoptional
is True.
- Raises:
ValueError – Variable does not exist and
source
is a MetDataset.
- 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 callscalculate_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 innp.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 iftakeoff_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 iftakeoff_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 iftakeoff_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 injet.initial_aircraft_mass()
. In this case, the parametersload_factor
,amass_oew
,amass_mtow
, andamass_mpl
are ignored.**kwargs (
Any
) – Additional keyword arguments are passed tocalculate_aircraft_performance()
.
- Returns:
AircraftPerformanceData
– Results from the final iteration is returned.
- source¶
Data evaluated in model
- synonym_dict¶
Aircraft type synonyms
- 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 inparams
with keyword arguments.
- version¶
BADA version. Currently only used on BADA3 class.