System configuration

AEIC uses a lot of configuration data loaded from different files. The system configuration system provides a clean way to manage these different configuration items, using models based on Pydantic to validate input data from TOML files or programmatic sources.

File paths

AEIC has a set of built-in data files, but many use cases will require access to additional external files (for aircraft performance data, weather data, mission databases and so on). AEIC can be given access to directories containing additional configuration or data files by adding those directories to the AEIC_PATH environment variable. This is a colon-separated sequence of absolute directory paths (just like the usual Linux PATH variable).

Anywhere that a file path is required in AEIC, AEIC will search through the directories in the AEIC_PATH variable and in the default AEIC data directory. This search process works slightly differently to the Linux PATH variable: leading directories in the file path that you supply to AEIC are included as part of the search. For example, if you set AEIC_PATH to /big/aeic/data and attempt to load a performance model with a path performance/b738-new.toml, then AEIC will load the file /big/aeic/data/performance/b738-new.toml if it exists.

Configuration initialization and access

The AEIC configuration system is accessed via the AEIC.config package. In normal usage, you import both the Config class and the config singleton instance from this module:

from AEIC.config import Config, config

A selected AEIC configuration must then be loaded using the Config.load method. Calling Config.load() without arguments loads the default AEIC configuration (from the file src/AEIC/data/default_config.toml in the AEIC source tree). Individual configuration settings can be overridden by providing either a TOML file (that needs to contain only the options that are modified), or by passing keyword arguments to the Config.load method. For example, here we set the lifecycle_enabled emissions option to false (it defaults to true). All other values are taken from the default configuration that’s included in the AEIC package.

from AEIC.config import Config, LTOInputMode

Config.load(emissions=dict(lifecycle_enabled=False))

The global AEIC system configuration can be accessed via the config proxy object in the {py.mod}AEIC.config package. Attempting to access values in this object before initializing the system configuration will result in an error:

from AEIC.config import Config, config

print(config.path)
# Raises "ValueError: AEIC configuration is not set"

Config.load()

print(config.path)
# Prints the default AEIC data directory, assuming we have not set AEIC_PATH.

Normally, in AEIC code that is doing calculations that relies on configuration values, you will do from AEIC.config import config at the top of your Python file and then use values like config.emissions.lifecycle_enabled, and these will come from whatever the currently loaded configuration is.

Sometimes, for debugging, you may want to get a real Config object for the current configuration, instead of going via the config proxy. You can do this using the Config.get method.

Configuration uniqueness and immutability

Only one Config object may exist at any time. This prevents accidentally running part of a simulation with one set of configuration data and another part with a different configuration. There should be no cases in code within AEIC where this poses an obstacle. (It does make testing a little more difficult, but this is dealt with in our test setup code.)

The configuration is frozen: it may not be modified it once it is initialized. This is also intended to avoid problems with simulations running with inconsistent configuration settings. (Again, this does mean that some special tricks are needed for modifying configuration data during tests, but it’s worth the small amount of additional effort to have immutable configuration data for non-test use cases.)

In normal use and development of AEIC code, you should not need to do this, but it’s possible to reset the configuration so that you can load a different one using the Config.reset method. This is important for testing and interactive use of the configuration system, but you should not be doing it in “normal” AEIC code!

Main configuration class

class AEIC.config.Config(*, path=<factory>, data_path_overrides=<factory>, performance_model, engine_file, weather, emissions)

Global AEIC configuration settings.

This is a singleton class; only one instance can be created. This instance can then be accessed as AEIC.config.config via the module-level proxy. To use this, create an instance of Config at the start of your program (probably using the load method), then anywhere else in the codebase you can access the configuration simply by doing from AEIC.config import config.

The intention here is to provide a single source of truth for configuration settings that can be accessed throughout AEIC without needing to pass configuration objects around explicitly. Restricting to a single instance of the configuration class helps to avoid inconsistencies in settings during execution of code using AEIC.

Parameters:

  • path (list[Path])

  • data_path_overrides (list[Path])

  • performance_model (Path)

  • engine_file (Path)

  • weather (WeatherConfig)

  • emissions (EmissionsConfig)

data_file_location(f)

Get the full path to a file within the configured paths.

Parameters:

f (Path | str)

Return type:

Path

data_path_overrides: list[Path]

List of paths used for overriding the normal data directory search. Used for testing.

default_data_file_location(f, missing_ok=False)

Get the full path to a file within the default data directory.

Parameters:

  • f (Path | str)

  • missing_ok (bool)

Return type:

Path

emissions: EmissionsConfig

Global emissions configuration settings.

engine_file: Path

Path to engine database file.

file_location(f)

Get path to a file, checking local and configured paths.

Parameters:

f (Path | str)

Return type:

Path

classmethod get()

Get the global configuration singleton.

Raises an error if the configuration has not yet been initialized.

Return type:

Config

classmethod load(config_file=None, **kwargs)

Load configuration from TOML files.

The default_config.toml file included with AEIC is loaded first, and then TOML data from any config_file provided is loaded and overlaid on top. Additional keyword arguments are finally applied on top of the resulting configuration data. This allows users to only specify configuration options that differ from the defaults.

Parameters:

config_file (str | Path | None)

