Utilities

Custom types

Small custom types are used to represent “locations” (2-D) and “positions” (3-D), some time values and other small enumerations (e.g., aircraft classes).

class AEIC.types.Location(longitude, latitude)

A geographic location defined by longitude and latitude.

Parameters:

longitude (float)
latitude (float)

latitude: float: Latitude in decimal degrees.

longitude: float: Longitude in decimal degrees.

class AEIC.types.Position(longitude, latitude, altitude)

An aircraft position defined by longitude, latitude, and altitude.

Parameters:

longitude (float)
latitude (float)
altitude (float)

altitude: float: Altitude in meters above sea level.

latitude: float: Latitude in decimal degrees.

property location: Location: Get the 2D location (longitude and latitude) of this position.

longitude: float: Longitude in decimal degrees.

class AEIC.types.DayOfWeek(*values)

Days of the week, with Monday=1 through Sunday=7.

classmethod from_pandas(t)

Extract day of week from a pandas Timestamp.

Parameters:: t (Timestamp)
Return type:: Self

class AEIC.types.TimeOfDay(hour, minute)

A time of day as hours and minutes.

Parameters:

hour (int)
minute (int)

hour: int: Hour of day, 0-23.

minute: int: Minute of hour, 0-59.

enum AEIC.types.AircraftClass(value)

Member Type:: str

Valid values are as follows:

WIDE = <AircraftClass.WIDE: 'wide'>

NARROW = <AircraftClass.NARROW: 'narrow'>

SMALL = <AircraftClass.SMALL: 'small'>

FREIGHT = <AircraftClass.FREIGHT: 'freight'>

Airport handling

Airport data is downloaded from the OurAirports project. Data for some missing airports is added from a supplemental CSV file. The canonical way to use this module is as follows:

from AEIC.utils import airports

...

ap = airports.airport('LHR')
print(f'{ap.name} @ {ap.elevation} MSL')

class AEIC.utils.airports.Airport(iata_code, name, latitude, longitude, elevation, country, municipality)

Airport data.

Parameters:

iata_code (str)
name (str)
latitude (float)
longitude (float)
elevation (float | None)
country (str)
municipality (str | None)

country: str: ISO 3166-1 alpha-2 country code.

elevation: float | None: Elevation in meters above sea level, or None if not available.

iata_code: str: IATA airport code.

latitude: float: Latitude in decimal degrees.

longitude: float: Longitude in decimal degrees.

municipality: str | None: Municipality (city) where the airport is located, or None if not available.

name: str: Airport name.

property position: Position: Get the geographic position of the airport.

class AEIC.utils.airports.Country(code, name, continent)

Country data, including ISO 3166-1 alpha-2 code, name, and continent.

Parameters:

code (str)
name (str)
continent (str)

code: str: ISO 3166-1 alpha-2 country code.

continent: str: Continent code (e.g., ‘EU’ for Europe).

name: str: Country name.

AEIC.utils.airports.airport(code)

Retrieve airport data by IATA code.

Parameters:: code (str)
Return type:: Airport | None

AEIC.utils.airports.country(code)

Retrieve country data by ISO 3166-1 alpha-2 code.

Parameters:: code (str)
Return type:: Country | None

Unit conversion

Unit conversions are done with simple multiplying factors with a common x_TO_y naming pattern.

Note

The flight level conversions here are based on pressure altitudes, i.e., they simply scale given altitudes by 100 feet intervals.

Unit conversion factors for various measurements.

AEIC.units.FEET_TO_METERS = 0.3048: Unit conversion factor for feet to meters.

AEIC.units.FL_TO_METERS = 30.48: Unit conversion factor for flight level to meters.

AEIC.units.FPM_TO_MPS = 0.00508: Unit conversion factor for feet per minute to meters per second.

AEIC.units.KG_TO_GRAMS = 1000.0: Unit conversion factor for kilograms to grams.

AEIC.units.KNOTS_TO_MPS = 0.514444: Unit conversion factor for knots to m/s.

AEIC.units.METERS_TO_FEET = 3.28084: Unit conversion factor for meters to feet.

AEIC.units.METERS_TO_FL = 0.0328084: Unit conversion factor for meters to flight level.

AEIC.units.MINUTES_TO_SECONDS = 60: Unit conversion factor for minutes to seconds.

