Performance model API

Performance model classes are all Pydantic models derived from BasePerformanceModel. This is an abstract base class that includes data common to all performance model types (aircraft name and class, maximum altitude and payload, number of engines, optional APU information and optional LTO and speed information) and that defines the performance model API. The legacy table-based performance model is represented by the LegacyPerformanceModel class. This includes a performance table represented by the PerformanceTable class which performs subsetting and interpolation within the input data.

Loading performance models

Performance models can be loaded from TOML files. A top-level model_type string field is used to distinguish between different types of performance model and a PerformanceModel wrapper class is used to enable this: there is a load class method with a polymorphic return type, that takes a path to a TOML file containing a performance model definition and returns an instance of the correct performance model class based on the model_type field. For the current legacy-based performance models, use model_type = "legacy".

Performance evaluation

The fundamental operation of a performance model is to take an aircraft state, (represented by a value of the AircraftState type) and a flight rule (see below) and to return aircraft performance data (a value of the Performance type). This is achieved by calling the evaluate method on a performance model instance.

Aircraft state includes altitude, aircraft mass and optionally a target true airspeed and/or rate of climb/descent. Some performance models may make use of the optional values, some may not. The legacy table-based performance model does not: all return values from the legacy model depend only on aircraft altitude, aircraft mass and a simple climb/cruise/descent flight rule.

The performance data returned from the evaluate method contains actual achievable true airspeed, actual achievable rate of climb/descent and fuel flow rate.

Different types of performance model may implement different kinds of potential flight rules. For example, a performance model might support specifying that climb and descent phases should be conducted at constant rate of climb, constant calibrated airspeed, or constant Mach number, and the cruise phase at constant altitude or constant lift coefficient. The simplest flight rules, as used by the LegacyPerformanceModel class, are represented by the SimpleFlightRules class, which simply specifies “climb”, “cruise”, or “descend”.

Usage example

import tomllib
from AEIC.config import Config, config
from AEIC.types import AircraftState, SimpleFlightRules
from AEIC.performance.models import PerformanceModel, LegacyPerformanceModel
from AEIC.units import FL_TO_METERS

# Load default AEIC configuration.
Config.load();

# Load (table-based legacy) performance model.
model = PerformanceModel.load(
    config.file_location('performance/sample_performance_model.toml')
)
assert isinstance(model, LegacyPerformanceModel)

# Create aircraft state.
state = AircraftState(altitude=350*FL_TO_METERS, aircraft_mass=70000)

# Evaluate performance model for state and flight rules.
perf = model.evaluate(state, SimpleFlightRules.CLIMB)

print(perf)
# Result:
# Performance(
#     true_airspeed=237.4846304442151,
#     rate_of_climb=33.69675733337415,
#     fuel_flow=1.5102911008506104
# )

Performance model members

After a performance model instance is created (of any type derived from BasePerformanceModel), as well as being set up for calls to the evaluate method, the instance also contains:

  • Basic information about the performance model: aircraft name and class, number of engines, maximum altitude and payload.

  • lto_performance: modal thrust settings, fuel flows, and emission indices taken from the performance file.

  • apu: auxiliary-power-unit properties resolved from engines/APU_data.toml using the apu_name specified in the performance file.

  • speeds: cruise speed data.

API reference

class AEIC.performance.models.BasePerformanceModel(*, aircraft_name, aircraft_class, maximum_altitude_ft, maximum_payload_kg, number_of_engines, apu_name=None, speeds, lto_performance)

Base class for aircraft performance models.

This a generic class parameterized by the type of flight rules accepted by the class’s evaluate method. By default, this is SimpleFlightRules, but subclasses can override this to specify more sophisticated flight rule types.

(This class uses the pattern of splitting the evaluate method into two steps to allow for type checking of the flight rules input before calling the actual implementation defined in subclasses. Similarly, it duplicates the flight rules class generic parameter as a class variable to allow for both static and runtime checking of the flight rules type in subclasses.)

