.. _Amalgamator:

Amalgamator (Internal/Advanced)
================================

.. note::
   Amalgamator is used internally by the confidence interval code and
   is not deprecated. However, most users should use
   ``generic_cylinders.py`` (see :ref:`generic_cylinders`) as their
   entry point. This section is primarily of interest to maintainers of
   confidence interval and related code.

The file ``amalgamator.py``
provides several drivers to solve a problem without writing a program
that creates the cylinders one by one. ``amalgamator.from_module`` enables
a high-level user to create a hub-and-spoke architecture using the command 
line, with only a few lines of code.

The Amalgamator class
-------------------------
The ``Amalgamator`` class basically wraps up the creation and run of a simple
hub-and-spokes architecture.
It creates hub and spokes dictionaries using vanilla,
calls ``sputils.spin_the_wheel`` and finally writes 
the solution to a file or a directory.

It takes as inputs scenario names, a scenario creator, options and
a ``kw_creator`` function. ``kw_creator`` must be a function specific to your
problem, taking the amalgamator options as an input, and giving as an output
additional arguments for the ``scenario_creator``. The amalgamator class
is not flexible with respect to function names in the module.

The ``cfg`` argument is a ``Config`` class object that specifies information 
about the problem, and dictates the way Amalgamator runs. 
It must contains the following attributes for use with cylinders:

* A boolean ``2stage`` or ``mstage`` equal to True, indicating a 2-stage or 
  a multistage problem.

* A list ``cylinders``, containing the names of the desired hub and spokes.

* A list ``extensions``, containing the names of the desired extensions.

* (optional) A dictionary ``write_solution`` with 2 attributes, 
  ``first_stage_solution`` (resp. ``tree_solution``) with a .csv file name to 
  write
  the first stage solution (resp. a directory to write the tree full solution)

* (optional) Various options, e.g. to control the cylinders creation or the
  extensions, or options used to construct ``scenario_creator`` additional 
  arguments
  
.. Note::
   Amalgamator does not work with everything. It only supports the cylinders and
   extensions that have a dedicated method in ``vanilla.py``.


Create Amalgamator from a module and command line
-------------------------------------------------

Given an options
``Config`` object (typically called `cfg`) as above,
``amalgamator.Amalgamator_parser`` creates calls the appropriate
functions to add the necessary information for different modules.

The method ``amalgamator.from_module`` uses the two utilities described above.
It takes as input a module name, and calls ``amalgamator.Amalgamator_parser``
to get cylinder options and the number of scenarios from the command line.
Then, it computes the scenario names, and finally creates and
runs an Amalgamator object.

.. Note::
   The module must contains several methods:
   ``scenario_creator``, ``scenario_names_creator``, ``inparser_adder`` and
   ``kw_creator``. The files ``examples.farmer.farmer.py``, ``mpisppy.tests.examples.aircond.py`` contain
   examples of these functions.

The full options dictionary is passed through to ``kw_creator`` so keyword arguments for
scenario creation can be placed in the almalgamator options dictionary.

Notes about ``inparser_adder``
------------------------------

The function adds config arguments unique to the instance. Note that `--branching-factors` can be added
even if something else added it, because the config.add functions bypass duplicates.

   
Amalgamator with EF
-------------------

It is possible to use ``amalgamator.py`` to solve a problem by solving 
directly its extensive form (see the section :ref:`EF Directly`). The options
must then include an attribute ``EF-2stage`` or ``EF-mstage`` set equal to 
True. It uses the ``sputils.create_EF`` method.

Examples
--------

As intended, the examples of use of Amalgamator are quite short. The first
example, ``examples.farmer.archive.farmer_ama.py``, solves directly the EF. The model can be specified,
e.g. by taking an integer version of it. This specification can be made via
the command line, thanks to the ``inparser_adder`` method of ``farmer.py``.

Another example uses amalgamator, this time to create a hub-and-spokes 
architecture. ``uc_ama.py`` creates a hub and 2 spokes. A notable feature of
this example is the use of the ``fixer`` extension. This extension needs a 
function "id_fix_list_fct" as a parameter. However, a function cannot be
passed via the command line. "id_fix_list_fct" must thus be an attribute of 
the options of ``amalgamator.from_module``.

Finally, it is possible to use Amalgamator without calling 
``amalgamator.from_module``. The example ``aircond_ama`` starts by
fetching informations from the command line via 
``amalgamator.Aamgomator_parser``, and then modifies the options to get an
appropriate number of scenarios before creating an Amalgamator object.