AEIC.units.MPS_TO_KNOTS = 1.9438461717893492: Unit conversion factor for m/s to knots.

AEIC.units.NAUTICAL_MILES_TO_METERS = 1852: Unit conversion factor for nautical miles to meters.

AEIC.units.PPM = 1e-06: Parts per million as a unitless fraction.

AEIC.units.STATUTE_MILES_TO_KM = 1.609344: Unit conversion factor for statute miles to kilometers.

Geospatial utilities

Great circle distance and azimuth calculations are needed in several places. These can all be done using the single pyproj.Geod instance defined in this module.

AEIC.utils.spatial.GEOD = Geod(ellps='WGS84'): WGS84 ellipsoid geodetic calculator.

AEIC.utils.spatial.great_circle_distance(lat1, lon1, lat2, lon2, degrees=False)

Calculates the great circle distance between two points. Note that the latitude and longitude inputs are in radians by default; set degrees=True if using degrees.

Parameters:

lat1 (Union[NDArray,float]) – latitude of the first point in radians
lon1 (Union[NDArray,float]) – longitude of the first point in radians
lat2 (Union[NDArray,float]) – latitude of the second point in radians
lon2 (Union[NDArray,float]) – longitude of the second point in radians
degrees (bool, optional) – If True, the input coordinates are in degrees.

Returns:

great circle distance between the two points in meters

Return type:

Union[NDArray,float]

File handling functions

AEIC.utils.files.download(url, dest_path)

Download a file from a URL to the given destination path.

Parameters:

url (str)
dest_path (Path | str)

Return type:

None

Standard atmosphere

AEIC.utils.standard_atmosphere.altitude_from_pressure_isa_bada4(pressure)

Return the altitude at the provided pressure(s). Units are SI (PA, m)

Parameters:: pressure (Union[float,NDArray]) – Pressure in Pascals.
Returns:: Altitude in meters.
Return type:: NDArray
Raises:: ValueError – If pressure is less than 0.

AEIC.utils.standard_atmosphere.calculate_air_density(pressure, temperature)

Calculate the air density depending on the provided pressure and temperature. Units are SI (Pa, K)

Parameters:

pressure (Union[float,NDArray]) – Pressure in Pascals.
temperature (Union[float,NDArray]) – Temperature in Kelvin.

Returns:

Air density in kg/m^3.

Return type:

NDArray

AEIC.utils.standard_atmosphere.calculate_speed_of_sound(temperature)

Calculate the speed of sound depending on the provided temperature(s). Units are SI (K, m/s)

Parameters:: temperature (Union[float,NDArray]) – Temperature in Kelvin.
Returns:: Speed of sound in m/s.
Return type:: NDArray
Raises:: ValueError – If temperature is greater than 216.69K.

AEIC.utils.standard_atmosphere.pressure_at_altitude_isa_bada4(altitude)

Return the pressure at the provided altitude(s). Units are SI (m, PA)

Parameters:: altitude (Union[float,NDArray]) – Altitude in meters.
Returns:: Pressure in Pascals.
Return type:: NDArray
Raises:: ValueError – If altitude is greater than 25000m.

AEIC.utils.standard_atmosphere.speed_of_sound_at_altitude(altitude)

Calculate the speed of sound depending on the provided altitude(s). Units are SI (m, m/s)

Parameters:: altitude (Union[float,NDArray]) – Altitude in meters.
Returns:: Speed of sound in m/s.
Return type:: NDArray
Raises:: ValueError – If altitude is greater than 25000m.

AEIC.utils.standard_atmosphere.temperature_at_altitude_isa_bada4(altitude)

Return the temperature at the provided altitude(s). Units are SI (m, Kelvin)

Parameters:: altitude (Union[float,NDArray]) – Altitude in meters.
Returns:: Temperature in Kelvin.
Return type:: NDArray
Raises:: ValueError – If altitude is greater than 25000m.

Standard fuel

As well as the functions in the AEIC.utils.standard_fuel module, there is a Fuel class defined in AEIC.types.

AEIC.utils.standard_fuel.get_SLS_equivalent_fuel_flow(fuel_flow, Pamb, Tamb, mach_number, z=3.8, P_SL=101325.0, T_SL=288.15, n_eng=2)

Convert in-flight fuel flow to its sea-level-static (SLS) equivalent using the Fuel-Flow Method 2 correction (Eq. 40 in DuBois & Paynter, 2006).

