.. _lblCustomUQ:

Configuring CustomUQ Engine
***************************
In order to use the **CustomUQ** engine option, the following two tasks need to be performed:

* Configure UQ tab to accept the required inputs
* Add UQ engine to customized UQ backend

These two steps are explained in more detail next.

Configuring UQ tab
==================

The quoFEM interface can be customized to accept the required inputs for user-specified UQ engines. The "CustomUQ" option should be selected, as shown in :numref:`figCustomUQOption`. This will direct quoFEM to invoke the customized UQ backend where users can plug in their own functionality.	   

.. _figCustomUQOption:

.. figure:: figures/customUQ.png
   :align: center
   :figclass: align-center

   CustomUQ engine selection. 

Next, users must configure the interface to accept inputs required to run their UQ engine. This is done through a JSON configuration file that is specified through "Configuration Input File". Once this file is input, the user interface will be automatically updated to accept the inputs specified in the JSON configuration. An example JSON configuration is shown :ref:`below <jsonInput>`. This
configuration file generates the interface shown in :numref:`CustomUQInput`.

.. _jsonInput:
.. literalinclude:: JsonWidgetConfig.json


.. _customUQInput:
.. figure:: figures/CustomUQEngine.png
     
   Custom UQ Engine Configuration

Currently, users are able to specify the following types of inputs:

#.  **ComboBox**: Allows selection of a particular option from a specified set

#.  **Spin Box**: Used to input integer values

#.  **Double Spin Box**: Used to input floating point numbers

#.  **File Input**: Used for inputting file locations

#.  **Line Edit**: Used to input text values	  

Lastly, users must specify the UQ driver name. This is required to direct the
customized UQ backend to the correct UQ driver. The driver name must correspond
the name provided in the customized backend, as described below.

Adding UQ Engine to Customized Backend	  
======================================

In addition to configuring the user interface to accept the required inputs, it is necessary
to make the custom UQ engine accessible to the customized UQ backend in quoFEM. This is achieved
by providing a UQ runner class in Python that follows the defined interface. Users must create
a UQ runner class that inherits from the *UqRunner* class, which is shown :ref:`below <uqRunner>`

.. _uqRunner:
.. literalinclude:: uqRunner.py
   :language: python

This runner class only needs to provide a *runUQ* method and a factory class
that creates an instance of this class. The *runUQ* method is where the
customized inputs from the user interface can be accessed and passed to the
custom UQ driver.

As an example, **UQpy** has been implemented in the customized backend--the source code for the customized *UqRunner* class can be found in the SimCenterBackendApplications repository, linked `here <https://github.com/NHERI-SimCenter/SimCenterBackendApplications/blob/master/modules/performUQ/other/UQpyRunner.py>`_, and is also availble in the ``{Path to quoFEM app contents}/applications/performUQ/other`` directory.

.. note::

   The parameters generated by the UQ engine must be stored in a file named
   ``params.in`` and placed in the current working directory. The file must
   follow the format shown in the example ``params.in`` file shown :ref:`below
   <paramsIn>`. The first line specifies the number of random variables while
   the subsequent lines first contain the name of the random variable and the
   value of the current realization separated by a space.

   .. _paramsIn:
   .. literalinclude:: params.in   


Lastly, the name of the UQ driver needs to be added to *configureAndRunUQ.py* in
the list of UQ driver options--this corresponds to the UQ driver name provided
in the customized user interface. 

The *configureAndRunUQ.py* file is as shown `here <https://github.com/NHERI-SimCenter/SimCenterBackendApplications/blob/refactorUQ/modules/performUQ/other/configureAndRunUQ.py>`_, and is located in the ``{Path to quoFEM app contents}/applications/performUQ/other`` directory. 

With the derived UQ runner class and the name of the UQ driver added to the list of UQ driver options, the custom UQ engine has been plugged into the quoFEM backend and can now be invoked from the quoFEM user interface.