openairclim.core.read_config

Reads a config file, checks it, and creates the output directory.

Configuration checking runs in two layers, split across two modules:

  • Structural validation (openairclim.core.config_model) — types, required/optional keys, valid option strings, and defaults, enforced by the pydantic Config schema. Pure in-memory validation: nothing here touches the filesystem, and it doesn’t need aircraft/inventory/response files to actually exist. Entered via validate_config().

  • Everything that needs the filesystem or cross-references other data (this module) — merging in an optional aircraft csv file, and checking that referenced files actually exist.

check_config() runs both layers in order:

  1. validate_config() — validate structure/types, migrate deprecated keys (see ALIAS_MAP), and fill in defaults. Inline [aircraft.<id>] entries are validated here too, deriving G_250/PMrel from sub-values where possible (see AircraftEntry); if output.run_metrics is set, metrics.types/t_0/H are checked for completeness and consistency with time.range.

  2. _resolve_repository_dirs() - if background.dir/responses.dir were left unset, fill them in with OpenAirClim’s shared repository data cache directory (openairclim.repository.get_cache_dir()). Only resolves the path; doesn’t check whether it actually contains the required files or download anything. Downloads only ever happen via an explicit oac-download-data call to prevent surprise network calls.

  3. load_ac_data() - if aircraft.file is set, load that csv, validate each row (AircraftCsvRow), and merge it into config["aircraft"] — raising if an aircraft identifier is defined both inline and in the csv.

  4. _check_reserved_aircraft_ids() - reject aircraft identifiers that collide with core’s own internal bookkeeping ("TOTAL", "BASE_*").

  5. _check_fsc_range() - warn (once per aircraft, not raise) if any aircraft’s FSC falls outside openairclim_premium’s calibrated range.

  6. _check_required_contrail_vars() - if "cont" is an output species, every aircraft identifier must end up with complete G_250/b/PMrel data, from either source.

  7. _check_required_files() - every response, background, emission inventory and base inventory file the (now fully resolved) config references must actually exist on disk. If a missing file lives under the resolved repository data cache, the error points at oac-download-data.

  8. _check_nox_response_approaches() - check for compatibility of

    response approaches across NOx species. This check relies on response files.

create_output_dir() is a separate step, not part of check_config() — it’s only run once a config has passed all of the above (see get_config()), since it can create or wipe the output directory.

openairclim.core.read_config.check_config(config: dict)[source]

Checks if configuration is complete and correct.

Parameters:

config (dict) – Configuration dictionary

Returns:

Configuration dictionary

Return type:

dict

openairclim.core.read_config.classify_response_types(config: dict, species_arr: list[str]) → tuple[list[str], list[str]][source]

Classifies species into categories based on their response types.

Response types are defined in the config.

Parameters:

  • config (dict) – Configuration dictionary

  • species_arr (list[str]) – A list of strings representing the species

Returns:

species_rf contains species with response type ‘rf’, i.e. a response file must be given comprising the response surface from emissions to RF; species_tau contains species with response type ‘tau’, i.e. a response file must be given comprising the response surface from emissions to inverse species lifetime.

Return type:

tuple[list[str], list[str]]

Raises:

KeyError – If no valid response type is defined in the config for a species.

openairclim.core.read_config.classify_species(config: dict) → tuple[list[str], list[str], list[str], list[str]][source]

Classifies output species by response modelling method.

Parameters:

config (dict) – Configuration dictionary

Returns:

species_0d, species_2d, species_cont, species_sub

Return type:

tuple[list[str], list[str], list[str], list[str]]

openairclim.core.read_config.create_output_dir(config: dict) → None[source]

Check for existing output directory, results file, overwrite and run_oac.

Create new output directory if needed.

Parameters:

config (dict) – Configuration dictionary

Raises:

OSError – if no output directory is created or results file not existing with run_oac = false

openairclim.core.read_config.get_config(file_name: str) → dict[source]

load_config, check_config and create_output_dir.

Parameters:

file_name (str) – Name of config file

Returns:

Configuration dictionary

Return type:

dict

openairclim.core.read_config.load_ac_data(config: dict) → dict[source]

Load and validate aircraft identifier parameters from a separate csv file.

Parameters defined within the config file are checked by validate_config().

Parameters:

config (dict) – Configuration dictionary

Raises:

  • FileNotFoundError – File does not exist

  • KeyError – If the “ac” column does not exist

  • ValueError – If a duplicate identifier is found within the csv file; if an aircraft’s data is invalid or has G_250/PMrel that can’t be derived from sub-values (see AircraftCsvRow); or if an aircraft is defined both inline in the config file and in the csv file

Returns:

Configuration dictionary modified in-place

Return type:

dict

openairclim.core.read_config.load_config(file_name: str) → dict[source]

Loads config file in toml format.

Parameters:

file_name (str) – Name of config file

Returns:

Configuration dictionary

Return type:

dict