Parameters:

  • aircraft_name (str)

  • aircraft_class (AircraftClass)

  • maximum_altitude_ft (Annotated[int, Gt(gt=0)])

  • maximum_payload_kg (Annotated[int, Gt(gt=0)])

  • number_of_engines (Annotated[int, Gt(gt=0)])

  • apu_name (str | None)

  • speeds (Speeds | None)

  • lto_performance (LTOPerformanceInput | None)

FLIGHT_RULES_CLASS(value)

alias of SimpleFlightRules :Member Type: str

aircraft_class: AircraftClass

Aircraft class (e.g., wide or narrow body).

aircraft_name: str

Aircraft name (e.g., “A320”).

property apu: APU | None

APU data associated with the performance model.

This is loaded from the APU database based on the apu_name field using the AEIC.performance.utils.apu.find_apu function.

abstract property empty_mass: float

Aircraft empty mass, to be implemented by subclasses.

evaluate(state, rules)

Evaluate aircraft performance based on the given state and flight rules.

The implementation of this method is split into two steps (_evaluate_checked, defined here, and evaluate_impl, defined in subclasses) to ensure that the flight rules type is checked before evaluation. The type declaration on evaluate uses the generic type variable RulesT to allow subclasses to specify more specific flight rules types.

Parameters:
Return type:

Performance

abstractmethod evaluate_impl(state, rules)

Actual performance evaluation function, to be implemented in subclasses.

Parameters:
Return type:

Performance

property lto: LTOPerformance

LTO performance data associated with the performance model.

Raises:

ValueError – If LTO performance data is not available.

lto_performance: LTOPerformanceInput | None

Optional LTO performance data.

property maximum_altitude: float

Aircraft maximum altitude in meters.

maximum_altitude_ft: Annotated[int, Gt(gt=0)]

Aircraft maximum altitude in feet.

abstract property maximum_mass: float

Aircraft maximum mass, to be implemented by subclasses.

property maximum_payload: float

Aircraft maximum payload in kg.

maximum_payload_kg: Annotated[int, Gt(gt=0)]

Aircraft maximum payload in kilograms.

number_of_engines: Annotated[int, Gt(gt=0)]

Number of engines.

speeds: Speeds | None

Optional speed data.

class AEIC.performance.models.PerformanceModel(root=PydanticUndefined)

Performance model loader.

This is a wrapper class to implement loading of performance models from TOML data, and additionally to make the model_type field used for discriminating model types case-insensitive.

Parameters:

root (RootModelRootType)

classmethod from_data(data)

Initialize a performance model from a dictionary.

Parameters:

data (dict)

Return type:

Annotated[BADAPerformanceModel | TASOPTPerformanceModel | PianoPerformanceModel | LegacyPerformanceModel, FieldInfo(annotation=NoneType, required=True, discriminator=’model_type’)]

classmethod load(path)

Load a performance model from a TOML file.

The exact performance model type is determined by the model_type field in the TOML data.

Parameters:

path (str | Path)

Return type:

Annotated[BADAPerformanceModel | TASOPTPerformanceModel | PianoPerformanceModel | LegacyPerformanceModel, FieldInfo(annotation=NoneType, required=True, discriminator=’model_type’)]

class AEIC.types.AircraftState(altitude, aircraft_mass, true_airspeed=None, rate_of_climb=None)

Aircraft state container for performance model inputs.

The fundamental inputs required for performance model evaluation are altitude and aircraft mass. Depending on the performance model being used, true airspeed and rate of climb/descent may also be required.

Parameters:

  • altitude (float)

  • aircraft_mass (float | Literal['min', 'max'])

  • true_airspeed (float | None)

  • rate_of_climb (float | None)

aircraft_mass: float | Literal['min', 'max']

Aircraft total mass [kg]. Can also be ‘min’ or ‘max’ to indicate minimum or maximum aircraft mass.

altitude: float

Altitude [m].

rate_of_climb: float | None = None

