Model Configuration#

This part of the FAQs is concerned with all questions surrounding the configuration of Utopia models. It does not cover the general aspects of YAML as a configuration language or the configuration of the frontend and the evaluation of simulations; for this, see the frontend FAQs instead.

Passing configurations to the model#

How does my model instance receive its configuration?#

This is taken care of by Utopia’s Model base class, using the configuration files generated by the frontend. The frontend prepares the configuration for each individual universe by storing the contents of the parameter_space to a file. The PseudoParent takes care of loading that configuration file. When you instantiate your model, you pass it a name and a reference to the PseudoParent instance. The Model base class then extracts a configuration node from the parent model, using the instance name as the key.

To illustrate this, let’s look at an example YAML configuration:

# Parameters on the top level are handled by the PseudoParent
seed: 42
num_steps: 1000

# Parameters under the instance name are passed on to models of that name
my_model_instance:
  some_parameter: foo
  another_parameter: bar
  some_mapping:
    spam: fish

If the name of your model instance is my_model_instance the instance can access the following part of the configuration:

some_parameter: foo
another_parameter: bar
some_mapping:
  spam: fish

This procedure maintains hierarchic encapsulation. See the doxygen docs for more information.

Can I pass a custom configuration to a model during initialization?#

Yes. The Utopia::Model constructor supports an optional custom_cfg argument. If that argument is given, the custom configuration node is used instead of the one that is being extracted from the parent model. Consult the CopyMe model implementations for how your model constructor should look like to support passing a custom configuration. For the CopyMeBare model, it looks like this:

/// Construct the CopyMeBare model
/** \param name             Name of this model instance; is used to extract
 *                          the configuration from the parent model and
 *                          set up a HDFGroup for this instance
 *  \param parent_model     The parent model this model instance resides in
 *  \param custom_cfg       A custom configuration to use instead of the
 *                          one extracted from the parent model using the
 *                          instance name
 */
template<class ParentModel>
CopyMeBare (
    const std::string& name,
    ParentModel& parent_model,
    const DataIO::Config& custom_cfg = {}
)
:
    Base(name, parent_model, custom_cfg)
{}

Read content from the configuration#

In my model, how can I read entries from the configuration?#

To extract parameters for your model from the configuration, you can use the Utopia::get_as function and the corresponding shortcuts:

auto my_double = get_as<double>("my_double", cfg);
auto my_str = get_as<std::string>("my_str", cfg);
auto my_int = get_as<int>("my_int", cfg);
auto my_uint = get_as<unsigned int>("my_int", cfg);

One way of remembering the order of arguments is: “get_as an object of type double: the entry my_double from this cfg node”. See below for the function signature and more information

How can I read linear algebra objects (vectors, matrices, …) from the config?#

For linear algebra operations, the Armadillo library is a dependency of Utopia. For example, the SpaceVec used in Utopia::Space and related classes is such a type. The config utilities provide two convenience functions to extract data in this fashion:

auto some_pos = get_as_SpaceVec<2>("initial_pos", cfg);
auto some_midx = get_as_MultiIndex<2>("some_midx", cfg);

For information on these functions and the return types, see below.

To load data into custom arma objects, you will have to use an intermediate object that can be used to construct them. Please refer to the Armadillo Documentation, where the supported constructors are specified. For example, an arma::vec (double-valued column vector of arbitrary size) can be constructed from an std::vector, so you would use get_as<std::vector> and then invoke the arma::vec constructor. Note that for the ::fixed vectors, not all these constructors are available; items need to be assigned element-wise for such cases.

Note

We are aware that the current implementation is somewhat inconsistent. The aim is to implement overloads for get_as that automatically extract the desired type and (if it is a fixed-size object) take care of assigning elements.

C++ documentation of Config Utilities#

group ConfigUtilities

Allows reading configuration entries from YAML files.

Typedefs

using Config = YAML::Node#: Type of a variadic dictionary-like data structure used throughout Utopia.

Functions

template<typename ReturnType> ReturnType get_as(const std::string &key, const DataIO::Config &node)#

This function is a wrapper around the yaml-cpp YAML::Node::as function.

It enhances the error messages that can occur in a read operation.

Example:

using namespace Utopia;

auto cfg = YAML::Load("{my_double: 3.14, my_int: 42, my_str: foo}");
auto my_double = get_as<double>("my_double", cfg);
auto my_uint = get_as<unsigned int>("my_int", cfg);
auto my_int = get_as<int>("my_int", cfg);
auto my_str = get_as<std::string>("my_str", cfg);

Note

This method may throw Utopia::KeyError, which contains the name of the key that could not be accessed. Also, the conversion needs to be supported by the underlying YAML library.

Template Parameters:

ReturnType – The type to evaluate from the YAML::Node

Parameters:

key – The key that is to be read
node – The node to read the entry with the given key from

Throws:

Utopia::KeyError – On missing key
YAML::Exception – On bad conversions or other YAML-related errors

Returns:

The value of node[key], cast to ReturnType

template<typename ReturnType> ReturnType get_as(const std::string &key, const DataIO::Config &node, ReturnType fallback)#: Like Utopia::get_as, but instead of KeyError, returns a fallback value.

template<DimType dim> SpaceVecType<dim> get_as_SpaceVec(const std::string &key, const DataIO::Config &node)#

Special case of Utopia::get_as to retrieve an entry as SpaceVec.

Template Parameters:: dim – The dimensionality of the returned Utopia::SpaceVecType

template<DimType dim> MultiIndexType<dim> get_as_MultiIndex(const std::string &key, const DataIO::Config &node)#

Special case of Utopia::get_as to retrieve an entry as MultiIndex.

Template Parameters:: dim – The dimensionality of the returned Utopia::MultiIndexType

class KeyError : public Utopia::Exception#: For access to a dict-like structure with a bad key.

template<DimType dim> using Utopia::SpaceVecType = arma::Col<double>::fixed<dim>#

Type for vector-like data that is associated with a physical space.

Uses a fixed-size Armadillo column vector of doubles

Template Parameters:: dim – The dimensionality (or: rank) of the vector

template<DimType dim> using Utopia::MultiIndexType = arma::Col<IndexType>::fixed<dim>#

Type for index type vectors that are associated with a physical space.

Uses a fixed-size Armadillo column vector of IndexType

Note

This vector is not to be interpreted as a “container”

Template Parameters:: dim – The dimensionality (or: rank) of the vector

Model Configuration

Contents

Model Configuration#

Passing configurations to the model#

How does my model instance receive its configuration?#

Can I pass a custom configuration to a model during initialization?#

Read content from the configuration#

In my model, how can I read entries from the configuration?#

How can I read linear algebra objects (vectors, matrices, …) from the config?#

C++ documentation of Config Utilities#