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:: DayOfWeek

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.GEOD = Geod(ellps='WGS84'): WGS84 ellipsoid geodetic calculator.

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.

Fuel

class AEIC.types.Fuel(*, name, energy_MJ_per_kg, EI_H2O, EI_CO2, non_volatile_carbon_fraction, 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_fraction (float)
lifecycle_CO2 (float | None)
fuel_sulfur_content_nom (float)
sulfate_yield_nom (float)

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

EI_H2O: float: Emission index for water vapor (g H₂O / 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 CO₂ emissions (g CO₂e / MJ fuel).

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

name: str: Fuel name.

non_volatile_carbon_fraction: float: Mass fraction of non-volatile particulate matter (PMnvol) that is carbon by weight (kg C / kg PMnvol)

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

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