Configuration

In order to set the configurations required by all the modules within Avaframe, the python module configparser is used.

This is done in two steps. The first step fetches the main settings:

from avaframe.in3Utils import cfgUtils
# Load avalanche directory from general configuration file
cfgMain = cfgUtils.getGeneralConfig()
avalancheDir = cfgMain['MAIN']['avalancheDir']

In the second step the specific settings to a given module are imported:

from avaframe.tmp1Ex import tmp1Ex
# Load all input Parameters from config file
# get the configuration of an already imported module
# Write config to log file
cfg = cfgUtils.getModuleConfig(tmp1Ex)

The in3Utils.cfgUtils.getModuleConfig() function reads the settings from a configuration file (tmpExCfg.ini in our example) and writes these settings to the log file. The default settings can be found in the configuration file provided within each module.

It is possible to modify these settings. The main options are:

• provide the path to your own configuration file using the fileOverride parameter when calling in3Utils.cfgUtils.getModuleConfig()

• create an expert configuration file at {avalancheDir}/Inputs/CFGs/{moduleName}Cfg.ini (see Advanced Usage (QGis, Script) for details)

• create a copy of the module configuration file called local_ followed by the name of the original configuration file and set the desired values of the individual parameters. local_ needs to be in the same folder as the original.

• see Override configuration for additional options to modify configuration

So the order is as follows:

1. if batchCfgDir is provided, the path to the batch configuration directory is returned (this is used for batch processing and returns a pathlib.Path instead of a ConfigParser object).

2. if onlyDefault=True is passed to in3Utils.cfgUtils.getModuleConfig(), only the default configuration is used (all overrides are skipped).

3. if there is a path provided via the fileOverride parameter, configuration is read from this file.

4. if the avalancheDir is provided and {avalancheDir}/Inputs/CFGs/{moduleName}Cfg.ini exists, this expert config is used (see Advanced Usage (QGis, Script) for details).

5. if there is no expert config, the local_... configuration file is read if it exists.

6. if there is no local_..., the getModuleConfig function reads the settings from the default configuration file with the default settings.

The following flowchart illustrates this priority order:

In the configuration file itself, there are multiple options to vary a parameter:

• replace the default parameter value with desired value

• provide a number of parameter values separated by | (e.g. relTh=1.|2.|3.)

• provide a number of parameter values using start:stop:numberOfSteps (e.g. relTh=1.:3.:3)) - a single value can be added by appending &4.0 for example

Override configuration

When module B calls tools from module A, you can override A’s configuration directly in B’s config file. This keeps all settings for a workflow in one place.

How it works:

1. Add a section named [collectionName_moduleName_override] to module B’s config file

2. List the parameters you want to override from module A

3. When B runs, it loads A’s default config and applies your overrides (happens in cfgHandling.applyCfgOverride)

Example: ana1Tests/energyLineTestCfg.ini overrides com1DFA settings:

[energyLineTest]
# energyLineTest's own settings
runDFAModule = True
pathFromPart = True

[com1DFA_com1DFA_override]
# these override com1DFA's defaults when called from energyLineTest
defaultConfig = True
simTypeList = null
relTh = 1
frictModel = Coulomb

The defaultConfig = True parameter ensures the override starts from A’s default configuration (rather than a local_ file if one exists).