.. _faq_model_config:

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 :ref:`the frontend FAQs <faq_frontend>` 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:

.. code-block:: yaml

    # 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:

.. code-block:: yaml

    some_parameter: foo
    another_parameter: bar
    some_mapping:
      spam: fish

This procedure maintains hierarchic encapsulation.
See `the doxygen docs <../doxygen/html/group___model.html>`_ 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:

.. literalinclude:: ../../../src/utopia/models/CopyMeBare/CopyMeBare.hh
    :language: c++
    :start-after: // -- Model Setup
    :end-before: private:
    :dedent: 4


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:

.. code-block:: c++

    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:

.. doxygenfunction:: Utopia::get_as(const std::string &key, const DataIO::Config &node)
.. doxygenfunction:: Utopia::get_as(const std::string &key, const DataIO::Config &node, ReturnType fallback)
.. doxygenclass:: Utopia::KeyError


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

For linear algebra operations, the `Armadillo <http://arma.sourceforge.net/>`_
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:

.. code-block:: c++

    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 <http://arma.sourceforge.net/docs.html#Col>`_,
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.

.. doxygenfunction:: Utopia::get_as_SpaceVec
.. doxygenfunction:: Utopia::get_as_MultiIndex
.. doxygentypedef:: Utopia::SpaceVecType
.. doxygentypedef:: Utopia::MultiIndexType