Return type:

Config

normalize_search_paths()

Resolve search paths and initialize the global configuration singleton.

path: list[Path]

List of paths to search for data files. If not initialized explicitly, this is taken from the AEIC_PATH environment variable if set, or defaults to the current working directory only.

performance_model: Path

Path to performance model data file.

static reset()

Reset the global configuration singleton.

This is mostly intended for testing purposes, where it can be useful to modify the configuration between or within tests. In most non-test use cases, the intention is to create a single configuration instance at the start of the program and use that instance throughout.

weather: WeatherConfig

Global weather configuration settings.

Emissions module configuration classes

class AEIC.config.emissions.EmissionsConfig(*, fuel, climb_descent_mode=ClimbDescentMode.TRAJECTORY, co2_enabled=True, h2o_enabled=True, sox_enabled=True, nox_method=EINOxMethod.BFFM2, hc_method=EINOxMethod.BFFM2, co_method=EINOxMethod.BFFM2, pmvol_method=PMvolMethod.FUEL_FLOW, pmnvol_method=PMnvolMethod.MEEM, apu_enabled=True, gse_enabled=True, lifecycle_enabled=True)

Configuration data for emissions module.

Parameters:
DEFAULT_METHOD: ClassVar[EINOxMethod] = 'bffm2'

Default method for NOₓ, HC, and CO emissions calculations.

apu_enabled: bool

Toggle APU emission calculation. (APU emissions are only calculated if the performance model provides an APU name.)

climb_descent_mode: ClimbDescentMode

Flag controlling how emissions are calculated for non-cruise flight phases. If set to ‘trajectory’, emissions are calculated for the entire trajectory (takeoff, climb, cruise, descent); if set to ‘lto’, emissions are only calculated for cruise and LTO data is used for takeoff, climb and approach.

co2_enabled: bool

Toggle fuel-dependent CO₂ emission calculation.

property co_enabled: bool

CO emission calculation flag.

co_method: EINOxMethod

CO emission calculation method. (“None” disables CO emissions.)

fuel: str

Fuel used (conventional Jet-A, SAF, etc.). Should be the name of a file accessible as “fuels/{fuel}.toml” using the AEIC configuration system.

property fuel_file: str

Fuel file path.

gse_enabled: bool

Toggle GSE emission calculation.

h2o_enabled: bool

Toggle fuel-dependeny H₂O emission calculation.

property hc_enabled: bool

HC emission calculation flag.

hc_method: EINOxMethod

HC emission calculation method. (“None” disables HC emissions.)

lifecycle_enabled: bool

Toggle CO₂ lifecycle emission calculation.

property nox_enabled: bool

NOₓ emission calculation flag.

nox_method: EINOxMethod

NOₓ emission calculation method. (“None” disables NOₓ emissions.)

property pmnvol_enabled: bool

PMnvol emission calculation flag.

pmnvol_method: PMnvolMethod

PMnvol emission calculation method. (“None” disables PMnvol emissions.)

property pmvol_enabled: bool

PMvol emission calculation flag.

pmvol_method: PMvolMethod

PMvol emission calculation method. (“None” disables PMvol emissions.)

sox_enabled: bool

Toggle fuel-dependency SOₓ (SO₂ and SO₄) emission calculation.

enum AEIC.config.emissions.ClimbDescentMode(value)

Climb/descent emissions calculation mode.

Member Type:

str

Valid values are as follows:

TRAJECTORY = <ClimbDescentMode.TRAJECTORY: 'trajectory'>
LTO = <ClimbDescentMode.LTO: 'lto'>
enum AEIC.config.emissions.EINOxMethod(value)

NOₓ emissions calculation methods.

Member Type:

str

Valid values are as follows:

BFFM2 = <EINOxMethod.BFFM2: 'bffm2'>
P3T3 = <EINOxMethod.P3T3: 'p3t3'>
NONE = <EINOxMethod.NONE: 'none'>
enum AEIC.config.emissions.PMvolMethod(value)

PMvol emissions calculation methods.

Member Type:

str

Valid values are as follows:

FUEL_FLOW = <PMvolMethod.FUEL_FLOW: 'fuel_flow'>
FOA3 = <PMvolMethod.FOA3: 'foa3'>
NONE = <PMvolMethod.NONE: 'none'>
enum AEIC.config.emissions.PMnvolMethod(value)

PMnvol emissions calculation methods.

Member Type:

str

Valid values are as follows:

MEEM = <PMnvolMethod.MEEM: 'meem'>
SCOPE11 = <PMnvolMethod.SCOPE11: 'scope11'>
FOA3 = <PMnvolMethod.FOA3: 'foa3'>
NONE = <PMnvolMethod.NONE: 'none'>

Weather module configuration class

class AEIC.config.weather.WeatherConfig(*, use_weather=True, weather_data_dir=None)

Configuration settings for weather module.

Parameters:

  • use_weather (bool)

  • weather_data_dir (Path | None)

use_weather: bool

Whether to use weather data for emissions calculations.

weather_data_dir: Path | None

Directory path for weather data files. (Files should be NetCDF files following ERA5 conventions with names of the form YYYYMMDD.nc.) If None, defaults to the current working directory.