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".

Mission-based performance model selection

When simulating trajectories from multiple missions, it will often be the case the different performance models will be used for different missions, depending on the aircraft type (and possibly other missions parameters). To enable this, it is possible to pass a PerformanceModelSelector value instead of an individual performance model when simulating a trajectory. A performance model selector is essentially just a function from a Mission to a BasePerformanceModel and is called to determine the performance model to use for each mission.

A simple performance model selector implementation is provided by the SimplPerformanceModelSelector class. This class implements a simple mapping from aircraft type to performance model based on the contents of a directory that holds TOML performance model files with names based on the aircraft type along with a configuration file that defines a default performance model and synonyms for aircraft types without their own performance model files.

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.performance.models import PerformanceModel, LegacyPerformanceModel
from AEIC.performance.types import AircraftState, SimpleFlightRules
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.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: PositiveInt

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

Aircraft maximum payload in kilograms.

number_of_engines: PositiveInt

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.performance.model_selector.PerformanceModelSelector(*args, **kwargs)

Protocol defining the interface for performance model selectors. A performance model selector is a callable that takes a Mission and returns a performance model to use for that mission.

class AEIC.performance.model_selector.SimplePerformanceModelSelector(directory, cache_size=16)

A simple performance model selector that selects a performance model based on the aircraft type of the mission. The performance model files are stored in a directory provided to the class constructor. A TOML configuration file in the same specifies a default performance model and performance models to use for aircraft types that do not have their own performance models.

Performance model lookup proceeds by first looking for a performance model file with the same name as the aircraft type (with a .toml extension). If no such file exists, then the configuration file is checked for a synonym for that aircraft type, and if a synonym exists, the performance model file for that aircraft type is used. If no synonym exists, then the default performance model is used.

Parameters:

  • directory (Path)

  • cache_size (int)

__call__(mission)

Main API for looking up a performance model for a mission. This is all that’s required to satisfy the PerformanceModelSelector protocol.

Parameters:

mission (Mission)

Return type:

BasePerformanceModel

__init__(directory, cache_size=16)

Initialize the performance model selector.

The directory must contain a config.toml file with lines of the form <aircraft-type> = <performance-model-file>, which specify synonyms for aircraft types that do not have their own performance model files. The config.toml file must also contain a default entry specifying the default performance model file to use when no performance model file or synonym exists for a given aircraft type.

The performance model selector maintains a LRU cache of performance models that have been loaded, keyed by the name of the performance model file (i.e., the aircraft type). The cache_size parameter specifies the maximum size of this cache.

Parameters:

  • directory (Path)

  • cache_size (int)

class AEIC.performance.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.performance.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.performance.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.performance.types.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: ThrustModeValues

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

EI_HC: ThrustModeValues

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

EI_NOx: ThrustModeValues

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

ICAO_UID: str

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

fuel_flow: ThrustModeValues

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

Thrust percentage in thrust mode (0-100).

enum AEIC.performance.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.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

NOₓ 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.performance.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.performance.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.