Parameters:

fuel_flow (numpy.ndarray) – In-flight (altitude) fuel flow, \(\dot m_{f,\text{alt}}\) .
Pamb (numpy.ndarray) – Ambient static pressure, \(P_{amb}\), in Pa.
mach_number (numpy.ndarray) – Flight Mach number, \(M\).
z (float, default 3.8) – Exponent applied to the temperature ratio \(\theta\); default value 3.8.
P_SL (float, default 101 325 Pa) – Sea-level standard static pressure, \(P_{SL}\) (ISA).
Tamb (ndarray)
T_SL (float)
n_eng (int)

Returns:

Wf_SL – Sea-level-static equivalent fuel flow, \(\dot m_{f,SL}\) in kg s⁻¹.

Return type:

float or numpy.ndarray

References

DuBois, D. & Paynter, G. (2006). Fuel Flow Method 2 for Estimating Aircraft Emissions. SAE Technical Paper 2006-01-1987.

AEIC.utils.standard_fuel.get_thrust_cat_cruise(ff_eval, ff_cal)

Classify each cruise fuel-flow value into a discrete thrust-setting category.

Parameters:

ff_eval (numpy.ndarray) – Fuel-flow values to be evaluated Shape (n_times,).
ff_cal (numpy.ndarray) – Calibration fuel-flow points: at least the first three cruise calibration points are required (typically Idle, Approach, Climb/Take-off).

Returns:

thrustCat – Integer category codes, same length as ff_eval:

Return type:

numpy.ndarray, dtype=int (ICAOThrustMode)

Raises:

ValueError – If the size/length constraints on ff_eval or ff_cal are violated.

Notes

Two mid-points define the category boundaries lowLimit = (ff_cal[0] + ff_cal[1]) / 2 approachLimit = (ff_cal[1] + ff_cal[2]) / 2

Idle : ff_eval ≤ lowLimit → IDLE
Take-off/Climb: ff_eval > approachLimit → TAKEOFF_CLIMB
Approach : remainder → APPROACH

class AEIC.types.Fuel(*, name, energy_MJ_per_kg, EI_H2O, EI_CO2, non_volatile_carbon_content, lifecycle_CO2=None, fuel_sulfur_content_nom, sulfate_yield_nom)

Parameters:

name (str)
energy_MJ_per_kg (float)
EI_H2O (float)
EI_CO2 (float)
non_volatile_carbon_content (float)
lifecycle_CO2 (float | None)
fuel_sulfur_content_nom (float)
sulfate_yield_nom (float)

EI_CO2: float: Emission index for carbon dioxide (g CO2 / kg fuel).

EI_H2O: float: Emission index for water vapor (g H2O / kg fuel).

energy_MJ_per_kg: float: Fuel energy content in MJ/kg.

fuel_sulfur_content_nom: float: Fuel sulfur content (nominal) in ppm by weight (mg S / kg fuel).

lifecycle_CO2: float | None: Life-cycle CO2 emissions (g CO2e / MJ fuel).

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration is frozen after creation.

name: str: Fuel name.

non_volatile_carbon_content: float: Non-volatile carbon content (???).

sulfate_yield_nom: float: Sulfate yield (nominal) as fraction of fuel sulfur content converted to sulfate.

Miscellaneous utility functions

AEIC.utils.helpers.calculate_line_parameters(x, y)

Calculates the slope and intercept of the lines defined by the points (x, y).

Parameters:

x (NDArray) – The x coordinates of the points.
y (NDArray) – The y coordinates of the points.

Returns:

The slopes and intercepts of the lines defined by the points (x, y).

Return type:

tuple[NDArray, NDArray]

AEIC.utils.helpers.date_to_timestamp(d)

Convert a Python date to a UTC Pandas Timestamp at midnight.

Parameters:: d (date)
Return type:: Timestamp

AEIC.utils.helpers.iso_to_timestamp(s)

Convert an ISO 8601 string to a UTC Pandas Timestamp.

Parameters:: s (str)
Return type:: Timestamp

Data modeling utility classes

class AEIC.utils.models.CIBaseModel

Pydantic base model that recursively normalizes input keys to match lower-case model field names.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enum AEIC.utils.models.CIStrEnum(value)

Case-insensitive string enumeration.

Member Type:: str