Multiverse Meta-Configuration#

Todo

Work in Progress đźš§

Configuration Layers#

The final Multiverse meta-configuration is built by recursively updating the base configuration with successive configuration files, if they are present.

Base#

The utopya base configuration defines the starting point for the meta-configuration. It aims at providing good default values and also documenting the possible configuration options.

Framework & Project#

Both at the framework and the project level, additional configuration files can be specified.

For instance, if using Utopia as a framework to implement C++ models, it supplies a configuration file that specifies configuration entries that are required for C++-based models.

After framework-specific updates were carried out, the project can do the same.

To define framework- and project-specific update configurations, add the paths.mv_project_cfg key in the respective .utopya-project.yml files:

paths:
  # Path to project-level default configuration for Multiverse
  mv_project_cfg: cfg/mv_project_cfg.yml

Model-specific#

Models can also specify updates to the meta-configuration (not only the model-related default values, see below).

To define a model-specific update configuration, add the paths.mv_model_cfg key in the respective <ModelName>_info.yml file:

paths:
  # Path to model-specific Multiverse configuration updates
  mv_model_cfg: MyModel_mv_update_cfg.yml

User Configuration#

A user-specific configuration, typically stored in ~/.config/utopya/user.yml. These are applied to all models and all projects that are invoked from that user’s account.

The file can be accessed and edited also via the CLI:

utopya config user --help

Model Defaults#

Each model defines the default model parameters in their model configuration.

Unlike all other configuration layers, the model defaults do not update the whole meta-configuration, but only the parameter_space.<ModelName> entry.

Run Config & Config Sets#

The run configuration is a configuration file that is used for a specific run. It is the “last” layer of file-based updates.

When calling utopya run, the configuration file can be passed either as a file path — or, alternatively, by means of so-called configuration sets that can be accessed by an alias.

CLI Updates#

Some parameters can be defined via the CLI directly and are the very last recursive update procedure before arriving at the final meta-configuration.

For instance, when calling

utopya run MyModel -W 12 -N 4k --mp my_param=123

there are three CLI-based updates to the meta configuration:

worker_manager:
  num_workers: 12

parameter_space:
  num_steps: 4k

  MyModel:
    my_param: 123