gum::Configuration is a thread-safe, typed and documented key/value store organised in sections. A single global instance, gum::Configuration::instance(), is shared by aGrUM and pyAgrum (pyagrum.config is a thin layer above it). It is meant for parameters that a user may want to change without recompiling, by editing a small text file (agrum.ini), and that the library, or the user's code, can read or react to.
Where the values come from
- The defaults of aGrUM are in src/agrum/base/core/configuration/defaults.ini. This file is embedded in the library at build time (it is not read from the disk at run time). It declares every section and key of aGrUM, its default value, its type and its documentation.
- The defaults of pyAgrum (pyAgrum only) are in wrappers/pyagrum/pyLibs/defaults.ini. When pyAgrum is compiled, cmake embeds this file next to the one of aGrUM and gum::Configuration reads the two files in this order, as two sources. pyAgrum can thus create its own sections and keys, and add keys to a section of aGrUM (for instance [notebook]): a section may be opened by both files, but only once inside a file. A key is defined by one file only (a duplicated key is a gum::SyntaxError when the library is loaded). In a shared section, the keys of aGrUM come first. A deprecated key of one file may point to a key of the other one. The keys that give the look of the graphs drawn with graphviz (colors, sizes, shapes, layout) are in the defaults of aGrUM, in the sections [notebook], [factorgraph], [dynamicBN], [influenceDiagram], [credalnet] and [causal], in lowerCamelCase (notebook.nodeBgColor); the keys that need matplotlib stay in the defaults of pyAgrum.
- The user file, if it exists in the current directory, overrides some of these values. Its name is agrum.ini for aGrUM, pyagrum.ini for pyAgrum (which does not read agrum.ini), see gum::Configuration::userFileName(). It can only change the value of existing keys: an unknown section or key is reported by a notice and not created. It only needs to contain the keys to change:
[core]
maxNumberOfThreads = 4
jgumIndent = 2
The first call to gum::Configuration::instance() builds the configuration from the defaults, then loads the user file. This call is also made when the library is loaded, so the configuration is applied at start-up, before any user code runs.
The syntax of defaults.ini
The file is a classical .ini file ([section], key = value, comments starting with # or ;). Every key is documented by a metadata line placed immediately above it:
[core]
### int :: default maximum number of threads used by aGrUM (-1 = adapted to the machine)
maxNumberOfThreads = -1
### bool :: allow to fix syntax errors in a model instead of raising when exporting
allowModificationWhenSaving = False
where type is one of
- int, float, bool, str,
- an enumeration v1|v2|...,
- a deprecation deprecated -> section.key: the key is kept for compatibility, every access to it is redirected to section.key (and a notice is queued, see below).
A line starting with exactly three # is a metadata line; #### and a plain # are ordinary comments. A malformed metadata line, a metadata line which is not immediately followed by its key, a section opened twice in the same file, a duplicated key, a default value which does not respect its own type... all raise a gum::SyntaxError (or a gum::InvalidArgument) as soon as the library is loaded: defaults.ini is a file maintained by the developers, so it fails fast.
A key without metadata line is accepted and treated as an undocumented str.
Section names are case-sensitive, key names are not.
Reading and writing values
std::string s = conf.get("core", "jgumIndent");
auto n = conf.typed< std::int64_t >("core", "maxNumberOfThreads");
bool ok = conf.typed< bool >("core", "allowModificationWhenSaving");
conf.set("core", "jgumIndent", "2");
static Configuration & instance()
The global configuration.
Typed, documented, sectioned configuration singleton read from an .ini content.
- Values are stored as strings and are canonicalized when set: any accepted spelling of a boolean (true/1/on/yes, false/0/off/no, whatever the case) is stored as True or False; an enumerated value is stored with the casing declared in defaults.ini.
- gum::Configuration::typed() accepts bool, int64_t, double (also valid for an int key) and std::string (valid for any key). Another type is a gum::InvalidArgument.
- gum::Configuration::getValue() gives the value converted according to the declared type of its key (a gum::Configuration::Value: bool, int64_t, double or std::string), when the type is not known at compile time. This is what pyAgrum uses for config.typed.
- gum::config() is a short name for gum::Configuration::instance().
- The three numerical tolerances of aGrUM (core.epsilonCoarse = 1e-2, core.epsilonStandard = 1e-6 and core.epsilonFine = 1e-10, in the non-overlapping domains [1e-3,1e-1], [1e-8,1e-5] and [1e-11,1e-9]) have dedicated accessors, gum::config().epsilonStandard() and so on, which read an atomic updated by every change of the configuration: no lock, no allocation, so they can be used in loops. Other keys (typed(), get()) take a lock and should be read once, in a constructor.
- gum::Configuration::describe() gives a human-readable summary: the differences with the defaults (see gum::Configuration::diff()) or, if there are none, a note saying so followed by the whole configuration. This is what repr(pyagrum.config) shows.
- An unknown section or key raises a gum::SyntaxError; a value which does not respect the declared type raises a gum::InvalidArgument and nothing is changed.
- A float is written in decimal or scientific notation with a . (0.25, 1e-6), whatever the locale of the program.
- gum::Configuration::get() returns a copy: the result stays valid whatever other threads do.
A configuration can also be saved (gum::Configuration::save(): only the differences with the defaults are written), restored (gum::Configuration::reset()), or stacked (gum::Configuration::push() / gum::Configuration::pop()), which is handy in a test:
conf.push();
conf.set("core", "jgumIndent", "2");
conf.pop();
Hooks
A hook is a function registered with gum::Configuration::addHook() and called every time the configuration changes. It is the way to make a value act on the library: the configuration only stores values, a hook applies them.
Registering a hook
conf.
typed< std::int64_t >(
"core",
"maxNumberOfThreads")));
});
Sectioned key/value configuration with typed and documented keys.
T typed(std::string_view section, std::string_view key) const
Value of section.key converted according to its declared type.
void addHook(Hook hook)
Adds a function called after each change (see set(), reset(), pop(), load()).
void setNumberOfThreads(unsigned int number)
Set the max number of threads to be used when entering the next parallel region.
The hook receives the configuration as a const reference. This is what the library does itself for core.maxNumberOfThreads (see gum::Configuration::instance()), except that a negative value (the default, -1) gives back the number of threads provided by the machine.
When are hooks run ?
Hooks are run, in the order of their registration,
A hook is not called when it is registered: if it must apply the current values immediately, call gum::Configuration::runHooks() just after gum::Configuration::addHook() (hooks must be idempotent, as they are called after any change, not only the one they are interested in). The library runs the hooks once at start-up, after having loaded the user file.
gum::Configuration::push() does not run the hooks (nothing changes).
What a hook may (not) do
- Hooks are run outside of any internal lock: a hook may freely read the configuration (get, typed...).
- A hook must not change the configuration with a call that runs the hooks (set without noHook = true, reset, pop, load): it would call itself endlessly. Use set(section, key, value, true) if it really has to correct a value.
- When a hook throws, the exception goes out of the call which triggered it (set, reset...); the new value is already stored and the hooks registered after the failing one are not run. A hook should therefore only throw for a real error.
- There is no way to unregister a hook: a hook captures only what is still alive for the whole life of the program (no reference to a local variable or to an object which can be destroyed).
- Hooks are shared by all the users of the singleton. In a test, prefer a local gum::Configuration conf(defaults_text) (its own, independent instance) to a hook on instance().
Hooks and threads
Hooks may be called from any thread (the one which changed the configuration). A hook which touches shared state must protect it (the number of threads of aGrUM, for instance, is an atomic).
Hooks in pyAgrum
pyagrum.config.add_hook(fn) registers a Python function (without argument) in the C++ configuration itself: it is called after each change, from Python or from C++, after the C++ hooks registered before it. An exception raised by the function is propagated to whoever changed the configuration.
Notices
Some events are not errors, but should not be silent: using a deprecated key, or finding an unknown key or an invalid value in the user file (the valid part of the file is loaded anyway, the file itself is never modified by gum::Configuration::load()). A deprecated key found in the user file is applied to its replacement, so gum::Configuration::save() writes the file with the new key names. Only a malformed line stops gum::Configuration::load() with a gum::SyntaxError: the whole file is read before anything is applied, so nothing at all is changed in this case. The library never prints anything: these events are queued (a notice already waiting is not queued twice), and gum::Configuration::takeNotices() returns and empties the queue.
std::cerr << notice.message << std::endl;
pyAgrum turns them into Python warnings (DeprecationWarning for the deprecated keys). As the user file is loaded when the library is loaded, the notices raised by this first loading are waiting in the queue for the first call to gum::Configuration::takeNotices().
Using the configuration in a class of aGrUM
The usual idiom is a constructor with an explicit parameter, and a constructor (or a default argument) which falls back on the configuration. For instance, the writers of the jgum format:
template class GUM_PUBLIC_BN GumBNWriter< double >
The configuration is read when the object is built, not when it is used: changing the configuration later does not change an existing object.
To add a new key, add it to defaults.ini (with its metadata line, in the section of its module), then read it where it is needed. No other change is required: sections and keys are not declared in C++. A key which has to act on the library at start-up needs a hook (see above).
Several independent configurations
gum::Configuration can also be instantiated from any defaults text (its constructor takes the text, not a file name). Such an instance is independent from the singleton, does not load any user file and has no hook: this is what the unit tests use.
void set(std::string_view section, std::string_view key, std::string_view value, bool noHook=false)
Sets section.key.
Thread-safety
Every public method is thread-safe: reads (get, typed, diff...) run concurrently, writes (set, load, push...) are exclusive.
See also
- gum::Configuration for the complete API,
- pyagrum.config (and defaults.ini, which documents every key) on the pyAgrum side.