Utilities

Custom types

Small custom types are used to represent “locations” (2-D) and “positions” (3-D) and some time values.

class AEIC.utils.types.Location(longitude: float, latitude: float)

A geographic location defined by longitude and latitude.

latitude: float: Latitude in decimal degrees.

longitude: float: Longitude in decimal degrees.

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

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

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.utils.types.DayOfWeek(*values)

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

classmethod from_pandas(t: Timestamp) → Self: Extract day of week from a pandas Timestamp.

class AEIC.utils.types.TimeOfDay(hour: int, minute: int)

A time of day as hours and minutes.

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

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

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: str, name: str, latitude: float, longitude: float, elevation: float | None, country: str, municipality: str | None)

Airport data.

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: str, name: str, continent: str)

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

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: str) → Airport | None: Retrieve airport data by IATA code.

AEIC.utils.airports.country(code: str) → Country | None: Retrieve country data by ISO 3166-1 alpha-2 code.

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.

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

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

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

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

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

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

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

AEIC.utils.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: float | ndarray[tuple[Any, ...], dtype[float64]], lon1: float | ndarray[tuple[Any, ...], dtype[float64]], lat2: float | ndarray[tuple[Any, ...], dtype[float64]], lon2: float | ndarray[tuple[Any, ...], dtype[float64]], degrees: bool = 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: str, dest_path: Path | str) → None: Download a file from a URL to the given destination path.

Standard atmosphere

AEIC.utils.standard_atmosphere.altitude_from_pressure_isa_bada4(pressure: float | ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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: float | ndarray[tuple[Any, ...], dtype[_ScalarT]], temperature: float | ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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: float | ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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: float | ndarray[tuple[Any, ...], dtype[float64]]) → float | ndarray[tuple[Any, ...], dtype[float64]]

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: float | ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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

AEIC.utils.standard_fuel.get_SLS_equivalent_fuel_flow(fuel_flow: ndarray, Pamb: ndarray, Tamb: ndarray, mach_number: ndarray, z: float = 3.8, P_SL: float = 101325.0, T_SL: float = 288.15, n_eng: int = 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).

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(ff_eval: ndarray, ff_cal: ndarray, cruiseCalc: bool) → ndarray

Classify each 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 If cruiseCalc is True: at least the first three cruise calibration points are required (typically Idle, Approach, Climb/Take-off). If cruiseCalc is False: exactly four LTO-mode points are expected.
cruiseCalc (bool) –
- True → Cruise calculation.
- False → Only LTO calculation.

Returns:

thrustCat – Integer category codes, same length as ff_eval:

Code | Meaning (ICAO convention) |

|------|—————————| | 1 | Take-off / Climb | | 2 | Idle | | 3 | Approach |

Return type:

numpy.ndarray, dtype=int

Raises:

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

Notes

Cruise mode (`cruiseCalc=True`)

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 → code 2
Take-off/Climb: ff_eval > approachLimit → code 1
Approach : remainder → code 3

LTO mode (`cruiseCalc=False`)

The four thrust categories are fixed to [2, 2, 3, 1] (Idle, Idle-2, Approach, Take-off) and simply returned.

Miscellaneous utility functions

AEIC.utils.helpers.calculate_line_parameters(x: ndarray[tuple[Any, ...], dtype[_ScalarT]], y: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → tuple[ndarray[tuple[Any, ...], dtype[_ScalarT]], ndarray[tuple[Any, ...], dtype[_ScalarT]]]

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: date) → Timestamp: Convert a Python date to a UTC Pandas Timestamp at midnight.

AEIC.utils.helpers.filter_order_duplicates(seq): Filters duplicate list entries while perserving order

AEIC.utils.helpers.iso_to_timestamp(s: str) → Timestamp: Convert an ISO 8601 string to a UTC Pandas 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