Uncertainty modelling for BOSP
------------------------------
------------------------------

This software provides uncertainty modelling of rainfall-runoff model Math1D
adapted for execution as a managed application under the BOSP.



Prerequisities
--------------

    - Properly installed and configured BOSP framework
    (http://bosp.dei.polimi.it/doku.php?id=how-to)



Installation
------------

1) Place root folder of the application (MpiUncertainty) to the user
contribution folder of the BOSP installation
(e.g. /home/%user%/BOSP/contrib/user).

2) Start a BOSP shell by sourcing the environment configuration script
bosp_init.env:

    $ . ~/BOSP/out/etc/bbque/bosp_init.env

3) Move to the BOSP working directory and install the newly added application:

    $ cd path/to/BOSP
    $ make bootstrap

4) Start a BOSP configuration menu:

    $ make menuconfig

5) In the menuconfig, enable the newly added application (e.g. MpiUncertainty):

    Applications -> [*] MpiUncertainty (NEW)

6) Edit AWMs resources requirements in recipes located under the application
recipes folder (e.g. /home/%user%/BOSP/contrib/user/MpiUncertainty/recipes)
to fit the hardware platform possibilities. For more details about recipes see
http://bosp.dei.polimi.it/doku.php?id=docs:rtlib:recipes 

7) Recompile BOSP including all enabled applications:

    $ make

or compile only newly added application (e.g. MpiUncertainty):

    $ make mpiuncertainty



Running application
-------------------

1) Start a BOSP shell by sourcing the environment configuration script
bosp_init.env:

    $ . ~/BOSP/out/etc/bbque/bosp_init.env

2) Move to the BOSP working directory:

    $ cd path/to/BOSP

3) Start a BBQUE deamon (requires root privileges):

    $ bbque-startd

4) Run the application:

Usage: mpiuncertainty [options]
MpiUncertainty Configuration Options:
  -h [ --help ]                         print help message
  -v [ --version ]                      print program version
  -C [ --conf ] arg (=/home/%user%/BOSP/out/etc/bbque/MpiUncertainty.conf)
                                        MpiUncertainty BBQUE configuration file
  -u [ --unconf ] arg (=/home/%user%/BOSP/contrib/user/MpiUncertainty/data/config.xml)
                                        Uncertainty configuration file
  -r [ --recipe ] arg (=MpiUncertainty) recipe name (for all EXCs)



Enabling additional BBQUE recipes
---------------------------------

By default, usage of two independent recipes is supported. To enable additional
recipes follow the steps below:

1) Create a new receipe (XML file with filename terminated by .recipe extension)
under the application recipes folder
(e.g. /home/%user%/BOSP/contrib/user/MpiUncertainty/recipes). If any parameters
and/or system metrics are used, continue with following steps.

2) Add the opList genertion target to the CMakeLists.txt file located
in the application src folder
(e.g. /home/%user%/BOSP/contrib/user/MpiUncertainty/src):

    add_custom_command(
    	OUTPUT  oplist3.cc
    	DEPENDS ${PROJECT_SOURCE_DIR}/recipes/MpiUncertainty3.recipe
    	COMMAND bbque-oplb -v OUTF=oplist3.cc -v BBQUE_RTLIB_OPLIST=opList3 ${PROJECT_SOURCE_DIR}/recipes/MpiUncertainty3.recipe
    	COMMENT "Generating OPList3..."
    )

Where oplist3.cc is any unique filename of the generated source file,
opList3 is an appropriate variable name and MpiUncertainty3.recipe is filename
of the newly created recipe.

3) Add the filename (without the .cc extension) of the generated oplist
source file from the previous step to the sources list in the same
CMakeLists.txt file located in the application src folder
(e.g. /home/%user%/BOSP/contrib/user/MpiUncertainty/src).

4) Declare the oplist variable (e.g. opList3) at the beginning
of the MpiUncertainty_exc.cc source file:

    extern ba::OperatingPointsList opList3;

5) Use the oplist variable in the MpiUncertainty::onConfigure method, e.g.:

    if(rpc_name == "MpiUncertainty3")
		m_threadsNumber = opList3[awm_id].parameters["threads"];

Where MpiUncertainty3 is the filename of the newly created receipe,
m_threadsNumber is the member variable, opList3 is a vector of AWM parameters
(e.g. threads) and system metrics, and awm_id is the ID of the current AWM. For
more details about advanced receipe creation see 
http://bosp.dei.polimi.it/doku.php?id=docs:rtlib:advancedrecipes

6) Build the application:

    $ make mpiuncertainty

7) Run the application with the -r flag, e.g.:

   $ mpiuncertainty -r MpiUncertainty3