# Performance model API Performance model classes are all Pydantic models derived from {py:class}`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 {py:class}`LegacyPerformanceModel ` class. This includes a performance table represented by the {py:class}`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 {py:class}`PerformanceModel ` wrapper class is used to enable this: there is a {py:meth}`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 {py:class}`PerformanceModelSelector ` value instead of an individual performance model when simulating a trajectory. A performance model selector is essentially just a function from a {py:class}`Mission ` to a {py:class}`BasePerformanceModel ` and is called to determine the performance model to use for each mission. A simple performance model selector implementation is provided by the {py:class}`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 {py:class}`AircraftState ` type) and a flight rule (see below) and to return aircraft performance data (a value of the {py:class}`Performance ` type). This is achieved by calling the {py:meth}`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 {py:meth}`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 {py:class}`LegacyPerformanceModel ` class, are represented by the {py:class}`SimpleFlightRules ` class, which simply specifies "climb", "cruise", or "descend". ## Usage example ```python 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 {py:class}`BasePerformanceModel `), as well as being set up for calls to the {py:meth}`evaluate ` method, the instance also contains: - Basic information about the performance model: aircraft name and class, number of engines, maximum altitude and payload. - {py:attr}`lto_performance `: modal thrust settings, fuel flows, and emission indices taken from the performance file. - {py:attr}`apu `: auxiliary-power-unit properties resolved from `engines/APU_data.toml` using the `apu_name` specified in the performance file. - {py:attr}`speeds `: cruise speed data. ## API reference ```{eval-rst} .. autoclass:: AEIC.performance.models.BasePerformanceModel :members: :exclude-members: apu_name, load_apu_data, model_config ``` ```{eval-rst} .. autoclass:: AEIC.performance.models.PerformanceModel :members: :exclude-members: model_config ``` ```{eval-rst} .. autoclass:: AEIC.performance.model_selector.PerformanceModelSelector :members: ``` ```{eval-rst} .. autoclass:: AEIC.performance.model_selector.SimplePerformanceModelSelector :members: :special-members: __init__, __call__ ``` ```{eval-rst} .. autoclass:: AEIC.performance.types.AircraftState :members: ``` ```{eval-rst} .. autoclass:: AEIC.performance.types.Performance :members: ``` ```{eval-rst} .. autoenum:: AEIC.performance.types.SimpleFlightRules ``` ```{eval-rst} .. autoclass:: AEIC.performance.types.LTOPerformance :members: :exclude-members: model_config ``` ```{eval-rst} .. autoenum:: AEIC.performance.types.ThrustMode ``` ```{eval-rst} .. autoclass:: AEIC.performance.apu.APU :members: :exclude-members: model_config ``` ```{eval-rst} .. autoclass:: AEIC.performance.types.Speeds :members: :exclude-members: model_config ``` ```{eval-rst} .. autoclass:: AEIC.performance.types.SpeedData :members: :exclude-members: model_config ```