Rappture-PUQ Integration Notes
This should be a living document detailing how PUQ and Rappture work together. This is not a comprehensive list of the thousands of changes made to Rappture to support UQ. Instead it is intended to be a detailed overview showing the execution flow.
Input Control Changes
A small icon shows up next to number controls.
Implementation:
The NumberEntry constructor looks at the xml for tool.uq and $path.uq to determine if UQ is enabled for this control. It passes that information to the gauge constructor.
gauge.tcl has numerous changes, implementing a UQ button to the right of the number entry. Clicking on the button creates a popup dialog with a probdisteditor widget (see probdisteditor.tcl). The UQ button image is in gui/scripts/images/UQ.png
When a UQ value is entered in the number entry, it appears as something like "uniform 100 200" or "gaussian 100 1". Many places in Rappture will choke on those values because they are obviously not numbers. To fix this, some new functions were added to gui/scripts/units.tcl ( and weirdly lang/tcl/scripts/units.tcl, which is a copy of the same file).
# ----------------------------------------------------------------------
# USAGE: mcheck_range value {min ""} {max ""}
#
# Checks a value or PDF to determine if is is in a required range.
# Automatically does unit conversion if necessary.
# Returns value if OK. Error if out-of-range
# Examples:
# [mcheck_range "gaussian 0C 1C" 200K 500K] returns 1
# [mcheck_range "uniform 100 200" 150 250] returns 0
# [mcheck_range 100 0 200] returns 1
# ----------------------------------------------------------------------
# ----------------------------------------------------------------------
# USAGE: mconvert value ?-context units? ?-to units? ?-units on/off?
#
# This version of convert() converts multiple values. Used when the
# value could be a range or probability density function (PDF).
# Examples:
# gaussian 100k 1k
# uniform 0eV 10eV
# 42
# exact 42
# ----------------------------------------------------------------------Execution Changes
When the simulate button is clicked...
Analyzer::simulate calls get_uq from tool.tcl which calls get_uq from task.tcl.
Task::get_uq calls LibraryObj::uq_get_vars, which scans the number XML elements and returns a list of UQ variables. Then get_uq uses that varlist to create and return a Rappture::UQ object.
Analyzer::simulate calls the UQ::num_runs method which returns the number of runs necessary for the default UQ method (currently Smolyak level 2) for the UQ varlist we got from uq_get_vars. If num_runs is > 1, then UQ is used and the popup dialog from Rappture::UQ is displayed. uq_type and uq_args are set from the dialog and appended to the args for the tool.
A <uq> element is created under <run> for the xml file. <uq><type><current> is set to the UQ type used. <uq><args><current> contains the arguments for that type. These are necessary to distinguish UQ runs where the tool paramaters are the same but the UQ parameters change. Without this, you cannot run and compare multiple UQ runs.
Note:
It may be desireable in the future to change the UQ dialog to specify a sampling strategy in conjunction with the UQ method. UQ methods can be changed in postprocessing. For example, Sparse Grid sampling can be used with Gaussian Process Regression as well as Smolyak GPC.
Analyzer::simulate calls Tool::Run which calls Task::Run which checks -uq_type and -uq_args which were set in Analyzer::simulate. Now, assuming UQ is used:
Instead of simply writing a driver xml file, a template xml file is also created where the current values of UQ variables are replaced with a submit-compatible template like "@@my_var"
Next, Task::_get_params is called to create a CSV file of parameter values for submit to use. This is actually very tricky. _get_params runs the python script get_params.py, which starts up a puq session using the UQ parameters, UQ type and UQ args. It uses PUQ RapptureHost as the execution host. RapptureHost does not invoke any jobs, just saves its state. The state of the PUQ session is saved in its hdf5 file, named puq_[pid].hdf5.
Then, Task::_build_submit_cmd turns the command string from the tool.xml file into a call to submit for a parameter sweep using the CSV file.
Finally the command is run. The submit job completes normally. Then "puq_analyze.py puq_[pid].hdf5" is run to complete the UQ analysis.
puq_analyze.py loads the HDF5 file, then calls the RapptureHost::collect() method which does all the fun work of combining the numerous xml output files into one xml file. It must also collect the data for UQ analysis into the HDF5 /output/data section. This is not too difficult except for curves. Curves must be sliced, and possibly parameterized, before UQ analysis. After collect(), UQ analysis is performed on the HDF5 file.
Now puq_analyze opens the HDF5 file again and reads the UQ data.
- plot_pdf_curve writes the simple (non-parameterized) curves
- plot_pdf_acruve writes the parameterized curves
- sensitivity is written to output.histogram(sens-$var)
- write_responses writes responses to output.response($var)
- write_summary writes a UQ summary to output.string(UQ Summary)
All UQ outputs have an <about><uqtype> attribute so Rappture can easily determine it is looking at UQ output and what type it is.
ResultSet Changes
After a successful Rappture run, the results are added to the ResultSet. Naturally we have to make some changes for the new UQ outputs.
Analyzer::_fixResultSet checks items for uq and passes uq_part to ResultViewer.
ResultViewer::_xml2data creates a UqInfo object for UQ items. This is so all the UQ pieces end up in a UQ tabbed notebook.
ResultViewer::_plotAdd creates a UqNotebook and adds UqInfo objects to it.
uqinfo.tcl stores the data displayed in the UqNotebook
uqnotebook.tcl implements a BLT tabbed notebook for each UQ variables. Tabs can contain response surfaces, PDFs, histograms (sensitivity), curves, or sequences.
uqcurve.tcl is a copy of xyresult.tcl that does the filled probability regions for probability curves. Perhaps it can be merged back into xyresult.tcl later.
responseviewer.tcl implements the vtk response surface viewer code.
TODO
- PDFs should be dynamically-generated like response surfaces. A special viewer should be written for them.
- We should have options for tuning reponse surface fits. Probably should wait for gaussian process regression to be added to PUQ.
- Response surfaces need a better way to show the quality of the surface fit.
