pycontrails.ext.bada.BADAFlight¶
- class pycontrails.ext.bada.BADAFlight(met=None, params=None, **params_kwargs)¶
Bases:
AircraftPerformance
Compute aircraft properties and fuel consumption.
- Parameters:
met (
MetDataset | None
, optional) – Dataset containing “air_temperature”, “eastward_wind”, and “northward_wind” variables. Only used if these variables are not already found on parametersource
ineval()
. By default None.params (
dict[str
,Any]
, optional) – Override model parameters with dictionary. SeeBADAFlightParams
for model parameters.**params_kwargs – Override model parameters with keyword arguments. See
BADAFlightParams
for model parameters.
See also
-
meth:eval
-
class:BADAFlightParams
- __init__(met=None, params=None, **params_kwargs)¶
Methods
__init__
([met, params])calculate_aircraft_performance
(*, ...)Calculate aircraft performance along a trajectory.
Add
true_airspeed
field tosource
data if not already present.eval
([source])Extract aircraft properties and calculate the fuel consumption.
get_bada
(aircraft_type)Check BADA databases for
aircraft_type
.get_source_param
(key[, default, set_attr])Get source data with default set by parameter key.
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
Meteorology data
Instantiated model parameters, in dictionary form
Data evaluated in model
Generate a unique hash for model instance.
Shortcut to create interpolation arguments from
params
.Require meteorology is not None on __init__()
Required meteorology pressure level variables.
Optional meteorology variables
Set of required parameters if processing already complete on
met
input.- 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.
- default_params¶
alias of
BADAFlightParams
- 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)¶
Extract aircraft properties and calculate the fuel consumption.
Input
source
must contain a validaircraft_type
in itssource.attrs["aircraft_type"]
.If
met
data is not passed into instance constructor, parametersource
must contain the following data variables. - true_airspeed - air_temperatureIf the following variables are not provided in the flight attribute, the default aircraft-engine assignment and aircraft mass properties from BADA will be assumed: - engine_uid - max_takeoff_weight - operating_empty_weight - max_payload
If ‘load_factor’ (ranging between 0 and 1) is not provided in the flight attribute, the aircraft mass at the first waypoint will be set to the reference mass for the specific aircraft type from the BADA database.
- This method extracts the following aircraft properties from the BADA database.
aircraft_type_bada
wingspan
max_mach
max_altitude
engine_name
n_engine
- From these BADA derived quantities, each of the following is computed.
fuel_flow: fuel mass flow rate, [\(kg s^{-1}\)]
fuel_burn: total fuel burn between two waypoints, [\(kg\)]
aircraft_mass
engine_efficiency
thrust
- get_bada(aircraft_type)¶
Check BADA databases for
aircraft_type
.- Parameters:
aircraft_type (
str
) – Aircraft type to check for.- Returns:
BADA
– BADA database object.
- 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
.
- long_name = 'Base of aircraft data flight 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 atuple[MetVariable]
. If element is atuple[MetVariable]
, the variable depends on the data source. Only one variable in the tuple is required.
- name = 'bada'¶
- 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 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