Rate of climb/descent [m/s]. Whether this needs to be provded depends on the performance model being used.

true_airspeed: float | None = None

True airspeed [m/s]. Whether this needs to be provided depends on the performance model being used.

class AEIC.types.Performance(true_airspeed, rate_of_climb, fuel_flow)

Aircraft performance outputs from performance model.

Parameters:

  • true_airspeed (float)

  • rate_of_climb (float)

  • fuel_flow (float)

fuel_flow: float

Fuel flow in [kg/s].

rate_of_climb: float

Actual achievable rate of climb/descent [m/s].

true_airspeed: float

Actual achievable true airspeed [m/s].

enum AEIC.types.SimpleFlightRules(value)

Flight rules class for simplest case, where the only distinction is between climb, cruise, and descent.

Member Type:

str

Valid values are as follows:

CLIMB = <SimpleFlightRules.CLIMB: 'climb'>
CRUISE = <SimpleFlightRules.CRUISE: 'cruise'>
DESCEND = <SimpleFlightRules.DESCEND: 'descend'>
class AEIC.types.performance.LTOPerformance(source, ICAO_UID, rated_thrust, thrust_pct, fuel_flow, EI_NOx, EI_HC, EI_CO)

LTO performance data as used internally.

Parameters:
EI_CO: ModeValues

Emission index for CO in thrust mode [g/kg fuel].

EI_HC: ModeValues

Emission index for HC in thrust mode [g/kg fuel].

EI_NOx: ModeValues

Emission index for NOx in thrust mode [g/kg fuel].

ICAO_UID: str

ICAO engine ID from engine database (EDB). For documentation only.

fuel_flow: ModeValues

Fuel flow rate in thrust mode [kg/s].

rated_thrust: float

Engine rated thrust [N].

source: str

Source of LTO data (e.g., ‘EDB’ or ‘BADA LTO file’). For documentation only.

thrust_pct: ModeValues

Thrust percentage in thrust mode (0-100).

enum AEIC.types.ThrustMode(value)

Flight modes for LTO data.

The enumeration values here are ordered by the format of LTO files.

Member Type:

str

Valid values are as follows:

IDLE = <ThrustMode.IDLE: 'idle'>
APPROACH = <ThrustMode.APPROACH: 'approach'>
CLIMB = <ThrustMode.CLIMB: 'climb'>
TAKEOFF = <ThrustMode.TAKEOFF: 'takeoff'>
class AEIC.performance.utils.apu.APU(*, name, defra, fuel_kg_per_s, NOx_g_per_kg, CO_g_per_kg, HC_g_per_kg, PM10_g_per_kg)

Pydantic model representing APU data.

Parameters:

  • name (str)

  • defra (str)

  • fuel_kg_per_s (float)

  • NOx_g_per_kg (float)

  • CO_g_per_kg (float)

  • HC_g_per_kg (float)

  • PM10_g_per_kg (float)

CO_g_per_kg: float

CO emissions in grams per kilogram of fuel.

HC_g_per_kg: float

HC emissions in grams per kilogram of fuel.

NOx_g_per_kg: float

NOx emissions in grams per kilogram of fuel.

PM10_g_per_kg: float

PM10 emissions in grams per kilogram of fuel.

defra: str

DEFRA code.

fuel_kg_per_s: float

Fuel consumption in kilograms per second.

name: str

APU name.

class AEIC.types.Speeds(*, climb, cruise, descent)

Speeds for different flight phases.

Parameters:
climb: SpeedData

Speed data for climb phase.

cruise: SpeedData

Speed data for cruise phase.

descent: SpeedData

Speed data for descent phase.

class AEIC.types.SpeedData(*, cas_low, cas_high, mach)

Performance model speed data for different flight phases.

Parameters:

  • cas_low (float)

  • cas_high (float)

  • mach (float)

cas_high: float

High speed calibrated airspeed (CAS) [m/s].

cas_low: float

Low speed calibrated airspeed (CAS) [m/s].

mach: float

Mach number.