QUESO User's Manual Users

User Manual:

Open the PDF directly: View PDF .
Page Count: 206

Download
Open PDF In Browser	View PDF

The QUESO Library

User’s Manual
Version 0.50.0

Quantification of Uncertainty for Estimation,
Simulation, and Optimization (QUESO)

Editors:
Kemelli C. Estacio-Hiroms
Ernesto E. Prudencio

Center for Predictive Engineering and Computational Sciences (PECOS)
Institute for Computational and Engineering Sciences (ICES)
The University of Texas at Austin
Austin, TX 78712, USA

Copyright © 2008-2013 The PECOS Development Team, http://pecos.ices.utexas.edu
Permission is granted to copy, distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.2 or any later version published by the Free
Software Foundation; with the Invariant Sections being “GNU General Public License” and
“Free Software Needs Free Documentation”, the Front-Cover text being “A GNU Manual”,
and with the Back-Cover text being “You have the freedom to copy and modify this GNU
Manual”. A copy of the license is included in the section entitled “GNU Free Documentation
License”.

iii

Abstract
QUESO stands for Quantification of Uncertainty for Estimation, Simulation and Optimization and consists of a collection of algorithms and C++ classes intended for research in
uncertainty quantification, including the solution of statistical inverse and statistical forward
problems, the validation of mathematical models under uncertainty, and the prediction of
quantities of interest from such models along with the quantification of their uncertainties.
QUESO is designed for flexibility, portability, easy of use and easy of extension. Its software
design follows an object-oriented approach and its code is written on C++ and over MPI. It
can run over uniprocessor or multiprocessor environments.
QUESO contains two forms of documentation: a user’s manual available in PDF format
and a lower-level code documentation available in web based/HTML format.
This is the user’s manual: it gives an overview of the QUESO capabilities, provides procedures for software execution, and includes example studies.

iv

v

Disclaimer
This document was prepared by The University of Texas at Austin. Neither the University of
Texas at Austin, nor any of its institutes, departments and employees, make any warranty, express or implied, or assume any legal liability or responsibility for the accuracy, completeness,
or usefulness of any information, apparatus, product, or process disclosed, or represent that
its use would not infringe privately owned rights. Reference herein to any specific commercial
product, process, or service by trade name, trademark, manufacturer, or otherwise, does not
necessarily constitute or imply its endorsement, recommendation, or favoring by The University of Texas at Austin or any of its institutes, departments and employees thereof. The views
and opinions expressed herein do not necessarily state or reflect those of The University of
Texas at Austin or any institute or department thereof.
QUESO library as well as this material are provided as is, with absolutely no warranty
expressed or implied. Any use is at your own risk.

vi

Contents

Abstract

iii

Disclaimer

v

Preface

x

1 Introduction
1.1 Preliminaries . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Key Statistical Concepts . . . . . . . . . . . . . . . . . . . .
1.3 The Software Stack of an Application Using QUESO . . . .
1.4 Algorithms for solving Statistical Inverse Problems . . . . .
1.4.1 DRAM Algorithm . . . . . . . . . . . . . . . . . . . .
1.4.2 Adaptive Multilevel Stochastic Simulation Algorithm
1.5 Algorithms for solving the Statistical Forward Problem . . .
2 Installation
2.1 Getting started . . . . . . . . . . . . . . . . . . .
2.1.1 Obtain and Install QUESO Dependencies .
2.1.2 Prepare your LINUX Environment . . . .
2.2 Obtaining a Copy of QUESO . . . . . . . . . . .
2.2.1 Recommended Build Directory Structure .
2.3 Configure QUESO Building Environment . . . . .
2.4 Compile, Check and Install QUESO . . . . . . . .
2.5 QUESO Developer’s Documentation . . . . . . .
2.6 Summary of Installation Steps . . . . . . . . . . .
2.7 The Build Directory Structure . . . . . . . . . . .
vii

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

1
1
2
4
5
6
9
15

.
.
.
.
.
.
.
.
.
.

17
17
18
19
19
20
20
21
22
22
23

viii
2.8
2.9

The Installed Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . .
Create your Application with the Installed QUESO . . . . . . . . . . . . . . .

3 C++ Classes in the Library
3.1 Core Classes . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Environment Class (and Options) . . . . . . .
3.1.2 Vector . . . . . . . . . . . . . . . . . . . . . .
3.1.3 Matrix . . . . . . . . . . . . . . . . . . . . . .
3.2 Templated Basic Classes . . . . . . . . . . . . . . . .
3.2.1 Vector Set, Subset and Vector Space Classes .
3.2.2 Scalar Function and Vector Function Classes .
3.2.3 Scalar Sequence and Vector Sequence Classes
3.3 Templated Statistical Classes . . . . . . . . . . . . .
3.3.1 Vector Realizer Class . . . . . . . . . . . . . .
3.3.2 Vector Random Variable Class . . . . . . . . .
3.3.3 Statistical Inverse Problem (and Options) . .
3.3.4 Metropolis-Hastings Solver (and Options) . .
3.3.5 Multilevel Solver (and Options) . . . . . . . .
3.3.6 Statistical Forward Problem (and Options) . .
3.3.7 Monte Carlo Solver (and Options) . . . . . . .
3.4 Miscellaneous Classes and Routines . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

24
25

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

27
27
27
29
29
33
33
33
36
39
39
39
40
42
42
48
48
50

4 Important Remarks
4.1 Revisiting Input Options . . . . . . . . . . . . . . . . . .
4.2 Revisiting Priors . . . . . . . . . . . . . . . . . . . . . .
4.3 Running with Multiple Chains or Monte Carlo Sequences
4.4 Running with Models that Require Parallel Computing .
4.5 A Requirement for the DRAM Algorithm . . . . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

51
51
52
52
53
53

5 QUESO Examples
5.1 simpleStatisticalInverseProblem . . . . .
5.1.1 Running the Example . . . . . . . . .
5.1.2 Example Code . . . . . . . . . . . . . .
5.1.3 Input File . . . . . . . . . . . . . . . .
5.1.4 Create your own Makefile . . . . . . .
5.1.5 Data Post-Processing and Visualization
5.2 simpleStatisticalForwardProblem . . . . .
5.2.1 Running the Example . . . . . . . . .
5.2.2 Example Code . . . . . . . . . . . . . .
5.2.3 Input File . . . . . . . . . . . . . . . .
5.2.4 Create your own Makefile . . . . . . .
5.2.5 Data Post-Processing and Visualization
5.3 gravity . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

54
55
56
57
60
61
62
65
66
66
69
70
71
73

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

ix

5.4

5.5

5.6

5.7

5.3.1 Statistical Inverse Problem . . . . . . . . . . . . . . . .
5.3.2 Statistical Forward Problem . . . . . . . . . . . . . . .
5.3.3 Running the Example . . . . . . . . . . . . . . . . . .
5.3.4 Example Code . . . . . . . . . . . . . . . . . . . . . . .
5.3.5 Input File . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.6 Create your own Makefile . . . . . . . . . . . . . . . .
5.3.7 Running the Gravity Example with Several Processors
5.3.8 Data Post-Processing and Visualization . . . . . . . . .
validationCycle . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Thermogravimetric Experiments and a Simple Model .
5.4.2 Statistical Inverse Problem . . . . . . . . . . . . . . . .
5.4.3 Statistical Forward Problem . . . . . . . . . . . . . . .
5.4.4 Running the Example . . . . . . . . . . . . . . . . . .
5.4.5 TGA Example Code . . . . . . . . . . . . . . . . . . .
5.4.6 Input File . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.7 Data Post-Processing and Visualization . . . . . . . . .
modal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.1 One-mode distribution . . . . . . . . . . . . . . . . . .
5.5.2 Two-mode distribution . . . . . . . . . . . . . . . . . .
5.5.3 Example Code . . . . . . . . . . . . . . . . . . . . . . .
5.5.4 Input File . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.5 Create your own Makefile . . . . . . . . . . . . . . . .
5.5.6 Data Post-Processing and Visualization . . . . . . . . .
bimodal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.1 Running the Example . . . . . . . . . . . . . . . . . .
5.6.2 Example Code . . . . . . . . . . . . . . . . . . . . . . .
5.6.3 Input File . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.4 Create your own Makefile . . . . . . . . . . . . . . . .
5.6.5 Data Post-Processing and Visualization . . . . . . . . .
hysteretic . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.1 Running the Example . . . . . . . . . . . . . . . . . .
5.7.2 Example Code . . . . . . . . . . . . . . . . . . . . . . .
5.7.3 Input File . . . . . . . . . . . . . . . . . . . . . . . . .
5.7.4 Create your own Makefile . . . . . . . . . . . . . . . .
5.7.5 Data Post-Processing and Visualization . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

73
76
77
79
87
88
89
90
98
98
99
101
102
102
121
124
127
127
128
130
135
136
137
141
141
142
147
148
149
150
154
154
162
163
164

References

167

A Free Software Needs Free Documentation

171

B GNU General Public License

173

C GNU Free Documentation License

186

Preface

The QUESO project started in 2008 as part of the efforts of the recently established Center
for Predictive Engineering and Computational Sciences (PECOS) at the Institute for Computational and Engineering Sciences (ICES) at The University of Texas at Austin.
The PECOS Center was selected by the National Nuclear Security Administration (NNSA)
as one of its new five centers of excellence under the Predictive Science Academic Alliance
Program (PSAAP). The goal of the PECOS Center is to advance predictive science and to
develop the next generation of advanced computational methods and tools for the calculation of reliable predictions on the behavior of complex phenomena and systems (multiscale,
multidisciplinary). This objective demands a systematic, comprehensive treatment of the calibration and validation of the mathematical models involved, as well as the quantification of
the uncertainties inherent in such models. The advancement of predictive science is essential
for the application of Computational Science to the solution of realistic problems of national
interest.
The QUESO library, since its first version, has been publicly released as open source
under the GNU General Public License and is available for free download world-wide. See
http://www.gnu.org/licenses/gpl.html for more information on the GPL software use agreement.
Contact Information:
Paul T. Bauman, Kemelli C. Estacio-Hiroms or Damon McDougall,
Institute for Computational and Engineering Sciences
1 University Station C0200
Austin, Texas 78712
email: pecos-dev@ices.utexas.edu
web: http://pecos.ices.utexas.edu
x

xi

Referencing the QUESO Library
When referencing the QUESO library in a publication, please cite the following:
@incollection{QUESO,
author
= "Ernesto Prudencio and Karl W. Schulz",
title
= {The Parallel C++ Statistical Library ‘QUESO’:
Quantification of Uncertainty for Estimation,
Simulation and Optimization},
booktitle = {Euro-Par 2011: Parallel Processing Workshops},
series
= {Lecture Notes in Computer Science},
publisher = {Springer Berlin / Heidelberg},
isbn
= {978-3-642-29736-6},
keyword
= {Computer Science},
pages
= {398-407},
volume
= {7155},
url
= {http://dx.doi.org/10.1007/978-3-642-29737-3_44},
year
= {2012}
}
@TechReport{queso-user-ref,
Author
= {Kemelli C. Estacio-Hiroms and Ernesto E. Prudencio},
Title
= {{T}he {QUESO} {L}ibrary, {U}ser’s {M}anual},
Institution = {Center for Predictive Engineering and Computational Sciences
(PECOS), at the Institute for Computational and Engineering
Sciences (ICES), The University of Texas at Austin},
Note
= {in preparation},
Year
= {2013}
}

@Misc{queso-web-page,
Author = {{QUESO} Development Team},
Title = {{T}he {QUESO} {L}ibrary: {Q}uantification of {U}ncertainty
for {E}stimation, {S}imulation and {O}ptimization},
Note
= \url{https://github.com/libqueso/},
Year
= {2008-2013}
}

xii

QUESO Development Team
The QUESO development team currently consists of Paul T. Bauman, Sai Hung Cheung,
Kemelli C. Estacio-Hiroms, Nicholas Malaya, Damon McDougall, Kenji Miki, Todd A. Oliver,
Ernesto E. Prudencio, Karl W. Schulz, Chris Simmons, and Rhys Ulerich.

Acknowledgments
This work has been supported by the United States Department of Energy, under the National
Nuclear Security Administration Predictive Science Academic Alliance Program (PSAAP)
award number [DE-FC52-08NA28615], and under the Office of Science Scientific Discovery
through Advanced Computing (SciDAC) award number [DE-SC0006656].
We would also like to thank James Martin, Roy Stogner and Lucas Wilcox for interesting
discussions and constructive feedback.

Target Audience
QUESO is a collection of statistical algorithms and programming constructs supporting research into the uncertainty quantification (UQ) of models and their predictions. UQ may be a
very complex and time consuming task, involving many steps: decide which physical model(s)
to use; decide which reference or experimental data to use; decide which discrepancy models
to use; decide which quantity(ies) of interest (QoI) to compute; decide which parameters to
calibrate; perform computational runs and collect results; analyze computational results, and
eventually reiterate; predict QoI(s) with uncertainty.
The purpose of this manual is not to teach UQ and its methods, but rather to introduce
QUESO library so it can be used as a tool to assist and facilitate the uncertainty quantification
of the user’s application. Thus, the target audience of this manual is researchers who have
solid background in Bayesian methods, are comfortable with UNIX concepts and the command
line, and have knowledge of a programming language, preferably C/C++. Bellow we suggest
some useful literature:
1. Probability, statistics, random variables [11, 12, 25];
2. Bayes’ formula [5, 14, 26, 37];
3. Markov chain Monte Carlo (MCMC) methods [4, 15, 18, 19, 20, 28, 31, 34, 35];
4. Monte Carlo methods [38];
5. Kernel density estimation [39];
6. C++ [27, 32];
7. Message Passing Interface (MPI) [47, 45];
8. UNIX/Linux (installation of packages, compilation, linking);
9. MATLAB/GNU Octave (for dealing with output files generated by QUESO); and
10. UQ issues in general [10].

CHAPTER 1. INTRODUCTION

1

CHAPTER

1

Introduction

QUESO is a parallel object-oriented statistical library dedicated to the research of statistically robust, scalable, load balanced, and fault-tolerant mathematical algorithms for the
quantification of uncertainty (UQ) of mathematical models and their predictions.
The purpose of this chapter is to introduce relevant terminology, mathematical and statistical concepts, statistical algorithms, together with an overall description of how the user’s
application may be linked with the QUESO library.

1.1 Preliminaries
Statistical inverse theory reformulates inverse problems as problems of statistical inference by
means of Bayesian statistics: all quantities are modeled as random variables, and probability
distribution of the quantities encapsulates the uncertainty observed in their values. The solution to the inverse problem is then the probability distribution of the quantity of interest
when all information available has been incorporated in the model. This (posterior) distribution describes the degree of confidence about the quantity after the measurement has been
performed [28].
Thus, the solution to the statistical inverse problem may be given by Bayes’ formula,
which express the posterior distribution as a function of the prior distribution and the data
represented through the likelihood function.
The likelihood function has an open form and its evaluation is highly computationally
expensive. Moreover, simulation-based posterior inference requires a large number of forward
calculations to be performed, therefore fast and efficient sampling techniques are required for
posterior inference.

Chapter 1: Introduction

2

It is often not straightforward to obtain explicit posterior point estimates of the solution,
since it usually involves the evaluation of a high-dimensional integral with respect to a possibly
non-smooth posterior distribution. In such cases, an alternative integration technique is the
Markov chain Monte Carlo method: posterior means may be estimated using the sample mean
from a series of random draws from the posterior distribution.
QUESO is designed in an abstract way so that it can be used by any computational model,
as long as a likelihood function (in the case of statistical inverse problems) and a quantity of
interest (QoI) function (in the case of statistical forward problems) is provided by the user
application.
QUESO provides tools for both sampling algorithms for statistical inverse problems, following Bayes’ formula, and statistical forward problems. It contains Monte Carlo solvers (for
autocorrelation, kernel density estimation and accuracy assessment), MCMC (e.g. Metropolis
Hastings [34, 20]) as well as the DRAM [18] (for sampling from probability distributions); it
also has the capacity to handle many chains or sequences in parallel, each chain or sequence itself demanding many computing nodes because of the computational model being statistically
explored [36].

1.2 Key Statistical Concepts
A computational model is a combination of a mathematical model and a discretization that
enables the approximate solution of the mathematical model using computer algorithms and
might be used in two different types of problems: forward or inverse.
Any computational model is composed of a vector θ of n parameters, state variables u,
and state equations r(θ, u) = 0. Once the solution u is available, the computational model
also includes extra functions for e.g. the calculation of model output data y = y(θ, u), and
the prediction of a vector q = q(θ, u) of m quantities of interest (QoI),
Parameters designate all model variables that are neither state variables nor further quantities computed by the model, such as: material properties, coefficients, constitutive parameters,
boundary conditions, initial conditions, external forces, parameters for modeling the model
error, characteristics of an experimental apparatus (collection of devices and procedures),
discretization choices and numerical algorithm options.
In the case of a forward problem, the parameters θ are given and one then needs to compute
u, y and/or q. In the case of an inverse problem, however, experimental data d is given and
one then needs to estimate the values of the parameters θ that cause y to best fit d.
Figure 1.2.1 represents general inverse and forward problems respectively.
There are many possible sources of uncertainty on a computational model. First, d need
not be equal to the actual values of observables because of errors in the measurement process. Second, the values of the input parameters to the phenomenon might not be precisely
known. Third, the appropriate set of equations governing the phenomenon might not be well
understood.
Computational models can be classified as either deterministic or stochastic – which are
the ones of interest here. In deterministic models, all parameters are assigned numbers, and

Chapter 1: Introduction

3
State u =? -

Input θ- Forward
Problem

Output y =?Prediction q =?

Experimental d
r(θ, u) = 0 Inverse

Parameters θ=?

Problem
y(θ, u)
-

(a)
(b)
Figure 1.2.1: The representation of (a) a generic forward problem and (b) a generic inverse
problem.
no parameter is related to the parametrization of a random variable (RV) or field. As a
consequence, a deterministic model assigns a number to each of the components of quantities
u, y and q. In stochastic models, however, at least one parameter is assigned a probability
density function (PDF) or is related to the parametrization of a RV or field, causing u, y
and q to become random variables. Note that not all components of θ need to be treated as
random. As long as at least one component is random, θ is a random vector, and the problem
is stochastic.
In the case of forward problems, statistical forward problems can be represented very
similarly to deterministic forward problems, as seen in Figure 1.2.2. In the case of inverse
problems, as depicted in Figure 1.2.3, however, the conceptual connection between deterministic and statistical problems is not as straightforward.
Input RV Θ Statistical
Forward
q(θ)
- Problem

Output RV Q-

Figure 1.2.2: The representation of a statistical forward problem. Θ denotes a random variable
related to parameters, θ denotes a realization of Θ and Q denotes a random variable related
to quantities of interest.

Prior RV Θ

- Statistical
πlike (d | y, r, Θ)- Inverse
Problem

Posterior RV-Θ

Figure 1.2.3: The representation of a statistical inverse problem. Θ denotes a random variable
related to parameters, θ denotes a realization of Θ and r denotes model equations, y denotes
some model output data and d denotes experimental data.
QUESO adopts a Bayesian analysis [28, 37] for statistical inverse problems, interpreting

Chapter 1: Introduction

4

the posterior PDF
πposterior (θ|d) =

πprior (θ)πlikelihood (d|θ)
π(d)

(1.2.1)

as the solution. Such solutions combine the prior information πprior (θ) of the parameters,
the information π(d) on the data, and the likelihood πlikelihood (d|θ) that the model computes
certain data values with a given set of input parameters.
This semantic interpretation of achieving a posterior knowledge on the parameters (on the
model) after combining some prior model knowledge with experimental information provides
an important mechanism for dealing with uncertainty. Although mathematically simple, is
not computationally trivial.

1.3 The Software Stack of an Application Using QUESO
An application using QUESO falls into three categories: a statistical inverse problem (IP), a
statistical forward problem (FP), or combinations of both. In each problem the user might
deal with up to five vectors of potentially very different sizes: parameters θ, state u, output
y, data d and QoIs q.
Algorithms in the QUESO library require the supply of a likelihood routine πlike : Rn → R+
for statistical inverse problems and of a QoI routine q : Rn → Rm for statistical forward
problems. These routines exist at the application level and provide the necessary bridge
between the statistical algorithms in QUESO, model knowledge in the model library and
scenario and experimental data in the disk space. Figure 1.3.1 shows the software stack of a
typical application that uses QUESO. In the figure, the symbol θ represents a vector of n > 1
parameters.
Even though QUESO deals directly with θ and q only, it is usually the case the one of
the other three vectors (u, y and d) will have the biggest number of components and will
therefore dictate the size of the minimum parallel environment to be used in a problem. So,
for example, even though one processor might be sufficient for handling θ, y, d and q, eight
processors at least might be necessary to solve for u. QUESO currently only requires that the
amounts n and m can be handled by the memory available to one processor, which allows the
analysis of problems with thousands of parameters and QoIs, a large amount even for state of
the art UQ algorithms.
QUESO currently supports three modes of parallel execution: an application user may
simultaneously run:
(a) multiple instances of a problem where the physical model requires a single processor, or
(b) multiple instances of a problem where the physical model requires multiple processors, or
(c) independent sets of types (a) and (b).
For example, suppose an user wants to use the Metropolis-Hastings (MH) algorithm to
solve a statistical IP, and that 1,024 processors are available. If the physical model is simple

Chapter 1: Introduction

5

Figure 1.3.1: An application software stack. QUESO requires the input of a likelihood routine
πlike : Rn → R+ for IPs and of a QoI routine q : Rn → Rm for FPs. These application level
routines provide the bridge between the statistical algorithms in QUESO, physics knowledge
in the model library, and relevant experimental (calibration and validation) data.
enough to be handled efficiently by a single processor, then the user can run 1,024 chains
simultaneously, as in case (a). If the model is more complex and requires, say, 16 processors,
then the user can run 64 chains simultaneously, as in case (b), with 16 processors per chain.
QUESO treats this situation by using only 1 of the 16 processors to handle the chain. When
a likelihood evaluation is required, all 16 processors call the likelihood routine simultaneously.
Once the likelihood returns its value, QUESO puts 15 processors into idle state until the
routine is called again or the chain completes. Case (c) is useful, for instance, in the case of a
computational procedure involving two models, where a group of processors can be split into
two groups, each handling one model. Once the two-model analysis end, the combined model
can use the full set of processors.1

1.4 Algorithms for solving Statistical Inverse Problems
The goal of inference is to characterize the posterior PDF, or to evaluate point or interval
estimates based on the posterior [23]. Samples from posterior can be obtained using Markov
chain Monte Carlo (MCMC) which require only pointwise evaluations of the unnormalized
posterior. The resulting samples can then be used to either visually present the posterior
or its marginals, or to construct sample estimates of posterior expectations. Examples of
1

The parallel capabilities of QUESO have been exercised on the Ranger system of the TACC [2] with up
to 16k processors.

Chapter 1: Introduction

6

MCMC are: the Metropolis-Hastings (MH) algorithm [34, 20], the Delayed Rejection (DR)
algorithm [15, 35], and Adaptive Metropolis (AM) [19] which are combined together in the
Delayed Rejection Adaptive Metropolis, DRAM, algorithm [18]. The DRAM is implemented
in QUESO and available for the solution of SIP. MCMC methods are well-established and
documented [4, 15, 18, 19, 20, 28, 31, 34, 35]; thus only brief description of the DRAM
algorithm is presented in Section 1.4.1.
During model construction, errors arising from imperfect modeling and uncertainties due
to incomplete information about the system and its environment always exist; thus, there has
been a crescent interest in Bayesian model class updating and selection [9, 7, 8].
Model updating refers to the methodology that determines the most plausible model for a
system, given a prior PDF. One stochastic method that handles model updating successfully is
the multilevel method. Throughout the years, sereveral versions of the same method have been
implemented as improvements of its predecessors [3, 9, 8]. QUESO hosts the novel Adaptive
Multilevel Stochastic Simulation Algorithm (AMSSA) [8], which is described in Section 1.4.2.
For details about the method, please refer to [8].

1.4.1 DRAM Algorithm
DRAM is a combination of two ideas for improving the efficiency of Metropolis-Hastings type
Markov chain Monte Carlo (MCMC) algorithms, Delayed Rejection and Adaptive Metropolis [29].
Random walk Metropolis-Hasting algorithm with Gaussian proposal distribution is useful
in simulating from the posterior distribution in many Bayesian data analysis situations. In
order for the chain to be efficient, the proposal covariance must somehow be tuned to the
shape and size of the target distribution. This is important in highly nonlinear situations,
when there are correlation between the components of the posterior, or when the dimension
of the parameter is high. The problem of adapting the proposal distribution using the chain
simulated so far is that when the accepted values depend on the history of the chain, it is
no longer Markovian and standard convergence results do not apply. One solution is to use
adaptation only for the burn-in period and discard the part of the chain where adaptation
has been used. In that respect, the adaptation can be thought as automatic burn-in. The
idea of diminishing adaptation is that when adaptation works well, its effect gets smaller and
we might be able to prove the ergodicity properties of the chain even when adaptation is
used throughout the whole simulation. This is the ideology behind AM adaptation. On the
other hand, the DR method allows the use of the the current rejected values without losing
the Markovian property and thus allows to adapt locally to the current location of the target
distribution.
In Adaptive Metropolis [19] the covariance matrix of the Gaussian proposal distribution
is adapted on the fly using the past chain. This adaptation destroys the Markovian property
of the chain, however, it can be shown that the ergodicity properties of the generated sample
remain. How well this works on finite samples and on high dimension is not obvious and must
be verified by simulations.

Chapter 1: Introduction

7

Starting from initial covariance C (0) , the target covariance is updated at given intervals
from the chain generated so far.
C (i) = sd cov(chain1 : chaini ) + sd εId ,
the small number ε prevents the sample covariance matrix from becoming singular. For the
scaling factor, the value sd = 2.42 /d is standard optimal choice for Gaussian targets, d being
the dimension of the target [14]. A standard updating formula for the sample covariance
matrix can be used, so that the whole chain does not need to reside in the computer memory.
With the Delayed rejection method [35], it becomes possible to make use of several tries
after rejecting a value by using different proposals while keep the reversibility of the chain.
Delayed rejection method (DR) works in the following way. Upon rejection a proposed candidate point, instead of advancing time and retaining the same position, a second stage move
is proposed. The acceptance probability of the second stage candidate is computed so that
reversibility of the Markov chain relative to the distribution of interest is preserved. The
process of delaying rejection can be iterated for a fixed or random number of stages, let’s say
nstages . The higher stage proposals are allowed to depend on the candidates so far proposed
and rejected. Thus DR allows partial local adaptation of the proposal within each time step
of the Markov chain still retaining the Markovian property and reversibility.
The first stage acceptance probability in DR is the standard MH acceptance and it can be
written as


π(x(1) ) q1 (x(1) , a)
(1)
·
,
α1 (a, x ) = min 1,
π(a) q1 (a, x(1) )
Here a is the current point, x(1) is the proposed new value drawn from the distribution
q1 (a, ·), and π is the target distribution. If x(1) is rejected, a second candidate x(2) is drawn
from q2 (a, x(1) , ·) using the acceptance probability


π(x(2) )q1 (x(2) , x(1) )q2 (x(2) , x(1) , a)[1 − α1 (x(2) , x(1) )]
(1)
(2)
α2 (a, x , x ) = min 1,
π(a)q1 (a, x(1) )q2 (a, x(1) , x(2) )[1 − α1 (a, x(1) )]
i.e., it depends not only on the current position of the chain but also on what we have just
proposed and rejected.
As the reversibility property is preserved, this method also leads to the same stationary
distribution π as the standard MH algorithm. The procedure can be iterated further for
higher-stage proposals. The Gaussian proposal at each stage i is defined as:
1
−
[z − a]T · [C]−1 · [z − a]
(1)
(i−1)
2
qi (a, x , . . . , x
, z) = e
(1.4.1)
|
{z
}
i terms

where the covariance matrix C and the scalings for the higher-stage proposal covariances
1 = γ1 6 γ2 6 . . . 6 γnstages are given.
If qi denotes the proposal at the i-th stage, the acceptance probability at that stage is:


π(x(i) )
(1)
(i)
αi (a, x , . . . , x ) = min 1,
· qfraction · αfraction .
(1.4.2)
π(a)

Chapter 1: Introduction

8

where the expressions qfraction and αfraction are given by
qfraction =

q1 (x(i) , x(i−1) ) q2 (x(i) , x(i−1) , x(i−2) )
qi (x(i) , x(i−1) , . . . , x(1) , a)
.
.
.
q1 (a, x(1) )
q2 (a, x(1) , x(2) )
qi (a, x(1) , . . . , x(i−1) , x(i) )

and
αfraction =

[1 − αi−1 (x(i) , x(i−1) , . . . , x(1) )]
[1 − α1 (x(i) , x(i−1) )] [1 − α2 (x(i) , x(i−1) , x(i−2) )]
.
.
.
.
[1 − α1 (a, x(1) )]
[1 − α2 (a, x(1) , x(2) )]
[1 − αi−1 (a, x(1) , . . . , x(i−1) )]

Since all acceptance probabilities are computed so that reversibility with respect to π is
preserved separately at each stage, the process of delaying rejection can be interrupted at any
stage that is, we can, in advance, decide to try at most, say, 3 times to move away from the
current position, otherwise we let the chain stay where it is. Alternatively, upon each rejection,
we can toss a p-coin (i.e., a coin with head probability equal to p), and if the outcome is head
we move to a higher stage proposal, otherwise we stay put [18].
The smaller overall rejection rate of DR guarantees smaller asymptotic variance of the
estimates based on the chain. The DR chain can be shown to be asymptotically more efficient
that MH chain in the sense of Peskun ordering (Mira, 2001a).
Haario, et al. 2006 [18] combine AM and DR into a method called DRAM, in what they
claim to be a straightforward possibility amongst the possible different implementations of
the idea, and which is described in this section.
In order to be able to adapt the proposal, all you need some accepted points to start with.
One “master” proposal is tried first – i.e., the proposal at the first stage of DR is adapted
just as in AM: the covariance C (1) is computed from the points of the sampled chain, no
matter at which stage these points have been accepted in the sample path. After rejection,
a try with modified version of the first proposal is done according to DR. A second proposal
can be one with a smaller covariance, or with different orientation of the principal axes. The
most common choice is to always compute the covariance C (i) of the proposal for the i-th
stage (i = 2, . . . , nstages ) simply as a scaled version of the proposal of the first stage,
C (i) = γi C (1)
where the scale factors γi can be somewhat freely chosen. Then, the master proposal is
adapted using the chain generated so far, and the second stage proposal follows the adaptation
in obvious manner.
The requirements for the DRAM algorithm are:
• Number npos > 2 of positions in the chain;
• Initial guess m(0) ;
• Number of stages for the DR method: nstages > 1;

Chapter 1: Introduction

9

N
• For 1 6 i 6 nstages , functions qi : R
. . × RN} → R+ , such that qi (a, x(1) , . . . , x(i−1) , ·)
| × .{z
(1)

(i+1) times
N
(i−1)

is a PDF for any (a, x , . . . , x

) ∈ R
. . × RN}; i.e., choose qi as in Equa| × .{z
i times

tion (1.4.1);
• Recursively define αi : |Rn × .{z
. . × Rn} → [0, 1],

1 6 i 6 nstages according to Equa-

(i+1) times

tion (1.4.2).
Recalling that a sample is defined as:
a sample = a + C1/2 N (0, I).
a simple, but useful, implementation of DRAM is described in Algorithm 1.
There are six variables in the QUESO input file used to set available options for the DRAM
algorithm, which are described in 3.3.4. Here, they are presented presented bellow together
with their respective definition in Algorithm 1.
ip mh dr maxNumExtraStages: defines how many extra stages should be considered in the
DR loop (nstages );
ip mh dr listOfScalesForExtraStages: defines the list s of scaling factors that will multiply the covariance matrix (values of γi );
ip mh am adaptInterval: defines whether or not there will be a period of adaptation;
ip mh am initialNonAdaptInterval: defines the initial interval where the proposal covariance matrix will not be changed (n0 );
ip mh am eta: is a factor used to scale the proposal covariance matrix, usually set to be 2.42 /d,
where d is the dimension of the problem [31, 18] (sd );
ip mh am epsilon: is the covariance regularization factor (ε).

1.4.2 Adaptive Multilevel Stochastic Simulation Algorithm
In this section we rewrite the Bayesian formula (1.2.1) by making explicit all the implicit
model assumptions. Such explication demands the use of probability logic and the concept of a
stochastic system model class (model class for short); as these concepts enable the comparison
of competing model classes.
Let Mj be one model class; the choice of θ specifies a particular predictive model in Mj ,
and, for brevity, we do not explicitly write θ j to indicate that the parameters of different
model classes may be different, but this should be understood. Based on Mj , one can use
data D to compute the updated relative plausibility of each predictive model in the set defined
by Mj . This relative plausibility is quantified by the posterior PDF π(θ|D, Mj ).

Chapter 1: Introduction

10

Algorithm 1: DRAM algorithm [31].
Input: Number of positions in the chain npos > 2; initial guess m(0) ; initial first stage proposal
covariance C (0) ; nstages > 1; and functions qi : RN × . . . × RN → R+
{z
}
|
(i+1) times

1
2
3
4
5
6
7
8
9

10
11
12

13
14

15
16
17
18
19
20
21
22
23
24

25
26
27
28
29
30
31
32
33

Select sd ;
// scaling factor
Select ε ;
// covariance regularization factor
Select n0 ;
// initial non-adaptation period
for i ← 1 to nstages do
// nstages is the number of tries allowed
Select γi ;
// scalings for the higher-stage proposal covariances
end
repeat
Set ACCEP T ← f alse;
Set i ← 1;
// After an initial period of simulation, adapt the master proposal (target)
covariance using the chain generated so far:
if k > n0 then
C (1) = sd Cov(m(0) , . . . , m(k−1) ) + sd εId ;
end
// nstages -DR loop:
repeat
Generate candidate c(i) ∈ RN by sampling qi (m(k) , c(1) , . . . , c(i−1) , ·) ;
// qi is the
proposal probability density
if c(i) ∈
/ supp(π) then
i←i+1
end
if c(i) ∈ supp(π) then
Compute αi (m(k) , c(1) , . . . , c(i−1) , c(i) ) ;
// acceptance probability
Generate a sample τ ∼ U ((0, 1])
if (αi < τ ) then i ← i + 1;
if (αi > τ ) then ACCEPT←true;
end
C (i) = γi C (1) ; // Calculate the higher-stage proposal as scaled versions of C (1) ,
according to the chosen rule
until (ACCEPT=false) and (i 6 nstages );
if (ACCEPT=true) then
Set m(k+1) ← c(i)
end
if (ACCEPT=false) then
Set m(k+1) ← m(k)
end
Set k ← k + 1;
until (k + 1 < npos );

Chapter 1: Introduction

11

Bayes theorem allows the update of the probability of each predictive model Mj by combining measured data D with the prior PDF into the posterior PDF:
f (D|θ, Mj ) · πprior (θ|Mj )
π(D, Mj )
f (D|θ, Mj ) · πprior (θ|Mj )
=R
f (D|θ, Mj ) · πprior (θ|Mj ) dθ

πposterior (θ|D, Mj ) =

(1.4.3)

where the denominator expresses the probability of getting the data D based on Mj and is
called the evidence for Mj provided by D; πprior (θ|Mj ) is the prior PDF of the predictive model
θ within Mj ; and the likelihood function f (D|θ, Mj ) expresses the probability of getting D
given the predictive model θ within Mj – and this allows stochastic models inside a model
class Mj to be compared.
When generating samples of posterior PDF πposterior (θ|D, Mj ) in order to forward propagate uncertainty and compute QoI RV’s, it is important to take into account potential multiple
modes in the posterior. One simple idea is to sample increasingly difficult intermediate distributions, accumulating “knowledge” from one intermediate distribution to the next, until the
target posterior distribution is sampled. In [8], an advanced stochastic simulation method,
referred to as Adaptive Multi Level Algorithms, is proposed which can generate posterior
samples from πposterior (θ|D, Mj ) and compute the log of the evidence p(D|θ, Mj ) at the same
time by adaptively moving samples from the prior to the posterior through an adaptively
selected sequence of intermediate distributions [7].
Specifically, the intermediate distributions are given by:
(`)

πint (θ|D) = f (θ|D, Mj )τ` · πprior (θ|Mj ),

` = 0, 1, . . . , L,

for a given L > 0 and a given sequence 0 = τ0 < τ1 < . . . < τL = 1 of exponents.
In order to compute the model evidence π(D|Mj ) where:
Z
π(D|Mj ) = f (θ|D, Mj ) · πprior (θ|Mj ) dθ,
the use of intermediate distribution is also beneficial. For that, recall that
Z
π(D|Mj ) = f (θ)π(θ) dθ
Z
= f π dθ
Z
= f 1−τL−1 f τL−1 −τL−2 . . . f τ2 −τ1 f τ1 π dθ
Z
f τ1 π
dθ
= c1 f 1−τL−1 f τL−1 −τL−2 . . . f τ2 −τ1
c1
Z
f τ2 −τ1 f τ1 π
= c2 c1 f 1−τL−1 f τL−1 −τL−2 . . .
dθ
c2 c1
= cL cL−1 · · · c2 c1 .

(1.4.4)

(1.4.5)

(1.4.6)

Chapter 1: Introduction

12

Assuming that the prior PDF is normalized (it integrates to one) and if τ` is small enough,
then Monte Carlo method can be efficiently applied to calculate c` in Equation (1.4.6). Due
to numerical (in)stability, it is more appropriate to calculate the estimators:
c˜i = ln ci ,

i = 1, . . . , L.

(1.4.7)

Combining Equations (1.4.6) and (1.4.7), we have:
ln[π(D|Mj )] = c̃L + c̃L−1 + . . . + c̃2 + c̃1 .
Computing the log of the evidence instead of calculating the evidence directly is attractive
because the evidence is often too large or too small relative to the computer precision. The
posterior probability can be calculated readily in terms of the log evidence, allowing overflow
and underflow errors to be avoided automatically [7].
(`)
Now let’s define some auxiliary variables for k = 1, . . . , ntotal :
• k-th sample at the `-th level:
θ (`)[k] ,

` = 0, 1, . . . , L

(1.4.8)

• Plausibility weight:
w(`)[k] =

f (θ (`)[k] |D, Mj )τ` · πprior (θ (`)[k] , Mj )
f (τ` ) (D|θ (`)[k] , Mj )
=
,
f (θ (`)[k] |D, Mj )τ` −1 · πprior (θ (`)[k] , Mj )
f (τ`−1 ) (D|θ (`)[k] , Mj )

=f

(τ` −τ`−1 )

(D|θ

(`)[k]

, Mj ),

(1.4.9)

` = 0, 1, . . . , L

• Normalized plausibility weight:
w(`)[k]
,
w̃(`)[k] = P (`)
ntotal (`)[s]
s=1 w
• Effective sample size:
(`)

neff = P (`)
ntotal
s=1

` = 0, 1, . . . , L

(1.4.10)

1

(1.4.11)

2
(w̃(`)[s] )
(`)

• Estimate for the sample covariance matrix for πint :
(`−1)

(`−1)

Σ=

ntotal

ntotal

X

X

m=1

w̃m (θ (`−1)[m] − θ)(θ (`−1)[m] − θ)t ,

where θ =

m=1

w̃m θ (`−1)[m]

(1.4.12)

Chapter 1: Introduction

13

so we can define the discrete distribution:
P (`) (k) = w̃(`)[k] ,

(`)

k = 1, 2, . . . , ntotal .

(1.4.13)

The ML algorithm consists of a series of resampling stages, with each stage doing the
(`)
(`)
(`)
following: given ntotal samples from πint (θ|D), denoted by θ (`)[k] , k = 1...ntotal obtain samples
(`+1)
(`+1)
from πint (θ|D), denoted by θ (`+1)[k] , k = 1...ntotal .
(`)
This is accomplished by: given the samples θ (`)[k] , k = 1...ntotal , in Equation (1.4.8), from
(`)
πint (θ|D), we compute the plausibility weights w(`)[k] given in Equation (1.4.9) with respect
(`+1)
to πint (θ|D). Then we re-sample the uncertain parameters according to the normalized
weights w̃(`)[k] , given in Equation (1.4.10), through the distribution in Equation (1.4.13). This
(`)
(`+1)
(`+1)
is possible due to the fact that for large ntotal and ntotal , then θ (`+1)[k] , k = 1...ntotal will be
(`+1)
distributed as πint (θ|D) [9].
The choice of τ` , ` = 1, . . . , L − 1 is essential. It is desirable to increase the τ values slowly
so that the transition between adjacent PDFs is smooth, but if the increase of the τ values
is too slow, the required number of intermediate stages (L value) will be too large [9]. More
intermediate stages mean more computational cost. In the ML method proposed by [8] and
implemented in QUESO, τ` is computed through a bissection method so that:
(`)

(`)
βmin

<

neff
(`)

ntotal

(`)
< βmax

(1.4.14)

1.4.2.1 AMSSA Algorithm
(`)

Based on the above results, and recalling that the series of intermediate PDFs, πint (θ|D),
start from the prior PDF and ends with the posterior PDF, Algorithm 2 can be applied both
to draw samples from the posterior PDF, πposterior (θ|D, Mj ), and to estimate the evidence
π(D, Mj ).
Steps 15 and 16 in Algorithm 2 are accomplished by sampling the distribution in Equa(`)
tion (1.4.13) a total of ntotal times. The selected indices k determine the samples θ (`)[k] to be
used as initial positions, and the number of times an index k is selected determines the size
of the chain beginning at θ (`)[k] .
At each level `, many computing nodes can be used to sample the parameter space collec(`)
tively. Beginning with ` = 0, the computing nodes: (a) sample πint (θ|D, Mj ); (b) select some
of the generated samples (“knowledge”) to serve as initial positions of Markov chains for the
(`+1)
(`+1)
next distribution πint (θ|D, Mj ); and (c) generate the Markov chains for πint (θ|D, Mj ).
The process (a)–(b)–(c) continues until the final posterior distribution is sampled. As
` increases, the selection process tends to value samples that are located in the regions of
high probability content, which gradually “appear”as τ` increases. So, as ` increases, if the
“good” samples selected from the `-th level to the (`+1)-th level are not redistributed among
computing nodes before the Markov chains for the ( `+1)-th level are generated, the “lucky”
computing nodes (that is, the ones that had, already at the initial levels, samples in the

Chapter 1: Introduction

14

Algorithm 2: Detailed description of the Adaptive Multilevel Stochastic Simulation
Algorithm proposed by [8].
(`)

1
2
3
4

Input: for each ` = 0, . . . , L: the total amount of samples to be generated at `-th level (ntotal > 0) and
(`)
(`)
the thresholds (0 < βmin < βmax < 1) on the effective sample size of the `-th level
(m)
Output: Q
θ (m)[k] , k = 1, . . . , ntotal ; which are asymptotically distributed as πposterior (θ|D, Mj )
Output: ` c` ; which is asymptotically unbiased for π(D, Mj )
Set ` = 0;
Set τ` = 0;
(0)

(0)

Sample prior distribution, πprior (θ|Mj ), ntotal times ;
// i.e, obtain θ (0)[k] , k = 1, . . . , ntotal
while τ` < 1 do
(`−1)
/* At the beginning of the `-th level, we have the samples θ (`−1)[k] , k = 1...ntotal
(`−1)

5
6
7
8
9
10
11
12
13
14
15
16
17

from πint (θ|D), Equation (1.4.4).
Set ` ← ` + 1 ;
Compute plausibility weights w(`)[k] via Equation (1.4.9);
Compute normalized weights w̃(`)[k] via Equation (1.4.10);

*/
// begin next level

(`)

Compute neff via Equation (1.4.11);
Compute τ` so that Equation (1.4.14) is satisfied;
if τ` > 1 then
τ` ← 1;
Recompute w(`)[k] and w̃(`)[k] ;
end
(`)

Compute an estimate for the sample covariance matrix for πint via Equation (1.4.12);
Select, from previous level, the initial positions for the Markov chains;
Compute sizes of the chains ;
Redistribute chain initial positions among processors;
(`)

(`)

// the sum of the sizes = ntotal

(`)

/* Then the ntotal samples θ (`)[k] , from πint (θ) are generated by doing the following
(`)
1, . . . , ntotal :

18

19
20

for k =
*/
Generate chains: draw a number k 0 from a discrete distribution P (`) (k) in Equation (1.4.13) via
Metropolis-Hastings ;
// i.e., obtain θ (`)[k] = P (l)[k]


(`−1)
Pntotal
Q
1
Compute c` = (`−1)
ws ;
// recall that π(D|Mj ) = ` c` , Equation (1.4.5)
s=1
ntotal

end

final posterior regions of high probability content) will tend to accumulate increasingly more
samples in the next levels. This possible issue is avoided maintaining a balanced computational
load among all computing nodes, which is handled in the ML by the step in Line 17.
Running the step in Line 17 of Algorithm 2 is then equivalent of solving the following
problem: given the number of processors Np , the total number of runs ntotal and the number
of runs nj (to be) handled by the j-th processor; distribute Nt tasks among the Np processors
so that each processor gets its total number nj of program runs, j = 1, . . . , Np , the closest
possible to the mean n̄ = ntotal /Np . This parallel implementation of the algorithm is proposed
in [8], and it has been implemented in QUESO by the same authors/researchers.

Chapter 1: Introduction

15

1.5 Algorithms for solving the Statistical Forward Problem
The Monte Carlo method is commonly used for analyzing uncertainty propagation, where the
goal is to determine how random variation, lack of knowledge, or error affects the sensitivity,
performance, or reliability of the system that is being modeled [38].
Monte Carlo works by using random numbers to sample, according to a PDF, the ‘solution
space’ of the problem to be solved. Then, it iteratively evaluates a deterministic model using
such sets of random numbers as inputs.
Suppose we wish to generate random numbers distributed according to a positive definite
function in one dimension P (x). The function need not be normalized for the algorithm to
work, and the same algorithm works just as easily in a many dimensional space. The random
number sequence xi , i = 0, 1, 2, . . . is generated by a random walk as follows:
1. Choose a starting point x0
2. Choose a fixed maximum step size δ.
3. Given a xi , generate the next random number as follows:
(a) Choose xtrial uniformly and randomly in the interval [xi − δ, xi + δ].
P (xtrial )
.
(b) Compute the ratio w =
P (xi )
Note that P need not be normalized to compute this ratio.
(c) If w > 1 the trial step is in the right direction, i.e., towards a region of higher
probability.
Accept the step xi+1 = xtrial .
(d) If w < 1 the trial step is in the wrong direction, i.e., towards a region of lower
probability. We should not unconditionally reject this step! So accept the step
conditionally if the decrease in probability is smaller than a random amount:
i. Generate a random number r in the interval [0, 1].
ii. If r < w accept the trial step xi+1 = xtrial .
iii. If w ≤ r reject the step xi+1 = xi . Note that we don’t discard this step! The
two steps have the same value.
There are essentially two important choices to be made. First, the initial point x0 must be
chosen carefully. A good choice is close to the maximum of the desired probability distribution.
If this maximum is not known (as is usually the case in multi-dimensional problems), then the
random walker must be allowed to thermalize i.e., to find a good starting configuration: the
algorithm is run for some large number of steps which are then discarded. Second, the step
size must be carefully chosen. If it is too small, then most of the trial steps will be accepted,
which will tend to give a uniform distribution that converges very slowly to P (x). If it is
too large the random walker will step right over and may not ‘ ‘see” important peaks in the

Chapter 1: Introduction

16

probability distribution. If the walker is at a peak, too many steps will be rejected. A rough
criterion for choosing the step size is for the
Acceptance ratio =

Number of steps accepted
Total number of trial steps

to be around 0.5.
An implementation of Monte Carlo algorithm is described in Algorithm 3.
Algorithm 3: Detailed description of the Monte Carlo Algorithm proposed by [34].

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Input: Starting point x0 , step size δ, number of trials M , number of steps per trial N , unnormalized
density or probability function P (x) for the target distribution.
Output: Random number sequence xi , i = 0, 1, 2, . . .
for i = 0...M do
for j = 0...N do
Set xtrial ← xi + (2 RAND([0,1]) − 1)δ;
Set w = P (xtrial )/P (x);
Set accepts ← 0;
if w ≥ 1 then // uphill
xi+1 ← xtrial ;
// accept the step
accepts ← accepts+1;
else // downhill
Set r ← RAND([0,1]);
if r < w then // but not too far
xi+1 ← xtrial ;
// accept the step
accepts ← accepts+1;
end
end
end
end

Monte Carlo is implemented in QUESO and it is the chosen algorithm to compute a sample
of the output RV (the QoI) of the SFP for each given sample of the input RV.

CHAPTER 2. INSTALLATION

17

CHAPTER

2

Installation

This chapter covers the basic steps that a user will need follow when beginning to use QUESO:
how to obtain, configure, compile, build, install, and test the library. It also presents both
QUESO source and installed directory structure, some simple examples and finally, introduces
the user on how to use QUESO together with the user’s application.
This manual is current at the time of printing; however, QUESO library is under active
development. For the most up-to-date, accurate and complete information, please visit the
online QUESO Home Page1 .

2.1 Getting started
In operating systems which have the concept of a superuser, it is generally recommended
that most application work be done using an ordinary account which does not have the
ability to make system-wide changes (and eventually break the system via (ab)use of superuser
privileges).
Thus, suppose you want to install QUESO and its dependencies on the following directory:
$HOME / LIBRARIES /

so that you will not need superuser access rights. The directory above is referred to as the
QUESO installation directory (tree).
There are two main steps to prepare your LINUX computing system for QUESO library:
obtain and install QUESO dependencies, and define a number of environmental variables.
1

https://github.com/libqueso

Chapter 2: Installation

18

These steps are discussed bellow.

2.1.1 Obtain and Install QUESO Dependencies
QUESO interfaces to a number of high-quality software packages to provide certain functionalities. While some of them are required for the successful installation of QUESO, other may
be used for enhancing its performance. QUESO dependencies are:
1. C and C++ compilers. Either gcc or icc are recommended [41, 44].
2. Autotools: The GNU build system, also known as the Autotools, is a suite of programming tools (Automake, Autoconf, Libtool) designed to assist in making source-code
packages portable to many Unix-like systems [42].
3. STL: The Standard Template Library is a C++ library of container classes, algorithms,
and iterators; it provides many of the basic algorithms and data structures of computer
science [24]. The STL usually comes packaged with your compiler.
4. GSL: The GNU Scientific Library is a numerical library for C and C++ programmers.
It provides a wide range of mathematical routines such as random number generators,
special functions and least-squares fitting [13]. The lowest version of GSL required by
QUESO is GSL 1.10.
5. Boost: Boost provides free peer-reviewed portable C++ source libraries, which can be
used with the C++ Standard Library [40]. QUESO requires Boost 1.35.0 or newer.
6. MPI: The Message Passing Interface is a standard for parallel programming using the
message passing model. E.g. Open MPI [47] or MPICH [45]. QUESO requires MPI
during the compilation step; however, you may run it in serial mode (e.g. in one single
processor) if you wish.
QUESO also works with the following optional libraries:
1. GRVY: The Groovy Toolkit (GRVY) is a library used to house various support functions often required for application development of high-performance, scientific applications. The library is written in C++, but provides an API for development in C and
Fortran [43]. QUESO requires GRVY 0.29 or newer.
2. HDF5: The Hierarchical Data Format 5 is a technology suite that makes possible the
management of extremely large and complex data collections [16]. The lowest version
required by QUESO is HDF5 1.8.0.
3. GLPK: The GNU Linear Programming Kit package is is a set of routines written in
ANSI C and organized in the form of a callable library for solving large-scale linear
programming, mixed integer programming, and other related problems [33]. QUESO
works with GLPK versions newer than or equal to GLPK 4.35.

Chapter 2: Installation

19

4. Trilinos: The Trilinos Project is an effort to develop and implement robust algorithms
and enabling technologies using modern object-oriented software design, while still leveraging the value of established libraries. It emphasizes abstract interfaces for maximum
flexibility of component interchanging, and provides a full-featured set of concrete classes
that implement all abstract interfaces [22, 21]. QUESO requires Trilinos release to be
newer than or equal to 11.0.0. Remark: An additional requirement for QUESO work
with Trilinos is that the latter must have enabled both Epetra and Teuchos libraries.
The majority of QUESO output files is MATLABr /GNU Octave compatible [17, 46].
Thus, for results visualization purposes, it is recommended that the user have available either
one of these tools.

2.1.2 Prepare your LINUX Environment
This section presents the steps to prepared the environment considering the user LINUX
environment runs a BASH-shell. For other types of shell, such as C-shell, some adaptations
may be required.
Before using QUESO, the user must first set a number of environmental variables, and
indicate the full path of the QUESO’s dependencies (GSL and Boost) and optional libraries.
For example, supposing the user wants to install QUESO with two additional libraries:
HDF5 and Trilinos. Add the following lines to append the location of QUESO’s dependencies
and optional libraries to the LD_LIBRARY_PATH environment variable:
$ export LD_LIBRARY_PATH = $LD_LIBRARY_PATH :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib /:\
$HOME / LIBRARIES / trilinos -11.2.4/ lib :

which can be placed in the user’s .bashrc or other startup file.
In addition, the user must set the following environmental variables:
$
$
$
$
$
$

export
export
export
export
export
export

CC = gcc
CXX = g ++
MPICC = mpicc
MPICXX = mpic ++
F77 = fort77
FC = gfortran

2.2 Obtaining a Copy of QUESO
The latest supported public release of QUESO is available in the form of a tarball (tar format
compressed with gzip) from QUESO Home Page: https://github.com/libqueso.

Chapter 2: Installation

20

Suppose you have copied the file ‘queso-0.47.1.tar.gz’ into $HOME/queso download/.
Then just follow these commands to expand the tarball:
$ cd $HOME / queso_download /
$ tar xvf queso -0.47.1. tar . gz
$ cd queso -0.47.1
#e n t e r t h e d i r e c t o r y

Naturally, for versions of QUESO other than 0.50.0, the file names in the above commands
must be adjusted.

2.2.1 Recommended Build Directory Structure
Via Autoconf and Automake, QUESO configuration facilities provide a great deal of flexibility
for configuring and building the existing QUESO packages. However, unless a user has prior
experience with Autotools, we strongly recommend the following process to build and maintain
local builds of QUESO (as an example, see note on Section 2.6). To start, we defined three
useful terms:
Source tree - The directory structure where the QUESO source files are located. A source
tree is is typically the result of expanding an QUESO distribution source code bundle,
such as a tarball.
Build tree - The tree where QUESO is built. It is always related to a specific source tree,
and it is the directory structure where object and library files are located. Specifically,
this is the tree where you invoke configure, make, etc. to build and install QUESO.
Installation tree - The tree where QUESO is installed. It is typically the prefix argument
given to QUESO’s configure script; it is the directory from which you run installed
QUESO executables.
Although it is possible to run ./configure from the source tree (in the directory where
the configure file is located), we recommend separate build trees. The greatest advantage to
having a separate build tree is that multiple builds of the library can be maintained from the
same source tree [22].

2.3 Configure QUESO Building Environment
QUESO uses the GNU Autoconf system for configuration, which detects various features of
the host system and creates Makefiles. The configuration process can be controlled through
environment variables, command-line switches, and host configuration files. For a complete
list of switches type:
$ ./ configure

-- help

Chapter 2: Installation

21

from the top level of the source tree (exemplified as $HOME/queso_download/queso-0.47.1
in this report).
This command will also display the help page for QUESO options. Many of the QUESO
configure options are used to describe the details of the build. For instance, to include HDF5,
a package that is not currently built by default, append --with-hdf5=DIR, where DIR is the
root directory of HDF5 installation, to the configure invocation line.
QUESO default installation location is ‘/usr/local’, which requires superuser privileges. To use a path other than ‘/usr/local’, specify the path with the ‘--prefix=PATH’
switch. For instance, to follow the suggestion given in Section 2.1, the user should append
‘--prefix=$HOME/LIBRARIES’.
Therefore, the basic steps to configure QUESO using Boost, GSL (required), HDF5 and
Trilinos (optional) for installation at ‘$HOME/LIBRARIES/QUESO-0.50.0’ are:
$

./ configure -- prefix = $HOME / LIBRARIES / QUESO -0.50.0 \
-- with - boost = $HOME / LIBRARIES / boost -1.53.0 \
-- with - gsl = $HOME / LIBRARIES / gsl -1.15 \
-- with - hdf5 = $HOME / LIBRARIES / hdf5 -1.8.10 \
-- with - trilinos = $HOME / LIBRARIES / trilinos -11.2.4

Note: the directory ‘$HOME/LIBRARIES/QUESO-0.50.0’ does not need to exist in advance,
since it will be created by the command make install described in Section 2.4.

2.4 Compile, Check and Install QUESO
In order to build, check and install the library, the user must enter the following three commands sequentially:
$ make
$ make check
$ make install

# optional

Here, make builds the library, confidence tests, and programs; make check conducts
various test suites in order to check the compiled source; and make install installs QUESO
library, include files, and support programs.
The files are installed under the installation tree (refer to Section 2.2.1), e.g. the directory
specified with ‘--prefix=DIR’ in Section 2.3. The directory, if not existing, will be created
automatically.
By running make check, several printouts appear in the screen and you should see messages
such as:
-------------------------------------------------------------------( rtest ) : PASSED : Test 1 ( TGA Validation Cycle )
--------------------------------------------------------------------

Chapter 2: Installation

22

The tests printed in the screen are tests under your QUESO build tree, i.e., they are
located at the directory $HOME/queso_download/queso-0.47.1/test (see Section 2.7 for the
complete list of the directories under QUESO build tree). These tests are used as part of
the periodic QUESO regression tests, conducted to ensure that more recent program/code
changes have not adversely affected existing features of the library.

2.5 QUESO Developer’s Documentation
QUESO code documentation is written using Doxygen [48], and can be generated by typing
in the build tree:
$ make docs

A directory named docs will be created in $HOME/queso_download/queso-0.47.1 (the
build tree; your current path) and you may access the code documentation in two different
ways:
1. HyperText Markup Language (HTML) format: docs/html/index.html, and the browser
of your choice can be used to walk through the HTML documentation.
2. Portable Document Format (PDF) format: docs/queso.pdf, which can be accessed
thought any PDF viewer.

2.6 Summary of Installation Steps
Supposing you have downloaded the file ‘queso-0.47.1.tar.gz’ into $HOME/queso download/.
In a BASH shell, the basic steps to configure QUESO using GRVY, Boost and GSL for
installation at ‘$HOME/LIBRARIES/QUESO-0.50.0’ are:
$ export LD_LIBRARY_PATH = $LD_LIBRARY_PATH :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib /:\
$HOME / LIBRARIES / trilinos -11.2.4/ lib :
$ export CC = gcc
$ export CXX = g ++
$ export MPICC = mpicc
$ export MPICXX = mpic ++
$ export F77 = fort77
$ export FC = gfortran
$ cd $HOME / queso_download /
#e n t e r s o u r c e d i r
$ gunzip < queso -0.47.1. tar . gz | tar xf $ cd $HOME / queso_download / queso -0.47.1
#e n t e r t h e b u i l d d i r
$ ./ configure -- prefix = $HOME / LIBRARIES / QUESO -0.50.0 \
-- with - boost = $HOME / LIBRARIES / boost -1.53.0 \

Chapter 2: Installation
-- with - gsl = $HOME / LIBRARIES / gsl -1.15 \
-- with - hdf5 = $HOME / LIBRARIES / hdf5 -1.8.10 \
-- with - trilinos = $HOME / LIBRARIES / trilinos -11.2.4
$ make
$ make check
$ make install
$ make docs
$ ls $HOME / LIBRARIES / QUESO -0.50.0 # l i s t i n g QUESO i n s t a l l a t i o n
>> bin include lib examples

23

dir

2.7 The Build Directory Structure
The QUESO build directory contains three main directories, src, examples and test. They
are listed below and more specific information about them can be obtained with the Developer’s documentation from Section 2.5 above.
1. src: this directory contains the QUESO library itself, and its main subdirectories are:
(a) basic/: contain classes for dealing with vector sets, subsets and spaces, scalar and
vector functions and scalar and vector sequences
(b) core/: contain classes that handle QUESO environment, and vector/matrix operations
(c) stats/: contain classes that implement vector realizers, vector random variables,
statistical inverse and forward problems; and the Monte Carlo and the MetropolisHasting solvers
Details of QUESO classes are presented in Chapter 3.
2. examples: examples of different applications, with distinct levels of difficulty, using
QUESO. The following examples have been thoroughly documented and are included in
Chapter 5:
(a) gravity/: inference of the acceleration of gravity via experiments and a solution
of a SIP; and forward propagation of uncertainty in the calculation of the distance
traveled by a projectile. It is presented in detail in Section 5.3.
(b) simpleStatisticalForwardProblem/: simplest example of how to use QUESO to
solve a SFP, described in detail in Section 5.2.
(c) simpleStatisticalInverseProblem/: simplest example of how to use QUESO to
solve a SIP, thoroughly described in Section 5.1.
(d) validationCycle/: presents a combination of SIP and SFP to solve a thermogravimetric analysis problem; this problem has the majority of its code in *.h files,
with templated routines. This example is described in Section 5.4.

Chapter 2: Installation

24

(e) validationCycle2/: also presents a combination of SIP and SFP to solve a thermogravimetric analysis problem; but the majority of its code is in *.C files.
All the examples presented in Chapter 5 come with the mathematical formulation, their
translation into code, the options input file required by QUESO and auxiliary Matlab
(GNU Octave compatible) files for data visualization.
The build directory contains only the source files. The executables are available under
the QUESO installation directory, together with example of Makefiles that may be used
to re-build the examples without the need of re-building the library.
3. test: a set of tests used as part of the periodic QUESO regression tests, conduct
to ensure that more recent program/code changes have not adversely affected existing
features of the library, as described in Section 2.4.
(a) gsl tests
(b) t01 valid cycle/
(c) t02 sip sfp/
(d) t03 sequence/
(e) t04 bimodal/
(f) test Environment/
(g) test GaussianVectorRVClass/
(h) test GslMatrix/
(i) test GslVector/
(j) test uqEnvironmentOptions/
These tests can optionally be called during QUESO installation steps by entering the
instruction: make check.

2.8 The Installed Directory Structure
After having successfully executed steps described in Sections 2.1–2.4, the QUESO installed
directory will contain four subdirectories:
1. bin: contains the executable queso_version, which provides information about the
installed library. The code bellow presents a sample output:
keme lli@ma rgarid a :~/ LIBRARIES / QUESO -0.50.0/ bin$ ./ queso_version
--------------------------------------------------------------QUESO Library : Version = 0.47.1 (47.1)
Development Build

Chapter 2: Installation

Build
Build
Build
Build
Build

Date
Host
User
Arch
Rev

C ++ Config

=
=
=
=
=

25

2013 -07 -12 12:36
margarida
kemelli
i686 - pc - linux - gnu
40392

= mpic ++ -g - O2 - Wall

Trilinos DIR = / home / kemelli / LIBRARIES / trilinos -11.2.4
GSL Libs
= -L / home / kemelli / LIBRARIES / gsl -1.15/ lib - lgsl - lgslcblas
- lm
GRVY DIR
=
GLPK DIR
=
HDF5 DIR
=
--------------------------------------------------------------keme lli@ma rgarid a :~/ LIBRARIES / QUESO -0.50.0/ bin$

2. lib: contains the static and dynamic versions of the library. The full to path to
this directory, e.g., $HOME/LIBRARIES/QUESO-0.50.0/lib should be added to the user’s
LD_LIBRARY_PATH environmental variable in order to use QUESO library with his/her
application code:
$ export LD_LIBRARY_PATH = $LD_LIBRARY_PATH :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib

Note that due to QUESO being compiled/built with other libraries (GSL, Boost, Trilinos
and HDF5), LD_LIBRARY_PATH had already some values set in Section 2.1.2.
3. include: contains the library .h files.
4. examples: contains the same examples of QUESO build directory, and listed in Section 2.7, together with their executables and Matlab files that may be used for visualization purposes. A selection of examples are described in details in Chapter 5; the user
is invited understand their formulation, to run them and understand their purpose.

2.9 Create your Application with the Installed QUESO
Prepare your environment by either running or saving the following command in your .bashrc
(supposing you have a BASH-shell):
$ export LD_LIBRARY_PATH = $LD_LIBRARY_PATH :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib

Chapter 2: Installation

26

Suppose your application code consists of the files: example_main.C, example_qoi.C,
example_likelihood.C, example_compute.C and respective .h files. Your application code
may be linked with QUESO library through a Makefile such as the one displayed as follows:
QUESO_DIR = $HOME / LIBRARIES / QUESO -0.50.0/
BOOST_DIR = $HOME / LIBRARIES / boost -1.53.0/
GSL_DIR = $HOME / LIBRARIES / gsl -1.15/
GRVY_DIR = $HOME / LIBRARIES / grvy -0.32.0
TRILINOS_DIR = $HOME / LIBRARIES / trilinos -11.2.4/
INC_PATHS = \
-I . \
- I$ ( QUESO_DIR ) / include \
- I$ ( BOOST_DIR ) / include / boost -1.53.0 \
- I$ ( GSL_DIR ) / include \
- I$ ( GRVY_DIR ) / include \
- I$ ( TRILINOS_DIR ) / include \
LIBS = \
- L$ ( QUESO_DIR ) / lib - lqueso \
- L$ ( BOOST_DIR ) / lib - l b o o st _ p r o g r a m _ o p t i o n s \
- L$ ( GSL_DIR ) / lib - lgsl \
- L$ ( GRVY_DIR ) / lib - lgrvy \
- L$ ( TRILINOS_DIR ) / lib - lteuchoscore - lteuchoscomm - lteuchosnumerics \
- l t e u c h o s p a r a m e t e r l i s t - lt euchos remain der - lepetra
CXX = mpic ++
CXXFLAGS += - O3 - Wall -c
default : all
. SUFFIXES : . o . C
all :

ex_gsl

clean :
rm -f *~
rm -f *. o
%
rm -f example_gsl
ex_gsl : example_main . o ex amp le _l ik el ih oo d . o example_qoi . o example_compute . o
$ ( CXX ) example_main . o e xam pl e_ li ke li ho od . o example_qoi . o \
example_compute . o -o example_gsl $ ( LIBS )
%. o : %. C
$ ( CXX ) $ ( INC_PATHS ) $ ( CXXFLAGS ) $ <

CHAPTER 3. C++ CLASSES IN THE LIBRARY

27

CHAPTER

3

C++ Classes in the Library

QUESO is is a parallel object-oriented statistical library dedicated to the research of statistically robust, scalable, load balanced, and fault-tolerant mathematical algorithms for the
quantification of uncertainty in realistic computational models and predictions related to natural and engineering systems.
Classes in QUESO can be divided in four main groups: core, templated basic, templated
statistical and miscellaneous. The classed that handle environment (and options), vector and
matrix classes are considered core classes. Classes implementing vector sets and subsets,
vector spaces, scalar functions, vector functions, scalar sequences and vector sequences are
templated basic classes; they are necessary for the definition and description of other entities,
such as RVs, Bayesian solutions of IPs, sampling algorithms and chains. Vector realizer, vector
RV, statistical IP (and options), MH solver (and options), statistical FP (and options), MC
solver (and options) and sequence statistical options are part of templated statistical classes.
And finally, the miscellaneous classes consist of C and FORTRAN interfaces.

3.1 Core Classes
QUESO core classes are the classes responsible for handling the environment (and options),
vector and matrix operations. They are described in the following sections.

3.1.1 Environment Class (and Options)
The Environment class sets up the environment underlying the use of the QUESO library by an
executable. This class is virtual. It is inherited by EmptyEnvironment and FullEnvironment.

Chapter 3: C++ Classes in the Library

28

The QUESO environment class is instantiated at the application level, right after
MPI_Init(&argc,&argv). The QUESO environment is required by reference by many constructors in the QUESO library, and is available by reference from many classes as well.
The constructor of the environment class requires a communicator, the name of an options
input file, and the eventual prefix of the environment in order for the proper options to be
read (multiple environments can coexist, as explained further below).
The environment class has four primary tasks:
1. Assigns rank numbers, other than the world rank, to nodes participating in a parallel
job,
2. Provides MPI communicators for generating a sequence of vectors in a distributed way,
3. Provides functionality to read options from the options input file (whose name is passed
in the constructor of this environment class), and
4. Opens output files for messages that would otherwise be written to the screen (one
output file per allowed rank is opened and allowed ranks can be specified through the
options input file).
Let S > 1 be the number of problems a QUESO environment will be handling at the same
time, in parallel. S has default value of 1 and is an option read by QUESO from the input file
provided by the user. The QUESO environment class manages five types of communicators,
referred to as:
1. world: MPI WORLD COMM;
2. full: communicator passed to the environment constructor, of size F and usually equal
to the world communicator;
3. sub: communicator of size F/S that contains the number of MPI nodes necessary to
solve a statistical IP or a statistical FP;
4. self: MPI SELF COMM, of size 1; and
5. inter0: communicator of size S formed by all MPI nodes that have subrank 0 in their
respective subcommunicators.
A subenvironment in QUESO is the smallest collection of processors necessary for the
proper run of the model code. An environment in QUESO is the collection of all subenvironments, if there is more than one subenvironment.
Each subenvironment is able to generate a statistical inverse problem and/or a statistical
forward problem; that is, each subenvironment is able to handle a “sub” Markov chain (a
sequence) of vectors and/or a “sub” Monte Carlo sequence of output vectors. The “sub”
sequences can be seen as forming a “unified” sequence in a distributed way. Indeed, the
virtual class VectorSequence provides “sub” and “unified” statistical operations.

Chapter 3: C++ Classes in the Library

29

Thus, if the model code requires 16 processors to run and the user decides to run 64
Markov chains in parallel, then the environment will consist of a total of F = 1024 processors
and S = 64 subenvironments, each subenvironment with F/S = 16 processors. Any given
computing node in a QUESO run has potentially five different ranks. Each subenvironment
is assigned a subid varying from 0 (zero) to S − 1, and is able to handle a statistical IP
and/or a statistical FP. That is, each subenvironment is able to handle a sub Markov chain
(a sequence) of vectors and/or a sub MC sequence of output vectors. The sub sequences form
an unified sequence in a distributed way. QUESO takes care of the unification of results for
the application programming and for output files. Of course, if the user is solving just one
statistical problem with just one MPI node, then all ranks are equal to zero.
A QUESO subenvironment eventually prints messages to its own output file. In order for
that to happen, the requirements are:
1. option m_subDisplayFileName, a string, must be different than the default value ".";
2. option m_subDisplayAllowedSet, a set of sub ids, must contain the id of the sub environment wanting to write a message to the output file;
3. the previous requirement is automatically satisfied if the option m_subDisplayAllowAll,
a boolean, is set to 1 (the default value is 0);
4. the processor wanting to write a message to the output file must have sub rank 0 (zero).
If all requirements are satisfied, then QUESO will generate a file with name
_sub.txt. For instance, if m_subDisplayFileName is
‘pROblem_775_’ then a node of sub rank 0 in sub environment 17 will write a message to
the file ‘pROblem_775_sub17.txt’. The class responsible for reading options one can pass to
a QUESO environment through an input file is the EnvironmentOptions class.
Figure 3.1.1 depicts class diagram for the environment class and Figure 3.1.2 display its
collaboration graph; and Figure 3.1.3 displays environment options class. Finally, the input
file options for a QUESO environment, i.e., the options the user may set in his/her input file
when using QUESO together with the application of interest, is presented in Table 3.1.1.

3.1.2 Vector
The Vector class handles all the vector operations carried out in QUESO, and currently has
two derived classes: GslVector and TeuchosVector. GslVector is based on the GSL vector
structure; whereas TeuchosVector is based on Trilinos Teuchos vector structure [22], and
therefore, it is only available if QUESO was compiled with Trilinos.
A class diagram for Vector class is presented in Figure 3.1.4.

3.1.3 Matrix
The Matrix class handles all the matrix operations carried out in QUESO. Analogously to
the vector class case described in the previous section, matrix class currently has two derived

Chapter 3: C++ Classes in the Library

30

QUESO::BaseEnvironment
# m_fullEnvIsReady
# m_worldRank
# m_fullComm
# m_fullRank
# m_fullCommSize
# m_fullGroup
# m_optionsInputFileName
# m_optionsInputFileAccessState
# m_allOptionsDesc
# m_allOptionsMap
and 17 more...
+ BaseEnvironment()
+ BaseEnvironment()
+ ~BaseEnvironment()
+ operator=()
+ fullEnvIsReady()
+ worldRank()
+ fullRank()
+ fullComm()
+ subGroup()
+ subRank()
+ subComm()
+ selfComm()
+ inter0Rank()
+ inter0Comm()
and 21 more...
+ openOutputFile()
+ openUnifiedOutputFile()
+ openInputFile()
+ openUnifiedInputFile()
+ closeFile()
+ setExceptionalCircumstance()
+ exceptionalCircumstance()
+ print()

QUESO::EmptyEnvironment

+ print()
+ EmptyEnvironment()
+ ~EmptyEnvironment()

QUESO::FullEnvironment

+ FullEnvironment()
+ ~FullEnvironment()
+ print()
- readOptionsInputFile()

Figure 3.1.1: The class diagram for the Environment class described in Section 3.1.1.

Chapter 3: C++ Classes in the Library

QUESO::EnvOptionsValues

QUESO::BasicPdfsBase

31

m_ov
m_alternativeOptionsValues
m_basicPdfs
m_rngObject

m_env
QUESO::BaseEnvironment

QUESO::EnvironmentOptions

m_optionsObj
m_env

QUESO::RngBase
m_inter0Comm
m_selfComm
m_subComm
m_fullComm

QUESO::MpiComm

Figure 3.1.2: Collaboration graph for the environment class described in Section 3.1.1.

QUESO::EnvironmentOptions
+ m_ov
- m_env
- m_prefix
- m_optionsDesc
- m_option_help
- m_option_numSubEnvironments
- m_option_subDisplayFileName
- m_option_subDisplayAllowAll
- m_option_subDisplayAllowInter0
- m_option_subDisplayAllowedSet
- m_option_displayVerbosity
and 5 more...
+ EnvironmentOptions()
+ EnvironmentOptions()
+ ~EnvironmentOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

Figure 3.1.3: The environment options class with its attributes and methods.
Table 3.1.1: Input file options for a QUESO environment.
Option name

Default value

〈PREFIX〉env help
〈PREFIX〉env numSubEnvironments
〈PREFIX〉env subDisplayFileName

1
"."

〈PREFIX〉env subDisplayAllowAll

0

〈PREFIX〉env
〈PREFIX〉env
〈PREFIX〉env
〈PREFIX〉env

""
0
0
0

subDisplayAllowedSet
displayVerbosity
syncVerbosity
seed

Description
Produces help message for environment class
Number of subenvironments
Output filename for sub-screen writing
Allows all subenvironments to write to output
file
Subenvironments that will write to output file
Sets verbosity
Sets syncronized verbosity
Set seed

Chapter 3: C++ Classes in the Library

32
QUESO::Vector
# m_env
# m_map
# m_printHorizontally
# m_printScientific
+ Vector()
+ Vector()
+ Vector()
+ ~Vector()
+ operator=()
+ operator*=()
+ operator/=()
+ operator+=()
+ operator-=()
+ env()
+ map()
+ numOfProcsForStorage()
+ sizeLocal()
+ sizeGlobal()
+ cwSet()
+ cwSetGaussian()
+ cwInvert()
+ sort()
+ print()
+ setPrintHorizontally()
+ getPrintHorizontally()
+ setPrintScientific()
+ getPrintScientific()
# copy()

QUESO::TeuchosVector
QUESO::GslVector
- m_vec
+ sort()
+ matlabDiff()
+ matlabLinearInterpExtrap()
+ mpiBcast()
+ mpiAllReduce()
+ mpiAllQuantile()
+ subWriteContents()
+ subReadContents()
+ data()
+ GslVector()
+ GslVector()
+ GslVector()
+ GslVector()
+ GslVector()
+ GslVector()
+ ~GslVector()
+ operator=()
+ operator*=()
+ operator/=()
+ operator*=()
+ operator/=()
+ operator+=()
+ operator-=()
+ cwSet()
+ cwSetGaussian()
+ cwSetGaussian()
and 9 more...
+ operator[]()
+ operator[]()
+ sizeLocal()
+ sizeGlobal()
+ getMaxValue()
+ getMinValue()
+ getMaxValueIndex()
+ getMinValueIndex()
+ getMaxValueAndIndex()
+ getMinValueAndIndex()
+ abs()
+ norm2Sq()
+ norm2()
+ norm1()
+ normInf()
+ sumOfComponents()
+ print()
+ atLeastOneComponentSmallerT han()
+ atLeastOneComponentBiggerT han()
+ atLeastOneComponentSmallerOrEqualT han()
+ atLeastOneComponentBiggerOrEqualT han()
- copy()

- m_vec
+ TeuchosVector()
+ TeuchosVector()
+ TeuchosVector()
+ TeuchosVector()
+ TeuchosVector()
+ TeuchosVector()
+ ~TeuchosVector()
+ operator=()
+ operator=()
+ operator*=()
+ operator/=()
+ operator*=()
+ operator/=()
+ operator+=()
+ operator-=()
+ cwSet()
+ cwSet()
and 9 more...
+ operator[]()
+ operator[]()
+ sizeLocal()
+ sizeGlobal()
+ values()
+ getMaxValue()
+ getMinValue()
+ getMaxValueIndex()
+ getMinValueIndex()
+ getMaxValueAndIndex()
+ getMinValueAndIndex()
+ norm2Sq()
+ norm2()
+ norm1()
+ normInf()
+ atLeastOneComponentSmallerT han()
+ atLeastOneComponentBiggerT han()
+ atLeastOneComponentSmallerOrEqualT han()
+ atLeastOneComponentBiggerOrEqualT han()
+ abs()
+ copy_to_std_vector()
+ copy_from_std_vector()
+ sort()
+ sumOfComponents()
+ mpiBcast()
+ mpiAllReduce()
+ mpiAllQuantile()
+ matlabLinearInterpExtrap()
+ matlabDiff()
+ print()
+ subReadContents()
+ subWriteContents()
- copy()

Figure 3.1.4: The class diagram for the vector class described in Section 3.1.2.

Chapter 3: C++ Classes in the Library

33

classes: GslMatrix and TeuchosMatrix. GslMatrix is based on the GSL matrix structure;
whereas TeuchosMatrix is based on Trilinos Epetra matrix structure.
A class diagram for Matrix is presented in Figure 3.1.5; it displays its protected attributes
together with its member functions. Again, the diagram displays in some detail the inherited
classes GslMatrix and TeuchosMatrix.

3.2 Templated Basic Classes
The classes in this group are: vector sets, subsets and spaces (Section 3.2.1), scalar and vector
function classes (Section 3.2.2), and scalar and vector sequences (Section 3.2.3).
These classes constitute the core entities necessary for the formal mathematical definition
and description of other entities, such as random variables, Bayesian solutions of inverse
problems, sampling algorithms and chains.

3.2.1 Vector Set, Subset and Vector Space Classes
The vector set class is fundamental for the proper handling of many mathematical entities.
Indeed, the definition of a scalar function such as π : B ⊂ Rn → R requires the specification
of the domain B, which is a subset of the vector space Rn , which is itself a set. Additionally,
SIPs need a likelihood routine πlike : Rn → R+ , and SFPs need a QoI routine q : Rn → Rm ;
the sets Rn , Rm , etc., are vector spaces.
The relationship amongst QUESO classes for handling sets, namely VectorSet; subsets,
namely VectorSubset; and vector spaces, namely VectorSpace is sketched in Figure 3.2.1.
An attribute of the subset class is the vector space which it belongs to, and in fact a reference
to a vector space is required by the constructor of the subset class. An example of this case
is the definition of a scalar function such as π : B ⊂ Rn → R above.
The power of an object-oriented design is clearly featured here. The intersection subset
derived class IntersectionSubset is useful for handling a posterior PDF on Equation (1.2.1),
since its domain is the intersection of the domain of the prior PDF with the domain of the
likelihood function.

3.2.2 Scalar Function and Vector Function Classes
Joint PDF, marginal PDF, and CDF are all examples of scalar functions present in statistical
problems. QUESO currently supports basic PDFs such as uniform and Gaussian and also more
complex PDFs, such as the ones coming from a Bayesian analysis. They are implemented in
the classes UniformJointPdf, GaussianJointPdf, and BayesianJointPdf, respectively. The
posterior PDF may be represented within QUESO by GenericJointPdf. See Diagram 3.2.2
for the scalar function class.
The handling of vector functions within QUESO is also quite straightforward. Indeed,
the definition of a vector function q : B ⊂ Rn → Rm requires only the extra specifi-

Chapter 3: C++ Classes in the Library

34
QUESO::Matrix
# m_env
# m_map
# m_printHorizontally
# m_inDebugMode
+ Matrix() (3)
+ ~Matrix()
+ operator=()
+ operator*=()
+ operator+=()
+ operator-=()
+ env()
+ map()
+ numOfProcsForStorage()
+ numRowsLocal()
+ numRowsGlobal()
+ numCols()
+ chol()
+ zeroLower()
+ zeroUpper()
+ print()
+ setPrintHorizontally()
+ getPrintHorizontally()
+ setInDebugMode()
+ getInDebugMode()
# copy()

QUESO::GslMatrix
- m_mat
- m_LU
- m_inverse
- m_svdColMap
- m_svdUmat
- m_svdSvec
- m_svdVmat
- m_svdVTmat
- m_determinant
- m_lnDeterminant
- m_permutation
- m_signum
- m_isSingular
+ GslMatrix() (6)
+ ~GslMatrix()
+ operator=()
+ operator*=()
+ operator/=()
+ operator+=()
+ operator-=()
+ operator()(v)
+ operator()()
+ numRowsLocal()
+ numRowsGlobal()
+ numCols()
+ max()
+ rank()
+ transpose()
+ inverse()
+ determinant()
+ lnDeterminant()
+ normFrob()
+ normMax()
+ chol()
+ svd()
+ svdMatU()
+ svdMatV()
+ svdSolve() (2)
+ multiply()
+ invertMultiply() (3)
and 11 more...
+ cwSet() (2)
+ cwExtract()
+ zeroLower()
+ zeroUpper()
+ filterSmallValues()
+ filterLargeValues()
+ fillWithTranspose()
+ fillWithBlocksDiagonally()
+ fillWithBlocksDiagonally()
and 5 more...
+ data()
+ mpiSum()
+ matlabLinearInterpExtrap()
+ print()
+ subWriteContents()
+ subReadContents()
- copy()
- resetLU()
- multiply()
- internalSvd()

QUESO::TeuchosMatrix
- m_mat
- m_LU
- m_inverse
- m_svdColMap
- m_svdUmat
- m_svdSvec
- m_svdVmat
- m_svdVTmat
- m_determinant
- m_lnDeterminant
- m_permutation
- v_pivoting
- m_signum
- m_isSingular
+ TeuchosMatrix() (6)
+ ~TeuchosMatrix()
+ operator=()
+ operator*=()
+ operator/=()
+ operator+=()
+ operator-=()
+ operator()()
+ operator()()
+ numRowsLocal()
+ numRowsGlobal()
+ numCols()
+ values()
+ stride()
+ max()
+ rank()
+ transpose()
+ inverse()
+ determinant()
+ lnDeterminant()
+ normFrob()
+ normMax()
+ chol()
+ svd()
+ svdMatU()
+ svdMatV()
+ svdSolve() (2)
+ multiply()
+ invertMultiply() (3)
and 5 more...
+ cwSet() (2)
+ getColumn() (2)
+ setColumn()
+ getRow() (2)
setRow()
+ zeroLower()
+ zeroUpper()
and 10 more...
+ mpiSum()
+ matlabLinearInterpExtrap()
+ print()
+ subReadContents()
+ subWriteContents()
- copy()
- resetLU()
- multiply()
- internalSvd()

Figure 3.1.5: The class diagram for the matrix class.

Chapter 3: C++ Classes in the Library

35

QUESO::VectorSet< V, M >
# m_env
# m_prefix
# m_volume
+
+
+
+
+
+
+
+

VectorSet()
VectorSet()
~VectorSet()
env()
prefix()
volume()
vectorSpace()
contains()

QUESO::VectorSpace< V, M >
# m_dimGlobal
# m_map
# m_dimLocal
# m_componentsNamesArray
# m_componentsNamesVec
# m_emptyComponentName
# m_zeroVector
+ newVector()
+ newVector()
+ newMatrix()
+ newDiagMatrix()
+ VectorSpace()
+ VectorSpace()
+ VectorSpace()
+ ~VectorSpace()
+ env()
+ map()
+ numOfProcsForStorage()
+ dimLocal()
+ dimGlobal()
+ globalIdOfFirstComponent()
+ zeroVector()
+ newVector()
+ newVector()
+ newVector()
+ newMatrix()
+ newDiagMatrix()
+ newDiagMatrix()
+ newProposalMatrix()
+ vectorSpace()
+ contains()
+ componentsNamesArray()
+ componentsNamesVec()
+ localComponentName()
+ printComponentsNames()
+ print()
# newMap()
# newMap()

QUESO::BoxSubset< V, M >
# m_minValues
# m_maxValues
+
+
+
+
+
+

print()
BoxSubset()
~BoxSubset()
contains()
minValues()
maxValues()

QUESO::VectorSubset< V, M >
# m_vectorSpace
+
+
+
+
+
+

VectorSubset()
VectorSubset()
~VectorSubset()
vectorSpace()
contains()
print()

QUESO::ConcatenationSubset< V, M >
# m_sets
+
+
+
+
+

ConcatenationSubset()
ConcatenationSubset()
~ConcatenationSubset()
contains()
print()

QUESO::DiscreteSubset< V, M >
# m_elements
+
+
+
+

DiscreteSubset()
~DiscreteSubset()
contains()
print()

QUESO::IntersectionSubset< V, M >
# m_set1
# m_set2
+
+
+
+

IntersectionSubset()
~IntersectionSubset()
contains()
print()

Figure 3.2.1: The class diagram for vector set, vector subset and vector space classes, described
in Section 3.2.1.

Chapter 3: C++ Classes in the Library

36

cation of the image vector space Rm . The classes representing the vector function class
GenericVectorFunction and ConstantVectorFunction are derived from BaseVectorFunction
and are presented in Diagram 3.2.3

QUESO::BayesianJointPdf< V, M >

QUESO::BetaJointPdf< V, M >

QUESO::ConcatenatedJointPdf< V, M >

QUESO::GammaJointPdf< V, M >
QUESO::BaseJointPdf< V, M >
# m_normalizationStyle
# m_logOfNormalizationFactor
+ BaseJointPdf()
+ ~BaseJointPdf()
+ actualValue()
+ lnValue()
+ setNormalizationStyle()
+ setLogOfNormalizationFactor()
+ computeLogOfNormalizationFactor()
# commonComputeLogOfNormalizationFactor()

+
+
+
+
+

QUESO::ConstantScalarFunction< V, M >
# m_constantValue

BaseScalarFunction()
~BaseScalarFunction()
domainSet()
actualValue()
lnValue()

QUESO::GenericJointPdf< V, M >

QUESO::InverseGammaJointPdf< V, M >

QUESO::LogNormalJointPdf< V, M >

QUESO::BaseScalarFunction< V, M >
# m_env
# m_prefix
# m_domainSet

QUESO::GaussianJointPdf< V, M >

+
+
+
+

QUESO::PoweredJointPdf< V, M >

ConstantScalarFunction()
~ConstantScalarFunction()
actualValue()
lnValue()

QUESO::UniformJointPdf< V, M >

QUESO::WignerJointPdf< V, M >
QUESO::GenericScalarFunction< V, M >
# m_valueRoutinePtr
# m_routinesDataPtr
# m_routineIsForLn
+
+
+
+

GenericScalarFunction()
~GenericScalarFunction()
actualValue()
lnValue()

Figure 3.2.2: The class diagram for the scalar function class.

3.2.3 Scalar Sequence and Vector Sequence Classes
The scalar sequence class contemplates scalar samples generated by an algorithm, as well as
operations that can be done over them, e.g., calculation of means, variances, and convergence
indices. Similarly, the vector sequence class contemplates vector samples and operations such
as means, correlation matrices and covariance matrices.
Figures 3.2.4 and 3.2.5 display the class diagram for the scalar sequence and vector sequence
classes, respectively.

Chapter 3: C++ Classes in the Library

37

QUESO::BaseVectorFunction< P_V, P_M, Q_V, Q_M >
# m_env
# m_prefix
# m_domainSet
# m_imageSet
+
+
+
+
+

BaseVectorFunction()
~BaseVectorFunction()
domainSet()
imageSet()
compute()

QUESO::ConstantVectorFunction< P_V, P_M, Q_V, Q_M >
# m_constantImageVector
+ ConstantVectorFunction()
+ ~ConstantVectorFunction()
+ compute()

QUESO::GenericVectorFunction< P_V, P_M, Q_V, Q_M >
# m_routinePtr
# m_routineDataPtr
+ GenericVectorFunction()
+ ~GenericVectorFunction()
+ compute()

Figure 3.2.3: The class diagram for the vector function class described in Section 3.2.2.

QUESO::ScalarSequence< T >
- m_env
- m_name
- m_seq
- m_subMinPlain
- m_unifiedMinPlain
- m_subMaxPlain
- m_unifiedMaxPlain
- m_subMeanPlain
- m_unifiedMeanPlain
- m_subMedianPlain
- m_unifiedMedianPlain
- m_subSampleVariancePlain
- m_unifiedSampleVariancePlain
+ ScalarSequence()
+ ~ScalarSequence()
+ operator=()
+ operator[]()
+ operator[]()
+ env()
+ name()
+ setName()
+ clear()
+ subSequenceSize()
+ unifiedSequenceSize()
+ resizeSequence()
+ resetValues()
+ erasePositions()
+ getUnifiedContentsAtProc0Only()
and 55 more...- copy()
- extractScalarSeq()
- extractRawData()
- rawData()
- subSort()
- parallelMerge()
and 55 more...

Figure 3.2.4: The class diagram for the scalar sequence class.

Chapter 3: C++ Classes in the Library

38

QUESO::BaseVectorSequence< V, M >
# m_env
# m_vectorSpace
# m_name
# m_fftObj
# m_subMinPlain
# m_unifiedMinPlain
# m_subMaxPlain
# m_unifiedMaxPlain
# m_subMeanPlain
# m_unifiedMeanPlain
and 5 more...
+ BaseVectorSequence()
+ ~BaseVectorSequence()
+ subSequenceSize()
+ unifiedSequenceSize()
+ vectorSizeLocal()
+ vectorSizeGlobal()
+ vectorSpace()
+ name()
+ setName()
+ clear()
+ subMinPlain()
+ unifiedMinPlain()
and 51 more...
# copy()
# extractRawData()

QUESO::ArrayOfSequences< V, M >
- m_scalarSequences
+ ArrayOfSequences()
+ ~ArrayOfSequences()
+ subSequenceSize()
+ resizeSequence()
+ resetValues()
+ erasePositions()
+ getPositionValues()
+ setPositionValues()
+ setGaussian()
+ setUniform()
+ mean()
+ unifiedMean()
and 19 more...
- extractRawData()

QUESO::SequenceOfVectors< V, M >
- m_seq
+ SequenceOfVectors()
+ ~SequenceOfVectors()
+ operator=()
+ subSequenceSize()
+ resizeSequence()
+ resetValues()
+ erasePositions()
+ getPositionValues()
+ setPositionValues()
+ subUniformlySampledCdf()
+ unifiedUniformlySampledCdf()
+ subMeanExtra()
+ unifiedMeanExtra()
and 30 more...
- copy()
- extractRawData()

Figure 3.2.5: The class diagram for the vector sequence class.

Chapter 3: C++ Classes in the Library

39

3.3 Templated Statistical Classes
The classes in this group are: vector realizer, vector random variable, statistical inverse problem (and options), Metropolis-Hastings solver (and options), statistical forward problem (and
options), Monte Carlo solver (and options), and Sequence statistical options.
For QUESO, a SIP has two input entities, a prior RV and a likelihood routine, and one
output entity, the posterior RV, as shown in Chapter 1, Figure 1.2.3. Similarly, a SFP has
two input entities, a input RV and a QoI routine, and one output entity, the output RV, as
shown in Figure 1.2.2.

3.3.1 Vector Realizer Class
A realizer is an object that, simply put, contains a realization() operation that returns a
sample of a vector RV. QUESO currently supports several realizers:
• uniform, implemented in UniformVectorRealizer,
• Gaussian, implemented in GaussianVectorRealizer,
• Log Normal, implemented in LogNormalVectorRealizer,
• Gamma, implemented in GammaVectorRealizer,
• Inverse Gamma, implemented in InverseGammaVectorRealizer, and
• Beta, , implemented in BetaVectorRealizer,
which are all derived from the base class BaseVectorRealizer.
QUESO conveniently provides the class ConcatenatedVectorRealizer, which allows two
distinct realizers to be concatenated. It also contains a sequence realizer class for storing
samples of a MH algorithm.

3.3.2 Vector Random Variable Class
Vector RVs are expected to have two basic functionalities: compute the value of its PDF
at a point, and generate realizations following such PDF. The joint PDF (BaseJointPdf
and derived classes, see Section 3.2.2) and vector realizer (BaseVectorRealizer and derived
classes, see Section 3.3.1) classes allow a straightforward definition and manipulation of vector
RVs. Similarly to the vector realizer class above, QUESO also allows users to form new RVs
through the concatenation of existing RVs (class ConcatenatedVectorRV).
QUESO currently supports a few vector RVs such as uniform, Gaussian, Gamma and Beta,
as depicted in Diagram 3.3.1. A derived class called generic vector RV allows QUESO to store
the solution of an statistical IP: a Bayesian joint PDF becomes the PDF of the posterior RV,
while a sequence vector realizer becomes the realizer of the same posterior RV.

Chapter 3: C++ Classes in the Library

40

QUESO::BetaVectorRV< V, M >

QUESO::BaseVectorRV< V, M >
# m_env
# m_prefix
# m_imageSet
# m_pdf
# m_realizer
# m_subCdf
# m_unifiedCdf
# m_mdf
+
+
+
+
+
+
+
+
+
+

BaseVectorRV()
~BaseVectorRV()
env()
imageSet()
pdf()
realizer()
subCdf()
unifiedCdf()
mdf()
print()

QUESO::ConcatenatedVectorRV< V, M >

QUESO::GammaVectorRV< V, M >

QUESO::GaussianVectorRV< V, M >

QUESO::GenericVectorRV< V, M >

QUESO::InverseGammaVectorRV< V, M >

QUESO::LogNormalVectorRV< V, M >

QUESO::UniformVectorRV< V, M >

QUESO::WignerVectorRV< V, M >

Figure 3.3.1: The class diagram for the vector random variable class.

3.3.3 Statistical Inverse Problem (and Options)
Similarly to its mathematical concepts, a SIP in QUESO also expects two input entities, a prior
RV and a likelihood routine, and one output entity, the posterior RV. The SIP is represented
in QUESO through the templated class StatisticalInverseProblem, which is
illustrated in Figure 3.3.2a. One important characteristic of the QUESO design is that it
separates ‘what the problem is’ from ‘how the problem is solved’. The prior and the posterior
RV are instances of the BaseVectorRv class, while the likelihood function is an instance
of the BaseScalarFunction class.
The solution of a SIP is computed by calling either solveWithBayesMetropolisHastings()
or solveWithBayesMLSampling(), which are member functions of the class
StatisticalInverseProblem class. Upon return from a solution operation, the
posterior RV is available through the postRv() member function. More details are provided
about solveWithBayesMetropolisHastings() and solveWithBayesMLSampling() in Sections 3.3.4 and 3.3.5, respectively.
Figure 3.3.2b displays the StatisticalInverseProblemOptions class, i.e. that class that
handles a variety of options for solving the SIP. Such options may be provided to QUESO by
the user’s input file; and they are listed in Table 3.3.1.

Chapter 3: C++ Classes in the Library

41

QUESO::StatisticalInverseProblem< P_V, P_M >
- m_env
- m_priorRv
- m_likelihoodFunction
- m_postRv
- m_solutionDomain
- m_solutionPdf
- m_subSolutionMdf
- m_subSolutionCdf
- m_solutionRealizer
- m_mhSeqGenerator
and 5 more...
+
+
+
+
+
+
+
+
+
+
+

QUESO::StatisticalInverseProblemOptions
+ m_ov
+ m_prefix
- m_env
- m_optionsDesc
- m_option_help
- m_option_computeSolution
- m_option_dataOutputFileName
- m_option_dataOutputAllowedSet

StatisticalInverseProblem()
~StatisticalInverseProblem()
computeSolutionFlag()
solveWithBayesMetropolisHastings()
solveWithBayesMLSampling()
priorRv()
postRv()
logEvidence()
meanLogLikelihood()
eig()
print()

+ StatisticalInverseProblemOptions()
+ StatisticalInverseProblemOptions()
+ ~StatisticalInverseProblemOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

(a) StatisticalInverseProblem

(b) StatisticalInverseProblemOptions

Figure 3.3.2: The statistical inverse problem class, which implements the representation in
Figure 1.2.3, and statistical inverse problem options class.

Table 3.3.1: Input file options for a QUESO statistical inverse problem.
Option name

Default Value

〈PREFIX〉ip help
〈PREFIX〉ip computeSolution
〈PREFIX〉ip dataOutputFileName

1
"."

〈PREFIX〉ip dataOutputAllowedSet

""

Description
Produces help message for statistical inverse
problem
Computes solution process
Name of data output file
Subenvironments that will write to data output file

Chapter 3: C++ Classes in the Library

42

3.3.4 Metropolis-Hastings Solver (and Options)
The templated class that represents a Metropolis-Hastings generator of samples in QUESO
is MetropolisHastingsSG, where SG stands for ’Sequence Generator’. This class
implements the DRAM algorithm of Haario, Laine, Mira and Saksman [18] together with an
operation named generateSequence() based on the core routine at the MCMC toolbox for
MATLAB [30].
The Metropolis-Hastings sequence generator class is depicted in Figure 3.3.3a; the MetropolisHastings sequence generator options class is depicted in Figure 3.3.3b. A collaboration graph
for the Metropolis-Hastings class is presented in Figure 3.3.4; and the options are presented
in Table 3.3.2.

QUESO::MetropolisHastingsSG< P_V, P_M >
- m_env
- m_vectorSpace
- m_targetPdf
- m_initialPosition
- m_initialProposalCovMatrix
- m_nullInputProposalCovMatrix
- m_targetPdfSynchronizer
- m_tk
- m_positionIdForDebugging
- m_stageIdForDebugging
and 9 more...
+ MetropolisHastingsSG()
+ MetropolisHastingsSG()
+ ~MetropolisHastingsSG()
+ generateSequence()
+ getRawChainInfo()
+ print()
- commonConstructor()
- generateFullChain()
- readFullChain()
- updateAdaptedCovMatrix()
- alpha()
- alpha()
- acceptAlpha()
- writeInfo()

(a) MetropolisHastingsSG

QUESO::MetropolisHastingsSGOptions
+ m_ov
+ m_prefix
- m_env
- m_optionsDesc
- m_option_help
- m_option_dataOutputFileName
- m_option_dataOutputAllowAll
- m_option_dataOutputAllowedSet
- m_option_totallyMute
- m_option_initialPosition_dataInputFileName
- m_option_initialPosition_dataInputFileT ype
- m_option_initialProposalCovMatrix_dataInputFileName
and 37 more...
+ MetropolisHastingsSGOptions()
+ MetropolisHastingsSGOptions()
+ MetropolisHastingsSGOptions()
+ ~MetropolisHastingsSGOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

(b) MetropolisHastingsSGOptions

Figure 3.3.3: The Metropolis-Hastings sequence generator class and the Metropolis-Hastings
sequence generator options class.

3.3.5 Multilevel Solver (and Options)
The templated class that represents a Multilevel generator of samples in QUESO is
MLSampling. This class implements the Adaptive Multilevel Stochastic Simulation
Algorithm of Cheung and Prudencio [8]. The Multilevel sequence generator class is assisted
by two extra classes, MLSamplingOptions and MLSamplingLevelOptions, for handling the
options to be used.
The Multilevel class, the Multilevel options and level options classes are depicted in Figure 3.3.5. A collaboration graph for the Multilevel class is presented in Figure 3.3.6; whereas
its associated options are presented in Table 3.3.3.

QUESO::EnvironmentOptions

m_optionsObj

m_ov

m_env

m_env

QUESO::EnvOptionsValues

m_domainSet

QUESO::VectorSet< P_V, P_M >

m_targetPdfSynchronizer

m_bayesianJointPdfPtr

QUESO::BayesianJointPdf< P_V, P_M >

m_likelihoodFunction m_priorDensity

QUESO::BaseJointPdf< P_V, P_M >

QUESO::BaseScalarFunction< P_V,P_M >

QUESO::ScalarFunctionSynchronizer< P_V, P_M >

m_scalarFunction

QUESO::BaseScalarFunction< P_V, P_M >

m_env

m_env

m_env

m_targetPdf

m_MpiComm

m_map

m_vectorSpace

QUESO::VectorSpace< P_V, P_M >

m_componentsNamesVec
m_componentsNamesArray

m_env

m_env

m_emptyEnv

QUESO::EmptyEnvironment

m_env

m_ov

m_optionsObj

QUESO::MHRawChainInfoStruct
m_rawChainInfo

m_alternativeOptionsValues

QUESO::MhOptionsValues

QUESO::MetropolisHastingsSGOptions

m_env

QUESO::MetropolisHastingsSG< P_V, P_M >

m_tk

QUESO::BaseT KGroup< P_V, P_M >

m_vectorSpace

QUESO::VectorSet< P_V,P_M >

QUESO::Map

m_Map

QUESO::DistArray< std::string >

QUESO::BaseJointPdf< P_V,P_M >

m_env

QUESO::MpiComm

m_inter0Comm
m_selfComm
m_subComm
m_fullComm

QUESO::BaseScalarFunction< V, M >

m_env

QUESO::BaseEnvironment

m_rngObject

QUESO::RngBase

m_basicPdfs

QUESO::BasicPdfsBase
m_alternativeOptionsValues

Chapter 3: C++ Classes in the Library
43

Figure 3.3.4: Collaboration graph of the Metropolis-Hastings sequence generator class.

Chapter 3: C++ Classes in the Library

44

Table 3.3.2: Input file options for a QUESO Metropolis-Hastings solver.
Option Name
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh
〈PREFIX〉mh

dataOutputFileName
dataOutputAllowAll
initialPositionDataInputFileName
initialPositionDataInputFileType
initialProposalCovMatrixDataInputFileName
initialProposalCovMatrixDataInputFileType
rawChainDataInputFileName
rawChainDataInputFileType
rawChainSize
rawChainGenerateExtra
rawChainDisplayPeriod
rawChainMeasureRunTimes
rawChainDataOutputPeriod
rawChainDataOutputFileName
rawChainDataOutputFileType
rawChainDataOutputAllowAll
filteredChainGenerate
filteredChainDiscardedPortion
filteredChainLag
filteredChainDataOutputFileName
filteredChainDataOutputFileType
filteredChainDataOutputAllowAll
displayCandidates
putOutOfBoundsInChain
tkUseLocalHessian
tkUseNewtonComponent
drMaxNumExtraStages
drDuringAmNonAdaptiveInt
amKeepInitialMatrix
amInitialNonAdaptInterval
amAdaptInterval
amAdaptedMatricesDataOutputPeriod
amAdaptedMatricesDataOutputFileName
amAdaptedMatricesDataOutputFileType
amAdaptedMatricesDataOutputAllowAll
amEta
amEpsilon
enableBrooksGelmanConvMonitor
BrooksGelmanLag

Default Value
"."
0
"."
"m"
"."
"m"
"."
"m"
100
0
500
1
0
"."
"m"
0
0
0.
1
"."
"m"
0
0
1
0
1
0
1
0
0
0
0
"."
"m"
0
1.
1 × 10−5
0
100

Chapter 3: C++ Classes in the Library

45

QUESO::MLSampling< P_V, P_M >
- m_env
- m_priorRv
- m_likelihoodFunction
- m_vectorSpace
- m_targetDomain
- m_options
- m_currLevel
- m_currStep
- m_debugExponent
- m_logEvidenceFactors
- m_logEvidence
- m_meanLogLikelihood
- m_eig
+ MLSampling()
+ ~MLSampling()
+ generateSequence()
+ logEvidence()
+ meanLogLikelihood()
+ eig()
+ print()
- checkpointML()
- restartML()
- generateSequence_Level0_all()
- generateSequence_Step01_inter0()
- generateSequence_Step02_inter0()
- generateSequence_Step03_inter0()
- generateSequence_Step04_inter0()
- generateSequence_Step05_inter0()
- generateSequence_Step06_all()
- generateSequence_Step07_inter0()
and 11 more...

(a) MLSampling

QUESO::MLSamplingLevelOptions

QUESO::MLSamplingOptions
+ m_prefix
+ m_restartInputFileName
+ m_restartInputFileT ype
+ m_restartChainSize
+ m_dataOutputFileName
+ m_dataOutputAllowAll
+ m_dataOutputAllowedSet
- m_env
- m_optionsDesc
- m_option_help
- m_option_restartInputFileName
- m_option_restartInputFileT ype
- m_option_restartChainSize
- m_option_dataOutputFileName
- m_option_dataOutputAllowAll
- m_option_dataOutputAllowedSet
+ MLSamplingOptions()
+ ~MLSamplingOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

(b) MLSamplingOptions

+ m_prefix
+ m_checkpointOutputFileName
+ m_stopAtEnd
+ m_dataOutputFileName
+ m_dataOutputAllowAll
+ m_dataOutputAllowedSet
+ m_str1
+ m_loadBalanceAlgorithmId
+ m_loadBalanceTreshold
+ m_minEffectiveSizeRatio
and 49 more...
- m_env
- m_optionsDesc
- m_option_help
- m_option_checkpointOutputFileName
- m_option_stopAtEnd
- m_option_dataOutputFileName
- m_option_dataOutputAllowAll
- m_option_dataOutputAllowedSet
- m_option_loadBalanceAlgorithmId
- m_option_loadBalanceTreshold
and 46 more...
+ MLSamplingLevelOptions()
+ ~MLSamplingLevelOptions()
+ env()
+ scanOptionsValues()
+ print()
- copyOptionsValues()
- defineMyOptions()
- getMyOptionValues()

(c) MLSamplingLevelOptions

Figure 3.3.5: The Multilevel sequence generator options class (3.3.5a) and its associated classes
for handling options.

m_domainSet

m_env

m_options

QUESO::MLSamplingOptions

m_likelihoodFunction

QUESO::BaseScalarFunction< P_V, P_M >

m_env

m_pdfSupport

QUESO::MLSampling< P_V, P_M >

m_targetDomain

m_unifiedCdf
m_subCdf

m_domainSet

QUESO::BaseVectorRV

m_realizer

m_env

m_env

m_vectorSpace

m_pdf

QUESO::BaseJointPdf< P_V, P_M >

QUESO::BaseScalarFunction< P_V,P_M >

QUESO::BaseVectorMdf

m_env

m_mdf

m_env

QUESO::BaseVectorRealizer< P_V, P_M >

m_priorRv

m_imageSet

m_unifiedImageSet

QUESO::VectorSet< P_V, P_M >

QUESO::BaseVectorCdf

m_env

m_env

QUESO::VectorSpace< P_V, P_M >

m_map

m_env

m_componentsNamesVec
m_componentsNamesArray

QUESO::DistArray< std::string >

m_Map

m_MpiComm

QUESO::EnvironmentOptions

m_optionsObj

QUESO::Map

m_env

QUESO::MpiComm

m_inter0Comm
m_selfComm
m_subComm
m_fullComm

QUESO::EnvOptionsValues
m_alternativeOptionsValues

QUESO::VectorSet< P_V,P_M >

m_env

QUESO::BaseEnvironment

m_basicPdfs

QUESO::BasicPdfsBase

m_rngObject

QUESO::RngBase

m_env

m_ov

Chapter 3: C++ Classes in the Library
46

Figure 3.3.6: Collaboration graph of the Multilevel sampling class.

Chapter 3: C++ Classes in the Library

47

Table 3.3.3: Input file options for a QUESO Multilevel solver (to be continued).
Option Name
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml
〈PREFIX〉ml

restartOutput levelPeriod
restartOutput baseNameForFiles
restartOutput fileType
restartInput baseNameForFiles
restartInput fileType
stopAtEnd
dataOutputFileName
dataOutputAllowAll
loadBalanceAlgorithmId
loadBalanceTreshold
minEffectiveSizeRatio
maxEffectiveSizeRatio
scaleCovMatrix
minRejectionRate
maxRejectionRate
covRejectionRate
minAcceptableEta
totallyMute
initialPositionDataInputFileName
initialPositionDataInputFileType
initialProposalCovMatrixDataInputFileName
initialProposalCovMatrixDataInputFileType
rawChainDataInputFileName
rawChainDataInputFileType
rawChainSize
rawChainGenerateExtra
rawChainDisplayPeriod
rawChainMeasureRunTimes
rawChainDataOutputPeriod
rawChainDataOutputFileName
rawChainDataOutputFileType
rawChainDataOutputAllowAll
filteredChainGenerate
filteredChainDiscardedPortion
filteredChainLag
filteredChainDataOutputFileName
filteredChainDataOutputFileType
filteredChainDataOutputAllowAll
displayCandidates
putOutOfBoundsInChain
tkUseLocalHessian
tkUseNewtonComponent
drMaxNumExtraStages
drScalesForExtraStages
drDuringAmNonAdaptiveInt
amKeepInitialMatrix
amInitialNonAdaptInterval
amAdaptInterval
amAdaptedMatricesDataOutputPeriod
amAdaptedMatricesDataOutputFileName
amAdaptedMatricesDataOutputFileType
amAdaptedMatricesDataOutputAllowAll
amEta
amEpsilon

Default Value
0
"."
"m"
"."
"m"
0
"."
0
2
1.0
0.85
0.91
1
0.50
0.75
0.25
0.
1
"."
"m"
"."
"m"
"."
"m"
100
0
500
1
0
"."
"m"
0
0
0.
1
"."
"m"
0
0
1
0
1
0
0
1
0
0
0
0
"."
"m"
0
1.
1.e-5

Chapter 3: C++ Classes in the Library

48

3.3.6 Statistical Forward Problem (and Options)
A SFP in QUESO also has two input entities, the input (parameter) RV and a QoI function, and one output entity, the QoI RV. The SIP is represented through the templated
class StatisticalForwardProblem, which diagram is presented in Figure 3.3.7a. Again, the types P_V and Q_V of vectors and types P_M and Q_M of matrices, where
P_ stands for ’parameter’ and Q_ stands for ’quantities of interest’.
The input RV and the output QoI RV are instances of the BaseVectorRv class,
while the QoI function is an instance of BaseVectorFunction. In the
template parameters, the prefix P_ refers to the parameters, whereas the prefix Q_ refers to
the QoIs.
In order to find the solution of a SFP, one must call the solveWithMonteCarlo() member
function of the StatisticalForwardProblem class. Upon return from a solution
operation, the QoI RV is available through the qoiRv() member function. Such QoI RV is able
to provide: a vector realizer through the operation ’qoiRv().realizer()’, which returns an
instance of the class ’uqBaseVectorRealizer’.
Figure 3.3.7b displays the statistical forward problem options class, i.e. that class that
handles a variety of options for solving the SFP. Such options may be provided to QUESO at
the user’s input file; and they are listed in Table 3.3.4. In the table, p-q stands for parameter–
quantity of interest.
Table 3.3.4: Input file options for a QUESO statistical forward problem.
Option Name
〈PREFIX〉fp
〈PREFIX〉fp
〈PREFIX〉fp
〈PREFIX〉fp

computeSolution
computeCovariances
computeCorrelations
dataOutputFileName

〈PREFIX〉fp dataOutputAllowedSet

Default Value
1
1
1
"."
""

Description
Computes the solution process
Compute p-q covariances
Compute p-q correlations
Name of data output file
Subenvironments that will write to data
output file

3.3.7 Monte Carlo Solver (and Options)
The templated class that implements a Monte Carlo generator of samples within QUESO
is MonteCarloSG, as illustrated in Figure 3.3.8a. This class has the requirement that the image set of the vector random variable and the domain set of the QoI
function belong to vector spaces of equal dimensions. If the requirements are satisfied, the class
constructor reads input options that begin with the string ‘_mc_’ (See Table 3.3.5).
Options reading is handled by class MonteCarloOptions, which is illustrated in Figure 3.3.8b.

Chapter 3: C++ Classes in the Library

49

QUESO::StatisticalForwardProblem< P_V, P_M, Q_V, Q_M >
- m_env
- m_paramRv
- m_qoiFunction
- m_qoiRv
- m_paramChain
- m_qoiChain
- m_mcSeqGenerator
- m_solutionRealizer
- m_solutionPdf
- m_alternativeOptionsValues
- m_optionsObj
+ StatisticalForwardProblem()
+ ~StatisticalForwardProblem()
+ computeSolutionFlag()
+ solveWithMonteCarlo()
+ qoiRv()
+ getParamChain()
+ print()
- commonConstructor()

(a) StatisticalForwardProblem

QUESO::StatisticalForwardProblemOptions
+ m_ov
+ m_prefix
- m_env
- m_optionsDesc
- m_option_help
- m_option_computeSolution
- m_option_computeCovariances
- m_option_computeCorrelations
- m_option_dataOutputFileName
- m_option_dataOutputAllowedSet
+ StatisticalForwardProblemOptions()
+ StatisticalForwardProblemOptions()
+ ~StatisticalForwardProblemOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

(b) StatisticalForwardProblemOptions

Figure 3.3.7: The statistical forward problem class, which implements the representation in
Figure 1.2.2, and the statistical forward problem options class.

QUESO::MonteCarloSGOptions

- m_env
- m_paramRv
- m_qoiFunction
- m_paramSpace
- m_qoiSpace
- m_qoiFunctionSynchronizer
- m_numPsNotSubWritten
- m_numQsNotSubWritten
- m_alternativeOptionsValues
- m_optionsObj

+ m_ov
+ m_prefix
- m_env
- m_optionsDesc
- m_option_help
- m_option_dataOutputFileName
- m_option_dataOutputAllowedSet
- m_option_pseq_dataOutputPeriod
- m_option_pseq_dataOutputFileName
- m_option_pseq_dataOutputFileT ype
- m_option_pseq_dataOutputAllowedSet
- m_option_qseq_dataInputFileName
and 7 more...

+ MonteCarloSG()
+ ~MonteCarloSG()
+ generateSequence()
+ print()
- internGenerateSequence()
- actualGenerateSequence()
- actualReadSequence()

+ MonteCarloSGOptions()
+ MonteCarloSGOptions()
+ ~MonteCarloSGOptions()
+ scanOptionsValues()
+ print()
- defineMyOptions()
- getMyOptionValues()

QUESO::MonteCarloSG< P_V, P_M, Q_V, Q_M >

(a) MonteCarloSG

(b) MonteCarloSGOptions

Figure 3.3.8: The Monte Carlo sequence generator class and the Monte Carlo sequence generator options class.

Chapter 3: C++ Classes in the Library

50

Table 3.3.5: Input file options for a QUESO statistical forward problem solved via Monte
Carlo algorithm.
Option Name
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc
〈PREFIX〉mc

dataOutputFileName
dataOutputAllowedSet
pseq dataOutputFileName
pseq dataOutputAllowedSet
qseq dataInputFileName
qseq size
qseq displayPeriod
qseq measureRunTimes
qseq dataOutputFileName
qseq dataOutputAllowedSet

Default Value
"."
"."
"."
100
500
0
"."

3.4 Miscellaneous Classes and Routines
As the name suggests, QUESO miscellaneous classes and routines have a variety of routines.
For instance, the function MiscReadDoublesFromString is used for reading the options input files and assigning the values to the respective variables, in uqMonteCarloSGOptions::
getMyOptionValues and in MetropolisHastingsSGOptions::getMyOptionValues.
QUESO class BaseOneDGrid generates grids necessary for calculating the CDF of a RV; it is
required by class ArrayOfOneDGrids, which, in turn, is used in both classes:
StatisticalForwardProblem and StatisticalInverseProblem.

CHAPTER

4

Important Remarks

At this point, the user may feel comfortable and ready to start his/her validation and calibration exercises using QUESO. There are, however, a few quite important remarks that will
make the linkage of the QUESO Library with the user application code possible. They are
addressed in the following sections.

4.1 Revisiting Input Options
Input options are read from the QUESO input file, whose name is required by the constructor
of the QUESO environment class. Herein, suppose that no prefix is defined, i.e., nothing
will precede the input variables names (PREFIX = "" in Tables 3.1.1 – 3.3.5). An example
of the use of prefixes may be found in the input file tgaCycle.inp under the subdirectory
/examples/validationCycle/ of QUESO installation tree.
The first part of a input file commonly handles the environment options. he variable assignment env_numSubEnvironments = 1 indicates to QUESO that only one subenvironment
should be used. The variable assignment env subDisplayFileName = outputData/ display
create both the subdirectory outputData/ and a file named display_sub0.txt that contains
all the options listed in the input file together with more specific information, such as the
chain run time and the number of delayed rejections. The existence of file display_sub0.txt
allows, for instance, the user in verifying the actual parameters read by QUESO.
For an SIP, the user may set up variables related to the DRAM algorithm. Six important variables are: ip mh dr maxNumExtraStages defines how many extra candidates will be
generated; ip mh dr listOfScalesForExtraStages defines the list s of scaling factors that
will multiply the covariance matrix. The variable ip mh am initialNonAdaptInterval de51

CHAPTER 4. IMPORTANT REMARKS

52

fines the initial interval in which the proposal covariance matrix will not be changed; whereas
ip mh am adaptInterval defines the size of the interval in which each adapted proposal covariance matrix will be used. ip mh am eta is a factor used to scale the proposal covariance
matrix, usually set to be 2.42 /d, where d is the dimension of the problem [31, 18]. Finally,
ip mh am epsilon is the covariance regularization factor used in the DRAM algorithm.
For a SFP, the variable assignment fp_computeSolution = 1 tells QUESO to compute the
solution process; the assignment fp_computeCovariances = 1, instructs QUESO to compute
parameter–QoI covariances, and analogously, fp_computeCorrelations = 1 inform QUESO
to compute parameter–QoI correlations. The name of the data output file can be set with
variable fp_dataOutputFileName arg; and fp_dataOutputAllowedSet defines which subenvironments will write to data output file.
An example a complete input file used by QUESO to solve a SIP–SFP is presented in
Section 5.3.5; however every application example included in QUESO build and installation
directories examples has an options input file and the user is invited to familiarize him/herself
with them.

4.2 Revisiting Priors
QUESO offers a variety of prior distributions: uniform, Gaussian, Beta, Gamma, Inverse
Gamma, and Log Normal. Also, QUESO presents the option of concatenating any of those
priors, through the Concatenated prior.
Concatenated priors are employed in problems with multiple random parameters. They
allow one random parameter to have a different prior distribution then other; i.e., one variable
may have a uniform prior distribution whereas other may have a Gaussian prior distribution.
It is important to notice that, in order to set a Gaussian prior, besides providing the mean,
the user must also supply the variance, not the standard deviation.

4.3 Running with Multiple Chains or Monte Carlo Sequences
As presented in the previous section, the variable env_numSubEnvironments determines how
many subenvironments QUESO will work with. Thus, if env_numSubEnvironments=1, then
only one subenvironment will be used, and QUESO will use only one set on Monte Carlo
chains of size defined by ones of the variables ip_mh_rawChain_size or fp_mc_qseq_size,
depending either the user is solving a SIP or a SFP.
If the user wants to run QUESO with multiple chains or Monte Carlo sequences, then two
variables have to be set in QUESO input file: env_numSubEnvironments = Ns , with Ns > 1
is the number of chains and/or Monte Carlo sequences of samples; and env_seed = −z, with
z > 1, so that each processor sets the seed to value MPI RANK+z. It is crucial that env_seed
takes a negative value, otherwise all chain samples are going to be the same.

CHAPTER 4. IMPORTANT REMARKS

53

Also, the total number Np of processors in the full communicator, usually named
MPI COMM WORLD, needs to be a multiple of Ns .

4.4 Running with Models that Require Parallel Computing
It is possible to run QUESO with models that require parallel computing as long as total
number of processors Np is multiple of the number of subenvironments Ns . QUESO will
internally create Ns subcommunicators, each of size Np /Ns , and make sure that the likelihood
and QoI routines are called for all processors in these subcommunicators – the likelihood/QoI
routine will have available a communicator of size Np /Ns . For instance, if Np = 2048 and
Ns = 16, then each likelihood/QoI will have available a communicator of size 128. s Each
subcommunicator is accessible through env.subComm(). At the end of the simulation, there
will be a total of Ns chains.
The user, however, must keep in mind the possible occurrence of race condition, especially
in the case where the application is a black box and files are being accessed constantly (e.g.
data is being written and read).

4.5 A Requirement for the DRAM Algorithm
Besides setting up the variables related to the DRAM algorithm in the input file, as described
in Section 4.1 above, the user must also provide an initialized covariance matrix before calling
the DRAM solver, solveWithBayesMetropolisHastings(...), in his/her application code.
It is worth to note that this is rather a DRAM requirement [31], not a QUESO limitation.
An example of the instantiation and initialization of a proposal covariance matrix and its
subsequent use is presented in lines 145-147 of Listings 5.27, Section 5.3.4.

CHAPTER

5

QUESO Examples

This chapter assumes that the user has successfully installed QUESO and its dependencies.
It presents a variety of examples of how to use QUESO in order to develop applications.
There are examples that solve a statistical inverse problem (Sections 5.1, 5.5, 5.6 and 5.7),
a statistical forward problem (Section 5.2) or a combination of both, where the solution of
the former serves as input to the later (Sections 5.3 and 5.4). Three of the first four examples
(Sections 5.1, 5.3 –5.4) use the DRAM algorithm for solving the SIP, and the last three
examples use the Multilevel algorithm. Each section presents:
• the mathematical models for the SIP and/or the SFP;
• the application codes that translate the mathematical language into C++ using the
QUESO classes and algorithms;
• the input file that contains a list of options for either the Markov chain Monte Carlo
algorithm or the Multilevel algorithm (in case of SIPs) and the Monte Carlo algorithm
(in case of SFPs) which will be used by QUESO classes and algorithms;
• examples of Makefiles which may be used to link the code with QUESO library;
• how to plot figures using Matlab/GNU Octave and the output data generated by each
application.
All the examples presented in this chapter may be found under the directory examples in
both QUESO installation and build directories and are compatible with QUESO 0.50.0.
Note: Even though the Multilevel method is a methodology very useful for stochastic system
model class comparison (model updating, model selection, model validation) [6], such tasks
are not discussed in this manual. Thus the explicit dependency of the statistical variables on
the predictive model in the set Mj as presented in Section 1.4.2 are omitted herein.
54

CHAPTER 5. QUESO EXAMPLES

55

5.1 simpleStatisticalInverseProblem
According to the Bayesian paradigm, the unobservable parameters in a statistical model are
treated as random. When no data is available, a prior distribution is used to quantify our
knowledge about the parameter. When data are available, we can update our prior knowledge
using the conditional distribution of parameters, given the data. The transition from the prior
to the posterior is possible via the Bayes theorem:
πposterior (θ|d) =

πprior (θ)πlikelihood (d|θ)
π(d)

In this example, suppose a random variable of interest with two parameters θ ∈ R2 has
a uniform prior distribution, and suppose that a suitable likelihood has normal distribution
with mean µ and covariance matrix C, given by:




−1
4 0
µ=
and C =
.
(5.1.1)
2
0 1
Therefore, we have:
πprior (θ) ∝ 1
and




1
T
−1
πlike (θ) ∝ exp − (θ − µ) [C ](θ − µ) ,
2

where



θ1
θ2

θ=



∈ R2 .

Therefore, posterior PDF is given by:
πpost (θ) ∝ e− 2 {(θ−µ)
1

T [C−1 ](θ−µ)

}.

(5.1.2)

In this example, we can replace the values for the mean and covariance matrix given in
Equation (5.1.1) into Equation (5.1.2), in order to analytically compute both the posterior
PDF:


1
1
T
−1
πpost (θ) =
exp − (θ − µ) [C ](θ − µ)
4π
2


1
1
1
2
2
exp − (θ1 + 1) − (θ2 − 2) ,
=
4π
8
2
and the marginal results for θ1 and θ2 :


1
1
2
πpost (θ1 ) = √ exp − (θ1 + 1) ,
8
2 2π


1
1
2
πpost (θ1 ) = √ exp − (θ2 − 2) .
2
2π

(5.1.3)

CHAPTER 5. QUESO EXAMPLES

56

Recall that the posterior PDF given in Equation (5.1.2) can be sampled through the
expression:
µ + C1/2 N (0, I),
(5.1.4)
where N (0, I) designates a Gaussian joint PDF of zero mean and unit covariance matrix, and
C1/2 is given by:


2 0
1/2
C =
.
0 1
Thus, in this simple statistical inverse problem, we use QUESO implementation of the
Markov chain algorithm to sample the posterior (5.1.2) via Expression (5.1.4) and compare
the calculated marginal results for θ1 and θ2 against the analytical formulas given in Equation (5.1.3).
Note: Due to the possibility to compare QUESO sampling algorithms to analytical expressions, this example is also used in the verification procedures and regression tests within
QUESO, and it is reproduced in the directory tests/t02_sip_sfp.

5.1.1 Running the Example
To run the executable provided (available after QUESO installation), enter the following
commands:
$
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/
cd examples / s i m p l e S t a t i s t i c a l I n v e r s e P r o b l e m
rm outputData /*
./ e x S i m p l e S t a t i s t i c a l I n v e r s e P r o b l e m _ g s l example . inp
matlab
$ s im pl e_ i p_ pl ot s
# i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
s i m p l e _ i p _ a u t o c o r r e l a t i o n _ r a w _ f i l t . png s i m p l e _ i p _ h i s t _ f i l t . png
s i m p l e _ i p _ c d f _ f i l t . png
s i m p l e _ i p _ h i s t _ r a w . png
s i m p l e _ i p _ c d f _ r a w . png
s i m p l e _ i p _ k d e _ f i l t . png
s i m p l e _ i p _ c h a i n _ p o s _ f i l t . png
s i m p l e _ i p _ k d e _ r a w . png

As a result, the user should have created several of PNG figures containing marginal posterior PDF, chain positions, histograms, cumulative density distributions and autocorrelation
of both parameters. The name of the figure files have been chosen to be informative, as shown
in the Listing above.
It is worth noting presence of an argument passed to the executable in the example, namely
‘example.inp’. The argument is a input file to be provided to QUESO with options for the
solution of the SIP and/or SFP; and it is always required. Each option in the input file is
related to one (or more) of the QUESO classes, and is presented throughout Chapter 3.

CHAPTER 5. QUESO EXAMPLES

57

5.1.2 Example Code
The source code for the example is composed of 5 files: example main.C (Listing 5.1),
example likelihood.h and example likelihood.C (Listings 5.2 and 5.3), example compute.h
and example compute.C (Listings 5.4 and 5.5).
#i n c l u d e 
int main ( int argc , char * argv [])
{
// Initialize environment
MPI_Init (& argc ,& argv ) ;
U Q _ F A T A L _ T E S T _ M A C R O ( argc != 2 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" main () " ,
" input file must be specified in command line as argv [1] , just after
executable argv [0] " ) ;
QUESO :: Fu ll En v ir on me n t * env =

new QUESO :: Fu ll En v ir on me n t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;

// Compute
compute (* env ) ;
// Finalize environment
delete env ;
MPI_Finalize () ;
return 0;
}

Listing 5.1: File example main.C.
#i f n d e f EX LIKELIHOOD H
#d e f i n e EX LIKELIHOOD H
#i n c l u d e 
struct
likelihoodRoutine_DataType
{
const QUESO :: GslVector * meanVector ;
const QUESO :: GslMatrix * covMatrix ;
};
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *

paramValues ,
paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect ) ;

#e n d i f

Listing 5.2: File example likelihood.h.

CHAPTER 5. QUESO EXAMPLES

58

#i n c l u d e < e x a m p l e l i k e l i h o o d . h>
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector & paramValues ,
const QUESO :: GslVector * paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector *
gradVector ,
QUESO :: GslMatrix *
hessianMatrix ,
QUESO :: GslVector *
hessianEffect )
{
// Logic just to avoid warnings from INTEL compiler
const QUESO :: GslVector * aux1 = p aramDire ction ;
if ( aux1 ) {};
aux1 = gradVector ;
aux1 = hessianEffect ;
QUESO :: GslMatrix * aux2 = hessianMatrix ;
if ( aux2 ) {};
// Just checking : the user , at the application level , expects
// vector ’ paramValues ’ to have size 2.
U Q _ F A T A L _ T E S T _ M A C R O ( paramValues . sizeGlobal () != 2 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" l i k e l i h o o d R o u t i n e () " ,
" paramValues vector does not have size 2 " ) ;
//
//
//
//
//
//
//
//
//

Actual code
This code exemplifies multiple Metropolis - Hastings solvers , each calling this likelihood
routine . In this simple example , only node 0 in each subenvi ronment does the job even
though there might be more than one node per sub - environment . In a more realistic
situation , if the user is asking for multiple nodes per subenvironment , then the model
code in the likelihood routines might really demand more than one node . Here we use
’ env . subRank () ’ only . A realistic application might want to use either ’ env . subComm () ’
or ’ env . subComm () . Comm () ’.

double result = 0.;
const QUESO :: B as eE n vi ro nm e nt & env = paramValues . env () ;
if ( env . subRank () == 0) {
const QUESO :: GslVector & meanVector =
*(( l i k e l i h o o d R o u t i n e _ D a t a T y p e *) fu nc t io nD at a Pt r ) -> meanVector ;
const QUESO :: GslMatrix & covMatrix =
*(( l i k e l i h o o d R o u t i n e _ D a t a T y p e *) fu nc t io nD at a Pt r ) -> covMatrix ;
QUESO :: GslVector diffVec ( paramValues - meanVector ) ;
result = scalarProduct ( diffVec , covMatrix . inver tMultip ly ( diffVec ) ) ;
}
else {
// Do nothing ;
}
#i f d e f QUESO EXPECTS LN LIKELIHOOD INSTEAD OF MINUS 2 LN
return -.5* result ;
#e l s e
return result ;
#e n d i f
}

Listing 5.3: File example likelihood.C.

CHAPTER 5. QUESO EXAMPLES

#i f n d e f EX COMPUTE H
#d e f i n e EX COMPUTE H
#i n c l u d e 
void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) ;
#e n d i f

Listing 5.4: File example compute.h.

3

#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e


< e x a m p l e l i k e l i h o o d . h>





8 void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) {
// Step 1 of 5: Instantiate the parameter space
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpace ( env , " param_ " , 2 , NULL ) ;

13

18

23

28

// Step 2 of 5: Instantiate the parameter domain
QUESO :: GslVector paramMins ( paramSpace . zeroVector () ) ;
paramMins . cwSet ( - INFINITY ) ;
QUESO :: GslVector paramMaxs ( paramSpace . zeroVector () ) ;
paramMaxs . cwSet ( INFINITY ) ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " param_ " , paramSpace , paramMins , paramMaxs ) ;
// Step 3 of 5: Instantiate the likelihood function object
QUESO :: GslVector meanVector ( paramSpace . zeroVector () ) ;
meanVector [0] = -1;
meanVector [1] = 2;
QUESO :: GslMatrix covMatrix ( paramSpace . zeroVector () ) ;
covMatrix (0 ,0) = 4.; covMatrix (0 ,1) = 0.;
covMatrix (1 ,0) = 0.; covMatrix (1 ,1) = 1.;
likelihoodRoutine_DataType likelihoodRoutine_Data ;
l i k e l i h o o d R o u t i n e _ D a t a . meanVector = & meanVector ;
l i k e l i h o o d R o u t i n e _ D a t a . covMatrix = & covMatrix ;

33

38

43

QUESO :: GenericScalarFunction < QUESO :: GslVector , QUESO :: GslMatrix >
l i k e l i h o o d F u n c t i o n O b j ( " like_ " ,
paramDomain ,
likelihoodRoutine ,
( void *) & likelihoodRoutine_Data ,
true ) ; // routine computes [ ln ( function ) ]
// Step 4 of 5: Instantiate the inverse problem
QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRv ( " prior_ " , paramDomain ) ;
QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
postRv ( " post_ " , paramSpace ) ;
QUESO :: StatisticalInverseProblem < QUESO :: GslVector , QUESO :: GslMatrix >
ip ( " " , NULL , priorRv , likelihoodFunctionObj , postRv ) ;

48
// Step 5 of 5: Solve the inverse problem
QUESO :: GslVector paramInitials ( paramSpace . zeroVector () ) ;
paramInitials [0] = 0.1;

59

CHAPTER 5. QUESO EXAMPLES

60

paramInitials [1] = -1.4;

53
QUESO :: GslMatrix p r o p o s a l C o v M a t r i x ( paramSpace . zeroVector () ) ;
p r o p o s a l C o v M a t r i x (0 ,0) = 8.; p r o p o s a l C o v M a t r i x (0 ,1) = 4.;
p r o p o s a l C o v M a t r i x (1 ,0) = 4.; p r o p o s a l C o v M a t r i x (1 ,1) = 16.;

58

ip . s o l v e W i t h B a y e s M e t r o p o l i s H a s t i n g s ( NULL , paramInitials , & p r o p o s a l C o v M a t r i x ) ;
return ;
}

Listing 5.5: File example compute.C.

5.1.3 Input File
QUESO reads an input file for solving statistical problems. In the case of a SIP, it expects
a list of options for MCMC (or Multilevel), together with options for QUESO environment;
such as the amount of processors to be used and the seed for its random algorithms. Note
that the names of the variables have been designed to be informative:
env: refers to QUESO environment;
ip: refers to inverse problem;
mh: refers to Metropolis-Hastings;
dr: refers to delayed rejection;
am: refers to adaptive Metropolis;
rawChain: refers to the raw, entire chain;
filteredChain: refers to a filtered chain (related to a specified lag);
The options used for solving this simple SIP are displayed in Listing 5.6.
###############################################
# UQ E n v i r o n m e n t
###############################################
#e n v h e l p
= anything
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0
env_displayVerbosity
= 2
env_syncVerbosity
= 0
env_seed
= 0
###############################################
# S t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
#i p h e l p
= anything
ip_computeSolution
= 1
ip_dataOutputFileName
= outputData / sipOutput
ip_dataOutputAllowedSet = 0
###############################################
# ’ i p ’ : i n f o r m a t i o n f o r M e t r o p o l i s −H a s t i n g s a l g o r i t h m
###############################################
#i p m h h e l p
= anything
ip_mh_dataOutputFileName
= outputData / sipOutput

CHAPTER 5. QUESO EXAMPLES

61

ip_mh_dataOutputAllowedSet = 0 1
ip_mh_rawChain_dataInputFileName
ip_mh_rawChain_size
ip_mh_rawChain_generateExtra
ip_mh_rawChain_displayPeriod
ip_mh_rawChain_measureRunTimes
ip_mh_rawChain_dataOutputFileName
ip_mh_rawChain_dataOutputAllowedSet
ip_mh_rawChain_computeStats

=
=
=
=
=
=
=
=

.
32768
0
50000
1
outputData / ip_raw_chain
0 1
1

ip_mh_displayCandidates
ip_mh_putOutOfBoundsInChain
ip_mh_tk_useLocalHessian
ip_mh_tk_useNewtonComponent
ip_mh_dr_maxNumExtraStages
ip_mh_dr_listOfScalesForExtraStages
ip_mh_am_initialNonAdaptInterval
ip_mh_am_adaptInterval
ip_mh_am_eta
i p _ m h _ a m _ e p s i lo n

=
=
=
=
=
=
=
=
=
=

0
1
0
1
1
5.
0
100
1.92
1. e -5

ip_mh_filteredChain_generate
ip_mh_filteredChain_discardedPortion
ip_mh_filteredChain_lag
ip_mh_filteredChain_dataOutputFileName
ip_mh_filteredChain_dataOutputAllowedSet

=
=
=
=
=

1
0.
16
outputData / ip_filt_chain
0 1

Listing 5.6: Options for QUESO library used in application code (Listings 5.1-5.5).

5.1.4 Create your own Makefile
Makefiles are special format files that together with the make utility will help one to compile
and automatically build and manage projects (programs). Listing 5.7 presents a Makefile,
named ‘Makefile sip example margarida’, that may be used to compile the code and create
the executable simple_sip_example. Naturally, it must be adapted to the user’s settings,
i.e., it has to have the correct paths for the user’s libraries that have actually been used to
compile and install QUESO (see Sections 2.1–2.4).
##########################################################
# U s i n g i n s t a l l e d QUESO 0 . 5 0 . 0 , from e x t e r n a l r e l e a s e i n ’ m a r g a r i d a ’
##########################################################
QUESO_DIR =
BOOST_DIR =
GSL_DIR =
HDF5_DIR =

/ home / kemelli / LIBRARIES / QUESO -0.50.0
/ home / kemelli / LIBRARIES / boost -1.53.0
/ home / kemelli / LIBRARIES / gsl -1.15
/ home / kemelli / LIBRARIES / hdf5 -1.8.10

INC_PATHS = \
-I . \
- I$ ( QUESO_DIR ) / include \
- I$ ( BOOST_DIR ) / include \
- I$ ( GSL_DIR ) / include \
- I$ ( HDF5_DIR ) / include
LIBS = \
- L$ ( QUESO_DIR ) / lib - lqueso \

CHAPTER 5. QUESO EXAMPLES

62

- L$ ( BOOST_DIR ) / lib - l b o o s t _ p r o g r a m _ o p t i o n s \
- L$ ( GSL_DIR ) / lib - lgsl \
- L$ ( HDF5_DIR ) / lib - lhdf5
CXX = mpic ++
CXXFLAGS += -g - Wall -c
default : all
. SUFFIXES : . o . C
all :

example_sip

clean :
rm -f *~
rm -f *. o
rm -f s i m p l e _ s i p _ e x a m p l e
example_sip : example_main . o e x a m p l e _ l i k e l i h o o d . o ex am pl e _c om p ut e . o
$ ( CXX ) example_main . o \
example_likelihood .o \
e xa mp le _ co mp ut e . o \
-o s i m p l e _ s i p _ e x a m p l e $ ( LIBS )
%. o : %. C
$ ( CXX ) $ ( INC_PATHS ) $ ( CXXFLAGS ) $ <

Listing 5.7: Makefile for the application code in Listings 5.1-5.5
Thus, to compile, build and execute the code, the user just needs to run the following
commands in the same directory where the files are:
$ cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / s i m p l e S t a t i s t i c a l I n v e r s e P r o b l e m /
$ export L D_ L IB RA RY _ PA TH = $ L D _ L I B R A R Y _ P A T H :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib
$ make -f M a k e f i l e _ e x a m p l e _ m a r g a r i d a
$ ./ s i m p l e _ s i p _ e x a m p l e example . inp

The ‘export’ instruction above is only necessary if the user has not saved it in his/her
.bashrc file.

5.1.5 Data Post-Processing and Visualization
There are a few Matlab-ready commands that are very helpful tools for post-processing the
data generated by QUESO when solving statistical inverse problems. This section discusses
the results computed by QUESO with the code of Section 5.1.2, and shows how to use Matlab
for the post-processing of such results. Only the essential Matlab commands are presented;
for the complete/detailed codes, please refer to file ’simple_ip_plots.m’.
According to the specifications of the input file in Listing 5.6, a folder named ‘outputData’
containing the following files should be created: display_sub0.txt, ip_filt_chain_sub0.m,
ip_raw_chain_sub0.m, sipOutput_sub0.m, ip_filt_chain.m, ip_raw_chain.m

CHAPTER 5. QUESO EXAMPLES

63

The code bellow shows how to load the data provided by QUESO during the solution
process of the SIP described, in the form of chains of positions.
% inside Matlab
>> clear all
>> si mp le _ ip _p lo t s

Listing 5.8: Matlab code for loading the data in both raw and filtered chains of the SIP, by
calling the file simple ip plots.m.

5.1.5.1 Autocorrelation Plots
The code presented in Listing 5.9 uses Matlab function autocorr to generate Figure 5.1.1
which presents the autocorrelation of the parameters θ1 and θ2 in both cases: raw and filtered
chain.
% inside Matlab
% theta_1
>> nlags =10;
>> [ ACF_raw , lags ] = autocorr ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,1) , nlags , 0) ;
>> [ ACF_filt , lags ] = autocorr ( i p _ m h _ f i l t C h a i n _ u n i f i e d (: ,1) , nlags , 0) ;
>> [ ACF_raw2 , lags2 ] = autocorr ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,2) , nlags , 0) ;
>> [ ACF_filt2 , lags3 ] = autocorr ( i p _ m h _ f i l t C h a i n _ u n i f i e d (: ,2) , nlags , 0) ;
>> plot ( lags , ACF_raw , ’b - -* ’ , lags , ACF_filt , ’ b * - ’ , lags2 , ACF_raw2 , ’g - -* ’ , lags2 , ACF_filt2 , ’ g * - ’ , ’
linewidth ’ ,3) ;
>> h = legend ( ’\ theta_1 , raw chain ’ , ’\ theta_1 , filtered chain ’ , ’\ theta_2 , raw chain ’ , ’\ theta_2 ,
filtered chain ’ , ’ location ’ , ’ northeast ’) ;

Listing 5.9: Matlab code for the autocorrelation plots depicted in Figure 5.1.1.

Figure 5.1.1: Autocorrelation plots obtained with QUESO for the SIP.

5.1.5.2 KDE Plots
Matlab function [f,xi] = ksdensity(x) (kernel smoothing density estimate) computes a
probability density estimate of the sample in the vector x. f is the vector of density values

CHAPTER 5. QUESO EXAMPLES

64

evaluated at the points in xi. The estimate is based on a normal kernel function, using a
window parameter (‘width’) that is a function of the number of points in x. The density is
evaluated at 100 equally spaced points that cover the range of the data in x. In order to
estimate the KDE of the parameters, it is used together with the option ‘pdf’.
% Inside Matlab
% Raw chain
>> [f , x ] = ksdensity ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,1) ,’ function ’ , ’ pdf ’) ;
>> [ f2 , x2 ] = ksdensity ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,2) ,’ function ’ , ’ pdf ’) ;
>> x_p1 = sort ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,1) ) ; % analytical
>> f_p1 =( exp ( -( x_p1 +1) .*( x_p1 +1) /8) ) /2/ sqrt (2* pi ) ;
>> x_p2 = sort ( i p _ m h _ r a w C h a i n _ u n i f i e d (: ,1) ) ;
>> f_p2 =( exp ( -( x_p2 -2) .*( x_p2 -2) /2) ) / sqrt (2* pi ) ;
>> plot (x ,f , ’b ’ , x2 , f2 , ’g ’ , ’ linewidth ’ ,4) ;
>> hold ;
>> plot ( x_p1 , f_p1 , ’ - -k ’ , x_p2 , f_p2 , ’ -k ’ , ’ linewidth ’ ,2) ;
>> h = legend ( ’\ theta_1 ’ , ’\ theta_2 ’ , ’ analytical (\ theta_1 ) ’, ’ analytical (\ theta_2 ) ’, ’
location ’ , ’ northwest ’) ;

Listing 5.10: Matlab code for the KDE plots displayed in the left of Figure 5.1.2.

(a) Raw chain

(b) Filtered chain

Figure 5.1.2: Kernel Density Estimation. QUESO results for estimation of the KDE 
of θ1
and θ2 are plotted against the analytical expressions πpost (θ1 ) = 2√12π exp − 18 (θ1 + 1)2 and


πpost (θ2 ) = √12π exp − 12 (θ2 − 2)2 , respectively.

5.1.5.3 Covariance and Correlation Matrices
Matlab function cov calculates the covariance matrix for a data matrix (where each column
represents a separate quantity), and corr calculates the correlation matrix.
Listing 5.39 presents the Matlab steps for calculating the covariance and correlation matrices for the parameters θ1 and θ2 .

CHAPTER 5. QUESO EXAMPLES

65

% inside Matlab
>> c o v _ m a t r i x _ t h e t a 1 _ t h e t a 2 = cov ( i p _ m h _ r a w C h a i n _ u n i f i e d )
cov_matrix_theta1_theta2 =
3.8729
0.0259

0.0259
1.0050

>> c o r r _ m a t r i x _ t h e t a 1 _ t h e t a 2 = corr ( i p _ m h _ r a w C h a i n _ u n i f i e d )
corr_matrix_theta1_theta2 =
1.0000
0.0132

0.0132
1.0000

Listing 5.11: Matlab code for finding covariance and correlation matrices.

5.2 simpleStatisticalForwardProblem
In this simple statistical forward problem (SFP), suppose that the quantity of interest q is a
function of a random variable θ of two parameters, namely q : R2 → R such as:
q(θ) = θ1 + θ2 ,

∀θ = (θ1 , θ2 ) ∈ R2 .

(5.2.1)

Suppose also that the parameters in θ have Gaussian distribution with mean µ and covariance matrix C given by:




−1
4 0
µ=
and C =
.
(5.2.2)
2
0 1
Notice that since the solution Q of this SFP is the sum of two random variables Θ1 and
Θ2 , and since these two random variables independent Gaussian by assumption, should have:
E[Q] = E[Θ1 ] + E[Θ2 ] = −1 + 2 = 1 and V [Q] = V [Θ1 ] + V [Θ2 ] = 4 + 1 = 5

(5.2.3)

where E and V indicate expectation and variance, respectively. Thus the analytical expression
for the solution Q is this SFP is the one-dimensional Gaussian distribution of mean 1 and
variance 5:


1
1
2
exp − (x − 1)
(5.2.4)
Q(x) = √
10
10π
In this example, we use QUESO Monte Carlo algorithm to sample from the QoI given
in Equation (5.2.1) and analyze it. Since the parameters have known independent Gaussian
distributions, the results obtained by QUESO via sampling the QoI, in Equation (5.2.1),
should match the Gaussian distribution given in Equation (5.2.4).
Note: Due to the possibility to compare QUESO sampling algorithms to an analytical expression, this example is also used in the verification procedures and regression tests within
QUESO. In fact it is the second part of the test tests/t02_sip_sfp.

CHAPTER 5. QUESO EXAMPLES

66

5.2.1 Running the Example
To run the executable provided (available after QUESO installation), enter the following
commands:
$
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/
cd examples / s i m p l e S t a t i s t i c a l F o r w a r d P r o b l e m
rm outputData /*
./ e x S i m p l e S t a t i s t i c a l F o r w a r d P r o b l e m _ g s l example . inp
matlab
$ s im pl e_ f p_ pl ot s
# i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
s i m p l e _ f p _ a u t o c o r r e l a t i o n _ q o i . png s i m p l e _ f p _ c h a i n _ p o s _ p a r a m . png
s i m p l e _ f p _ h i s t _ q o i . png
s i m p l e _ f p _ c d f _ q o i . png
s i m p l e _ f p _ c h a i n _ p o s _ q o i . png
s i m p l e _ f p _ k d e _ q o i . png

As a result, the user should have created several of PNG figures containing marginal posterior PDF, chain positions of the parameters and the QoI, histogram, cumulative density
distribution and autocorrelation. The name of the figure files have been chosen to be informative, as shown in the Listing above.

5.2.2 Example Code
The source code for the SFP example is composed of 5 files: simple sfp example main.C
(Listing 5.12), simple sfp example qoi.h and simple sfp example qoi.C (Listings 5.13
and 5.14), simple sfp example compute.h and simple sfp example compute.C (Listings
5.15 and 5.16).
#i n c l u d e 
int main ( int argc , char * argv [])
{
// Initialize environment
MPI_Init (& argc ,& argv ) ;
U Q _ F A T A L _ T E S T _ M A C R O ( argc != 2 , QUESO :: UQ_UNAVAILABLE_RANK , " main () " ,
" input file must be specified in command line as argv [1] , just after
executable argv [0] " ) ;
QUESO :: Fu ll En v ir on me n t * env =
new QUESO :: Fu ll En v ir on me n t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;
// Compute
compute (* env ) ;
// Finalize environment
delete env ;
MPI_Finalize () ;
return 0;
}

Listing 5.12: File simple sfp example main.C.

CHAPTER 5. QUESO EXAMPLES

#i f n d e f
#d e f i n e

67

EX QOI H
EX QOI H

#i n c l u d e 
#i n c l u d e 
struct
qoiRoutine_DataType
{
double coef1 ;
double coef2 ;
};
void
qoiRoutine (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector &
QUESO :: DistArray < QUESO :: GslVector * >*
QUESO :: DistArray < QUESO :: GslMatrix * >*
QUESO :: DistArray < QUESO :: GslVector * >*

paramValues ,
paramDirection ,
functionDataPtr ,
qoiValues ,
gradVectors ,
hessianMatrices ,
hessi anEffect s ) ;

#e n d i f

Listing 5.13: File simple sfp example qoi.h.
#i n c l u d e < s i m p l e s f p e x a m p l e q o i . h>
void
qoiRoutine (
const QUESO :: GslVector &
paramValues ,
const QUESO :: GslVector *
paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector &
qoiValues ,
QUESO :: DistArray < QUESO :: GslVector * >* gradVectors ,
QUESO :: DistArray < QUESO :: GslMatrix * >* hessianMatrices ,
QUESO :: DistArray < QUESO :: GslVector * >* hessi anEffect s )
{
// Logic just to avoid warnings from INTEL compiler
const QUESO :: GslVector * aux1 = p aramDire ction ;
if ( aux1 ) {};
QUESO :: DistArray < QUESO :: GslVector * >* aux2 = gradVectors ;
if ( aux2 ) {};
aux2 = he ssianEff ects ;
QUESO :: DistArray < QUESO :: GslMatrix * >* aux3 = h e ss ia nM a tr ic es ;
if ( aux3 ) {};
// Just checking : the user , at the application level , expects
// vector ’ paramValues ’ to have size 2 and
// vector ’ qoiValues ’ to have size 1.
U Q _ F A T A L _ T E S T _ M A C R O ( paramValues . sizeGlobal () != 2 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" qoiRoutine () " ,
" paramValues vector does not have size 2 " ) ;
U Q _ F A T A L _ T E S T _ M A C R O ( qoiValues . sizeGlobal () != 1 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" qoiRoutine () " ,
" qoiValues vector does not have size 1 " ) ;
// Actual code

CHAPTER 5. QUESO EXAMPLES
//
//
//
//
//
//
//
//

This code exemplifies multiple Monte Carlo solvers , each calling this qoi routine .
In this simple example , only node 0 in each sub - environment does the job even though
there might be more than one node per sub - environment .
In a more realistic situation , if the user is asking for multiple nodes per sub environment , then the model code in the qoi routine might really demand more than one
node . Here we use ’ env . subRank () ’ only . A realistic application might want to use
either ’ env . subComm () ’ or ’ env . subComm () . Comm () ’.

const QUESO :: B as eE n vi ro nm e nt & env = paramValues . env () ;
if ( env . subRank () == 0) {
double coef1 = (( q o i R o u t i n e _ D a t a T y p e *) fu nc ti o nD at aP t r ) -> coef1 ;
double coef2 = (( q o i R o u t i n e _ D a t a T y p e *) fu nc ti o nD at aP t r ) -> coef2 ;
qoiValues [0] = ( coef1 * paramValues [0] + coef2 * paramValues [1]) ;
}
else {
qoiValues [0] = 0.;
}
return ;
}

Listing 5.14: File simple sfp example qoi.C.
#i f n d e f
#d e f i n e

EX COMPUTE H
EX COMPUTE H

#i n c l u d e 
void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) ;
#e n d i f

Listing 5.15: File simple sfp example compute.h.

3

#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e


< s i m p l e s f p e x a m p l e q o i . h>





8 void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) {
// Step 1 of 6: Instantiate the parameter space
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpace ( env , " param_ " , 2 , NULL ) ;

13

18

23

// Step 2 of 6: Instantiate the parameter domain
QUESO :: GslVector paramMins ( paramSpace . zeroVector () ) ;
paramMins . cwSet ( - INFINITY ) ;
QUESO :: GslVector paramMaxs ( paramSpace . zeroVector () ) ;
paramMaxs . cwSet ( INFINITY ) ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " param_ " , paramSpace , paramMins , paramMaxs ) ;
// Step 3 of 6: Instantiate the qoi space
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
qoiSpace ( env , " qoi_ " , 1 , NULL ) ;

68

CHAPTER 5. QUESO EXAMPLES

69

// Step 4 of 6: Instantiate the qoi function object
q o i R o u t i n e _ D a t a T y p e q oi R ou ti ne _ Da ta ;
q oi Ro ut i ne _D at a . coef1 = 1.;
q oi Ro ut i ne _D at a . coef2 = 1.;
QUESO :: GenericVectorFunction < QUESO :: GslVector , QUESO :: GslMatrix ,
QUESO :: GslVector , QUESO :: GslMatrix >
qoiF unctionO bj ( " qoi_ " ,
paramDomain ,
qoiSpace ,
qoiRoutine ,
( void *) & q oi R ou ti ne _ Da ta ) ;

28

33

38

// Step 5 of 6: Instantiate the forward problem
// Parameters are Gaussian RV
QUESO :: GslVector meanVector ( paramSpace . zeroVector () ) ;
meanVector [0] = -1;
meanVector [1] = 2;

43
QUESO :: GslMatrix
covMatrix (0 ,0) =
covMatrix (0 ,1) =
covMatrix (1 ,0) =
covMatrix (1 ,1) =

48

covMatrix = QUESO :: GslMatrix ( paramSpace . zeroVector () ) ;
4.;
0.;
0.;
1.;

QUESO :: GaussianVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
paramRv ( " param_ " , paramDomain , meanVector , covMatrix ) ;

53

QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
qoiRv ( " qoi_ " , qoiSpace ) ;
QUESO :: StatisticalForwardProblem < QUESO :: GslVector , QUESO :: GslMatrix ,
QUESO :: GslVector , QUESO :: GslMatrix >
fp ( " " , NULL , paramRv , qoiFunctionObj , qoiRv ) ;

58

// Step 6 of 6: Solve the forward problem
fp . s o l v e W i t h M o n t e C a r l o ( NULL ) ;

63

return ;
}

Listing 5.16: File simple sfp example compute.C.

5.2.3 Input File
In the case of a SFP, QUESO expects a list of options for Monte Carlo algorithm, together
with options for QUESO environment; such as the name of the output files and which subenvironments will write to to them. Note that the names of the variables have been designed
to be informative:
env: refers to QUESO environment;
fp: refers to forward problem;
mc: refers to Monte Carlo;
pseq: refers to the parameter sequence; and
qseq: refers to the quantity of interest sequence.
The options used for solving this simple SFP are displayed in Listing 5.17.

CHAPTER 5. QUESO EXAMPLES

70

###############################################
# UQ E n v i r o n m e n t
###############################################
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0
env_displayVerbosity
= 2
env_syncVerbosity
= 0
env_seed
= 0
###############################################
# S t a t i s t i c a l forward problem ( fp )
###############################################
fp_computeSolution
= 1
fp_computeCovariances
= 1
fp_computeCorrelations = 1
fp_dataOutputFileName
= outputData / sfpOutput
fp_dataOutputAllowedSet = 0 1
###############################################
# ’ f p ’ : i n f o r m a t i o n f o r Monte C a r l o a l g o r i t h m
###############################################
fp_mc_dataOutputFileName
= outputData / sfpOutput
fp_mc_dataOutputAllowedSet = 0 1
fp_mc_pseq_dataOutputFileName
= outputData / fp_p_seq
fp_mc_pseq_dataOutputAllowedSet = 0 1
f p_ mc _q s eq _s iz e
fp_mc_qseq_displayPeriod
fp_mc_qseq_measureRunTimes
fp_mc_qseq_dataOutputFileName
fp_mc_qseq_dataOutputAllowedSet

=
=
=
=
=

20000
2000
1
outputData / fp_q_seq
0 1

Listing 5.17: File name simple sfp example.inp with options for QUESO library used in
application code (Listings 5.12–5.16).

5.2.4 Create your own Makefile
Listing 5.33 presents a Makefile, named ‘Makefile sfp example margarida’, that may be
used to compile the code and create the executable simple_sfp_example. Naturally, it must
be adapted to the user’s settings, i.e., it has to have the correct paths for the user’s libraries
that have actually been used to compile and install QUESO.
##########################################################
# U s i n g i n s t a l l e d QUESO 0 . 5 0 . 0 , from e x t e r n a l r e l e a s e i n ’ m a r g a r i d a ’
##########################################################
QUESO_DIR =
BOOST_DIR =
GSL_DIR =
HDF5_DIR =

/ home / kemelli / LIBRARIES / QUESO -0.50.0
/ home / kemelli / LIBRARIES / boost -1.53.0
/ home / kemelli / LIBRARIES / gsl -1.15
/ home / kemelli / LIBRARIES / hdf5 -1.8.10

INC_PATHS = \
-I . \
- I$ ( QUESO_DIR ) / include \

CHAPTER 5. QUESO EXAMPLES

71

- I$ ( BOOST_DIR ) / include \
- I$ ( GSL_DIR ) / include \
- I$ ( HDF5_DIR ) / include
LIBS = \
- L$ ( QUESO_DIR ) / lib - lqueso \
- L$ ( BOOST_DIR ) / lib - l b o o s t _ p r o g r a m _ o p t i o n s \
- L$ ( GSL_DIR ) / lib - lgsl \
- L$ ( HDF5_DIR ) / lib - lhdf5
CXX = mpic ++
CXXFLAGS += -g - Wall -c
default : all
. SUFFIXES : . o . C
all :

example_sfp

clean :
rm -f *~
rm -f *. o
rm -f s i m p l e _ s f p _ e x a m p l e
example_sfp : s i m p l e _ s f p _ e x a m p l e _ m a i n . o s i m p l e _ s f p _ e x a m p l e _ q o i . o s i m p l e _ s f p _ e x a m p l e _ c o m p u t e . o
$ ( CXX ) s i m p l e _ s f p _ e x a m p l e _ m a i n . o \
simple_sfp_example_qoi .o \
simple_sfp_example_compute .o \
-o s i m p l e _ s f p _ e x a m p l e $ ( LIBS )
%. o : %. C
$ ( CXX ) $ ( INC_PATHS ) $ ( CXXFLAGS ) $ <

Listing 5.18: Makefile for the application code in Listings 5.12–5.16
Thus, to compile, build and execute the code, the user just needs to run the following
commands in the same directory where the files are:
$ cd HOME / LIBRARIES / QUESO -0.50.0/ examples / s i m p l e S t a t i s t i c a l F o r w a r d P r o b l e m
$ export L D_ L IB RA RY _ PA TH = $ L D _ L I B R A R Y _ P A T H :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib
$ make -f M a k e f i l e _ s f p _ e x a m p l e _ m a r g a r i d a
$ ./ s i m p l e _ s f p _ e x a m p l e s i m p l e _ s f p _ e x a m p l e . inp

The ‘export’ instruction above is only necessary if the user has not saved it in his/her
.bashrc file.

5.2.5 Data Post-Processing and Visualization
This section discusses the results computed by QUESO with the code of Section 5.2.2, and
shows how to use Matlab for the post-processing of the data generated by QUESO when
solving SFPs. Only the essential Matlab commands are presented; for the complete/detailed
codes, please refer to file ’simple_fp_plots.m’.

CHAPTER 5. QUESO EXAMPLES

72

According to the specifications of the input file in Listing 5.17, a folder named ‘outputData’
containing the following files should be created: display_sub0.txt, fp_p_seq.m,
fp_p_seq_sub0.m, fp_q_seq.m, fp_q_seq_sub0.m, and sfpOutput_sub0.m.
The code below shows how to load the data provided by QUESO during the solution
process of the SFP described, in the form of chains of positions.
% inside Matlab
>> clear all
>> fp_p_seq . m
>> fp_q_seq . m

Listing 5.19: Matlab code for loading the data in both parameter and QoI chains of the SFP.
Alternatively, the user may call the file simple fp plots.m, which contains the above
commands, together with a variety of others, for data visualization:
% inside Matlab
>> clear all
>> si mp le _ fp _p lo t s

Listing 5.20: Matlab code for loading the data in both parameter and QoI chains of the SFP,
by calling the file simple fp plots.m.

5.2.5.1 Histogram Plots
In order to plot a histogram of the QoI, you may use the pre-defined Matlab function hist.
The Matlab code presented in Listing 5.21 below shows how to create the Figure 5.2.1.
% inside Matlab
>> fp_q_seq % if commands of Listings 3.19/3.20 have not been called
>> nbins =20;
>> hist ( fp_mc_QoiSeq_unified , nbins ) ;
>> title ( ’ QoI Histogram ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ QoI =\ theta_1 +\ theta_2 ’ , ’ fontname ’ , ’ Times ’ , ’ fontsize ’ ,20)
>> ylabel ( ’ Frequency ’ , ’ fontsize ’ ,20) ;

Listing 5.21: Matlab code for the QoI histogram plot.

5.2.5.2 KDE Plot
Matlab function ksdensity (Kernel smoothing density estimate) together with the option
‘pdf’ may be used to estimate the KDE of the QoI.
% inside Matlab
>> fp_q_seq % if commands of Listing 5.19 have not been called
>> [ fi , xi ] = ksdensity ( fp_mc_QoiSeq_unified , ’ function ’ , ’ pdf ’) ;
>> x = sort ( f p _ m c _ Q o i S e q _ u n i f i e d ) ;
>> mu =1;
>> sigma2 =5;
>> f =( exp ( -(x - mu ) .*( x - mu ) / sigma2 /2) ) / sqrt (2* pi * sigma2 ) ;

CHAPTER 5. QUESO EXAMPLES
>>
>>
>>
>>

73

plot ( xi , fi , ’ -m ’ , ’ linewidth ’ ,4) ;
hold ;
plot (x ,f , ’ - -k ’ , ’ linewidth ’ ,2) ;
h = legend ( ’ QoI = \ theta_1 +\ theta_2 ’ , ’ analytical ’ , ’ location ’ , ’ northwest ’) ;

Listing 5.22: Matlab code for the KDE displayed in Figure 5.2.2

5.2.5.3 CDF Plot
Matlab function ksdensity with ’cdf’ option may also be used for plotting the Cumulative
Distribution Function of the QoI.
% inside Matlab
>> fp_q_seq % if commands of Listing 5.19 have not been called
>> [f , xi ] = ksdensity ( fp_mc_QoiSeq_unified , ’ function ’ , ’ cdf ’) ;
>> plot ( xi ,f , ’ -m ’ , ’ linewidth ’ ,3)

Listing 5.23: Matlab code for the QoI CDF plot displayed in Figure 5.2.3.

5.3 gravity
This section presents an example of how to use QUESO in order to develop an application
that solves a statistical inverse problem and a statistical forward problem, where the solution
of the former serves as input to the later. During the SIP, the acceleration due to gravity for
an object in free fall near the surface of the Earth is inferred. During the SFP, the distance
traveled by a projectile launched at a given angle and altitude is calculated using the calibrated
magnitude of the acceleration of gravity.
In this section we describe a statistical forward problem of predicting the described in
Section 5.3.1.

5.3.1 Statistical Inverse Problem
A possible deterministic mathematical model for the vertical motion of an object in free fall
near the surface of the Earth is given by
1
h(t) = − gt2 + v0 t + h0 .
2

(5.3.1)

where v0 [m/s] is the initial velocity, h0 [m] is the initial altitude, h(t) [m] is the altitude with
respect to time, t [s] is the elapsed time, and g [m/s2 ] is the magnitude of the acceleration
due to gravity (the parameter which cannot be directly measured and will be statistically
inferred).

CHAPTER 5. QUESO EXAMPLES

74

Figure 5.2.1: QoI histogram.

Figure 5.2.2: Kernel Density Estimation. QUESO results
are plotted against the PDF of a


1
1
2
√
Gaussian distribution Q(x) = 10π exp − 10 (x − 1) , where µ = 1 and σ 2 = 5.

Figure 5.2.3: Cumulative Distribution Function.

CHAPTER 5. QUESO EXAMPLES

75

5.3.1.1 Experimental Data
We assume that the experiment of allowing an object to fall from different altitudes with zero
initial velocity has been repeatedly conducted (See Figure 5.3.1). The data collected, e.g.
d, is displayed in Table 5.3.1; the standard deviations, σ’s, refer to the uncertainties in the
measured times during the experiment execution [1].
v0 = 0
6
?
u

h0

h(t) = − 12 g t2 + h0

?

Figure 5.3.1: An object falls from altitude h0 with zero initial velocity (v0 = 0).

Table 5.3.1: Measurement data d of size nd = 14. The object falls from altitude h0 in t
seconds, with standard deviation of σ seconds in the time measurement [1].
altitude [m]

time [s]

Std. Dev. σ [s]

10
20
30
40
50
60
70
80
90
100
110
120
130
140

1.41
2.14
2.49
2.87
3.22
3.49
3.81
4.07
4.32
4.47
4.75
4.99
5.16
5.26

0.02
0.12
0.02
0.01
0.03
0.01
0.03
0.03
0.03
0.05
0.01
0.04
0.01
0.09

5.3.1.2 The Prior RV, Likelihood and Posterior RV
In a straightforward classical interpretation of Bayesian inference, the prior signifies the modeler’s honest opinion about the unknown. For the gravity inference problem, let’s assume

CHAPTER 5. QUESO EXAMPLES

76

that gravity varies uniformly in the interval [8,11], or, in other words, we chose uniform prior
distribution in that interval:
πprior = U(8, 11).
We choose the usual likelihood function:


1
−1
T
πlike (d|θ) ∝ exp − [y(θ) − d] [C(θ)] [y(θ) − d] ,
2

(5.3.2)

(5.3.3)

where C(θ) is a given covariance matrix, d denotes experimental data, y(θ) is the model
output data.
Recalling the deterministic model for the acceleration of gravity (5.3.1) with zero initial
velocity, the information provided in Table 5.3.1, and Equation (5.3.3); and, additionally,
invoking the nomenclature used in Section 1.2, we have:

 r
2h1






 r g 
σ12 0 · · · 0
t1


2h2 
 0 σ2 · · · 0 
 t2 

2
def.





g 
θ = g, y(θ) = 
 , (5.3.4)
 , d =  ..  , C(θ) =  ..
.. . .






.
.
0
.
.
.
..


2

 r
0 0 · · · σnd
tnd

2hnd 
g
where nd = 14 is the number of data points in Table 5.3.1.
Now we are ready to evoke Bayes’ formula in order to obtain the posterior PDF πpost (θ):
πpost (θ|d) ∝ πlike (d|θ) πprior (θ).

(5.3.5)

5.3.2 Statistical Forward Problem
Projectile motion refers to the motion of an object projected into the air at an angle, e.g. a
soccer ball being kicked, a baseball being thrown, or an athlete long jumping. Supposing the
object does not have a propulsion system and neglecting air resistance, then the only force
acting on the object is a constant gravitational acceleration g.
A possible deterministic two-dimensional mathematical model for the vertical motion of
an object projected from near the surface of the Earth is given by
vx = v0x
vy = v0y − gt
x = v0x t
1
h = h0 + v0y t − gt2
2

(5.3.6)
(5.3.7)
(5.3.8)
(5.3.9)

CHAPTER 5. QUESO EXAMPLES

77

g

v0
α
y0
x
Figure 5.3.2: Object traveling with projectile motion.
where h0 is the initial height, x = x(t) is the distance traveled by the object, v0 = (v0x , v0y )
is the initial velocity, v0x = v0 cos(α), v0y = v0 sin(α), and v0 = kv0 k2 . Figure 5.3.2 displays
the projectile motion of an object in these conditions.
For this example, we assume that h0 = 0 m, α = π/4 radians, v0 = 5 m/s, all deterministic
variables; and g is the solution of the SIP described in Section 5.3.1.
Since a PDF is assigned to parameter g; thus, the output of the mathematical model
(5.3.6) becomes a random variable, thus we have a statistical forward problem.

5.3.2.1 The Input RV, QoI Function and Output RV
The input random variable for the statistical forward problem is the acceleration of gravity
g, which is also the solution (posterior PDF) of the inverse problem described in Section
5.3.1. The output random variable for this example is the distance x traveled by an object
in projectile motion. Note that, since there is uncertainty in the parameter g (g is given as a
PDF), one can expect that this uncertainty will be propagated to x, which will also be given
as a PDF.
Combining the expressions in Equation 5.3.6 and rearranging them, we have that QoI
function for x is:

p
v0 cos α 
v0 sin α + (v0 sin α)2 + 2g y0 .
(5.3.10)
x=
g
where y is the distance traveled and our quantity of interest (QoI).

5.3.3 Running the Example
To run the executable provided (available after QUESO installation), enter the following
commands:
$ cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / gravity
$ rm outputData /*
$ ./ gravity_gsl g ra vi t y_ in v_ f wd . inp

CHAPTER 5. QUESO EXAMPLES

78

The console output of the program is:
k em el li @ vi ol et a :~/ LIBRARIES / QUESO -0.50.0/ examples / gravity$ ./ gravity_gsl g ra vi t y_ in v_ f wd . inp
--------------------------------------------------------------------QUESO Library : Version = 0.47.1 (47.1)
Development Build
Build
Build
Build
Build
Build

Date
Host
User
Arch
Rev

C ++ Config

=
=
=
=
=

2013 -04 -29 17:05
violeta
kemelli
x86_64 - unknown - linux - gnu
38998 M

= mpic ++ -g - O2 - Wall

Trilinos DIR =
GSL Libs
= -L / home / kemelli / LIBRARIES / gsl -1.15/ lib - lgsl - lgslcblas - lm
GRVY DIR
=
GLPK DIR
=
HDF5 DIR
= / home / kemelli / LIBRARIES / hdf5 -1.8.10
-------------------------------------------------------------------------------------------------------Beginning run at Mon Apr 29 17:27:32 2013
MPI node of worldRank 0 has fullRank 0 , belongs to s ubEnviro nment of id 0 , and has subRank 0
MPI node of worldRank 0 belongs to sub communicator with full ranks 0
MPI node of worldRank 0 also belongs to inter0 communicator with full ranks 0 , and has
inter0Rank 0

Beginning run of ’ Gravity + Projectile motion ’ example at Mon Apr 29 17:27:32 2013
my
my
my
my

fullRank = 0
subEnvironmentId = 0
subRank = 0
interRank = 0

Beginning ’ SIP -> Gravity estimation ’ at Mon Apr 29 17:27:32 2013
Solving the SIP with Metropolis Hastings
Beginning ’ SFP -> Projectile motion ’ at Mon Apr 29 17:27:33 2013
Solving the SFP with Monte Carlo
Ending run of ’ Gravity + Projectile motion ’ example at Mon Apr 29 17:27:33 2013
Ending run at Mon Apr 29 17:27:33 2013
Total run time = 1 seconds
k em el li @ vi ol et a :~/ LIBRARIES / QUESO -0.50.0/ examples / gravity$

Listing 5.24: Console output of program gravity gsl
In order to generate chain plots, histograms, KDEs, etc., the user may use Matlab/GNU
Octave and call the following command lines:
$ matlab
$ g r a v i t y _ p l o t s _ ip
$ g r a v i t y _ p l o t s _ fp
$ exit
$ ls -l outputData /*. png

# i n s i d e matlab
# i n s i d e matlab
# i n s i d e matlab

CHAPTER 5. QUESO EXAMPLES
s f p _ g r a v i t y _ a u t o c o r r e l a t i o n . png
s f p _ g r a v i t y _ c h a i n _ p o s . png
s fp _g ra v it y_ kd e . png
s i p _ g r a v i t y _ c d f _ f i l t . png
s i p _ g r a v i t y _ c h a i n _ p o s _ f i l t . png
s i p _ g r a v i t y _ h i s t _ f i l t . png
s i p _ g r a v i t y _ k d e _ f i l t . png

79

sf p _g ra vi t y_ cd f . png
s f p _ g r a v i t y _ h i s t . png
s i p _ g r a v i t y _ a u t o c o r r e l a t i o n _ r a w _ f i l t . png
s i p _ g r a v i t y _ c d f _ r a w . png
s i p _ g r a v i t y _ c h a i n _ p o s _ r a w . png
s i p _ g r a v i t y _ h i s t _ r a w . png
s i p _ g r a v i t y _ k d e _ r a w . png

As a result, the user should have created several of PNG figures containing marginal posterior PDF, chain positions of the parameters and the QoI, histogram, cumulative density
distribution and autocorrelation. The name of the figure files have been chosen to be informative, as shown in the Listing above.

5.3.4 Example Code
The source code for the SIP and the SFP is composed of 7 files. Three of them are common for
both problems: gravity main.C, gravity compute.h and gravity compute.C; they combine both problems and use the solution of the SIP (the posterior PDF for the gravity) as
an input for the SFP and are presented, respectively, in Listings 5.25, 5.26 and 5.27. Two of
files specifically handle the SIP: gravity likelihood.h, and gravity likelihood.C, and are
displayed in Listings 5.28 and 5.29. Finally, the files specific for the SFP are gravity qoi.h
and gravity qoi.C, and they are presented in Listings 5.30 and 5.31.
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - * Brief description of this file :
*
* This is an example of how to use QUESO classes and algorithms in order to define and solve
* a statistical inverse problem ( SIP ) and / or a statistical forward problem ( SFP ) .
* The SIP consists on calibrating the magnitude ’g ’ of acceleration gravity using
* measurements of the time that it takes for an object in free fall to reach the ground from
* a given height and zero initial velocity . The solution of the SIP is the posterior
* probability density function ( PDF ) of ’g ’.
* The SFP consists of calculating the maximum distance traveled by an object in projectile
* motion . The posterior PDF of ’g ’ from the SIP might be used as input to the SFP .
*
* The code consists of 7 files :
* - ’ gravity_main .C ’ ( this file )
* - ’ g ra vi t y_ co mp u te .C ’ ( the driving application code )
* - ’ g ra vi t y_ co mp u te .h ’
* - ’ g r a v i t y _ l i k e l i h o o d .C ’ ( necessary for the SIP )
* - ’ g r a v i t y _ l i k e l i h o o d .h ’
* - ’ gravity_qoi .C ’ ( necessary for the SFP )
* - ’ gravity_qoi .h ’
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/
#i n c l u d e 
int main ( int argc , char * argv [])
{
// Initialize QUESO environment
MPI_Init (& argc ,& argv ) ;
QUESO :: Fu ll En v ir on me n t * env =
new QUESO :: Fu ll En v ir on me n t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;
// Call application
c o m p u t e G r a v i t y A n d T r a v e l e d D i s t a n c e (* env ) ;

CHAPTER 5. QUESO EXAMPLES

80

// Finalize QUESO environment
delete env ;
MPI_Finalize () ;
return 0;
}

Listing 5.25: File gravity main.C.
#i f n d e f EX COMPUTE H
#d e f i n e EX COMPUTE H
#i n c l u d e 
void c o m p u t e G r a v i t y A n d T r a v e l e d D i s t a n c e ( const QUESO :: F u ll En vi r on me nt & env ) ;
#e n d i f

Listing 5.26: File gravity compute.h.
1

6

11

16

21

/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - * This file is divided in two parts :
* - the first one handles the statistical inverse problem ( SIP ) for estimating the magnitude
* ’g ’ of gravity acceleration ; and
* - the second part handles the statistical forward problem ( SFP ) for predicting the maximum
* distance traveled by a projectile .
*
* The SIP definition requires a user defined likelihood function ; refer to files
* ’ g r a v i t y _ l i k e l i h o o d .h ’ and ’ g r a v i t y _ l i k e l i h o o d .C ’. The SFP definition requires a user
* defined qoi function ; refer to files ’ gravity_qoi .h ’ and ’ gravity_qoi .C ’.
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e


< g r a v i t y l i k e l i h o o d . h>
< g r a v i t y q o i . h>











26

31

//================================================================
// If P R I O R _ I S _ G A U S S I A N is defined , then :
// --> Gaussian prior for gravity .
// Otherwise :
// --> Uniform prior for gravity .
//================================================================
//#d e f i n e PRIOR IS GAUSSIAN

36 void c o m p u t e G r a v i t y A n d T r a v e l e d D i s t a n c e ( const QUESO :: F u ll En vi r on me nt & env ) {
struct timeval timevalNow ;
gettimeofday (& timevalNow , NULL ) ;

CHAPTER 5. QUESO EXAMPLES

41

46

51

56

61

66

71

76

81

86

91

96

if ( env . fullRank () == 0) {
std :: cout << " \ nBeginning run of ’ Gravity +
<< ctime (& timevalNow . tv_sec )
<< " \ n my fullRank = "
<<
<< " \ n my s u b E n v i r o n m e n t I d = " <<
<< " \ n my subRank = "
<<
<< " \ n my interRank = "
<<
<< std :: endl << std :: endl ;
}

81

Projectile motion ’ example at "
env . fullRank ()
env . subId ()
env . subRank ()
env . inter0Rank ()

// Just examples of possible calls
if (( env . subDisp layFile ()
) &&
( env . d i s p l a y V e r b os i t y () >= 2) ) {
* env . sub DisplayF ile () << " Beginning run of ’ Gravity + Projectile motion ’ example at "
<< ctime (& timevalNow . tv_sec )
<< std :: endl ;
}
env . fullComm () . Barrier () ;
env . subComm () . Barrier () ; // Just an example of a possible call
//================================================================
// Statistical inverse problem ( SIP ) : find posterior PDF for ’g ’
//================================================================
gettimeofday (& timevalNow , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Beginning ’ SIP -> Gravity estimation ’ at "
<< ctime (& timevalNow . tv_sec )
<< std :: endl ;
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 1 of 6: Instantiate the parameter space
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix > paramSpace ( env , " param_ " , 1 , NULL ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 2 of 6: Instantiate the parameter domain
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GslVector paramMin Values ( paramSpace . zeroVector () ) ;
QUESO :: GslVector paramMax Values ( paramSpace . zeroVector () ) ;
para mMinValu es [0] = 8.;
para mMaxValu es [0] = 11.;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " param_ " ,
paramSpace ,
paramMinValues ,
param MaxValu es ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 3 of 6: Instantiate the likelihood function
// object to be used by QUESO .
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - l i k e l i h o o d R o u t i n e _ D a t a l i k e l i h o o d R o u t i n e _ D a t a ( env ) ;
QUESO :: GenericScalarFunction < QUESO :: GslVector , QUESO :: GslMatrix >
l i k e l i h o o d F u n c t i o n O b j ( " like_ " ,
paramDomain ,
likelihoodRoutine ,
( void *) & likelihoodRoutine_Data ,
true ) ; // the routine computes [ ln ( function ) ]

101
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 4 of 6: Define the prior RV
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

CHAPTER 5. QUESO EXAMPLES

106 #i f d e f PRIOR IS GAUSSIAN
QUESO :: GslVector meanVector ( paramSpace . zeroVector () ) ;
meanVector [0] = 9;

111

QUESO :: GslMatrix covMatrix = QUESO :: GslMatrix ( paramSpace . zeroVector () ) ;
covMatrix (0 ,0) = 1.;
// Create a Gaussian prior RV
QUESO :: GaussianVectorRV < QUESO :: GslVector , QUESO :: GslMatrix > priorRv ( " prior_ " , paramDomain ,
meanVector , covMatrix ) ;

116 #e l s e
// Create an uniform prior RV
QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix > priorRv ( " prior_ " , paramDomain ) ;
#e n d i f

121

126

131

136

141

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 5 of 6: Instantiate the inverse problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
postRv ( " post_ " , // Extra prefix before the default " rv_ " prefix
paramSpace ) ;
QUESO :: StatisticalInverseProblem < QUESO :: GslVector , QUESO :: GslMatrix >
ip ( " " ,
// No extra prefix before the default " ip_ " prefix
NULL ,
priorRv ,
likelihoodFunctionObj ,
postRv ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SIP Step 6 of 6: Solve the inverse problem , that is ,
// set the ’pdf ’ and the ’ realizer ’ of the posterior RV
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - std :: cout << " Solving the SIP with Metropolis Hastings "
<< std :: endl << std :: endl ;
QUESO :: GslVector paramInitials ( paramSpace . zeroVector () ) ;
priorRv . realizer () . realization ( paramInitials ) ;

146

QUESO :: GslMatrix p r o p o s a l C o v M a t r i x ( paramSpace . zeroVector () ) ;
p r o p o s a l C o v M a t r i x (0 ,0) = std :: pow ( fabs ( paramInitials [0]) /20. , 2. ) ;
ip . s o l v e W i t h B a y e s M e t r o p o l i s H a s t i n g s ( NULL , paramInitials , & p r o p o s a l C o v M a t r i x ) ;

151

156

161

166

//================================================================
// Statistical forward problem ( SFP ) : find the max distance
// traveled by an object in projectile motion ; input pdf for ’g ’
// is the solution of the SIP above .
//================================================================
gettimeofday (& timevalNow , NULL ) ;
std :: cout << " Beginning ’ SFP -> Projectile motion ’ at "
<< ctime (& timevalNow . tv_sec )
<< std :: endl ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SFP Step 1 of 6: Instantiate the parameter * and * qoi spaces .
// SFP input RV = FIP posterior RV , so SFP parameter space
// has been already defined .
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix > qoiSpace ( env , " qoi_ " , 1 , NULL ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

82

CHAPTER 5. QUESO EXAMPLES

83

// SFP Step 2 of 6: Instantiate the parameter domain
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

171
// Not necessary because input RV of the SFP = output RV of SIP .
// Thus , the parameter domain has been already defined .

176

181

186

191

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SFP Step 3 of 6: Instantiate the qoi function object
// to be used by QUESO .
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - q oi Ro ut i ne _D at a qo iR o ut in e_ D at a ;
q oi Ro ut i ne _D at a . m_angle
= M_PI /4.0; //45 degrees ( radians )
q oi Ro ut i ne _D at a . m _ i n i t i a l V e l o c i t y = 5.;
// initial speed ( m / s )
q oi Ro ut i ne _D at a . m _ in it ia l He ig ht = 0.;
// initial height ( m )
QUESO :: GenericVectorFunction < QUESO :: GslVector , QUESO :: GslMatrix , QUESO :: GslVector , QUESO ::
GslMatrix >
qoiF unctionO bj ( " qoi_ " ,
paramDomain ,
qoiSpace ,
qoiRoutine ,
( void *) & q oi R ou ti ne _ Da ta ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SFP Step 4 of 6: Define the input RV
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

196

// Not necessary because input RV of SFP = output RV of SIP
// ( postRv ) .

201

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SFP Step 5 of 6: Instantiate the forward problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix > qoiRv ( " qoi_ " , qoiSpace ) ;

206

211

QUESO :: StatisticalForwardProblem < QUESO :: GslVector , QUESO :: GslMatrix , QUESO :: GslVector , QUESO ::
GslMatrix >
fp ( " " ,
NULL ,
postRv ,
qoiFunctionObj ,
qoiRv ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // SFP Step 6 of 6: Solve the forward problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - std :: cout << " Solving the SFP with Monte Carlo "
<< std :: endl << std :: endl ;
fp . s o l v e W i t h M o n t e C a r l o ( NULL ) ;

216

221

226

231

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - gettimeofday (& timevalNow , NULL ) ;
if (( env . subDisp layFile ()
) &&
( env . d i s p l a y V e r b os i t y () >= 2) ) {
* env . sub DisplayF ile () << " Ending run of ’ Gravity + Projectile motion ’ example at "
<< ctime (& timevalNow . tv_sec )
<< std :: endl ;
}
if ( env . fullRank () == 0) {
std :: cout << " Ending run of ’ Gravity + Projectile motion ’ example at "
<< ctime (& timevalNow . tv_sec )
<< std :: endl ;
}
return ;

CHAPTER 5. QUESO EXAMPLES

84

}

Listing 5.27: File gravity compute.C. The first part of the code (lines 60–150) handles the
statistical forward problem, whereas the second part of the code (lines 151–216) handles the
statistical forward problem.

#i f n d e f
#d e f i n e

GRAVITY LIKELIHOOD H
GRAVITY LIKELIHOOD H

#i n c l u d e 
struct l i k e l i h o o d R o u t i n e _ D a t a // user defined class
{
l i k e l i h o o d R o u t i n e _ D a t a ( const QUESO :: B as eE nv i ro nm en t & env ) ;
~ l i k e l i h o o d R o u t i n e _ D a t a () ;
std :: vector < double > m_heights ; // heights
std :: vector < double > m_times ;
// times
std :: vector < double > m_stdDevs ; // account for uncertainties in
// time measurement : sigmas
const QUESO :: B as eE n vi ro nm e nt * m_env ;
};
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *

// user defined routine
paramValues ,
paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect ) ;

#e n d i f

Listing 5.28: File gravity likelihood.h.
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e

< g r a v i t y l i k e l i h o o d . h>

< s t d i o . h>


// Construtor
l i k e l i h o o d R o u t i n e _ D a t a :: l i k e l i h o o d R o u t i n e _ D a t a ( const QUESO :: B as eE n vi ro nm e nt & env )
:
m_heights (0) ,
m_times (0) ,
m_stdDevs (0) ,
m_env
(& env )
{
// Data available in / inputData / data02 . dat
double const heights [] = {10 ,20 ,30 ,40 ,50 ,60 ,70 ,80 ,90 ,100 ,110 ,120 ,130 ,140};
double const times [] = {1.41 ,2.14 ,2.49 ,2.87 ,3.22 ,3.49 ,3.81 ,4.07 ,4.32 ,4.47 ,
4.75 ,4.99 ,5.16 ,5.26};
double const stdDevs [] = {0.020 ,0.120 ,0.020 ,0.010 ,0.030 ,0.010 ,0.030 ,0.030 ,
0.030 ,0.050 ,0.010 ,0.040 ,0.010 ,0.09};
std :: size_t const n = sizeof ( heights ) / sizeof (* heights ) ;
m_heights . assign ( heights , heights + n ) ;

CHAPTER 5. QUESO EXAMPLES

85

m_times . assign ( times ,
times
+ n);
m_stdDevs . assign ( stdDevs , stdDevs + n ) ;
}
// Destructor
l i k e l i h o o d R o u t i n e _ D a t a ::~ l i k e l i h o o d R o u t i n e _ D a t a ()
{
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // The user defined likelihood routine
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector & paramValues ,
const QUESO :: GslVector * paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector *
gradVector ,
QUESO :: GslMatrix *
hessianMatrix ,
QUESO :: GslVector *
hessianEffect )
{
const QUESO :: B as eE n vi ro nm e nt & env = *((( l i k e l i h o o d R o u t i n e _ D a t a *) f u nc ti on D at aP tr ) -> m_env ) ;
if ( paramDir ection && f u nc ti on D at aP tr && gradVector && hessianMatrix && hessianEffect )
{
// Just to eliminate INTEL compiler warnings
}
env . subComm () . Barrier () ;
// The user , at the application level , should have set
// the vector ’ paramValues ’ to have size 1.
U Q _ F A T A L _ T E S T _ M A C R O ( paramValues . sizeGlobal () != 1 ,
env . fullRank () ,
" l i k e l i h o o d R o u t i n e () " ,
" paramValues vector does not have size 1 " ) ;
// Compute likelihood
double g = paramValues [0];
const std :: vector < double >& heights =(( l i k e l i h o o d R o u t i n e _ D a t a *) f un ct i on Da t aP tr ) -> m_heights ;
const std :: vector < double >& times =(( l i k e l i h o o d R o u t i n e _ D a t a *) fu n ct io nD a ta Pt r ) -> m_times ;
const std :: vector < double >& stdDevs =(( l i k e l i h o o d R o u t i n e _ D a t a *) f un ct i on Da t aP tr ) -> m_stdDevs ;
double misfitValue = 0.;
for ( unsigned int i = 0; i < heights . size () ; ++ i ) {
double modelTime = sqrt (2.0 * heights [ i ]/ g ) ;
double ratio = ( modelTime - times [ i ]) / stdDevs [ i ];
misfitValue += ratio * ratio ;
}
return ( -0.5* misfitValue ) ;
}

Listing 5.29: File gravity likelihood.C.
#i f n d e f
#d e f i n e

GRAVITY QOI H
GRAVITY QOI H

#i n c l u d e 
#i n c l u d e 
struct
q oi Ro ut i ne _D at a
{

CHAPTER 5. QUESO EXAMPLES
double m_angle ;
double m _ i n i t i a l V e l o c i t y ;
double m _i n it ia lH e ig ht ;
};
void
qoiRoutine (
const QUESO :: GslVector &
paramValues ,
const QUESO :: GslVector *
paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector &
qoiValues ,
QUESO :: DistArray < QUESO :: GslVector * >* gradVectors ,
QUESO :: DistArray < QUESO :: GslMatrix * >* hessianMatrices ,
QUESO :: DistArray < QUESO :: GslVector * >* h essianEf fects ) ;
#e n d i f

Listing 5.30: File gravity qoi.h.
#i n c l u d e < g r a v i t y q o i . h>
#i n c l u d e 
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - /// The actual ( user - defined ) qoi routine
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - void
qoiRoutine (
const QUESO :: GslVector &
paramValues ,
const QUESO :: GslVector *
paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector &
qoiValues ,
QUESO :: DistArray < QUESO :: GslVector * >* gradVectors ,
QUESO :: DistArray < QUESO :: GslMatrix * >* hessianMatrices ,
QUESO :: DistArray < QUESO :: GslVector * >* hessi anEffect s )
{
const QUESO :: B as eE n vi ro nm e nt & env = paramValues . env () ;
if ( paramDir ection &&
gradVectors
&&
hessi anEffec ts &&
h es si an M at ri ce s ) {
// Logic just to avoid warnings from INTEL compiler
}
// The user , at the application level , should have set
// the vector ’ paramValues ’ to have size 1 and
// the vector ’ qoiValues ’ to have size 1.
U Q _ F A T A L _ T E S T _ M A C R O ( paramValues . sizeGlobal () != 1 ,
env . fullRank () ,
" qoiRoutine () " ,
" paramValues vector does not have size 1 " ) ;
U Q _ F A T A L _ T E S T _ M A C R O ( qoiValues . sizeGlobal () != 1 ,
env . fullRank () ,
" qoiRoutine () " ,
" qoiValues vector does not have size 1 " ) ;
// Compute qoi ( s )
double g = paramValues [0]; // Sample of the RV ’ gravity acceleration ’
double d i s t a nc e T r a v e l e d = 0.;
if ( env . subRank () == 0) {
double velocity = (( qo iR o ut in e_ D at a *) f u nc ti on D at aP tr ) -> m _ i n i t i a l V e l o c i t y ;

86

CHAPTER 5. QUESO EXAMPLES
double heights
double alpha

87

= (( q oi Ro ut i ne _D at a *) fu nc t io nD at a Pt r ) -> m_ in it i al He ig h t ;
= (( qo iR ou t in e_ Da t a *) f un c ti on Da t aP tr ) -> m_angle ;

double aux
= velocity * sin ( alpha ) ;
d i s t a n c e T r a v e l ed = ( velocity * cos ( alpha ) / g ) * ( aux + sqrt ( pow ( aux ,2) + 2.* g * heights )
);
}
qoiValues [0] = d i s t a n c e T r a v e l e d ;
return ;
}

Listing 5.31: File gravity qoi.C.

5.3.5 Input File
QUESO reads an input file for solving statistical problems. In the case of a SIP, it expects a
list of options for MCMC, while in case of SFP it expects a list of options for Monte Carlo.
The input file ‘gravity inv fwd.inp used in this example is presented in Listing 5.32.
###############################################
# UQ E n v i r o n m e n t
###############################################
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display_env
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0 1 2 3 4 5 6 7
env_displayVerbosity
= 2
env_seed
= -1
###############################################
# S t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
ip_computeSolution
= 1
ip_dataOutputFileName
= outputData / sip_gravity
ip_dataOutputAllowedSet = 0 1
###############################################
# I n f o r m a t i o n f o r M e t r o p o l i s −H a s t i n g s a l g o r i t h m
###############################################
ip_mh_dataOutputFileName
= outputData / sip_gravity
ip_mh_dataOutputAllowedSet = 0 1
ip_mh_rawChain_dataInputFileName
ip_mh_rawChain_size
ip_mh_rawChain_generateExtra
ip_mh_rawChain_displayPeriod
ip_mh_rawChain_measureRunTimes
ip_mh_rawChain_dataOutputFileName
ip_mh_rawChain_dataOutputAllowedSet

=
=
=
=
=
=
=

.
20000
0
2000
1
outputData / s i p _ g r a v i t y _ r a w _ c h a i n
0 1 2 3 4 5 6 7

ip_mh_displayCandidates
ip_mh_putOutOfBoundsInChain
ip_mh_dr_maxNumExtraStages
ip_mh_dr_listOfScalesForExtraStages
ip_mh_am_initialNonAdaptInterval
ip_mh_am_adaptInterval
ip_mh_am_eta

=
=
=
=
=
=
=

0
0
3
5. 10. 20.
0
100
1.98
#( 2 . 4 ˆ 2 ) /d , d i s t h e d i m e n s i o n o f t h e p r o b l e m

CHAPTER 5. QUESO EXAMPLES
i p _ m h _ a m _ e p s i lo n

88

= 1. e -5

ip_mh_filteredChain_generate
ip_mh_filteredChain_discardedPortion
ip_mh_filteredChain_lag
ip_mh_filteredChain_dataOutputFileName
ip_mh_filteredChain_dataOutputAllowedSet

=
=
=
=
=

1
0.
20
outputData / s i p _ g r a v i t y _ f i l t e r e d _ c h a i n
0 1

###############################################
# S t a t i s t i c a l forward problem ( fp )
###############################################
fp_help
= anything
fp_computeSolution
= 1
fp_computeCovariances
= 1
fp_computeCorrelations = 1
fp_dataOutputFileName
= outputData / sfp_gravity
fp_dataOutputAllowedSet = 0 1
###############################################
# ’ f p ’ : i n f o r m a t i o n f o r Monte C a r l o a l g o r i t h m
###############################################
fp_mc_help
= anything
fp_mc_dataOutputFileName
= outputData / sfp_gravity
fp_mc_dataOutputAllowedSet = 0 1
fp_mc_pseq_dataOutputFileName
= outputData / s f p _ g r a v i t y _ p _ s e q
fp_mc_pseq_dataOutputAllowedSet = 0 1
fp_mc_qseq_dataInputFileName
f p_ mc _q s eq _s iz e
fp_mc_qseq_displayPeriod
fp_mc_qseq_measureRunTimes
fp_mc_qseq_dataOutputFileName
fp_mc_qseq_dataOutputAllowedSet

=
=
=
=
=
=

.
16384
20000
1
outputData / s f p _ g r a v i t y _ q o i _ s e q
0 1

Listing 5.32: Some options for QUESO library used in application code (Listings 5.25-5.29).
Moreover, for the gravity inverse problem, one may notice that QUESO will use the
Metropolis-Hastings algorithm to sample the posterior PDF (indicated by the prefix mh in
the variable names) without adaptive steps (indicated by the zero value assigned to the variable
ip mh am initialNonAdaptInterval, which can also be achieved by setting zero to
ip_mh_am_adaptInterval) and with delayed rejection (indicated by the one-value assigned
to the variable ip mh dr maxNumExtraStages).

5.3.6 Create your own Makefile
Listing 5.33 presents a Makefile, named Makefile example violeta, that may be used to
compile the code and create the executable gravity_gsl. Naturally, it must be adapted to
the user’s settings, i.e., it has to have the correct paths for the user’s libraries that were
actually used to compile and install QUESO (see Sections 2.1–2.4).
##########################################################
# U s i n g i n s t a l l e d QUESO 0 . 5 0 . 0 , from e x t e r n a l r e l e a s e , i n ’ v i o l e t a ’
##########################################################
QUESO_DIR = / home / kemelli / LIBRARIES / QUESO -0.50.0

CHAPTER 5. QUESO EXAMPLES

89

BOOST_DIR = / home / kemelli / LIBRARIES / boost -1.53.0
GSL_DIR = / home / kemelli / LIBRARIES / gsl -1.15
HDF5_DIR = / home / kemelli / LIBRARIES / hdf5 -1.8.10
INC_PATHS = \
-I . \
- I$ ( QUESO_DIR ) / include \
- I$ ( BOOST_DIR ) / include \
- I$ ( GSL_DIR ) / include \
- I$ ( HDF5_DIR ) / include
LIBS = \
- L$ ( QUESO_DIR ) / lib - lqueso \
- L$ ( BOOST_DIR ) / lib - l b o o s t _ p r o g r a m _ o p t i o n s \
- L$ ( GSL_DIR ) / lib - lgsl \
- L$ ( HDF5_DIR ) / lib - lhdf5
CXX = mpic ++
CXXFLAGS += -g - Wall -c
default : all
. SUFFIXES : . o . C
all :

example_gravity_gsl

clean :
rm -f *~
rm -f *. o
rm -f gravity_gsl
e x a m p l e _ g r a v i t y _ g s l : gravity_main . o g r a v i t y _ l i k e l i h o o d . o gr a vi ty _c o mp ut e . o gravity_qoi . o
$ ( CXX ) gravity_main . o \
gravity_likelihood .o \
g ra vi ty _ co mp ut e . o \
gravity_qoi . o \
-o gravity_gsl $ ( LIBS )
%. o : %. C
$ ( CXX ) $ ( INC_PATHS ) $ ( CXXFLAGS ) $ <

Listing 5.33: Makefile for the application code in Listings 5.25-5.29

5.3.7 Running the Gravity Example with Several Processors
Even though the application described in Section 5.3.4 is a serial code, it is possible to run it
using more than one processor, i.e., in parallel mode. Supposing the user’s workstation has
Np = 8 processors, then, the user my choose to have Ns = 8, 4 or 2 subenvironments. This
complies with the requirement that the total number of processors in the environment must
be a multiple of the specified number of subenvironments.
Thus, to build and run the application code with Np = 8, and Ns = 8 subenvironments,
the must set the variable env numSubEnvironments = 8 in the input file (Listing 5.32) and
enter the following command lines:
cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / gravity /
mpirun - np 8 ./ gravity_gsl g r av it y _i nv _f w d . inp

CHAPTER 5. QUESO EXAMPLES

90

The steps above will create a total number of 8 raw chains, of size defined by the variable ip mh rawChain size. QUESO internally combines these 8 chains into a single chain
of size 8 × ip mh rawChain size and saves it in a file named according to the variable
ip mh rawChain dataOutputFileName. QUESO also provides the user with the option of
writing each chain – handled by its corresponding processor – in a separate file, which is accomplished by setting the variable ip mh rawChain dataOutputAllowedSet = 0 1 ... Ns-1.
Note: Although the discussion in the previous paragraph refers to the raw chain of a SIP,
the analogous is true for the filtered chains (SIP), and for the samples employed in the SFP
(ip mh filteredChain size, fp mc qseq size and fp mc qseq size, respectively).

5.3.8 Data Post-Processing and Visualization
According to the specifications of the input file in Listing 5.32, both a folder named outputData
and a the following files should be generated:
sfp_gravity_sub0.m,
sfp_gravity_p_seq.m,
sfp_gravity_p_seq_sub0.m
sfp_gravity_qoi_seq.m,
sfp_gravity_qoi_seq_sub0.m
display_env_sub0.txt

sip_gravity_sub0.m,
sip_gravity_filtered_chain.m,,
sip_gravity_filtered_chain_sub0.m,
sip_gravity_raw_chain.m,
sip_gravity_raw_chain_sub0.m,

In this section, a convenient capability of QUESO of internally handling possible conflicts in chain size is presented. Recalling the input file gravity_inv_fwd.inp presented in
Listing 5.32, one may notice that the raw chain size for the SIP is chosen to have 20000
positions (ip_mh_rawChain_size = 20000); the lag of the filtered chain is chosen to be
20 (ip_mh_filteredChain_lag = 20) and the chain size for the SFP has 16384 positions
(fp_mc_qseq_size = 16384). Because the solution of the SIP, ie, the posterior PDF, is used
as input PDF for the SFP, QUESO internally sets fp_mc_qseq_size = 20000, as can be seen
in the file display_env_sub0.txt. The file display_env_sub0.txt contains information
from the subenvironment ‘0’ that was generated during the run of the application code.

5.3.8.1 Statistical Inverse Problem
There are a few Matlab-ready commands that are very helpful tools for post-processing the
data generated by QUESO when solving statistical inverse problems. This section discusses
the results computed by QUESO with the code of Section 5.3.4, and shows how to use Matlab
for the post-processing of such results.
5.3.8.1.1 Chain Plots
It is quite simple to plot, using Matlab, the chain of positions used in the DRAM algorithm
implemented within QUESO. The sequence of Matlab commands presented in Listing 5.34
generates the graphic depicted in Figure 5.3.3a. Figure 5.3.3b is obtained analogously.

CHAPTER 5. QUESO EXAMPLES

91

% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n
>> plot ( i p _ m h _ r a w C h a i n _ u n i f i e d )
>> ylabel ( ’\ theta =g ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Number of positions ’ , ’ fontsize ’ ,20) ;
>> title ( ’ DRAM Chain Positions ( raw ) ’,’ fontsize ’ ,20) ;

Listing 5.34: Matlab code for the chain plot.

5.3.8.1.2 Histogram Plots
In order to plot histograms of the parameter using either the raw chain or the filtered
chain, you simply have to use the pre-defined Matlab function hist.
% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n
>> nbins =100;
>> hist ( ip_mh_rawChain_unified , nbins )
>> title ( ’ Parameter Histogram ( raw chain ) ’,’ fontsize ’ ,20) ;
>> xlabel ( ’ Gravity ( m / s ^2) ’,’ fontsize ’ ,20) ;
>> ylabel ( ’ Frequency ’ , ’ fontsize ’ ,20) ;
>> grid on ;

Listing 5.35: Matlab code for the histogram plot.

5.3.8.1.3 KDE Plots
Matlab function ksdensity (Kernel smoothing density estimate) together with the option
’pdf’ may be used for plotting the KDE of the parameter.
% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n
>> [f , xi ] = ksdensity ( ip_mh_rawChain_unified , ’ function ’ , ’ pdf ’) ;
>> plot ( xi ,f , ’ -b ’ , ’ linewidth ’ ,3)
>> title ( ’ Parameter Kernel Density Estimation ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Gravity ( m / s ^2) ’,’ fontsize ’ ,20) ;
>> ylabel ( ’ KDE ’ , ’ fontsize ’ ,20) ;
>> grid on ;

Listing 5.36: Matlab code for the KDE plot.

5.3.8.1.4 CDF Plots
Matlab function ksdensity (Kernel smoothing density estimate) with ’cdf’ option may
also be used for plotting the Cumulative Distribution Function of the parameter.
% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n
>> [f , xi ] = ksdensity ( ip_mh_rawChain_unified , ’ function ’ , ’ cdf ’) ;
>> plot ( xi ,f , ’ -b ’ , ’ linewidth ’ ,3)
>> title ( ’ Parameter Cumulative Distribution Function ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Gravity ( m / s ^2) ’,’ fontsize ’ ,20) ;
>> ylabel ( ’ CDF ’ , ’ fontsize ’ ,20) ;

CHAPTER 5. QUESO EXAMPLES

(a) Raw chain

92

(b) Filtered chain

Figure 5.3.3: MCMC raw chain with 20000 positions and a filtered chain with lag of 20
positions.

(a) Raw chain

(b) Filtered chain

Figure 5.3.4: Histograms of parameter θ = g.

(a) Raw chain

(b) Filtered chain

Figure 5.3.5: Kernel Density Estimation.

CHAPTER 5. QUESO EXAMPLES

93

>> grid on ;

Listing 5.37: Matlab code for the CDF plot.

5.3.8.1.5 Autocorrelation Plots
The code presented in Listing 5.38 uses matlab function autocorr to generate Figure 5.3.7
which presents the autocorrelation of the parameter g in both cases: raw and filtered chain.
% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n
>> s i p _ g r a v i t y _ f i l t e r e d _ c h a i n
>> nlags =10;
>> [ ACF_raw , lags , bounds ]= autocorr ( ip_mh_rawChain_unified , nlags , 0) ;
>> [ ACF_filt , lags , bounds ]= autocorr ( ip_mh_filtChain_unified , nlags , 0) ;
>> plot ( lags , ACF_raw , ’ bo - ’ , lags , ACF_filt , ’ r * - ’ , ’ linewidth ’ ,3) ;
>> ylabel ( ’ A ut o co rr el a ti on for \ theta =g ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Lag ’ , ’ fontsize ’ ,20) ;
>> title ( ’ Parameter Autocorrelation ’ , ’ fontsize ’ ,20) ;
>> grid on ;
>> h = legend ( ’ raw chain ’ , ’ filtered chain ’ , ’ location ’ , ’ northeast ’) ;
>> set (h , ’ fontsize ’ ,16) ;

Listing 5.38: Matlab code for the autocorrelation plots.

5.3.8.1.6 Covariance and Correlation Matrices
Matlab function cov calculates the covariance matrix for a data matrix (where each column represents a separate quantity), and corr calculates the correlation matrix. Since our
statistical inverse problem has only one parameter (the acceleration g due to gravity), both
covariance and correlation matrices have dimension 1 × 1, i.e., they are scalars.
% inside Matlab
>> s i p _ g r a v i t y _ r a w _ c h a i n ;
>> cov_matrix_g = cov ( i p _ m h _ r a w C h a i n _ u n i f i e d )
cov_matrix_g =
6.8709 e -04
>> corr_matrix_g = corr ( i p _ m h _ r a w C h a i n _ u n i f i e d )
corr_matrix_g =
1
>>

Listing 5.39: Matlab code for finding the covariance matrix.

CHAPTER 5. QUESO EXAMPLES

(a) Raw chain

94

(b) Filtered chain

Figure 5.3.6: Cumulative Distribution Function.

Figure 5.3.7: Autocorrelation plots.

CHAPTER 5. QUESO EXAMPLES

95

5.3.8.2 Statistical Forward Problem
5.3.8.2.1 Chain Plots
It is quite simple to plot, using Matlab, the chain of positions generated by the Monte
Carlo algorithm implemented within QUESO and called during the solution of the statistical
forward problem. The sequence of Matlab commands presented bellow generates the graphic
depicted in Figure 5.3.8a.
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q . m
>> plot ( f p _ m c _ Q o i S e q _ u n i f i e d ) ;
>> ylabel ( ’ QoI ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Number of positions ’ , ’ fontsize ’ ,20) ;
>> title ( ’ MC Chain Positions ’ , ’ fontsize ’ ,20) ;

Listing 5.40: Matlab code for the chain plot.

5.3.8.2.2 Histogram Plots
In order to plot a histogram of the QoI, you may use the pre-defined Matlab function hist.
The Matlab code presented in below shows how to create the Figure 5.3.8b.
>>
>>
>>
>>
>>
>>
>>

sfp_gravity_qoi_seq .m
nbins =100;
hist ( f p _ m c _ Q o i S e q _ u n i f i e d ) ;
title ( ’ QoI Histogram ’ , ’ fontsize ’ ,20) ;
xlabel ( ’ Distance traveled ( m ) ’,’ fontsize ’ ,20) ;
ylabel ( ’ Frequency ’ , ’ fontsize ’ ,20) ;
grid on ;

Listing 5.41: Matlab code for the QoI histogram plot.

(a) Chain positions

(b) Hystogram

Figure 5.3.8: MC chain positions and histogram of QoI = d.

CHAPTER 5. QUESO EXAMPLES

96

5.3.8.2.3 KDE Plots
Matlab function ksdensity (Kernel smoothing density estimate) together with the option
’pdf’ may be used for plotting the KDE of the he QoI, displayed in Figure 5.3.9a.
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q . m
>> [f , xi ] = ksdensity ( fp_mc_QoiSeq_unified , ’ function ’ , ’ pdf ’) ;
>> plot ( xi ,f , ’ -b ’ , ’ linewidth ’ ,3)
>> title ( ’ QoI Kernel Density Estimation ’,’ fontsize ’ ,20) ;
>> xlabel ( ’ Distance traveled ( m ) ’,’ fontsize ’ ,20) ;
>> ylabel ( ’ KDE ’ , ’ fontsize ’ ,20) ;
>> grid on ;

Listing 5.42: Matlab code for the QoI KDE plot.

5.3.8.2.4 CDF Plots
Matlab function ksdensity (Kernel smoothing density estimate) with ’cdf’ option may
also be used for plotting the Cumulative Distribution Function of the QoI, displayed in Figure 5.3.9b.
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q . m
>> [f , xi ] = ksdensity ( fp_mc_QoiSeq_unified , ’ function ’ , ’ cdf ’) ;
>> plot ( xi ,f , ’ -b ’ , ’ linewidth ’ ,3)
>> title ( ’ QoI Cumulative Distribution Function ’,’ fontsize ’ ,20) ;
>> xlabel ( ’ Distance traveled ( m ) ’,’ fontsize ’ ,20) ;
>> ylabel ( ’ CDF ’ , ’ fontsize ’ ,20) ;
>> grid on ;

Listing 5.43: Matlab code for the QoI CDF plot.

(a) KDE

(b) CDF

Figure 5.3.9: Kernel Density Estimation and Cumulative Distribution Function of QoI.

CHAPTER 5. QUESO EXAMPLES

97

5.3.8.2.5 Autocorrelation Plots
The code presented in Listing 5.44 uses Matlab function autocorr to generate Figure 5.3.10,
which presents the autocorrelation of the QoI d.
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q . m
>> nlags =10;
>> [ ACF , lags , bounds ] = autocorr ( fp_mc_QoiSeq_unified , nlags , 0) ;
>> plot ( lags , ACF , ’ bo - ’ , ’ linewidth ’ ,3) ;
>> ylabel ( ’ A ut o co rr el a ti on for QoI = d ’ , ’ fontsize ’ ,20) ;
>> xlabel ( ’ Lag ’ , ’ fontsize ’ ,20) ;
>> title ( ’ QoI Autocorrelation ’ , ’ fontsize ’ ,20) ;
>> grid on ;

Listing 5.44: Matlab code for the QoI autocorrelation plot.

Figure 5.3.10: Autocorrelation plot.

5.3.8.2.6 Covariance and Correlation Matrices
For a matrix input X, where each row is an observation, and each column is a variable, the
Matlab function cov(X) may be used to calculate the covariance matrix.
Thus, in order to calculated the covariance matrix between the parameter and the quantity
of interest sequences generated by Monte Carlo sampler with QUESO, one may simply define
X=[fp_mc_ParamSeq_unified fp_mc_QoiSeq_unified]. The code presented in Listing 5.45
shows the usage of Matlab commands for finding such the matrix.
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q ;
>> s f p _ g r a v i t y _ p _ s e q ;
>> X =[ f p _ m c _ P a r a m S e q _ u n i f i e d f p _ m c _ Q o i S e q _ u n i f i e d ];
>> cov_p_QoI = cov ( X )
cov_p_QoI =
[ 2.826 e -03
[ -8.555 e -04

-8.555 e -04 ]
2.599 e -04 ]

Listing 5.45: Matlab code for the matrix of covariance between parameter g and QoI d.

CHAPTER 5. QUESO EXAMPLES

98

Analogously, the Matlab function corrcoef(X) returns a matrix of correlation coefficients
calculated from an input matrix X whose rows are observations and whose columns are variables. In order to calculated the correlation matrix between the parameter and the QoI
sequences, one may simply define X=[fp_mc_ParamSeq_unified fp_mc_QoiSeq_unified].
% inside Matlab
>> s f p _ g r a v i t y _ q o i _ s e q ;
>> s f p _ g r a v i t y _ p _ s e q ;
>> X =[ f p _ m c _ P a r a m S e q _ u n i f i e d f p _ m c _ Q o i S e q _ u n i f i e d ];
>> corr_p_QoI = corrcoef ( X )
corr_p_QoI =
[ 1.000 e +00
[ -9.981 e -01
>>

-9.981 e -01 ]
1.000 e +00 ]

Listing 5.46: Matlab code for the matrix of correlation between parameter g and quantity of
interest d.

5.4 validationCycle
This is the last and more complex of all QUESO examples. In this example, we numerically
solve a statistical inverse problem related to a thermogravimetric experiment, where a material
sample has its mass measured while loosing it through a controlled heating process.
Given a simple mass evolution model that has a temperature profile and material properties
as input parameters, and given thermogravimetric measurements with prescribed variances,
the statistical inverse problems ask for the specification of the random variables that represent
the unknown material properties. We compute probability density functions with the Bayesian
approach and compute sets of realizations through the Metropolis-Hastings algorithm with
delayed rejection.
We qualitatively analyze the sensitivity of the solutions with respect to problem characteristics, namely “amount” of data and “quality” of data, and also with respect to algorithm
options, namely chain initial position, number of delayed rejections and chain size.

5.4.1 Thermogravimetric Experiments and a Simple Model
Suppose a given material sample of initial mass m0 and at initial temperature T0 is heated with
constant heating rate β (K/min). Heating is maintained until the sample fully ablates (decomposes). The sample mass m(T ) is measured at temperatures T > T0 . Let w(T ) = m(T )/m0
denote the mass fraction.
It is convenient to transform the kinetic equation to a per unit temperature form by dividing
through by β. Thus, a simple approach to the simulation of a thermogravimetric phenomenon
consists on modeling the sample as a homogeneous material of scalar properties A > 0 and
E > 0 whose relative mass w obeys the following initial value ordinal differential equation

CHAPTER 5. QUESO EXAMPLES

99

Figure 5.4.1: Mass fraction decay over temperature given different heating rates. Data from
J. A. Conesa, R. F. Marcilla and J. A. Caballero, “Thermogravimetric studies on the thermal
decomposition of polyethylene”, J. Anal. Appl. Pyrolysis, 36(1):1-15, 1996
problem:







Aw
dw
E
, t > 0,
= −
exp − RT
dt
β

(5.4.1)



 w(0) = 1,
where the kinetic parameters A and E are referred to, respectively, as pre-exponential factor
(min−1 ) and activation energy (J/mol).
In this combined SIP–SFP, we calibrate both model parameters A and E given the mathematical model in Equation (5.4.1) and experimental data (Section 5.4.2.3). Then the inferred
values for A and E are then used for uncertainty propagation on the remaining mass fraction
at time t = 3.9 s when β = 250 K/min, i.e., our quantity of interest is w(t = 3.9).

5.4.2 Statistical Inverse Problem
Let m = (A, E) be the vector of model parameters and M = R2+ be the space of model
parameters. Let VT denote the space of functions f : R+ → R+ that are weakly differentiable.
VT will be the space of temperature profiles. Finally, let Vw denote the space of functions
f : R+ → [0, 1] that are weakly differentiable. Vw will be the space of relative mass evolutions.
We will denote by
w(m, T ) ∈ Vw
the solution of Equation (5.4.1) for given m ∈ M and T ∈ VT .

5.4.2.1 Misfit Functions F(m)
Let VS denote the space of all functions f : R+ → R+ that are square-Lebesgue-integrable
over any finite interval. VS will be the space of misfit weight functions. Let Vσ denote the

CHAPTER 5. QUESO EXAMPLES

100

space of all functions f : R+ → R∗+ such that 1/f is square-Lebesgue-integrable over any finite
interval. Vσ will be the space of variance functions.
Given a reference relative mass evolution function d ∈ Vw , a temperature profile T ∈ VT ,
and some tF > 0, let F : M → R be the functional defined by
Z t
F
F(m) =
{[w(m, T )](t) − d(t)}2 · S(t) dt,
0

or simply
Z
F(m) =

tF

(w − d)2 · S dt.

(5.4.2)

0

The functional (5.4.2) is general enough for our studies, since it can properly describe not
only the case where one has continuous measurements d, but also the case of a finite set of
Nmeas discrete measurements 0 6 dj 6 1, 1 6 i 6 Nmeas at instants 0 6 t1 < t2 < . . . < tNmeas .
In the case of continuous measurements, for instance, one can set
Z t
F
1
{[w(m, T )](t) − d(t)}2 · 2
dt,
F1 (m) =
σ (t)
0
for some given variance function σ 2 ∈ VS satisfying σ(t) > 0 for all t > 0.
On the other hand, when measurements are discrete and a corresponding finite set of
variances σj2 > 0, j = 1, 2, . . . , Nmeas is given, one can set
"N
#
Z t
meas
X
F
δ(t
−
t
)
j
ˆ 2·
{[w(m, T )](t) − d(t)}
F2 (m) =
dt,
σ̂ 2 (t)
0
j=1
ˆ j ) = dj and σ̂(tj ) = σj , j =
where dˆ ∈ Vw and σ̂ ∈ Vσ are any functions satisfying d(t
1, 2, . . . , Nmeas , in which case the functional simply becomes
F2 (m) =

NX
meas
j=1

{[w(m, T )](tj ) − dj }2
,
σj2

assuming, without loss of generality, that tF > tNmeas .

5.4.2.2 Bayesian Approach: Prior RV, Likelihood and Posterior RV
In deterministic inverse problems treat the unknown parameters as scalars or vectors and the
goal is the calculation of their best values according to a given criteria, usually least squares,
e.g. solving the unconstrained optimization problem
min F(m).

m∈M

(5.4.3)

In statistical inverse problems, the unknown parameters are treated as random variables
(RVs) and the goal is the specification of their probability density functions (PDFs) [28].

CHAPTER 5. QUESO EXAMPLES

101

Applying the Bayesian approach
πposterior (m) ∝ πprior (m) · πlikelihood (m)
we have that for the TGA SIP, the prior distribution and the likelihood are, respectively:
1

πprior (m) ∝ e− 2 V (m)

1

and πlikelihood (m) ∝ e− 2 F (m) .

Thus, we chose parameters (A, E) to have joint uniform prior PDF over the open square
domain, i.e.:
πprior = U((1.0 × 1010 , 5.0 × 1011 ) × (4.0 × 105 , 6.0 × 105 )).

5.4.2.3 Data from experiments
Table 5.4.1 presents the data collected in the TGA experiment.
Observation
index “i”
1
2
3
4
5
6
7
8
9
10
11

Temperature Relative mass
Ti (K)
m∗obs,i (%)
673.034
682.003
690.985
699.979
708.989
718.02
727.089
735.96
744.904
754.062
763.049

96.5855
95.1549
92.5048
88.6353
83.0585
75.5306
64.1003
47.5474
23.6777
03.2234
00.0855448

Variance
Vi
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1
0.1

Table 5.4.1: Experimental data.

5.4.3 Statistical Forward Problem
In spacecraft design, ablation is used to both cool and protect mechanical parts and/or payloads that would otherwise be damaged by extremely high temperatures. Two principal
applications are heat shields for spacecraft entering a planetary atmosphere from space and
cooling of rocket engine nozzles [49].
Suppose that an object about to re-enter the Earth atmosphere has a thermal protection
layer (shield) of composition of the same sample material described in Section 5.4.2. Also, as
the object re-enters the atmosphere, its shield loses mass according to Equation (5.4.1). The
initial sample temperature is T0 = 0.1 K and it is then heated with constant rate β = 5 K/m.

CHAPTER 5. QUESO EXAMPLES

102

We are interested in answering the following question: at scenario β = 250 K/min, what
is the remaining mass fraction at time t = 3.9 s? In other words, the quantity of interest is
w(t = 3.9s).

5.4.3.1 The Input RV, QoI Function and Output RV
The input random variables for this SFP are the inferred parameters A and E which are
the solution (posterior PDF) of the inverse problem described in Section 5.4.2. The output
random variable for this example is the remaining mass fraction at 3.9 s, i.e. w(t = 3.9).
Note that, since there is uncertainty in the parameters A and E (both given as PDFs), one
can expect that this uncertainty will be propagated to w(t = 3.9), which will also be given
as a PDF. Finally, the QoI function for w is the solution of the Equation (5.4.1) evaluated
when t = 3.9 s, which is calculated using numerical integration with adjustable and acceptable
time-stepping using GSL function gsl_odeiv_evolve_apply1 .

5.4.4 Running the Example
To run the executable provided (available after QUESO installation), and generate figures for
the chains, PDFs, CDFs, etc., enter the following commands:
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / va l id at io n Cy cl e
rm outputData /*
./ e x T g a V a l i d a t i o n C y c l e _ g s l tagCycle . inp
matlab
$ tga_ cycle_pl ot . m
# i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
c a l _ p a r a m e t e r 1 _ p r i o r . png
c a l _ p a r a m e t e r 2 _ p r i o r . png
c a l _ v a l _ p a r a m e t e r 1 _ P D F . png
c a l _ v a l _ p a r a m e t e r 2 _ P D F . png
c a l _ v a l _ p a r a m e t e r 1 _ C D F . png
c a l _ v a l _ p a r a m e t e r 2 _ C D F . png
c a l _ v a l _ p a r a m e t e r 1 _ a u t o c o r r . png
c a l _ v a l _ p a r a m e t e r 2 _ a u t o c o r r . png
c al _v al _ Qo I_ CD F . png
ca l _v al _Q o I_ PD F . png
c a l _ v a l _ Q o I _ a u t o c o r r e l a t i o n . png

As a result, the user should have created several of PNG figures containing marginal posterior PDF, chain positions of the parameters and the QoI, histogram, cumulative density
distribution and autocorrelation. The name of the figure files have been chosen to be informative, as shown in the Listing above.

5.4.5 TGA Example Code
The program example given in this paper is compatible with version 0.47.1 of QUESO. The
source code for the example is composed of 5 files: exTgaValidationCycle gsl.C (Listing
5.47), exTgaValidationCycle appl.h (Listing 5.48), exTgaValidationCycle likelihood.h
(Listing 5.49) and exTgaValidationCycle qoi.C (Listing 5.50).
1

http://www.gnu.org/software/gsl/manual/html_node/Evolution.html#index-gsl_005fodeiv2_
005fevolve_005fapply

CHAPTER 5. QUESO EXAMPLES

/* This is an example of how to define and run a PECOS validation cycle for a
* t h e r m o g r a v i m e t r i c analysis ( TGA ) model
* using QUESO classes and algorithms . The code itself is in the templated
* routine ’ uqAppl (* env ) ’. This routine is called right after the init ializati on
* of the MPI environment and of the QUESO environment and is available in
* file ’ e x T g a V a l i d a t i o n C y c l e _ g s l .C ’.
*
* It is easier to understand this example after undertanding three other simpler
* examples :
* (1) examples / s i m p l e S t a t i s t i c a l I n v e r s e P r o b l e m / src / example_main . C
* (2) examples / s i m p l e S t a t i s t i c a l F o r w a r d P r o b l e m / src / s i m p l e _ s f p _ e x a m p l e _ m a i n . C
* (3) examples / gravity / src / gravity_main . C
*
* Example (1) focuses on the templated class StatisticalInverseProblem < P_V , P_M >.
* Example (2) focuses on the templated class StatisticalForwardProblem < P_V , P_M , Q_V , Q_M >.
* Example (3) focuses on both classes , since it uses the solution of the inverse problem
* as input to the forward problem .
*
* This example with TGA uses both statistical problem templated classes , twice each in
* fact , but it also :
* - uses the templated class ValidationCycle < P_V , P_M , Q_V , Q_M > ,
* - reads experimental data from files in order to compute the likelihood function
*
at candidate parameter vectors generated by the Metropolis - Hastings algorithm , and
* - compares the qoi cdfs computed from the two statistical forward problems at
*
the prediction scenario .
*-------------------------------------------------------------------------* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
#i n c l u d e 
#i n c l u d e 
#i n c l u d e 
int main ( int argc , char * argv [])
{
//************************************************
// Initialize environment
//************************************************
MPI_Init (& argc ,& argv ) ;
QUESO :: E n v O p t i o n s V al u e s * e n v O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
U Q _ F A T A L _ T E S T _ M A C R O ( argc != 2 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" main () " ,
" input file must be specified in command line as argv [1] , just after
executable argv [0] " ) ;
QUESO :: Fu ll En v ir on me n t * env = new QUESO :: F ul lE nv i ro nm en t ( MPI_COMM_WORLD , argv [1] , " " ,
envOptionsValues );
#e l s e
e n v O p t i o n s V a l u es = new QUESO :: E n v O p t i o n s V a l u e s () ;
envOptionsValues - > m _ s u b D i s p l a y F i l e N a m e
= " outputData / display " ;
envOptionsValues - > m _ s u b D i s p l a y A l l o w e d S e t . insert (0) ;
envOptionsValues - > m _ s u b D i s p l a y A l l o w e d S e t . insert (1) ;
envOptionsValues - > m _ d i s p l a y V e r b o s i t y
= 2;
envOptionsValues - > m_seed
= 0;
QUESO :: Fu ll En v ir on me n t * env = new QUESO :: F ul lE nv i ro nm en t ( MPI_COMM_WORLD , " " ," " ,
envOptionsValues );
#e n d i f
//************************************************
// Run application
//************************************************

103

CHAPTER 5. QUESO EXAMPLES
uqAppl < QUESO :: GslVector ,
QUESO :: GslMatrix ,
QUESO :: GslVector ,
QUESO :: GslMatrix
>(* env ) ;

//
//
//
//

type
type
type
type

for
for
for
for

104
parameter vectors
parameter matrices
qoi vectors
qoi matrices

//************************************************
// Finalize environment
//************************************************
delete env ;
delete e n v O p ti o n s V a l u e s ;
MPI_Finalize () ;
return 0;
}

Listing 5.47: File exTgaValidationCycle gsl.C.
#i f n d e f EX TGA VALIDATION CYCLE APPL H
#d e f i n e EX TGA VALIDATION CYCLE APPL H
#d e f i n e UQ EXAMPLES USES QUESO INPUT FILE
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e

< e x T g a V a l i d a t i o n C y c l e l i k e l i h o o d . h>





< g s l / g s l e r r n o . h>
< g s l / g s l o d e i v . h>

// Just declaration : actual code is below
template < class P_V , class P_M , class Q_V , class Q_M >
void
u q A p p l _ L o c a l C o m p a r i s o n S t a g e ( QUESO :: ValidationCycle < P_V , P_M , Q_V , Q_M >& cycle ) ;
template < class P_V , class P_M , class Q_V , class Q_M >
void
u q A p p l _ U n i f i e d C o m p a r i s o n S t a g e ( QUESO :: ValidationCycle < P_V , P_M , Q_V , Q_M >& cycle ) ;
//********************************************************
// The driving routine " uqAppl () " : called by main ()
// There are 5 main tasks :
// 1) initilization
// 2) the ’ calibration stage ’
// 3) the ’ validation stage ’
// 4) the ’ comparison stage ’
// 5) memory release
// Tasks 2 , 3 and 4 constitute the actual validation cycle .
//********************************************************
template < class P_V , class P_M , class Q_V , class Q_M >
void
uqAppl ( const QUESO :: B as eE n vi ro nm e nt & env )
{
if ( env . fullRank () == 0) {
std :: cout << " Beginning run of ’ uqTgaExample ’ example \ n "
<< std :: endl ;
}
int iRC ;
struct timeval timevalRef ;
struct timeval timevalNow ;

CHAPTER 5. QUESO EXAMPLES

105

//******************************************************
// Task 1 of 5: instantiation of basic classes
//******************************************************
// Instantiate the parameter space
std :: vector < std :: string > paramNames (2 , " " ) ;
paramNames [0] = " A_param " ;
paramNames [1] = " E_param " ;
QUESO :: VectorSpace < P_V , P_M > paramSpace ( env , " param_ " , paramNames . size () ,& paramNames ) ;
// Instantiate the parameter domain
P_V paramMi nValues ( paramSpace . zeroVector () ) ;
para mMinValu es [0] = 2.40 e +11;
para mMinValu es [1] = 1.80 e +05;
P_V paramMa xValues ( paramSpace . zeroVector () ) ;
para mMaxValu es [0] = 2.80 e +11;
para mMaxValu es [1] = 2.20 e +05;
QUESO :: BoxSubset < P_V , P_M > paramDomain ( " param_ " ,
paramSpace ,
paramMinValues ,
param MaxValu es ) ;
// Instantiate the qoi space
std :: vector < std :: string > qoiNames (1 , " " ) ;
qoiNames [0] = " T i m e F o r 2 5 P e r c e n t O f M a s s " ;
QUESO :: VectorSpace < Q_V , Q_M > qoiSpace ( env , " qoi_ " , qoiNames . size () ,& qoiNames ) ;
// Instantiate the validation cycle
QUESO :: ValidationCycle < P_V , P_M , Q_V , Q_M > cycle ( env ,
" " , // No extra prefix
paramSpace ,
qoiSpace ) ;
//********************************************************
// Task 2 of 5: calibration stage
//********************************************************
iRC = gettimeofday (& timevalRef , NULL ) ;
if ( iRC ) {}; // just to remove compiler warning
if ( env . fullRank () == 0) {
std :: cout << " Beginning ’ calibration stage ’ at " << ctime (& timevalRef . tv_sec )
<< std :: endl ;
}
// Inverse problem : instantiate the prior rv
QUESO :: UniformVectorRV < P_V , P_M > calPriorRv (
" cal_prior_ " , // Extra prefix before the default " rv_ " prefix
paramDomain ) ;
// Inverse problem : instantiate the likelihood function object ( data + routine )
likelihoodRoutine_Data < P_V , P_M > c a l L i k e l i h o o d R o u t i n e _ D a t a ( env ,
" s c e n a r i o _ 5 _ K _ m i n . dat " ,
" s c e n a r i o _ 2 5 _ K _ m i n . dat " ,
" s c e n a r i o _ 5 0 _ K _ m i n . dat " ) ;
QUESO :: GenericScalarFunction < P_V , P_M > c a l L i k e l i h o o d F u n c t i o n O b j ( " cal_like_ " ,
paramDomain ,
likelihoodRoutine < P_V , P_M > ,
( void *) &
calLikelihoodRoutine_Data
,
true ) ; // the routine
computes [ ln ( function ) ]

CHAPTER 5. QUESO EXAMPLES
// Inverse problem : instantiate it ( posterior rv is instantiated internally )
QUESO :: S i p O p t i o n s V al u e s * c a l I p O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
c a l I p O p t i o n s V a l u e s = new QUESO :: S i p O p t i o n s V a l u e s () ;
calIpOptionsValues - > m _ c o m p u t e S o l u t i o n
= true ;
calIpOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaCalOutput " ;
calIpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
calIpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
#e n d i f
cycle . i n s t a nt i a t e C a l I P ( calIpOptionsValues ,
calPriorRv ,
calLikelihoodFunctionObj );
// Inverse problem : solve it , that is , set ’pdf ’ and ’ realizer ’ of the posterior rv
P_V p a r a m I n i t i a l V a l u e s ( paramSpace . zeroVector () ) ;
if ( env . n u m S u b E n v i r o n m e n t s () == 1) {
// For regression test purposes
p a r a m I n i t i a l V a l u e s [0] = 2.41 e +11;
p a r a m I n i t i a l V a l u e s [1] = 2.19 e +05;
}
else {
calPriorRv . realizer () . realization ( p a r a m I n i t i a l V a l u e s ) ;
}
QUESO :: Mh Op ti o ns Va lu e s * c a l I p M h O p t i o n s V a l u e s = NULL ;
P_M * c a l P r o p o s a l C o v M a t r i x = cycle . calIP () . postRv () . imageSet () . vectorSpace () .
n e w P r o p o s a l M a t r i x ( NULL ,& p a r a m I n i t i a l V a l u e s ) ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 1 ;
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 2 ;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (9) ;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [1] = 0.05;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [2] = 0.10;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [3] = 0.15;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [4] = 0.20;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [5] = 0.25;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [6] = 0.30;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [7] = 0.35;
s s O p t i o n s V a l u e s1 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [8] = 0.40;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r C o m p u t e V i a D e f
= false ;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r C o m p u t e V i a F f t
= true ;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r S e c o n d L a g
= 2;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r L a g S p a c i n g
= 2;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r N u m L a g s
= 15;
s s O p t i o n s V a l u e s1 . m _ a u t o C o r r D i s p l a y
= true ;
s s O p t i o n s V a l u e s1 . m _a u to Co rr W ri te
= true ;
s s O p t i o n s V a l u e s1 . m_kdeCompute
= false ;
s s O p t i o n s V a l u e s1 . m _ c o v M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s1 . m _ c o r r M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s2 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s2 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r C o m p u t e V i a D e f
= false ;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r C o m p u t e V i a F f t
= true ;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r S e c o n d L a g
= 2;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r L a g S p a c i n g
= 2;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r N u m L a g s
= 15;
s s O p t i o n s V a l u e s2 . m _ a u t o C o r r D i s p l a y
= true ;
s s O p t i o n s V a l u e s2 . m _a u to Co rr W ri te
= true ;
s s O p t i o n s V a l u e s2 . m_kdeCompute
= true ;
s s O p t i o n s V a l u e s2 . m _ k d e N u m E v a l P o s i t i o n s
= 250;

106

CHAPTER 5. QUESO EXAMPLES
s s O p t i o n s V a l u e s2 . m _ c o v M a t r i x C o m p u t e
s s O p t i o n s V a l u e s2 . m _ c o r r M a t r i x C o m p u t e

107
= true ;
= true ;

c a l I p M h O p t i o n s V a l u e s = new QUESO :: Mh Op t io ns Va l ue s (& ssOptionsValues1 ,& s sO p t i o n s V a l u e s 2 ) ;
calIpMhOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaCalOutput " ;
calIpMhOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
calIpMhOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
calIpMhOptionsValues - > m _ r a w C h a i n D a t a I n p u t F i l e N a m e
= ".";
calIpMhOptionsValues - > m_ rawChain Size
= 1048576;
calIpMhOptionsValues - > m _ r a w C h a i n G e n e r a t e E x t r a
= false ;
calIpMhOptionsValues - > m _ r a w C h a i n D i s p l a y P e r i o d
= 20000;
calIpMhOptionsValues - > m _ r a w C h a i n M e a s u r e R u n T i m e s
= true ;
calIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t F i l e N a m e
= " outputData / f il e_ c al _i p_ r aw " ;
calIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t A l l o w e d S e t . insert (0) ;
calIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t A l l o w e d S e t . insert (1) ;
calIpMhOptionsValues - > m _ r a w C h a i n C o m p u t e S t a t s
= true ;
calIpMhOptionsValues - > m _ d i s p l a y C a n d i d a t e s
= false ;
calIpMhOptionsValues - > m _ p u t O u t O f B o u n d s I n C h a i n
= true ;
calIpMhOptionsValues - > m _ t k U s e L o c a l H e s s i a n
= false ;
calIpMhOptionsValues - > m _ t k U s e N e w t o n C o m p o n e n t
= true ;
calIpMhOptionsValues - > m _ d r M a x N u m E x t r a S t a g e s
= 1;
calIpMhOptionsValues - > m _ d r S c a l e s F o r E x t r a S t a g e s . resize (1) ;
calIpMhOptionsValues - > m _ d r S c a l e s F o r E x t r a S t a g e s [0] = 5.;
calIpMhOptionsValues - > m _ a m I n i t i a l N o n A d a p t I n t e r v a l = 0;
calIpMhOptionsValues - > m _ a m A d a p t I n t e r v a l
= 100;
calIpMhOptionsValues - > m_amEta
= 1.92;
calIpMhOptionsValues - > m_amEpsilon
= 1. e -5;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n G e n e r a t e
= true ;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n D i s c a r d e d P o r t i o n
= 0.;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n L a g
= 20;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t F i l e N a m e
= ".";
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t A l l o w e d S e t . insert (0) ;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t A l l o w e d S e t . insert (1) ;
calIpMhOptionsValues - > m _ f i l t e r e d C h a i n C o m p u t e S t a t s
= true ;
#e n d i f
cycle . calIP () . s o l v e W i t h B a y e s M e t r o p o l i s H a s t i n g s ( calIpMhOptionsValues ,
paramInitialValues ,
calProposalCovMatrix );
delete c a l P r o p o s a l C o v M a t r i x ;
delete c a l I p M h O p t i o n s V a l u e s ;
// Forward problem : instantiate it ( parameter rv = posterior rv of inverse problem ; qoi rv
is instantiated internally )
double b et a _p re di c ti on
= 250.;
double c r i t i c a l M a s s _ p r e d i c t i o n = 0.;
double c r i t i c a l T i m e _ p r e d i c t i o n = 3.9;
qoiRoutine_Data < P_V , P_M , Q_V , Q_M > c a l Q o i R o u t i n e _ D a t a ;
c a l Q o i R o u t i n e _ D a t a . m_beta
= be ta _ pr ed ic t io n ;
c a l Q o i R o u t i n e _ D a t a . m_criti calMass = c r i t i c a l M a s s _ p r e d i c t i o n ;
c a l Q o i R o u t i n e _ D a t a . m_criti calTime = c r i t i c a l T i m e _ p r e d i c t i o n ;
QUESO :: S f p O p t i o n s V al u e s * c a l F p O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
c a l F p O p t i o n s V a l u e s = new QUESO :: S f p O p t i o n s V a l u e s () ;
calFpOptionsValues - > m _ c o m p u t e S o l u t i o n
= true ;
calFpOptionsValues - > m _ c o m p u t e C o v a r i a n c e s
= true ;
calFpOptionsValues - > m _ c o m p u t e C o r r e l a t i o n s = true ;
calFpOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaCalOutput " ;
calFpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
calFpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;

CHAPTER 5. QUESO EXAMPLES

108

#e n d i f
cycle . i n s t a nt i a t e C a l F P ( calFpOptionsValues ,
qoiRoutine < P_V , P_M , Q_V , Q_M > ,
( void *) & c a l Q o i R o u t i n e _ D a t a ) ;
// Forward problem : solve it , that is , set ’ realizer ’ and ’ cdf ’ of the qoi rv
QUESO :: Mc Op ti o ns Va lu e s * c a l F p M c O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 3 ;
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 4 ;
s s O p t i o n s V a l u e s3 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s3 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s3 . m_kdeCompute
s s O p t i o n s V a l u e s3 . m _ k d e N u m E v a l P o s i t i o n s
s s O p t i o n s V a l u e s3 . m _ c o v M a t r i x C o m p u t e
s s O p t i o n s V a l u e s3 . m _ c o r r M a t r i x C o m p u t e

=
=
=
=

true ;
250;
true ;
true ;

s s O p t i o n s V a l u e s4 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s4 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;

s s O p t i o n s V a l u e s4 . m _ a u t o C o r r C o m p u t e V i a D e f
s s O p t i o n s V a l u e s4 . m _ a u t o C o r r C o m p u t e V i a F f t
s s O p t i o n s V a l u e s4 . m _ a u t o C o r r S e c o n d L a g
s s O p t i o n s V a l u e s4 . m _ a u t o C o r r L a g S p a c i n g
s s O p t i o n s V a l u e s4 . m _ a u t o C o r r N u m L a g s
s s O p t i o n s V a l u e s4 . m _ a u t o C o r r D i s p l a y
s s O p t i o n s V a l u e s4 . m _a u to Co rr W ri te
s s O p t i o n s V a l u e s4 . m_kdeCompute
s s O p t i o n s V a l u e s4 . m _ k d e N u m E v a l P o s i t i o n s
s s O p t i o n s V a l u e s4 . m _ c o v M a t r i x C o m p u t e
s s O p t i o n s V a l u e s4 . m _ c o r r M a t r i x C o m p u t e

=
=
=
=
=
=
=
=
=
=
=

false ;
true ;
2;
1;
15;
true ;
true ;
true ;
250;
true ;
true ;

c a l F p M c O p t i o n s V a l u e s = new QUESO :: Mc Op t io ns Va l ue s (& ssOptionsValues3 ,& s sO p t i o n s V a l u e s 4 ) ;
calFpMcOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaCalOutput " ;
calFpMcOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
calFpMcOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
calFpMcOptionsValues - > m _ p s e q D a t a O u t p u t F i l e N a m e
= ".";
calFpMcOptionsValues - > m _ p s e q D a t a O u t p u t A l l o w e d S e t . insert (0) ;
calFpMcOptionsValues - > m _ p s e q D a t a O u t p u t A l l o w e d S e t . insert (1) ;
calFpMcOptionsValues - > m _ p s e q C o m p u t e S t a t s
= true ;
calFpMcOptionsValues - > m _ q s e q D a t a I n p u t F i l e N a m e
= ".";
calFpMcOptionsValues - > m_qseqSize
= 1048576;
calFpMcOptionsValues - > m _ q s e q D i s p l a y P e r i o d
= 20000;
calFpMcOptionsValues - > m _ q s e q M e a s u r e R u n T i m e s
= true ;
calFpMcOptionsValues - > m _ q s e q D a t a O u t p u t F i l e N a m e
= " outputData / f i l e _ c a l _ f p _ q o i 2 " ;
calFpMcOptionsValues - > m _ q s e q D a t a O u t p u t A l l o w e d S e t . insert (0) ;
calFpMcOptionsValues - > m _ q s e q D a t a O u t p u t A l l o w e d S e t . insert (1) ;
calFpMcOptionsValues - > m _ q s e q C o m p u t e S t a t s
= true ;
#e n d i f
cycle . calFP () . s o l v e W i t h M o n t e C a r l o ( c a l F p M c O p t i o n s V a l u e s ) ; // no extra user entities needed
for Monte Carlo algorithm
delete c a l F p M c O p t i o n s V a l u e s ;
iRC = gettimeofday (& timevalNow , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Ending ’ calibration stage ’ at "
<< ctime (& timevalNow . tv_sec )
<< " Total ’ calibration stage ’ run time = " << timevalNow . tv_sec - timevalRef .
tv_sec
<< " seconds \ n "

CHAPTER 5. QUESO EXAMPLES

109

<< std :: endl ;
}
//********************************************************
// Task 3 of 5: validation stage
//********************************************************
iRC = gettimeofday (& timevalRef , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Beginning ’ validation stage ’ at " << ctime (& timevalRef . tv_sec )
<< std :: endl ;
}
// Inverse problem : no need to instantiate the prior rv (= posterior rv of calibration
inverse problem )
// Inverse problem : instantiate the likelihood function object ( data + routine )
likelihoodRoutine_Data < P_V , P_M > v a l L i k e l i h o o d R o u t i n e _ D a t a ( env ,
" s c e n a r i o _ 1 0 0 _ K _ m i n . dat " ,
NULL ,
NULL ) ;
QUESO :: GenericScalarFunction < P_V , P_M > v a l L i k e l i h o o d F u n c t i o n O b j ( " val_like_ " ,
paramDomain ,
likelihoodRoutine < P_V , P_M > ,
( void *) &
valLikelihoodRoutine_Data
,
true ) ; // the routine
computes [ ln ( function ) ]
// Inverse problem : instantiate it ( posterior rv is instantiated internally )
QUESO :: S i p O p t i o n s V al u e s * v a l I p O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
v a l I p O p t i o n s V a l u e s = new QUESO :: S i p O p t i o n s V a l u e s () ;
valIpOptionsValues - > m _ c o m p u t e S o l u t i o n
= true ;
valIpOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaValOutput " ;
valIpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
valIpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
#e n d i f
cycle . i n s t a nt i a t e V a l I P ( valIpOptionsValues ,
valLikelihoodFunctionObj );
// Inverse problem : solve it , that is , set ’pdf ’ and ’ realizer ’ of the posterior rv
QUESO :: Mh Op ti o ns Va lu e s * v a l I p M h O p t i o n s V a l u e s = NULL ;
const QUESO :: SequentialVectorRealizer < P_V , P_M >*
tmpRealizer = dynamic_cast < const QUESO :: SequentialVectorRealizer < P_V , P_M >* >(&( cycle .
calIP () . postRv () . realizer () ) ) ;
// Use ’ realizer () ’ because the post . rv was computed with Metr . Hast .
P_M * v a l P r o p o s a l C o v M a t r i x = cycle . calIP () . postRv () . imageSet () . vectorSpace () .
newProposalMatrix (
& tmpRealizer - > u n i f i e d S a m p l e V a r V e c t o r () ,
& tmpRealizer - > u n i f i e d S a m p l e E x p V e c t o r () ) ; // Use these values as the initial values
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 5 ;
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 6 ;
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (9) ;
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [1] = 0.05;

CHAPTER 5. QUESO EXAMPLES
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [2]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [3]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [4]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [5]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [6]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [7]
s s O p t i o n s V a l u e s5 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [8]
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r C o m p u t e V i a D e f
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r C o m p u t e V i a F f t
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r S e c o n d L a g
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r L a g S p a c i n g
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r N u m L a g s
s s O p t i o n s V a l u e s5 . m _ a u t o C o r r D i s p l a y
s s O p t i o n s V a l u e s5 . m _a u to Co rr W ri te
s s O p t i o n s V a l u e s5 . m_kdeCompute
s s O p t i o n s V a l u e s5 . m _ c o v M a t r i x C o m p u t e
s s O p t i o n s V a l u e s5 . m _ c o r r M a t r i x C o m p u t e

110
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0.10;
0.15;
0.20;
0.25;
0.30;
0.35;
0.40;
false ;
true ;
2;
2;
15;
true ;
true ;
false ;
true ;
true ;

s s O p t i o n s V a l u e s6 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s6 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r C o m p u t e V i a D e f
= false ;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r C o m p u t e V i a F f t
= true ;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r S e c o n d L a g
= 2;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r L a g S p a c i n g
= 2;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r N u m L a g s
= 15;
s s O p t i o n s V a l u e s6 . m _ a u t o C o r r D i s p l a y
= true ;
s s O p t i o n s V a l u e s6 . m _a u to Co rr W ri te
= true ;
s s O p t i o n s V a l u e s6 . m_kdeCompute
= true ;
s s O p t i o n s V a l u e s6 . m _ k d e N u m E v a l P o s i t i o n s
= 250;
s s O p t i o n s V a l u e s6 . m _ c o v M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s6 . m _ c o r r M a t r i x C o m p u t e
= true ;
v a l I p M h O p t i o n s V a l u e s = new QUESO :: Mh Op t io ns Va l ue s (& ssOptionsValues5 ,& s sO p t i o n s V a l u e s 6 ) ;
valIpMhOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaValOutput " ;
valIpMhOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
valIpMhOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
valIpMhOptionsValues - > m _ r a w C h a i n D a t a I n p u t F i l e N a m e
= ".";
valIpMhOptionsValues - > m_ rawChain Size
= 1048576;
valIpMhOptionsValues - > m _ r a w C h a i n G e n e r a t e E x t r a
= false ;
valIpMhOptionsValues - > m _ r a w C h a i n D i s p l a y P e r i o d
= 20000;
valIpMhOptionsValues - > m _ r a w C h a i n M e a s u r e R u n T i m e s
= true ;
valIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t F i l e N a m e
= " outputData / fi le _v a l_ ip _r a w " ;
valIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t A l l o w e d S e t . insert (0) ;
valIpMhOptionsValues - > m _ r a w C h a i n D a t a O u t p u t A l l o w e d S e t . insert (1) ;
valIpMhOptionsValues - > m _ r a w C h a i n C o m p u t e S t a t s
= true ;
valIpMhOptionsValues - > m _ d i s p l a y C a n d i d a t e s
= false ;
valIpMhOptionsValues - > m _ p u t O u t O f B o u n d s I n C h a i n
= true ;
valIpMhOptionsValues - > m _ t k U s e L o c a l H e s s i a n
= false ;
valIpMhOptionsValues - > m _ t k U s e N e w t o n C o m p o n e n t
= true ;
valIpMhOptionsValues - > m _ d r M a x N u m E x t r a S t a g e s
= 1;
valIpMhOptionsValues - > m _ d r S c a l e s F o r E x t r a S t a g e s . resize (1) ;
valIpMhOptionsValues - > m _ d r S c a l e s F o r E x t r a S t a g e s [0] = 5.;
valIpMhOptionsValues - > m _ a m I n i t i a l N o n A d a p t I n t e r v a l = 0;
valIpMhOptionsValues - > m _ a m A d a p t I n t e r v a l
= 100;
valIpMhOptionsValues - > m_amEta
= 1.92;
valIpMhOptionsValues - > m_amEpsilon
= 1. e -5;
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n G e n e r a t e
= true ;
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n D i s c a r d e d P o r t i o n
= 0.;
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n L a g
= 20;
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t F i l e N a m e
= ".";
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t A l l o w e d S e t . insert (0) ;
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n D a t a O u t p u t A l l o w e d S e t . insert (1) ;

CHAPTER 5. QUESO EXAMPLES
valIpMhOptionsValues - > m _ f i l t e r e d C h a i n C o m p u t e S t a t s
= true ;
#e n d i f
cycle . valIP () . s o l v e W i t h B a y e s M e t r o p o l i s H a s t i n g s ( valIpMhOptionsValues ,
tmpRealizer - > u n i f i e d S a m p l e E x p V e c t o r () ,
valProposalCovMatrix );
delete v a l P r o p o s a l C o v M a t r i x ;
delete v a l I p M h O p t i o n s V a l u e s ;
// Forward problem : instantiate it ( parameter rv = posterior rv of inverse problem ;
// qoi rv is instantiated internally )
qoiRoutine_Data < P_V , P_M , Q_V , Q_M > v a l Q o i R o u t i n e _ D a t a ;
v a l Q o i R o u t i n e _ D a t a . m_beta
= be ta _ pr ed ic t io n ;
v a l Q o i R o u t i n e _ D a t a . m_criti calMass = c r i t i c a l M a s s _ p r e d i c t i o n ;
v a l Q o i R o u t i n e _ D a t a . m_criti calTime = c r i t i c a l T i m e _ p r e d i c t i o n ;
QUESO :: S f p O p t i o n s V al u e s * v a l F p O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
v a l F p O p t i o n s V a l u e s = new QUESO :: S f p O p t i o n s V a l u e s () ;
valFpOptionsValues - > m _ c o m p u t e S o l u t i o n
= true ;
valFpOptionsValues - > m _ c o m p u t e C o v a r i a n c e s
= true ;
valFpOptionsValues - > m _ c o m p u t e C o r r e l a t i o n s = true ;
valFpOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaValOutput " ;
valFpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
valFpOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
#e n d i f
cycle . i n s t a nt i a t e V a l F P ( valFpOptionsValues ,
qoiRoutine < P_V , P_M , Q_V , Q_M > ,
( void *) & v a l Q o i R o u t i n e _ D a t a ) ;
// Forward problem : solve it , that is , set ’ realizer ’ and ’ cdf ’ of the qoi rv
QUESO :: Mc Op ti o ns Va lu e s * v a l F p M c O p t i o n s V a l u e s = NULL ;
#i f d e f UQ EXAMPLES USES QUESO INPUT FILE
#e l s e
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 7 ;
QUESO :: Ss Op ti o ns Va lu e s s s O p ti o n s V a l u e s 8 ;
s s O p t i o n s V a l u e s7 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s7 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s7 . m_kdeCompute
= true ;
s s O p t i o n s V a l u e s7 . m _ k d e N u m E v a l P o s i t i o n s
= 250;
s s O p t i o n s V a l u e s7 . m _ c o v M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s7 . m _ c o r r M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s8 . m _ i n i t i a l D i s c a r d e d P o r t i o n s . resize (1) ;
s s O p t i o n s V a l u e s8 . m _ i n i t i a l D i s c a r d e d P o r t i o n s [0] = 0.;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r C o m p u t e V i a D e f
= false ;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r C o m p u t e V i a F f t
= true ;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r S e c o n d L a g
= 2;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r L a g S p a c i n g
= 1;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r N u m L a g s
= 15;
s s O p t i o n s V a l u e s8 . m _ a u t o C o r r D i s p l a y
= true ;
s s O p t i o n s V a l u e s8 . m _a u to Co rr W ri te
= true ;
s s O p t i o n s V a l u e s8 . m_kdeCompute
= true ;
s s O p t i o n s V a l u e s8 . m _ k d e N u m E v a l P o s i t i o n s
= 250;
s s O p t i o n s V a l u e s8 . m _ c o v M a t r i x C o m p u t e
= true ;
s s O p t i o n s V a l u e s8 . m _ c o r r M a t r i x C o m p u t e
= true ;
v a l F p M c O p t i o n s V a l u e s = new QUESO :: Mc Op t io ns Va l ue s (& ssOptionsValues7 ,& s sO p t i o n s V a l u e s 8 ) ;
valFpMcOptionsValues - > m _ d a t a O u t p u t F i l e N a m e
= " outputData / tgaValOutput " ;
valFpMcOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (0) ;
valFpMcOptionsValues - > m _ d a t a O u t p u t A l l o w e d S e t . insert (1) ;
valFpMcOptionsValues - > m _ p s e q D a t a O u t p u t F i l e N a m e
= ".";
valFpMcOptionsValues - > m _ p s e q D a t a O u t p u t A l l o w e d S e t . insert (0) ;

111

CHAPTER 5. QUESO EXAMPLES

112

valFpMcOptionsValues - > m _ p s e q D a t a O u t p u t A l l o w e d S e t . insert (1) ;
valFpMcOptionsValues - > m _ p s e q C o m p u t e S t a t s
= true ;
valFpMcOptionsValues - > m _ q s e q D a t a I n p u t F i l e N a m e
= ".";
valFpMcOptionsValues - > m_qseqSize
= 1048576;
valFpMcOptionsValues - > m _ q s e q D i s p l a y P e r i o d
= 20000;
valFpMcOptionsValues - > m _ q s e q M e a s u r e R u n T i m e s
= true ;
valFpMcOptionsValues - > m _ q s e q D a t a O u t p u t F i l e N a m e
= " outputData / f i l e _ v a l _ f p _ q o i 2 " ;
valFpMcOptionsValues - > m _ q s e q D a t a O u t p u t A l l o w e d S e t . insert (0) ;
valFpMcOptionsValues - > m _ q s e q D a t a O u t p u t A l l o w e d S e t . insert (1) ;
valFpMcOptionsValues - > m _ q s e q C o m p u t e S t a t s
= true ;
#e n d i f
cycle . valFP () . s o l v e W i t h M o n t e C a r l o ( v a l F p M c O p t i o n s V a l u e s ) ; // no extra user entities needed
for Monte Carlo algorithm
delete v a l F p M c O p t i o n s V a l u e s ;
delete
delete
delete
delete

valFpOptionsValues ;
valIpOptionsValues ;
calFpOptionsValues ;
calIpOptionsValues ;

iRC = gettimeofday (& timevalNow , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Ending ’ validation stage ’ at "
<< ctime (& timevalNow . tv_sec )
<< " Total ’ validation stage ’ run time = " << timevalNow . tv_sec - timevalRef .
tv_sec
<< " seconds \ n "
<< std :: endl ;
}
//********************************************************
// Task 4 of 5: comparison stage
//********************************************************
iRC = gettimeofday (& timevalRef , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Beginning ’ comparison stage ’ at " << ctime (& timevalRef . tv_sec )
<< std :: endl ;
}
u q A p p l _ L o c a l C o m p a r i s o n S t a g e ( cycle ) ;
if ( env . n u m S u b E n v i r o n m e n t s () > 1) {
u q A p p l _ U n i f i e d C o m p a r i s o n S t a g e ( cycle ) ;
}
iRC = gettimeofday (& timevalNow , NULL ) ;
if ( env . fullRank () == 0) {
std :: cout << " Ending ’ comparison stage ’ at "
<< ctime (& timevalNow . tv_sec )
<< " Total ’ comparison stage ’ run time = " << timevalNow . tv_sec - timevalRef .
tv_sec
<< " seconds \ n "
<< std :: endl ;
}
//******************************************************
// Task 5 of 5: release memory before leaving routine .
//******************************************************
if ( env . fullRank () == 0) {
std :: cout << " Finishing run of ’ uqTgaExample ’ example "
<< std :: endl ;
}
return ;
}

CHAPTER 5. QUESO EXAMPLES

//********************************************************
// The ’ local comparison stage ’ of the driving routine " uqAppl () "
//********************************************************
template < class P_V , class P_M , class Q_V , class Q_M >
void
u q A p p l _ L o c a l C o m p a r i s o n S t a g e ( QUESO :: ValidationCycle < P_V , P_M , Q_V , Q_M >& cycle )
{
if ( cycle . calFP () . c o m p u t e S o l u t i o n F l a g () &&
cycle . valFP () . c o m p u t e S o l u t i o n F l a g () ) {
}
return ;
}
//********************************************************
// The ’ unified comparison stage ’ of the driving routine " uqAppl () "
//********************************************************
template < class P_V , class P_M , class Q_V , class Q_M >
void
u q A p p l _ U n i f i e d C o m p a r i s o n S t a g e ( QUESO :: ValidationCycle < P_V , P_M , Q_V , Q_M >& cycle )
{
if ( cycle . calFP () . c o m p u t e S o l u t i o n F l a g () &&
cycle . valFP () . c o m p u t e S o l u t i o n F l a g () ) {
}
return ;
}
#e n d i f // EX TGA VALIDATION CYCLE APPL H

Listing 5.48: File exTgaValidationCycle appl.h.
#i f n d e f EX TGA VALIDATION CYCLE LIKELIHOOD H
#d e f i n e EX TGA VALIDATION CYCLE LIKELIHOOD H
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e



< g s l / g s l e r r n o . h>
< g s l / g s l o d e i v . h>


#d e f i n e R CONSTANT 8 . 3 1 4 4 7 2
//********************************************************
// The ODE ( state dot ) function
//********************************************************
int func ( double t , const double Mass [] , double f [] , void * info )
{
double * params = ( double *) info ;
double A
= params [0];
double E
= params [1];
double beta = params [2];
f [0] = -A * Mass [0]* std :: exp ( - E /( R_CONSTANT * t ) ) / beta ;
return GSL_SUCCESS ;
}
//********************************************************
// The ( user defined ) data class that carries the data
// needed by the ( user defined ) likelihood routine
//********************************************************

113

CHAPTER 5. QUESO EXAMPLES
template < class P_V , class P_M >
struct
likelihoodRoutine_Data
{
l i k e l i h o o d R o u t i n e _ D a t a ( const QUESO :: B as eE nv i ro nm en t & env ,
const char * inpName1 ,
const char * inpName2 ,
const char * inpName3 ) ;
~ l i k e l i h o o d R o u t i n e _ D a t a () ;
double
double
std :: vector < double >
std :: vector < double >

m_beta1 ;
m_variance1 ;
m_Te1 ; // temperatures
m_Me1 ; // relative masses

double
double
std :: vector < double >
std :: vector < double >

m_beta2 ;
m_variance2 ;
m_Te2 ; // temperatures
m_Me2 ; // relative masses

double
double
std :: vector < double >
std :: vector < double >

m_beta3 ;
m_variance3 ;
m_Te3 ; // temperatures
m_Me3 ; // relative masses

const QUESO :: B as eE n vi ro nm e nt * m_env ;
};
template < class P_V , class P_M >
likelihoodRoutine_Data < P_V , P_M >:: l i k e l i h o o d R o u t i n e _ D a t a (
const QUESO :: B as eE n vi ro nm e nt & env ,
const char * inpName1 ,
const char * inpName2 ,
const char * inpName3 )
:
m_beta1
(0.) ,
m_variance1 (0.) ,
m_Te1
(0) ,
m_Me1
(0) ,
m_beta2
(0.) ,
m_variance2 (0.) ,
m_Te2
(0) ,
m_Me2
(0) ,
m_beta3
(0.) ,
m_variance3 (0.) ,
m_Te3
(0) ,
m_Me3
(0) ,
m_env
(& env )
{
// Read experimental data
if ( inpName1 ) {
m_Te1 . resize (11 ,0.) ;
m_Me1 . resize (11 ,0.) ;
// Open input file on experimental data
FILE * inp ;
inp = fopen ( inpName1 , " r " ) ;
// Read kinetic parameters and convert heating rate to K / s
int aux1 = fscanf ( inp , " % lf % lf " ,& m_beta1 ,& m_variance1 ) ;
m_beta1 /= 60.;
if ( aux1 ) {}; // just to eliminate warnings
unsigned int nu mO bs e rv at io n s = 0;

114

CHAPTER 5. QUESO EXAMPLES

115

double tmpTe ;
double tmpMe ;
while ( fscanf ( inp , " % lf % lf " ,& tmpTe ,& tmpMe ) != EOF ) {
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns >= m_Te1 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 1 has too many observations " ) ;
m_Te1 [ n um O bs er v at io ns ] = tmpTe ;
m_Me1 [ n um O bs er v at io ns ] = tmpMe ;
n um Ob se r va ti on s ++;
}
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns != m_Te1 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 1 has a smaller number of observations than expected " ) ;
// Close input file on experimental data
fclose ( inp ) ;
}
// Read experimental data
if ( inpName2 ) {
m_Te2 . resize (11 ,0.) ;
m_Me2 . resize (11 ,0.) ;
// Open input file on experimental data
FILE * inp ;
inp = fopen ( inpName2 , " r " ) ;
// Read kinetic parameters and convert heating rate to K / s
int aux2 = fscanf ( inp , " % lf % lf " ,& m_beta2 ,& m_variance2 ) ;
m_beta2 /= 60.;
if ( aux2 ) {}; // just to eliminate warnings
unsigned int nu mO bs e rv at io n s = 0;
double tmpTe ;
double tmpMe ;
while ( fscanf ( inp , " % lf % lf " ,& tmpTe ,& tmpMe ) != EOF ) {
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns >= m_Te2 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 2 has too many observations " ) ;
m_Te2 [ n um O bs er v at io ns ] = tmpTe ;
m_Me2 [ n um O bs er v at io ns ] = tmpMe ;
n um Ob se r va ti on s ++;
}
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns != m_Te2 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 2 has a smaller number of observations than expected " ) ;
// Close input file on experimental data
fclose ( inp ) ;
}
// Read experimental data
if ( inpName3 ) {
m_Te3 . resize (11 ,0.) ;
m_Me3 . resize (11 ,0.) ;
// Open input file on experimental data
FILE * inp ;
inp = fopen ( inpName3 , " r " ) ;

CHAPTER 5. QUESO EXAMPLES

116

// Read kinetic parameters and convert heating rate to K / s
int aux3 = fscanf ( inp , " % lf % lf " ,& m_beta3 ,& m_variance3 ) ;
m_beta3 /= 60.;
if ( aux3 ) {}; // just to eliminate warnings
unsigned int nu mO bs e rv at io n s = 0;
double tmpTe ;
double tmpMe ;
while ( fscanf ( inp , " % lf % lf " ,& tmpTe ,& tmpMe ) != EOF ) {
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns >= m_Te3 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 3 has too many observations " ) ;
m_Te3 [ n um O bs er v at io ns ] = tmpTe ;
m_Me3 [ n um O bs er v at io ns ] = tmpMe ;
n um Ob se r va ti on s ++;
}
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns != m_Te3 . size () ) ,
env . fullRank () ,
" uqAppl () , in uqTgaEx4 . h " ,
" input file 3 has a smaller number of observations than expected " ) ;
// Close input file on experimental data
fclose ( inp ) ;

}
}
template < class P_V , class P_M >
likelihoodRoutine_Data < P_V , P_M >::~ l i k e l i h o o d R o u t i n e _ D a t a ()
{
}
//********************************************************
// The actual ( user defined ) likelihood routine
//********************************************************
template < class P_V , class P_M >
double
likelihoodRoutine (
const P_V & paramValues ,
const P_V * paramDirection ,
const void * functionDataPtr ,
P_V *
gradVector ,
P_M *
hessianMatrix ,
P_V *
hessianEffect )
{
double resultValue = 0.;
const QUESO :: B as eE n vi ro nm e nt & env = *((( likelihoodRoutine_Data < P_V , P_M > *) fu n ct io n Da ta Pt r )
-> m_env ) ;
env . subComm () . Barrier () ;
// env . s y n c P r i n t D e b u g M s g ( " Entering l i k e l i h o o d R o u t i n e () " ,1 , env . fullComm () ) ;
// Compute likelihood for scenario 1
double betaTest = (( likelihoodRoutine_Data < P_V , P_M > *) fu n ct io nD a ta Pt r ) -> m_beta1 ;
if ( betaTest ) {
double A
= paramValues [0];
double E
= paramValues [1];
double beta
= (( likelihoodRoutine_Data < P_V , P_M > *) fu nc t io nD at a Pt r ) ->
m_beta1 ;
double variance
= (( likelihoodRoutine_Data < P_V , P_M > *) fu nc ti o nD at aP t r ) ->
m_variance1 ;

CHAPTER 5. QUESO EXAMPLES

117

const std :: vector < double >& Te = (( likelihoodRoutine_Data < P_V , P_M > *) f un ct i on Da ta P tr ) ->
m_Te1 ;
const std :: vector < double >& Me = (( likelihoodRoutine_Data < P_V , P_M > *) f un ct i on Da ta P tr ) ->
m_Me1 ;
std :: vector < double > Mt ( Me . size () ,0.) ;
double params []={ A ,E , beta };
// integration
const g s l _ o d e i v _ s t e p _ t y p e
gsl_o deiv_st ep
gsl_odeiv_control
gsl_odeiv_evolve
gsl_odeiv_system

*T
*s
*c
*e
sys

=
=
=
=
=

g s l _ o d e i v _ s t e p _ r k f 4 5 ; // rkf45 ; // gear1 ;
g s l _ o d e i v _ s t e p _ a l l o c (T ,1) ;
g s l _ o d e i v _ c o n t r o l _ y _ n e w (1 e -6 ,0.0) ;
g s l _ o d e i v _ e v o l v e _ a l l o c (1) ;
{ func , NULL , 1 , ( void *) params };

double t = 0.1 , t_final = 1900.;
double h = 1e -3;
double Mass [1];
Mass [0]=1.;
unsigned int i = 0;
double t_old = 0.;
double M_old [1];
M_old [0]=1.;
double misfit =0.;
// unsigned int loopSize = 0;
while (( t < t_final ) && ( i < Me . size () ) ) {
int status = g s l _ o d e i v _ e v o l v e _ a p p l y (e , c , s , & sys , &t , t_final , &h , Mass ) ;
U Q _ F A T A L _ T E S T _ M A C R O (( status != GSL_SUCCESS ) ,
paramValues . env () . fullRank () ,
" l i k e l i h o o d R o u t i n e () " ,
" g s l _ o d e i v _ e v o l v e _ a p p l y () failed " ) ;
// printf ( " t = %6.1 lf , mass = %10.4 lf \ n " ,t , Mass [0]) ;
// loopSize ++;
while ( ( i < Me . size () ) && ( t_old <= Te [ i ]) && ( Te [ i ] <= t ) ) {
Mt [ i ] = ( Te [ i ] - t_old ) *( Mass [0] - M_old [0]) /( t - t_old ) + M_old [0];
misfit += ( Me [ i ] - Mt [ i ]) *( Me [ i ] - Mt [ i ]) ;
// printf ( " % i % lf % lf % lf % lf \ n " ,i , Te [ i ] , Me [ i ] , Mt [ i ] , misfit ) ;
i ++;
}
t_old = t ;
M_old [0]= Mass [0];
}
resultValue += misfit / variance ;
// printf ( " loopSize = % d \ n " , loopSize ) ;
if (( paramValues . env () . d i s p l a y V e r b o s i t y () >= 10) && ( paramValues . env () . fullRank () == 0) )
{
printf ( " In l i k e l i h o o d R o u t i n e () , A = %g , E = %g , beta = %.3 lf : misfit = % lf , likelihood
= % lf .\ n " ,A ,E , beta , misfit , resultValue ) ;
}
gsl_odeiv_evolve_free (e);
gsl_odeiv_control_free (c);
gsl_odeiv_step_free
(s);
}
// Compute likelihood for scenario 2
betaTest = (( likelihoodRoutine_Data < P_V , P_M > *) fu nc ti o nD at a Pt r ) -> m_beta2 ;
if ( betaTest > 0.) {
double A
= paramValues [0];
double E
= paramValues [1];

CHAPTER 5. QUESO EXAMPLES
double beta
= (( likelihoodRoutine_Data < P_V , P_M >
m_beta2 ;
double variance
= (( likelihoodRoutine_Data < P_V , P_M >
m_variance2 ;
const std :: vector < double >& Te = (( likelihoodRoutine_Data < P_V , P_M >
m_Te2 ;
const std :: vector < double >& Me = (( likelihoodRoutine_Data < P_V , P_M >
m_Me2 ;
std :: vector < double > Mt ( Me . size () ,0.) ;

118
*) fu nc t io nD at a Pt r ) ->
*) fu nc ti o nD at aP t r ) ->
*) f un ct i on Da ta P tr ) ->
*) f un ct i on Da ta P tr ) ->

double params []={ A ,E , beta };
// integration
const g s l _ o d e i v _ s t e p _ t y p e
gsl_o deiv_st ep
gsl_odeiv_control
gsl_odeiv_evolve
gsl_odeiv_system

*T
*s
*c
*e
sys

=
=
=
=
=

g s l _ o d e i v _ s t e p _ r k f 4 5 ; // rkf45 ; // gear1 ;
g s l _ o d e i v _ s t e p _ a l l o c (T ,1) ;
g s l _ o d e i v _ c o n t r o l _ y _ n e w (1 e -6 ,0.0) ;
g s l _ o d e i v _ e v o l v e _ a l l o c (1) ;
{ func , NULL , 1 , ( void *) params };

double t = 0.1 , t_final = 1900.;
double h = 1e -3;
double Mass [1];
Mass [0]=1.;
unsigned int i = 0;
double t_old = 0.;
double M_old [1];
M_old [0]=1.;
double misfit =0.;
// unsigned int loopSize = 0;
while (( t < t_final ) && ( i < Me . size () ) ) {
int status = g s l _ o d e i v _ e v o l v e _ a p p l y (e , c , s , & sys , &t , t_final , &h , Mass ) ;
U Q _ F A T A L _ T E S T _ M A C R O (( status != GSL_SUCCESS ) ,
paramValues . env () . fullRank () ,
" l i k e l i h o o d R o u t i n e () " ,
" g s l _ o d e i v _ e v o l v e _ a p p l y () failed " ) ;
// printf ( " t = %6.1 lf , mass = %10.4 lf \ n " ,t , Mass [0]) ;
// loopSize ++;
while ( ( i < Me . size () ) && ( t_old <= Te [ i ]) && ( Te [ i ] <= t ) ) {
Mt [ i ] = ( Te [ i ] - t_old ) *( Mass [0] - M_old [0]) /( t - t_old ) + M_old [0];
misfit += ( Me [ i ] - Mt [ i ]) *( Me [ i ] - Mt [ i ]) ;
// printf ( " % i % lf % lf % lf % lf \ n " ,i , Te [ i ] , Me [ i ] , Mt [ i ] , misfit ) ;
i ++;
}
t_old = t ;
M_old [0]= Mass [0];
}
resultValue += misfit / variance ;
// printf ( " loopSize = % d \ n " , loopSize ) ;
if (( paramValues . env () . d i s p l a y V e r b o s i t y () >= 10) && ( paramValues . env () . fullRank () == 0) )
{
printf ( " In l i k e l i h o o d R o u t i n e () , A = %g , E = %g , beta = %.3 lf : misfit = % lf , likelihood
= % lf .\ n " ,A ,E , beta , misfit , resultValue ) ;
}
gsl_odeiv_evolve_free (e);
gsl_odeiv_control_free (c);
gsl_odeiv_step_free
(s);
}
// Compute likelihood for scenario 3

CHAPTER 5. QUESO EXAMPLES

119

betaTest = (( likelihoodRoutine_Data < P_V , P_M > *) fu nc ti o nD at a Pt r ) -> m_beta3 ;
if ( betaTest > 0.) {
double A
= paramValues [0];
double E
= paramValues [1];
double beta
= (( likelihoodRoutine_Data < P_V , P_M > *) fu nc t io nD at a Pt r ) ->
m_beta3 ;
double variance
= (( likelihoodRoutine_Data < P_V , P_M > *) fu nc ti o nD at aP t r ) ->
m_variance3 ;
const std :: vector < double >& Te = (( likelihoodRoutine_Data < P_V , P_M > *) f un ct i on Da ta P tr ) ->
m_Te3 ;
const std :: vector < double >& Me = (( likelihoodRoutine_Data < P_V , P_M > *) f un ct i on Da ta P tr ) ->
m_Me3 ;
std :: vector < double > Mt ( Me . size () ,0.) ;
double params []={ A ,E , beta };
// integration
const g s l _ o d e i v _ s t e p _ t y p e
gsl_o deiv_st ep
gsl_odeiv_control
gsl_odeiv_evolve
gsl_odeiv_system

*T
*s
*c
*e
sys

=
=
=
=
=

g s l _ o d e i v _ s t e p _ r k f 4 5 ; // rkf45 ; // gear1 ;
g s l _ o d e i v _ s t e p _ a l l o c (T ,1) ;
g s l _ o d e i v _ c o n t r o l _ y _ n e w (1 e -6 ,0.0) ;
g s l _ o d e i v _ e v o l v e _ a l l o c (1) ;
{ func , NULL , 1 , ( void *) params };

double t = 0.1 , t_final = 1900.;
double h = 1e -3;
double Mass [1];
Mass [0]=1.;
unsigned int i = 0;
double t_old = 0.;
double M_old [1];
M_old [0]=1.;
double misfit =0.;
// unsigned int loopSize = 0;
while (( t < t_final ) && ( i < Me . size () ) ) {
int status = g s l _ o d e i v _ e v o l v e _ a p p l y (e , c , s , & sys , &t , t_final , &h , Mass ) ;
U Q _ F A T A L _ T E S T _ M A C R O (( status != GSL_SUCCESS ) ,
paramValues . env () . fullRank () ,
" l i k e l i h o o d R o u t i n e () " ,
" g s l _ o d e i v _ e v o l v e _ a p p l y () failed " ) ;
// printf ( " t = %6.1 lf , mass = %10.4 lf \ n " ,t , Mass [0]) ;
// loopSize ++;
while ( ( i < Me . size () ) && ( t_old <= Te [ i ]) && ( Te [ i ] <= t ) ) {
Mt [ i ] = ( Te [ i ] - t_old ) *( Mass [0] - M_old [0]) /( t - t_old ) + M_old [0];
misfit += ( Me [ i ] - Mt [ i ]) *( Me [ i ] - Mt [ i ]) ;
// printf ( " % i % lf % lf % lf % lf \ n " ,i , Te [ i ] , Me [ i ] , Mt [ i ] , misfit ) ;
i ++;
}
t_old = t ;
M_old [0]= Mass [0];
}
resultValue += misfit / variance ;
// printf ( " loopSize = % d \ n " , loopSize ) ;
if (( paramValues . env () . d i s p l a y V e r b o s i t y () >= 10) && ( paramValues . env () . fullRank () == 0) )
{
printf ( " In l i k e l i h o o d R o u t i n e () , A = %g , E = %g , beta = %.3 lf : misfit = % lf , likelihood
= % lf .\ n " ,A ,E , beta , misfit , resultValue ) ;
}
gsl_odeiv_evolve_free (e);
gsl_odeiv_control_free (c);

CHAPTER 5. QUESO EXAMPLES
gsl_odeiv_step_free

(s);

}
env . subComm () . Barrier () ;
// env . s y n c P r i n t D e b u g M s g ( " Leaving l i k e l i h o o d R o u t i n e () " ,1 , env . fullComm () ) ;
#i f d e f QUESO EXPECTS LN LIKELIHOOD INSTEAD OF MINUS 2 LN
return -.5* resultValue ;
#e l s e
return resultValue ;
#e n d i f
}
#e n d i f // EX TGA VALIDATION CYCLE LIKELIHOOD H

Listing 5.49: File exTgaValidationCycle likelihood.h.
#i f n d e f EX TGA VALIDATION CYCLE QOI H
#d e f i n e EX TGA VALIDATION CYCLE QOI H
#i n c l u d e 
#i n c l u d e 
#i n c l u d e < g s l / g s l o d e i v . h>
//********************************************************
// The ( user defined ) data class that carries the data
// needed by the ( user defined ) qoi routine
//********************************************************
template < class P_V , class P_M , class Q_V , class Q_M >
struct
q oi Ro ut i ne _D at a
{
double m_beta ;
double m_cri ticalMas s ;
double m_cri ticalTim e ;
};
// The actual ( user defined ) qoi routine
template < class P_V , class P_M , class Q_V , class Q_M >
void qoiRoutine ( const P_V &
paramValues ,
const P_V *
paramDirection ,
const void *
functionDataPtr ,
Q_V &
qoiValues ,
QUESO :: DistArray < P_V * >* gradVectors ,
QUESO :: DistArray < P_M * >* hessianMatrices ,
QUESO :: DistArray < P_V * >* hess ianEffec ts )
{
double A
= paramValues [0];
double E
= paramValues [1];
double beta
= (( qoiRoutine_Data < P_V , P_M , Q_V , Q_M > *) fu nc t io nD a ta Pt r ) -> m_beta ;
double criticalMass = (( qoiRoutine_Data < P_V , P_M , Q_V , Q_M > *) f u nc ti on D at aP tr ) ->
m_cri ticalMa ss ;
double criticalTime = (( qoiRoutine_Data < P_V , P_M , Q_V , Q_M > *) f u nc ti on D at aP tr ) ->
m_cri ticalTi me ;
double params []={ A ,E , beta };
// integration
const g s l _ o d e i v _ s t e p _ t y p e
gsl_o deiv_st ep
gsl_odeiv_control
gsl_odeiv_evolve

*T
*s
*c
*e

=
=
=
=

g s l _ o d e i v _ s t e p _ r k f 4 5 ; // rkf45 ; // gear1 ;
g s l _ o d e i v _ s t e p _ a l l o c (T ,1) ;
g s l _ o d e i v _ c o n t r o l _ y _ n e w (1 e -6 ,0.0) ;
g s l _ o d e i v _ e v o l v e _ a l l o c (1) ;

120

CHAPTER 5. QUESO EXAMPLES
gsl_odeiv_system

121

sys = { func , NULL , 1 , ( void *) params };

double temperature = 0.1;
double h = 1e -3;
double Mass [1];
Mass [0]=1.;
double t em p er at ur e _o ld = 0.;
double M_old [1];
M_old [0]=1.;
double c r o s s i n g T e m p e r a t u r e = 0.;
// unsigned int loopSize = 0;
while (( temperature < criticalTime * beta ) &&
( Mass [0]
> criticalMass
)) {
int status = g s l _ o d e i v _ e v o l v e _ a p p l y (e , c , s , & sys , & temperature , criticalTime * beta , &h ,
Mass ) ;
U Q _ F A T A L _ T E S T _ M A C R O (( status != GSL_SUCCESS ) ,
paramValues . env () . fullRank () ,
" qoiRoutine () " ,
" g s l _ o d e i v _ e v o l v e _ a p p l y () failed " ) ;
// printf ( " t = %6.1 lf , mass = %10.4 lf \ n " ,t , Mass [0]) ;
// loopSize ++;
if ( Mass [0] <= criticalMass ) {
c r o s s i n g T e m p e r a t u r e = t em pe ra t ur e_ ol d + ( temperature - t em p er at ur e _o ld ) * ( M_old [0] criticalMass ) /( M_old [0] - Mass [0]) ;
}
t em pe ra t ur e_ ol d = temperature ;
M_old [0]= Mass [0];
}
if ( criticalMass > 0.) qoiValues [0] = c r o s s i n g T e m p e r a t u r e / beta ; // QoI = time to achieve
critical mass
if ( criticalTime > 0.) qoiValues [0] = Mass [0];
// QoI = mass fraction
remaining at critical time
// printf ( " loopSize = % d \ n " , loopSize ) ;
if (( paramValues . env () . d i s p l a y V e r b o s i t y () >= 3) && ( paramValues . env () . fullRank () == 0) ) {
printf ( " In qoiRoutine () , A = %g , E = %g , beta = %.3 lf , criticalTime = %.3 lf , criticalMass
= %.3 lf : qoi = % lf .\ n " ,A ,E , beta , criticalTime , criticalMass , qoiValues [0]) ;
}
gsl_odeiv_evolve_free (e);
gsl_odeiv_control_free (c);
gsl_odeiv_step_free
(s);
return ;
}
#e n d i f // EX TGA VALIDATION CYCLE QOI H

Listing 5.50: File exTgaValidationCycle qoi.h.

5.4.6 Input File
The input file used with this TGA SIP–SFP QUESO provides QUESO with options for its environments, and for both MCMC and Monte-Carlo algorithms. It is displayed in Listing 5.51.

CHAPTER 5. QUESO EXAMPLES

122

###############################################
# UQ E n v i r o n m e n t
###############################################
#e n v h e l p
= anything
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0 1
env_displayVerbosity
= 2
env_syncVerbosity
= 0
env_seed
= 0
###############################################
# C a l i b r a t i o n ( c a l ) s t a g e : s t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
cycle_cal_ip_help
= anything
cycle_cal_ip_computeSolution
= 1
cycle_cal_ip_dataOutputFileName
= outputData / tgaCalOutput
cycle_cal_ip_dataOutputAllowedSet = 0 1
###############################################
# ’ c a l i p ’ : i n f o r m a t i o n f o r M e t r o p o l i s −H a s t i n g s a l g o r i t h m
#
# ’ s i z e ’ e x a m p l e s 16K
128K
1M
2M
16M
#
16384 131072 1048576 2097152 16777216
###############################################
cycle_cal_ip_mh_help
= anything
cycle_cal_ip_mh_dataOutputFileName
= outputData / tgaCalOutput
cycle_cal_ip_mh_dataOutputAllowedSet = 0 1
cycle_cal_ip_mh_initialPosition_dataInputFileName
= . # inputData / i n i t P o s
cycle_cal_ip_mh_initialPosition_dataInputFileType
= m
cycle_cal_ip_mh_initialProposalCovMatrix_dataInputFileName = . # inputData /
adaptedMatrix am910000
cycle_cal_ip_mh_initialProposalCovMatrix_dataInputFileType = m
cycle_cal_ip_mh_rawChain_dataInputFileName
= . # outputData / f i l e c a l i p r a w i n p u t
cycle_cal_ip_mh_rawChain_size
= 1048576
cycle_cal_ip_mh_rawChain_generateExtra
= 0
cycle_cal_ip_mh_rawChain_displayPeriod
= 20000
cycle_cal_ip_mh_rawChain_measureRunTimes
= 1
cycle_cal_ip_mh_rawChain_dataOutputFileName
= outputData / fi le _ ca l_ ip _ ra w
cycle_cal_ip_mh_rawChain_dataOutputAllowedSet = 0 1
cycle_cal_ip_mh_displayCandidates
= 0
cycle_cal_ip_mh_putOutOfBoundsInChain
= 1
cycle_cal_ip_mh_tk_useLocalHessian
= 0
cycle_cal_ip_mh_tk_useNewtonComponent
= 1
cycle_cal_ip_mh_dr_maxNumExtraStages
= 1
c y c l e _ c a l _ i p _ m h _ d r _ l i s t O f S c a l e s F o r E x t r a S t a g e s = 5. 4. 3.
cycle_cal_ip_mh_am_initialNonAdaptInterval
= 0 # 10000
cycle_cal_ip_mh_am_adaptInterval
= 100 # 10000
cycle_cal_ip_mh_am_adaptedMatrices_dataOutputPeriod
= 60000
cycle_cal_ip_mh_am_adaptedMatrices_dataOutputFileName = . # outputData / adaptedMatrix
cycle_cal_ip_mh_am_adaptedMatrices_dataOutputFileType = m
cycle_cal_ip_mh_am_eta
= 1.92
cycle_cal_ip_mh_am_epsilon
= 1. e -5
cycle_cal_ip_mh_filteredChain_generate
cycle_cal_ip_mh_filteredChain_discardedPortion
cycle_cal_ip_mh_filteredChain_lag
cycle_cal_ip_mh_filteredChain_dataOutputFileName
cycle_cal_ip_mh_filteredChain_dataOutputAllowedSet
###############################################

=
=
=
=
=

1
0.
20
.
0 1

CHAPTER 5. QUESO EXAMPLES

123

# C a l i b r a t i o n ( c a l ) s t a g e : s t a t i s t i c a l forward problem ( fp )
###############################################
cycle_cal_fp_help
= anything
cycle_cal_fp_computeSolution
= 1
cycle_cal_fp_computeCovariances
= 1
cycle_cal_fp_computeCorrelations = 1
cycle_cal_fp_dataOutputFileName
= outputData / tgaCalOutput
cycle_cal_fp_dataOutputAllowedSet = 0 1
###############################################
# ’ c a l f p ’ : i n f o r m a t i o n f o r Monte C a r l o a l g o r i t h m
#
# ’ s i z e ’ e x a m p l e s 16K
128K
1M
2M
16M
#
16384 131072 1048576 2097152 16777216
###############################################
cycle_cal_fp_mc_help
= anything
cycle_cal_fp_mc_dataOutputFileName
= outputData / tgaCalOutput
cycle_cal_fp_mc_dataOutputAllowedSet = 0 1
cycle_cal_fp_mc_pseq_dataOutputFileName
= .
cycle_cal_fp_mc_pseq_dataOutputAllowedSet = 0 1
cycle_cal_fp_mc_qseq_dataInputFileName
cycle_cal_fp_mc_qseq_size
cycle_cal_fp_mc_qseq_displayPeriod
cycle_cal_fp_mc_qseq_measureRunTimes
cycle_cal_fp_mc_qseq_dataOutputFileName
cycle_cal_fp_mc_qseq_dataOutputAllowedSet

=
=
=
=
=
=

. # outputData / f i l e c a l f p q o i 1
1048576
20000
1
outputData / f i l e _ c a l _ f p _ q o i 2
0 1

###############################################
# V a l i d a t i o n ( v a l ) s t a g e : s t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
cycle_val_ip_help
= anything
cycle_val_ip_computeSolution
= 1
cycle_val_ip_dataOutputFileName
= outputData / tgaValOutput
cycle_val_ip_dataOutputAllowedSet = 0 1
###############################################
# ’ v a l i p ’ : i n f o r m a t i o n f o r M e t r o p o l i s −H a s t i n g s a l g o r i t h m
#
# ’ s i z e ’ e x a m p l e s 16K
128K
1M
2M
16M
#
16384 131072 1048576 2097152 16777216
###############################################
cycle_val_ip_mh_help
= anything
cycle_val_ip_mh_dataOutputFileName
= outputData / tgaValOutput
cycle_val_ip_mh_dataOutputAllowedSet = 0 1
cycle_val_ip_mh_rawChain_dataInputFileName
cycle_val_ip_mh_rawChain_size
cycle_val_ip_mh_rawChain_generateExtra
cycle_val_ip_mh_rawChain_displayPeriod
cycle_val_ip_mh_rawChain_measureRunTimes
cycle_val_ip_mh_rawChain_dataOutputFileName
cycle_val_ip_mh_rawChain_dataOutputAllowedSet

=
=
=
=
=
=
=

. # outputData / f i l e v a l i p r a w i n p u t
1048576
0
20000
1
outputData / fi le _ va l_ ip _ ra w
0 1

cycle_val_ip_mh_displayCandidates
cycle_val_ip_mh_putOutOfBoundsInChain
cycle_val_ip_mh_tk_useLocalHessian
cycle_val_ip_mh_tk_useNewtonComponent
cycle_val_ip_mh_dr_maxNumExtraStages
cycle_val_ip_mh_dr_listOfScalesForExtraStages
cycle_val_ip_mh_am_initialNonAdaptInterval
cycle_val_ip_mh_am_adaptInterval
cycle_val_ip_mh_am_eta
cycle_val_ip_mh_am_epsilon

=
=
=
=
=
=
=
=
=
=

0
1
0
1
1
5. 4. 3.
0
100
1.92
1. e -5

CHAPTER 5. QUESO EXAMPLES

124

cycle_val_ip_mh_filteredChain_generate
cycle_val_ip_mh_filteredChain_discardedPortion
cycle_val_ip_mh_filteredChain_lag
cycle_val_ip_mh_filteredChain_dataOutputFileName
cycle_val_ip_mh_filteredChain_dataOutputAllowedSet

=
=
=
=
=

1
0.
20
.
0 1

###############################################
# V a l i d a t i o n ( v a l ) s t a g e : s t a t i s t i c a l forward problem ( fp )
###############################################
cycle_val_fp_help
= anything
cycle_val_fp_computeSolution
= 1
cycle_val_fp_computeCovariances
= 1
cycle_val_fp_computeCorrelations = 1
cycle_val_fp_dataOutputFileName
= outputData / tgaValOutput
cycle_val_fp_dataOutputAllowedSet = 0 1
###############################################
# ’ v a l f p ’ : i n f o r m a t i o n f o r Monte C a r l o a l g o r i t h m
#
# ’ s i z e ’ e x a m p l e s 16K
128K
1M
2M
16M
#
16384 131072 1048576 2097152 16777216
###############################################
cycle_val_fp_mc_help
= anything
cycle_val_fp_mc_dataOutputFileName
= outputData / tgaValOutput
cycle_val_fp_mc_dataOutputAllowedSet = 0 1
cycle_val_fp_mc_pseq_dataOutputFileName
= .
cycle_val_fp_mc_pseq_dataOutputAllowedSet = 0 1

cycle_val_fp_mc_qseq_dataInputFileName
cycle_val_fp_mc_qseq_size
cycle_val_fp_mc_qseq_displayPeriod
cycle_val_fp_mc_qseq_measureRunTimes
cycle_val_fp_mc_qseq_dataOutputFileName
cycle_val_fp_mc_qseq_dataOutputAllowedSet

=
=
=
=
=
=

. # outputData / f i l e v a l f p q o i 1
1048576
20000
1
outputData / f i l e _ v a l _ f p _ q o i 2
0 1

Listing 5.51: File name tgaCycle.inp with options for QUESO library used in application
code (Listings 5.47-5.49).

5.4.7 Data Post-Processing and Visualization
According to the specifications of the input file in Listing 5.51, both a folder named outputData
and a the following files should be generated:
file_cal_ip_raw.m
file_cal_ip_raw_sub0.m
file_cal_fp_qoi2.m
file_cal_fp_qoi2_sub0.m
tgaCalOutput_sub0.m
display_sub0.txt

file_val_ip_raw.m
file_val_ip_raw_sub0.m
file_val_fp_qoi2.m
file_val_fp_qoi2_sub0.m
tgaValOutput_sub0.m

The sequence of Matlab commands is identical to the ones presented in Sections 5.1.5,
5.2.5 and 5.3.8; therefore, are omitted here. The reader is invited to explore the Matlab file
tga cycle plot.m for details of how the figures have been generated.

CHAPTER 5. QUESO EXAMPLES

125

5.4.7.1 KDE Plots of Parameters
Matlab function ksdensity (Kernel smoothing density estimate) together with the option
‘pdf’ may be used to estimate the KDE of the parameters, as illustrated in Figure 5.4.2.

Figure 5.4.2: Posterior distributions of parameters A and E.

5.4.7.2 CDF Plots of Parameters
Matlab function ksdensity with ’cdf’ option may also be used for plotting the Cumulative
Distribution Function of each one of the parameters, as illustrated in Figure 5.4.3.

Figure 5.4.3: Cumulative density functions of parameters A and E.

5.4.7.3 Autocorrelation Plots of Parameters
Figure 5.4.4 presents the autocorrelation of the parameters A and E in both cases: calibration
and validation stages.

5.4.7.4 KDE, CDF and Autocorrelation Plots of QoI
Figures 5.4.5a and 5.4.5b present PDF and CDF of QoI, respectively and Figure 5.4.6 presents
its autocorrelation.

CHAPTER 5. QUESO EXAMPLES

126

Figure 5.4.4: Autocorrelation of parameters A and E (filtered chain).

(a) QoI PDF

(b) QoI CDF

Figure 5.4.5: QoI PDF and CDF, during calibration and validation stages.

Figure 5.4.6: QoI autocorrelation.

CHAPTER 5. QUESO EXAMPLES

127

5.5 modal
This example presents a combination of two statistical inverse problems in one. It presents
the capability of the Multilevel method in sampling from a target distribution that has either
one or two modes (distinct peaks). The random variable of interest has three parameters, i.e.,
θ = (θ1 , θ2 , σ 2 ) ∈ R3 , where the third parameter may be seen as variation.
The example also it gives the user the opportunity to chose either one single type of prior
distribution, uniform, for the three components of the random variable, or two different priors:
a uniform and a beta distribution.
Choosing between a one-mode or a two-mode target distribution is done at execution level,
as presented in the following code line:
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/
cd examples / modal
rm outputData /*
./ modal_gsl example . inp < num_of_nodes >

where  is either 1 or 2.

5.5.1 One-mode distribution
In this case, the target distribution is assumed to have only one mode. Suppose also that the
random variable θ can either have a uniform prior distribution for all its components, i.e.:
πprior = U([0, 3]) × U([0, 3]) × U([0, 0.3]).
or, the prior distribution is defined as a combination of uniform prior for θ1 and θ2 , with a
beta prior for σ 2 :
πprior = U([0, 3]) × U([0, 3]) × B(α, β),

with α = 3 and β = 0.09709133373799.

The likelihood function is defined as follows:
"
r

!2
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 72.0470 +



1
5
f (D|θ) = − log 2πσ 2 − 2
2
2σ

+

!2
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 71.8995 +

+

!2
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 72.2801 + (5.5.1)

+

!2
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 71.9421 +

+

!2 #
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 72.3578
.

r

r

r

r

CHAPTER 5. QUESO EXAMPLES

128

5.5.1.1 Running the One-Mode Example
To run the executable provided considering a one-mode distribution, enter the following commands:
$
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/
cd examples / modal
rm outputData /*
./ modal_gsl example . inp 1
#one mode !
matlab
$ plot_modal_all_levels_1mode # i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
m o d a l _ 1 _ m o d e _ k d e _ t a r g e t . png m o d a l _ 1 _ m o d e _ l e v e l _ 1 . png
m o d a l _ 1 _ m o d e _ k d e _ t h e t a 1 . png m o d a l _ 1 _ m o d e _ l e v e l _ 2 . png
m o d a l _ 1 _ m o d e _ k d e _ t h e t a 2 . png m o d a l _ 1 _ m o d e _ l e v e l _ 3 . png
m o d a l _ 1 _ m o d e _ k d e _ t h e t a 3 . png m o d a l _ 1 _ m o d e _ l e v e l _ 4 . png

m o d a l _ 1 _ m o d e _ l e v e l _ 5 . png
m o d a l _ 1 _ m o d e _ l e v e l _ 6 . png
m o d a l _ 1 _ m o d e _ l e v e l _ 7 . png

Listing 5.52: Running the example with a one-mode distribution.
As a result, the user should have created several of PNG figures scatter plots of each one of
the levels and the kernel density estimation of the parameters, for each level in the Multilevel
method. The name of the figure files have been chosen to be informative, as shown in the
Listing above.

5.5.2 Two-mode distribution
In this case, the target distribution is assumed to have two modes. Suppose that θ has a
either uniform distribution for all its components, i.e.:
πprior = U([0, 3]) × U([0, 3]) × U([0, 0.3]).
or, the prior distribution is defined as a combination of uniform prior for the θ1 , with a beta
prior for θ2 :
πprior = U([0, 3]) × U([0, 3]) × B(α, β),

with α = 3 and β = 0.08335837191688.

CHAPTER 5. QUESO EXAMPLES

129

The likelihood function is defined as follows:
"
r
f (D|θ) = −5 log 2πσ



2

!2
q
10 10θ1 + 20θ2 + 10 θ12 + 4θ22 − 72.0470 +

1
− 2
2σ

r
+

10 10θ1 + 20θ2 + 10
r

+

10 10θ1 + 20θ2 + 10
r

+

10 10θ1 + 20θ2 + 10
r

q

q

q

q

!2
θ12 + 4θ22 − 71.8995

+

!2
θ12 + 4θ22 − 72.2801

+

!2
θ12 + 4θ22 − 71.9421

+

!2
θ12 + 4θ22 − 72.3578

+

10 10θ1 + 20θ2 + 10

+

!2
q
10 10θ1 + 20θ2 − 10 θ12 + 4θ22 − 28.0292 +

+

!2
q
10 10θ1 + 20θ2 − 10 θ12 + 4θ22 − 27.3726 +

+

!2
q
10 10θ1 + 20θ2 − 10 θ12 + 4θ22 − 27.5388 +

+

!2
q
10 10θ1 + 20θ2 − 10 θ12 + 4θ22 − 27.0357 +

+

!2 #
q
10 10θ1 + 20θ2 − 10 θ12 + 4θ22 − 27.1588
.

+

r

(5.5.2)

r

r

r

r

5.5.2.1 Running the Two-Mode Example
To run the executable provided considering a two-modes distribution, enter the following
commands:
$
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/
cd examples / modal
rm outputData /*
./ modal_gsl example . inp 2
# two modes !
matlab
$ plot_modal_all_levels_2modes # i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
m o d a l _ 2 _ m o d e s _ k d e _ t a r g e t . png m o d a l _ 2 _ m o d e s _ l e v e l _ 1 . png
m o d a l _ 2 _ m o d e s _ k d e _ t h e t a 1 . png m o d a l _ 2 _ m o d e s _ l e v e l _ 2 . png

m o d a l _ 2 _ m o d e s _ l e v e l _ 5 . png
m o d a l _ 2 _ m o d e s _ l e v e l _ 6 . png

CHAPTER 5. QUESO EXAMPLES
m o d a l _ 2 _ m o d e s _ k d e _ t h e t a 2 . png
m o d a l _ 2 _ m o d e s _ k d e _ t h e t a 3 . png

m o d a l _ 2 _ m o d e s _ l e v e l _ 3 . png
m o d a l _ 2 _ m o d e s _ l e v e l _ 4 . png

130
m o d a l _ 2 _ m o d e s _ l e v e l _ 7 . png
m o d a l _ 2 _ m o d e s _ l e v e l _ 8 . png

Listing 5.53: Running the example with a two-mode distribution.
As a result, the user should have created several of PNG figures scatter plots of each one of
the levels and the kernel density estimation of the parameters, for each level in the Multilevel
method. The name of the figure files have been chosen to be informative, as shown in the
Listing above.

5.5.3 Example Code
The source code for the example is composed of 5 files: example main.C (Listing 5.54),
example likelihood.h and example likelihood.C (Listings 5.55 and 5.56), example compute.h
and example compute.C (Listings 5.57 and 5.58).
#i n c l u d e 
int main ( int argc , char * argv [])
{
// Initialize environment
MPI_Init (& argc ,& argv ) ;
U Q _ F A T A L _ T E S T _ M A C R O ( argc != 3 ,
QUESO :: UQ_UNAVAILABLE_RANK ,
" main () " ,
" after executable argv [0] , input file must be specified in command line
as argv [1] , then numModes (1 or 2) must be specified as argv [2] " ) ;
QUESO :: Fu ll En v ir on me n t * env =
new QUESO :: Fu ll En v ir on me n t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;
// Compute
unsigned int numModes = ( unsigned int ) atoi ( argv [2]) ;
compute (* env , numModes ) ;
// Finalize environment
delete env ;
MPI_Finalize () ;
std :: cout << std :: endl << " FIM ! " << std :: endl << std :: endl ;
return 0;
}

Listing 5.54: File example main.C.
#i f n d e f
#d e f i n e

EX LIKELIHOOD H
EX LIKELIHOOD H

#i n c l u d e 
struct
likelihoodRoutine_DataType

CHAPTER 5. QUESO EXAMPLES
{
unsigned int numModes ;
};
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *

paramValues ,
paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect ) ;

#e n d i f

Listing 5.55: File example likelihood.h.
#i n c l u d e < e x a m p l e l i k e l i h o o d . h>
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector & paramValues ,
const QUESO :: GslVector * paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector *
gradVector ,
QUESO :: GslMatrix *
hessianMatrix ,
QUESO :: GslVector *
hessianEffect )
{
double theta1 = paramValues [0];
double theta2 = paramValues [1];
double sigmaSq = paramValues [2];
unsigned int numModes = (( l i k e l i h o o d R o u t i n e _ D a t a T y p e *) fu n ct io n Da ta Pt r ) -> numModes ;
double aux1 = theta1 + 2.* theta2 ;
double aux2 = sqrt ( theta1 * theta1 +4.* theta2 * theta2 ) ;
double w1 = 10.* sqrt (10.*( aux1 + aux2 ) ) ;
double w2 = 10.* sqrt (10.*( aux1 - aux2 ) ) ;
double sum1 = 0.;
double sum2 = 0.;
double aux = ( w1 - 72.0470) ;
sum1 += aux * aux ;
aux = ( w1 - 71.8995) ;
sum1 += aux * aux ;
aux = ( w1 - 72.2801) ;
sum1 += aux * aux ;
aux = ( w1 - 71.9421) ;
sum1 += aux * aux ;
aux = ( w1 - 72.3578) ;
sum1 += aux * aux ;
if ( numModes == 1) {
// Ok , do nothing
}
else if ( numModes == 2) {
aux = ( w2 - 28.0292) ;
sum2 += aux * aux ;
aux = ( w2 - 27.3726) ;
sum2 += aux * aux ;
aux = ( w2 - 27.5388) ;
sum2 += aux * aux ;

131

CHAPTER 5. QUESO EXAMPLES

132

aux = ( w2 - 27.0357) ;
sum2 += aux * aux ;
aux = ( w2 - 27.1588) ;
sum2 += aux * aux ;
}
else {
U Q _ F A T A L _ T E S T _ M A C R O ( true ,
paramValues . env () . fullRank () ,
" e x a m p l e _ l i k e l i h o o d () " ,
" invalid ’ numModes ’ " ) ;
}
double result = -0.5*(( double ) numModes ) *5.* log (2.* M_PI * sigmaSq ) - 0.5*( sum1 + sum2 ) / sigmaSq ;

#i f d e f QUESO EXPECTS LN LIKELIHOOD INSTEAD OF MINUS 2 LN
return result ;
#e l s e
return -2.* result ;
#e n d i f
}

Listing 5.56: File example likelihood.C.
#i f n d e f
#d e f i n e

EX COMPUTE H
EX COMPUTE H

#i n c l u d e 
void compute ( const QUESO :: Fu l lE nv ir o nm en t & env , unsigned int numModes ) ;
#e n d i f

Listing 5.57: File example compute.h.
Note that in line 12 of Listings 5.58 the #define directive creates the macro
APPLS_MODAL_USES_CONCATENATION. Such macro, together with the directives #ifdef, #else,
and #endif, tells the compiler that the application will use concatenated priors, by controlling
compilation of portions of file example compute.C. Commenting line 12 of Listings 5.58 will
make the application to use uniform priors only:
1 #i n c l u d e 

6

#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e

< e x a m p l e l i k e l i h o o d . h>









11
#d e f i n e APPLS MODAL USES CONCATENATION

16

void compute ( const QUESO :: Fu l lE nv ir o nm en t & env , unsigned int numModes ) {
////////////////////////////////////////////////////////
// Step 1 of 5: Instantiate the parameter space
////////////////////////////////////////////////////////

CHAPTER 5. QUESO EXAMPLES

21

26

31

36

#i f d e f APPLS MODAL USES CONCATENATION
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpaceA ( env , " paramA_ " , 2 , NULL ) ;
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpaceB ( env , " paramB_ " , 1 , NULL ) ;
#e n d i f
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpace ( env , " param_ " , 3 , NULL ) ;
////////////////////////////////////////////////////////
// Step 2 of 5: Instantiate the parameter domain
////////////////////////////////////////////////////////
#i f d e f APPLS MODAL USES CONCATENATION
QUESO :: GslVector paramMinsA ( paramSpaceA . zeroVector () ) ;
paramMinsA [0] = 0.;
paramMinsA [1] = 0.;
QUESO :: GslVector paramMaxsA ( paramSpaceA . zeroVector () ) ;
paramMaxsA [0] = 3.;
paramMaxsA [1] = 3.;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >

41

paramDomainA ( " paramA_ " , paramSpaceA , paramMinsA , paramMaxsA ) ;

46

QUESO :: GslVector paramMinsB ( paramSpaceB . zeroVector () ) ;
paramMinsB [0] = 0.;
QUESO :: GslVector paramMaxsB ( paramSpaceB . zeroVector () ) ;
paramMaxsB [0] = INFINITY ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomainB ( " paramB_ " , paramSpaceB , paramMinsB , paramMaxsB ) ;

51

56

61

66

71

76

81

QUESO :: ConcatenationSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " " , paramSpace , paramDomainA , paramDomainB ) ;
#e l s e
QUESO :: GslVector paramMins ( paramSpace . zeroVector () ) ;
paramMins [0] = 0.;
paramMins [1] = 0.;
paramMins [2] = 0.;
QUESO :: GslVector paramMaxs ( paramSpace . zeroVector () ) ;
paramMaxs [0] = 3.;
paramMaxs [1] = 3.;
paramMaxs [2] = .3;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " param_ " , paramSpace , paramMins , paramMaxs ) ;
#e n d i f
////////////////////////////////////////////////////////
// Step 3 of 5: Instantiate the likelihood function object
////////////////////////////////////////////////////////
likelihoodRoutine_DataType likelihoodRoutine_Data ;
l i k e l i h o o d R o u t i n e _ D a t a . numModes = numModes ;
QUESO :: GenericScalarFunction < QUESO :: GslVector , QUESO :: GslMatrix >
l i k e l i h o o d F u n c t i o n O b j ( " like_ " ,
paramDomain ,
likelihoodRoutine ,
( void *) & likelihoodRoutine_Data ,
true ) ; // routine computes [ -2.* ln ( function ) ]
////////////////////////////////////////////////////////
// Step 4 of 5: Instantiate the inverse problem
////////////////////////////////////////////////////////
#i f d e f APPLS MODAL USES CONCATENATION
QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRvA ( " priorA_ " , paramDomainA ) ;

133

CHAPTER 5. QUESO EXAMPLES

134

QUESO :: GslVector alpha ( paramSpaceB . zeroVector () ) ;
alpha [0] = 3.;
QUESO :: GslVector beta ( paramSpaceB . zeroVector () ) ;
if ( numModes == 1) {
beta [0] = 0 . 0 9 7 0 9 1 3 3 3 7 3 7 9 9 ;
}
else {
beta [0] = 0 . 0 8 3 3 5 8 3 7 1 9 1 6 8 8 ;
}
QUESO :: InverseGammaVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRvB ( " priorB_ " , paramDomainB , alpha , beta ) ;

86

91

96

101

QUESO :: ConcatenatedVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRv ( " prior_ " , priorRvA , priorRvB , paramDomain ) ;
#e l s e
QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRv ( " prior_ " , paramDomain ) ;
#e n d i f
QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
postRv ( " post_ " , paramSpace ) ;

106
QUESO :: StatisticalInverseProblem < QUESO :: GslVector , QUESO :: GslMatrix >
ip ( " " , NULL , priorRv , likelihoodFunctionObj , postRv ) ;
////////////////////////////////////////////////////////
// Step 5 of 5: Solve the inverse problem
////////////////////////////////////////////////////////
ip . s o l v e W i t h B a y e s M L S a m p l i n g () ;

111

////////////////////////////////////////////////////////
// Print some statistics
////////////////////////////////////////////////////////
unsigned int numPosTotal = postRv . realizer () . subPeriod () ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " numPosTotal = " << numPosTotal
<< std :: endl ;
}

116

121

QUESO :: GslVector auxVec ( paramSpace . zeroVector () ) ;
unsigned int n u m P o s T h e t a 1 S m a l l e r T h a n 1 d o t 5 = 0;
for ( unsigned int i = 0; i < numPosTotal ; ++ i ) {
postRv . realizer () . realization ( auxVec ) ;
if ( auxVec [0] < 1.5) n u m P o s T h e t a 1 S m a l l e r T h a n 1 d o t 5 ++;
}

126

131

if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " n u m P o s T h e t a 1 S m a l l e r T h a n 1 d o t 5 = " <<
numPosTheta1SmallerThan1dot5
<< " , ratio = " << (( double ) n u m P o s T h e t a 1 S m a l l e r T h a n 1 d o t 5 ) /(( double
) numPosTotal )
<< std :: endl ;
}

136
return ;
}

Listing 5.58: File example compute.C.

CHAPTER 5. QUESO EXAMPLES

135

5.5.4 Input File
QUESO reads an input file for solving statistical problems, which provides options for the
Multilevel or MCMC method. In this example, the Multilevel method is chosen to sample
from the distribution. Many variables are common to both MCMC and Multilevel method,
especially because the Multilevel method also has the option of delaying the rejection of a
candidate. The names of the variables have been designed to be informative in this case as
well:
env: refers to QUESO environment;
ip: refers to inverse problem;
ml: refers to Multilevel;
dr: refers to delayed rejection;
rawChain: refers to the raw, entire chain;
filteredChain: refers to a filtered chain (related to a specified lag);
last: refers to instructions specific for the last level of the Multilevel algorithm.
The user may select options for a specific level by naming its number, i.e., in case the user
wants to write the raw chain of the level 3 in a separate file, say ’rawChain_ml_level3.m’,
he/she may include the line:
i p _ m l _ 3 _ r a w C h a i n _ d a t a O u t p u t F i l e N a m e = outputData / r a w C h a i n _ m l _ l e v e l 3

in the input file.
The options used for solving this example are displayed in Listing 5.59.
###############################################
# UQ E n v i r o n m e n t
###############################################
#e n v h e l p
= anything
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0
env_displayVerbosity
= 0
env_syncVerbosity
= 0
env_seed
= 0
###############################################
# S t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
#i p h e l p
= anything
ip_computeSolution
= 1
ip_dataOutputFileName
= outputData / sipOutput
ip_dataOutputAllowedSet = 0
###############################################
# ’ ip ’ : information for Multilevel algorithm
###############################################
#i p m l h e l p
= anything
ip_ml_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_dataOutputAllowedSet = 0

CHAPTER 5. QUESO EXAMPLES

136

###############################################
# All levels , unless otherwise specified
###############################################
i p _ m l _ d e f a u l t _ m i n E f f e c t i v e S i z e R a t i o = 0.49
i p _ m l _ d e f a u l t _ m a x E f f e c t i v e S i z e R a t i o = 0.51
i p _ m l _ d e f a u l t _ r a w C h a i n _ s i z e = 10000
i p _ m l _ d e f a u l t _ r a w C h a i n _ d a t a O u t p u t F i l e N a m e = outputData / rawChain_ml
ip_ml_default_scaleCovMatrix
= 1
ip_ml_default_dr_maxNumExtraStages
= 2
ip_ml_default_dr_listOfScalesForExtraStages
= 10. 25.
###############################################
# Last l e v e l ( l e v e l 7 or 8 f o r ’ example gsl ’ executable )
###############################################
ip_ml_last_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_last_dataOutputAllowedSet
= 0 1
ip_ml_last_rawChain_size
= 10000
ip_ml_last_rawChain_computeStats
= 1
ip_ml_last_rawChain_dataOutputFileName
= outputData / rawChain_ml

Listing 5.59: Options for QUESO library used in application code (Listings 5.54-5.58).

5.5.5 Create your own Makefile
Makefiles are special format files that together with the make utility will help one to compile
and automatically build and manage projects (programs). Listing 5.60 presents a Makefile,
named ‘Makefile modal example margarida’, that may be used to compile the code and
create the executable modal_gsl. Naturally, it must be adapted to the user’s settings, i.e., it
has to have the correct paths for the user’s libraries that have actually been used to compile
and install QUESO (see Sections 2.1–2.4).
##########################################################
# U s i n g i n s t a l l e d QUESO 0 . 4 7 . 1 , from t a r b a l l , i n ’ v i o l e t a ’
##########################################################
QUESO_DIR =
BOOST_DIR =
GSL_DIR =
HDF5_DIR =

/ home / kemelli / LIBRARIES / QUESO -0.50.0
/ home / kemelli / LIBRARIES / boost -1.53.0
/ home / kemelli / LIBRARIES / gsl -1.15
/ home / kemelli / LIBRARIES / hdf5 -1.8.10

INC_PATHS = \
-I . \
- I$ ( QUESO_DIR ) / include \
- I$ ( BOOST_DIR ) / include \
- I$ ( GSL_DIR ) / include \
- I$ ( HDF5_DIR ) / include
LIBS = \
- L$ ( QUESO_DIR ) / lib - lqueso \
- L$ ( BOOST_DIR ) / lib - l b o o s t _ p r o g r a m _ o p t i o n s \
- L$ ( GSL_DIR ) / lib - lgsl \
- L$ ( HDF5_DIR ) / lib - lhdf5
CXX = mpic ++
CXXFLAGS += -g - Wall -c
default : all

CHAPTER 5. QUESO EXAMPLES

137

. SUFFIXES : . o . C
all :

modal_example_gsl

clean :
rm -f *~
rm -f *. o
rm -f modal_gsl
m o d a l _ e x a m p l e _ g s l : example_main . o e x a m p l e _ l i k e l i h o o d . o ex a mp le _c o mp ut e . o
$ ( CXX ) example_main . o \
example_likelihood .o \
e xa mp le _ co mp ut e . o \
-o modal_gsl $ ( LIBS )
%. o : %. C
$ ( CXX ) $ ( INC_PATHS ) $ ( CXXFLAGS ) $ <

Listing 5.60: Makefile for the application code in Listings 5.54-5.58
Thus, to compile, build and execute the code, the user just needs to run the following
commands in the same directory where the files are:
$ cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / modal /
$ export L D_ L IB RA RY _ PA TH = $ L D _ L I B R A R Y _ P A T H :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib
$ make -f M a k e f i l e _ m o d a l _ v i o l e t a
$ ./ modal_gsl example . inp < num_modes >

The ‘export’ instruction above is only necessary if the user has not saved it in his/her
.bashrc file.

5.5.6 Data Post-Processing and Visualization
According to the specifications of the input file in Listing 5.59, both a folder named outputData
and a the following files should be generated:
rawChain_ml.m
display_sub0.txt
The sequence of Matlab commands is identical to the ones presented in Sections 5.1.5,
5.2.5, 5.3.8 and 5.4.7; therefore, are omitted here. The reader is invited to explore the Matlab
files plot modal all levels 1mode.m and/or plot modal all levels 2modes.m for details
of how the figures have been generated.

5.5.6.1 Scatter Plots
The code presented in Listing 5.61 uses Matlab function plotmatrix to generate Figures 5.5.1
and 5.5.2 which presents the scatter plots and histograms of the parameters θ1 and θ2 , based

CHAPTER 5. QUESO EXAMPLES

138

on the generated raw chains.
fprintf (1 , ’ Scatter plots and histograms of raw chains - Level 1 < press any key >\ n ’) ;
plotmatrix ( ip_ml_1_rawChain_unified , ’+b ’)
set ( gca , ’ fontsize ’ ,20) ;
xlabel ( ’\ theta_1
\ theta_2
\ theta_3 ’ , ’ fontsize ’ ,16) ;
ylabel ( ’\ theta_3
\ theta_2
\ theta_1 ’ , ’ fontsize ’ ,16) ;
title ( ’ Scatter plots and histograms , Level 1 - 1 mode ’)

Listing 5.61: Matlab code for the scatter plots depicted in Figures 5.5.1 and 5.5.2.

Figure 5.5.1: Scatter plots for θ1 , θ2 and θ3 = σ 2 , levels 1, 3, 5 and 7 (last). One mode
distribution.

5.5.6.2 KDE Plots
Figures 5.5.3 and 5.5.4 present the KDE plots of the parameters θ1 , θ2 , θ3 and target PDF in
both cases: one-mode and two-modes distribution.

5.5.6.3 Autocorrelation Plots
Figures 5.5.5 and 5.5.6 present the autocorrelation of the parameters θ1 , θ2 and θ3 in both
cases: one-mode and two-modes distribution.

CHAPTER 5. QUESO EXAMPLES

139

Figure 5.5.2: Scatter plots for θ1 , θ2 and θ3 = σ 2 , levels 1, 3, 6 and 9 (last). Two-mode
distribution.

Figure 5.5.3: KDE plots for θ1 , θ2 , θ3 = σ 2 , and the target PDF. One mode distribution.

CHAPTER 5. QUESO EXAMPLES

140

Figure 5.5.4: KDE plots for θ1 , θ2 , θ3 = σ 2 , and the target PDF. Two-mode distribution.

Figure 5.5.5: Autocorrelation plots for θ1 , θ2 and θ3 = σ 2 . One-mode distribution.

Figure 5.5.6: Autocorrelation plots for θ1 , θ2 and θ3 = σ 2 . Two-mode distribution.

CHAPTER 5. QUESO EXAMPLES

141

5.6 bimodal
This example replicates the problem in “Section 4.1 A 1D Problem” of [8]: it presents how to
use QUESO and the Multilevel method for sampling from a posterior PDF composed of the
sum of two Gaussian distributions.
Let’s define D = [−250, 250] and the three distributions πprior : D → R+ , f1 : R → R+
and f2 : R → R+ by:
1
1
=
, ∀θ ∈ D
|D|
500


1
1
T
−1
p
f1 (θ) =
exp − (θ − µ1 ) V1 (θ − µ1 ) ,
2
(2π)1/2 |V1 |


1
1
T
−1
p
f2 (θ) =
exp − (θ − µ2 ) V2 (θ − µ2 ) ,
2
(2π)1/2 |V2 |
πprior =

∀θ ∈ R

(5.6.1)

∀ θ ∈ R,

where
µ1 = 10,

V1 = 12 ,

µ2 = 100,

V2 = 52 .

In this example, we want to sample the posterior PDF given by:


1
1
πposterior (θ) ∝ f1 (θ) + f2 (θ) · πprior = f (θ) · πprior
2
2

(5.6.2)

1
1
where f (θ) = f1 (θ) + f2 (θ) is the likelihood function, which is depicted in Figure 5.6.1.
2
2

Figure 5.6.1: Likelihood function given by f = f1 /2 + f2 /2, where f1 and f2 are defined in
Equation (5.6.1).

5.6.1 Running the Example
To run the executable provided (available after QUESO installation), and generate figures for
the chains, PDFs, CDFs, etc., enter the following commands:

CHAPTER 5. QUESO EXAMPLES

142

$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / bimodal
rm outputData /*
./ bimodal_gsl bimodal _1chain . inp
matlab
$ plot_all . m
# i n s i d e matlab
$ plot_likelihood_normalized_taus .m
# i n s i d e matlab
$ plot_likelihood_unnormalized_taus .m # i n s i d e matlab
$ exit
# i n s i d e matlab
$ ls -l outputData /*. png
b i m o d a l _ a u t o c o r r e l a t i o n _ r a w c h a i n . png b i m o d a l _ l i k e l i h o o d . png
b i m o d a l _ c d f _ r a w c h a i n . png
b i m o d a l _ l i k e l i h o o d _ t a u s _ n o r m a l i z e d . png
b i m o d a l _ k d e _ r a w c h a i n . png
b i m o d a l _ l i k e l i h o o d _ t a u s . png

As a result, the user should have created several of PNG figures containing marginal
posterior PDF, cumulative density distribution and autocorrelation. The name of the figure
files have been chosen to be informative, as shown in the Listing above.

5.6.2 Example Code
The source code for the example is composed of 5 files: bimodal main.C (Listing 5.62),
bimodal likelihood.h and bimodal likelihood.C (Listings 5.63 and 5.64), bimodal compute.h
and bimodal compute.C (Listings 5.65 and 5.66).
#i n c l u d e 
int main ( int argc , char * argv [])
{
// Initialize environment
MPI_Init (& argc ,& argv ) ;
QUESO :: Fu ll En v ir on me n t * env = new QUESO :: F ul lE nv i ro nm en t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;
// Compute
compute (* env ) ;
// Finalize environment
delete env ;
MPI_Finalize () ;
return 0;
}

Listing 5.62: File bimodal main.C.
#i f n d e f EX LIKELIHOOD H
#d e f i n e EX LIKELIHOOD H
#i n c l u d e 
struct
likelihoodRoutine_DataType
{
const QUESO :: GslVector * meanVector ;
const QUESO :: GslMatrix * covMatrix ;
};
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector & paramValues ,

CHAPTER 5. QUESO EXAMPLES
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *

paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect ) ;

#e n d i f

Listing 5.63: File bimodal likelihood.h.
#i n c l u d e < b i m o d a l l i k e l i h o o d . h>
#i n c l u d e 
static unsigned int l i k e l i h o o d C o u n t e r = 0;
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *
{
l i k e l i h o o d C o u n t e r ++;

paramValues ,
paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect )

if ( paramDir ection ||
f un ct io n Da ta Pt r ||
gradVector
||
hessianMatrix
||
hessianEffect ) {}; // just to remove compiler warning
double
double
double
double
double
double

returnValue = 0.;
x = paramValues [0];
mean1 = 10.;
sigma1 = 1.;
y1 = (x - mean1 ) *( x - mean1 ) /(2.* sigma1 * sigma1 ) ;
z1 = (1./ sigma1 / sqrt (2* M_PI ) ) * exp ( - y1 ) ;

double
double
double
double

mean2 = 100.;
sigma2 = 5.;
y2 = (x - mean2 ) *( x - mean2 ) /(2.* sigma2 * sigma2 ) ;
z2 = (1./ sigma2 / sqrt (2* M_PI ) ) * exp ( - y2 ) ;

double resultValue = -2* log (( z1 +2.* z2 ) /3.) ;
if ( resultValue == INFINITY ) {
// std :: cerr << " WARNING In l i k e l i h o o d R o u t i n e "
//
<< " , fullRank "
<< paramValues . env () . fullRank ()
//
<< " , subEnv ironment " << paramValues . env () . subId ()
//
<< " , subRank "
<< paramValues . env () . subRank ()
//
<< " , inter0Rank "
<< paramValues . env () . inter0Rank ()
//
<< " : x = "
<< x
//
<< " , z1 = "
<< z1
//
<< " , z2 = "
<< z2
//
<< " , resultValue = " << resultValue
//
<< std :: endl ;
resultValue = 1040.;
}
#i f d e f QUESO EXPECTS LN LIKELIHOOD INSTEAD OF MINUS 2 LN
returnValue = -.5* resultValue ;
#e l s e

143

CHAPTER 5. QUESO EXAMPLES

144

returnValue = resultValue ;
#e n d i f

if ( paramValues . env () . e x c e p t i o n a l C i r c u m s t a n c e () ) {
if (( paramValues . env () . subDispl ayFile ()
) &&
( paramValues . env () . d i s p l a y V e r b o si t y () >= 0) ) { // detailed output debug
* paramValues . env () . subD isplayF ile () << " Leaving likelihood function "
<< " : paramValues = " << paramValues
<< " , returnValue = " << returnValue
<< std :: endl ;
}
}
return returnValue ;
}

Listing 5.64: File bimodal likelihood.C.
#i f n d e f EX COMPUTE H
#d e f i n e EX COMPUTE H
#i n c l u d e 
void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) ;
#e n d i f

Listing 5.65: File bimodal compute.h.
Note that in line 57 of Listings 5.66 the ‘#if 0’ directive tells the compiler that the
application will not use DRAM algorithm, but rather the Multilevel solver (line 65). Naturally,
the user may chose to use the DRAM algorithm by changing the directive in line 57 to ‘#if 1’.

3

8

13

18

23

#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e


< b i m o d a l l i k e l i h o o d . h>







void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) {
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 1 of 5: Instantiate the parameter space
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpace ( env , " param_ " , 1 , NULL ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 2 of 5: Instantiate the parameter domain
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GslVector paramMins ( paramSpace . zeroVector () ) ;
paramMins . cwSet ( -250.) ;
QUESO :: GslVector paramMaxs ( paramSpace . zeroVector () ) ;
paramMaxs . cwSet ( 250.) ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " param_ " , paramSpace , paramMins , paramMaxs ) ;

CHAPTER 5. QUESO EXAMPLES

28

33

38

145

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 3 of 5: Instantiate the likelihood function object
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GslVector meanVector ( paramSpace . zeroVector () ) ;
meanVector [0] = 10.;
QUESO :: GslMatrix * covMatrix = paramSpace . newMatrix () ;
(* covMatrix ) (0 ,0) = 1.;
likelihoodRoutine_DataType likelihoodRoutine_Data ;
l i k e l i h o o d R o u t i n e _ D a t a . meanVector = & meanVector ;
l i k e l i h o o d R o u t i n e _ D a t a . covMatrix = covMatrix ;
QUESO :: GenericScalarFunction < QUESO :: GslVector , QUESO :: GslMatrix >
l i k e l i h o o d F u n c t i o n O b j ( " like_ " ,
paramDomain ,
likelihoodRoutine ,
( void *) & likelihoodRoutine_Data ,
true ) ; // routine computes [ -2.* ln ( function ) ]

43

48

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 4 of 5: Instantiate the inverse problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRv ( " prior_ " , paramDomain ) ;
QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
postRv ( " post_ " , paramSpace ) ;
QUESO :: StatisticalInverseProblem < QUESO :: GslVector , QUESO :: GslMatrix >
ip ( " " , NULL , priorRv , likelihoodFunctionObj , postRv ) ;

53

58

63

68

73

78

83

88

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 5 of 5: Solve the inverse problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #i f 0
uqGslVector paramInitials ( paramSpace . zeroVector () ) ;
paramInitials [0] = 45.;
uqGslMatrix * p r o p o s a l C o v M a t r i x = paramSpace . newMatrix () ;
(* p r o p o s a l C o v M a t r i x ) (0 ,0) = 1600.;
ip . s o l v e W i t h B a y e s M e t r o p o l i s H a s t i n g s ( NULL , paramInitials , p r o p o s a l C o v M a t r i x ) ;
delete p r o p o s a l C o v M a t r i x ;
#e l s e
ip . s o l v e W i t h B a y e s M L S a m p l i n g () ;
#e n d i f
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Print some statistics in the file ’ display_sub0 . txt ’
// They will be in the last part of the file .
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - unsigned int numPosTotal = postRv . realizer () . subPeriod () ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " numPosTotal = " << numPosTotal
<< std :: endl ;
}
QUESO :: GslVector auxVec ( paramSpace . zeroVector () ) ;
unsigned int n u m P o s S m a l l e r T h a n 4 0 = 0;
for ( unsigned int i = 0; i < numPosTotal ; ++ i ) {
postRv . realizer () . realization ( auxVec ) ;
if ( auxVec [0] < 40.) n u m P o s S m a l l e r T h a n 4 0 ++;
}
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " n u m P o s S m a l l e r T h a n 4 0 = " << n u m P o s S m a l l e r T h a n 4 0
<< " , ratio = " << (( double ) n u m P o s S m a l l e r T h a n 4 0 ) /(( double )
numPosTotal )
<< std :: endl ;
}
QUESO :: ScalarSequence < double > seq1

( env , numPosSmallerThan40 , " " ) ;

CHAPTER 5. QUESO EXAMPLES

93

98

103

108

113

118

123

128

133

138

146

QUESO :: ScalarSequence < double > seq2 ( env , numPosTotal - numPosSmallerThan40 , " " ) ;
QUESO :: ScalarSequence < double > seqAll ( env , numPosTotal , " " ) ;
unsigned int i1 = 0;
unsigned int i2 = 0;
for ( unsigned int i = 0; i < numPosTotal ; ++ i ) {
postRv . realizer () . realization ( auxVec ) ;
if ( auxVec [0] < 40.) seq1 [ i1 ++] = auxVec [0];
else
seq2 [ i2 ++] = auxVec [0];
seqAll [ i ] = auxVec [0];
}
double mean1 = seq1 . subMeanExtra (0 , seq1 . s ub Se qu e nc eS iz e () ) ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " seq1 . size () = "
<< seq1 . su bS eq u en ce Si z e ()
<< " \ n seq1 . mean () = " << mean1
<< " \ n seq1 . std () = " << sqrt ( seq1 . s u b S a m p l e V a r i a n c e E x t r a (0 , seq1 .
s ub Se qu e nc eS iz e () , mean1 ) )
<< std :: endl ;
}
double mean2 = seq2 . subMeanExtra (0 , seq2 . s ub Se qu e nc eS iz e () ) ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " seq2 . size () = "
<< seq2 . su bS eq u en ce Si z e ()
<< " \ n seq2 . mean () = " << mean2
<< " \ n seq2 . std () = " << sqrt ( seq2 . s u b S a m p l e V a r i a n c e E x t r a (0 , seq2 .
s ub Se qu e nc eS iz e () , mean2 ) )
<< std :: endl ;
}
double meanAll = seqAll . subMeanExtra (0 , seqAll . s ub S eq ue nc e Si ze () ) ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " seqAll . size () = "
<< seqAll . s u bS eq ue n ce Si ze ()
<< " \ n seqAll . mean () = " << meanAll
<< " \ n seqAll . std () = " << sqrt ( seqAll . s u b S a m p l e V a r i a n c e E x t r a (0 ,
seqAll . s ub Se q ue nc eS i ze () , meanAll ) )
<< std :: endl ;
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Test if likelihood is normalized
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - unsigned int numGridPoints = 1000001;
double xMin = paramDomain . minValues () [0];
double xMax = paramDomain . maxValues () [0];
double intervalSize = ( xMax - xMin ) /(( double ) numGridPoints - 1) ;
double integral = 0.;
for ( unsigned int i = 0; i < numGridPoints ; ++ i ) {
auxVec [0] = xMin + i * intervalSize ;
integral += l i k e l i h o o d F u n c t i o n O b j . actualValue ( auxVec , NULL , NULL , NULL , NULL ) ;
}
integral *= intervalSize ;
if ( env . s ubDispla yFile () ) {
* env . sub DisplayF ile () << " integral = " << integral
<< std :: endl ;
}

143
// Return
delete covMatrix ;
return ;

148 }

Listing 5.66: File bimodal compute.C.

CHAPTER 5. QUESO EXAMPLES

147

5.6.3 Input File
QUESO reads an input file for solving statistical problems, which provides options for the
Multilevel or MCMC method. In this example, the Multilevel method is chosen to sample
from the distribution. Many variables are common to both MCMC and Multilevel method,
especially because the Multilevel method also has the option of delaying the rejection of a
candidate. The names of the variables have been designed to be informative in this case as
well:
env: refers to QUESO environment;
ip: refers to inverse problem;
ml: refers to Multilevel;
dr: refers to delayed rejection;
rawChain: refers to the raw, entire chain;
filteredChain: refers to a filtered chain (related to a specified lag);
last: refers to instructions specific for the last level of the Multilevel algorithm.
The user may select options for a specific level by naming its number, i.e., in case the
user wants to define a different number of extra stages together with the scales for each stage
(in the DRAM part of the ML algorithm) for the level 3, he/she may include the following
instructions:
ip_ml_3_dr_maxNumExtraStages
= 1
i p _ m l _ 3 _ d r _ l i s t O f S c a l e s F o r E x t r a S t a g e s = 3.333

in the input file.
The options used for solving this example are displayed in Listing 5.67.
###############################################
# UQ E n v i r o n m e n t
###############################################
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0 1
env_displayVerbosity
= 2
env_syncVerbosity
= 0
env_seed
= -1
###############################################
# S t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
ip_computeSolution
= 1
ip_dataOutputFileName
= outputData / sipOutput
ip_dataOutputAllowedSet = 0
###############################################
# ’ ip ’ : information for Multilevel algorithm
###############################################
ip_ml_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_dataOutputAllowedSet = 0 1
###############################################

CHAPTER 5. QUESO EXAMPLES

148

# All levels , unless otherwise specified
###############################################
#i p m l d e f a u l t l o a d B a l a n c e = 0
i p _ m l _ d e f a u l t _ r a w C h a i n _ s i z e = 10000
i p _ m l _ d e f a u l t _ r a w C h a i n _ d a t a O u t p u t F i l e N a m e = outputData / rawChain_ml #d a t a from a l l
be w r i t t e n
i p _ m l _ d e f a u l t _ m i n E f f e c t i v e S i z e R a t i o = 0.49
i p _ m l _ d e f a u l t _ m a x E f f e c t i v e S i z e R a t i o = 0.51
ip_ml_default_minRejectionRate
= 0.24
ip_ml_default_maxRejectionRate
= 0.4
ip_ml_default_putOutOfBoundsInChain = 0

levels

will

###############################################
# Level 3
###############################################
#i p m l 3 d r m a x N u m E x t r a S t a g e s
= 1
#i p m l 3 d r l i s t O f S c a l e s F o r E x t r a S t a g e s = 3 . 3 3 3
###############################################
# Last l e v e l ( l e v e l 4 for ’ bimodal gsl ’ executable )
###############################################
ip_ml_last_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_last_dataOutputAllowedSet
= 0 1
#i p m l l a s t l o a d B a l a n c e
ip_ml_last_rawChain_size
ip_ml_last_rawChain_dataOutputFileName
ip_ml_last_rawChain_dataOutputAllowedSet
ip_ml_last_rawChain_computeStats
ip_ml_last_rawChain_stats_kde_compute
ip_ml_last_rawChain_stats_kde_numEvalPositions
ip_ml_last_rawChain_stats_covMatrix_compute
ip_ml_last_rawChain_stats_corrMatrix_compute

= 0
= 10000
= outputData / rawChain_ml
= 0
= 1
= 1
= 200
= 1
= 1

ip_ml_last_filteredChain_generate
ip_ml_last_filteredChain_lag
ip_ml_last_filteredChain_dataOutputFileName
ip_ml_last_filteredChain_dataOutputAllowedSet
ip_ml_last_filteredChain_computeStats
ip_ml_last_filteredChain_stats_kde_compute
ip_ml_last_filteredChain_stats_kde_numEvalPositions
ip_ml_last_filteredChain_stats_covMatrix_compute
ip_ml_last_filteredChain_stats_corrMatrix_compute
ip_ml_last_dr_maxNumExtraStages
ip_ml_last_dr_listOfScalesForExtraStages
ip_ml_last_minEffectiveSizeRatio
ip_ml_last_maxEffectiveSizeRatio
ip_ml_last_minRejectionRate
ip_ml_last_maxRejectionRate
ip_ml_last_putOutOfBoundsInChain

=
=
=
=
=

=
=
=
=
=
=
=
=
=

1
2
outputData / filtChain_ml
0
1
1
200
1
1

= 1
= 5.

0.49
0.51
0.24
0.4
0

Listing 5.67: Options for QUESO library used in application code (Listings 5.62-5.66).

5.6.4 Create your own Makefile
Similarly to the other examples presented in this user’s manual and also available with QUESO
distribution, a user-created makefile is available: ‘Makefile bimodal violeta’. When adapted

CHAPTER 5. QUESO EXAMPLES

149

to the user’s settings, namely paths for QUESO required libraries, it may be used to compile
the code and create the executable bimodal_gsl.
Thus, to compile, build and execute the code, the user just needs to run the following
commands in the same directory where the files are:
$ cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / bimodal /
$ export L D_ L IB RA RY _ PA TH = $ L D _ L I B R A R Y _ P A T H :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib
$ make -f M a k e f i l e _ b i m o d a l _ v i o l e t a
$ ./ bimodal_gsl example . inp

Again, the ‘export’ instruction above is only necessary if the user has not saved it in
his/her .bashrc file.

5.6.5 Data Post-Processing and Visualization
According to the specifications of the input file in Listing 5.67, both a folder named outputData
and a the following files should be generated:
rawChain_ml.m
display_sub0.txt
The sequence of Matlab commands is identical to the ones presented in Sections 5.1.5,
5.2.5, 5.3.8 and 5.4.7; therefore, are omitted here. The reader is invited to explore the Matlab
files plot likelihood normalized taus.m, plot likelihood unnormalized taus.m and/or
plot all.m, for details of how the figures have been generated.

5.6.5.1 KDE and CDF Plots
Figure 5.6.2 presents the KDE and CDF plots of the parameter θ.

(a) KDE

(b) CDF

Figure 5.6.2: KDE and CDF plots of parameter θ, for all fours levels.

CHAPTER 5. QUESO EXAMPLES

150

5.6.5.2 Autocorrelation Plots
Figure 5.6.3 presents the autocorrelation of the parameter θ, in each one of the intermediate
levels.

Figure 5.6.3: Autocorrelation plots for θ, all four levels.

5.6.5.3 Intermediary Likelihood Plots

(a) normalized

(b) unnormalized

Figure 5.6.4: Intermediary likelihood functions f (θ)τ , where τi is the exponent computed at
the i-th level of Multilevel algorithm. In this simple problem, only four levels are needed, i.e.
i = 1 . . . 4. The cyan-colored curve (exponent τ = 1) is the same curve as in Figure 5.6.1.

5.7 hysteretic
This example replicates the problem in “Section 4.3 A Hysteretic Model Class ” of [8], and
which is also discussed in [6]. In this example we consider the nonlinear seismic response
of a four-story building. This response is modeled with an inelastic shear building model
with some linear viscous damping and hysteretic bilinear interstory restoring forces [6]. More

CHAPTER 5. QUESO EXAMPLES

151

specifically, let t ≥ 0 denote time, let ag (t) be a given total acceleration at the base (Fig. 13),
and for the i-th floor [degree of freedom (dof)], 1 ≤ i ≤ No ≡ 4, let us denote:
mi = lumped mass,
qi (t) = horizontal displacement,
Fi (t) = hysteretic restoring force

(5.7.1)

The hysteretic restoring force is illustrated in Figure 5.7.1 and the horizontal base (ground)
acceleration (input data) used in [8] is illustrated in 5.7.2.
1




ri ki

6
7



 ki

 1

ui




1

i-th floor
interstory



Figure 5.7.1: Illustration of the hysteretic restoring force [see Eq. (5.7.2)] used in our hysteretic
test problem. The terms ri , ki , and ui denote model parameters.

Figure 5.7.2: Horizontal base acceleration (input data) used in the hysteretic test problem [8].

CHAPTER 5. QUESO EXAMPLES

152

We also define the mass matrix M and the stiffness matrix K:




m1 0
0
0
k1 + k2
−k2
0
0
 0 m2 0

0
k2 + k3
−k3
0 
 and K =  −k2

M =
0
 0
0 m3 0 
−k3
k3 + k4 −k4
0
0
0 m4
0
0
−k4
k4
and the Rayleigh damping matrix
C = ρM + γK
for given positive scalar parameters ρ and γ. The response q(t) ≡ [q1 (t), q2 (t), q3 (t), q4 (t)] is
modeled as satisfying the equation of motion:
 
1
 .. 
M q̈(t) + C q̇(t) + F (t) = −M ·  . 
· ag (t),
(5.7.2)
1 4×1
where F (t) ≡ [F1 (t), F2 (t), F3 (t), F4 (t)]. In this model, the hysteretic restoring force F (t)
depends on the whole time history [q(t), q̇(t)] of responses from the initial instant until time t.
The (noisy) measured data y = (y1 , y2 , y3 , y4 ) available for model calibration consists of 4
s of accelerometer data at each floor (refer to Fig. 5.7.3), with a sample interval ∆t = 0.01
s. The simulated dynamic data was obtained by adding Gaussian white noise to the output
simulation of the hysteretic model with the following input values:
m1 = m2 = m3 = m4 = 2 × 104 kg,
k1 = 2.2 × 107 N m−1 ,
k2 = 2.0 × 107 N m−1 ,
k3 = 1.7 × 107 N m−1 ,
k4 = 1.45 × 107 N m−1 ,
r1 = r2 = r3 = r4 = 0.1,
u1 = u2 = 8 × 10−3 m,
u3 = u4 = 7 × 10−3 m,
ρ = 7.959 × 10−1 ,
γ = 2.5 × 10−3 ,
σ 2 = 0.62 ,
where for i = 1, 2, 3, 4, ki is the initial stiffness, ri is the post-yield stiffness reduction factor,
and ui is yield displacement.
According to Cheung and Prudencio [8], these input values were chosen deliberately so
that the excitation ag did not cause some of the upper floors to enter the nonlinear regime;
that is, so that our test inverse problem did not become globally identifiable.
In this section, 400 time-steps are used, as the data is available at instants
tn = (n − 1) × ∆t,

1 ≤ n ≤ NT ≡ 401,

∆t = 0.01

CHAPTER 5. QUESO EXAMPLES

153

Figure 5.7.3: Horizontal acceleration of each of the four floors (measured data aimed for
calibration) used in our hysteretic test problem.
however, Cheung and Prudencio used only 250 time steps [8].
An additive noise is assumed to be present in the measurements; i.e.,
yi (n) = qi (n) + εi (n),

1 ≤ i ≤ No ,

1 ≤ n ≤ NT ≡ 401,

where qi (n; θ2 , ..., θ15 ) denotes the output at time tn = n∆t (∆t = 0.01s) at the i-th observed
degree of freedom predicted by the proposed structural model, and yi (n) denotes the corresponding measured output.
They considered a total of 15 unknown parameters θ = (θ1 , ..., θ15 ) and modeled the
variables εi as independently and identically distributed Gaussian variables with mean zero
and some unknown prediction-error variance σ 2 . The variance σ 2 is assumed to be the same
for all No = 4 floors. The first component θ1 is equal to the prediction error variance σ 2 and
the other 14 parameters are related to the four triples (ki , ri , ui ), 1 ≤ i ≤ No (see Fig. 5.7.1),
to ρ, and to γ. The likelihood function is given by:
!
NT
No X
1
1 X
exp − 2
[yi (tn ) − qi (tn ; θ2 , . . . , θ15 )]2 .
(5.7.3)
f (y|θ) =
(2πσ 2 )No NT /2
2σ i=1 n=1
An inverse gamma prior was used for θ1 = σ 2 , and a 14-dimensional Gaussian prior was used
for θ2 , ..., θ15 with zero mean and diagonal covariance matrix equal to a scaled identity matrix.

CHAPTER 5. QUESO EXAMPLES

154

5.7.1 Running the Example
To run the executable provided (available after QUESO installation), and generate figures for
the chains, KDEs, CDFs, autocorrelation and scatter plots, enter the following commands:
$
$
$
$

cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / example
rm outputData /*
./ example_gsl example _1chain . inp
matlab
$ plot_all . m
# i n s i d e matlab
$ ls -l outputData /*. png
h y s t e r e t i c _ a u t o c o r r _ t h e t a s . png h y s t e r e t i c _ k d e _ t h e t a 8 . png
h y s t e r e t i c _ c d f _ t h e t a s . png
h y s t e r e t i c _ k d e _ t h e t a 9 . png
h y s t e r e t i c _ k d e _ t h e t a 1 . png
h y s t e r e t i c _ k d e _ t h e t a 1 0 . png
h y s t e r e t i c _ k d e _ t h e t a 2 . png
h y s t e r e t i c _ k d e _ t h e t a 1 1 . png
h y s t e r e t i c _ k d e _ t h e t a 3 . png
h y s t e r e t i c _ k d e _ t h e t a 1 2 . png
h y s t e r e t i c _ k d e _ t h e t a 4 . png
h y s t e r e t i c _ k d e _ t h e t a 1 3 . png
h y s t e r e t i c _ k d e _ t h e t a 5 . png
h y s t e r e t i c _ k d e _ t h e t a 1 4 . png
h y s t e r e t i c _ k d e _ t h e t a 6 . png
h y s t e r e t i c _ k d e _ t h e t a 1 5 . png
h y s t e r e t i c _ k d e _ t h e t a 7 . png
h y s t e r e t i c _ s c a t t e r _ t h e t a s . png

As a result, the user should have created several of PNG figures containing kernel density
estimate of the 15 parameters, cumulative density distribution, autocorrelation and scatter
plots. The name of the figure files have been chosen to be informative, as shown in the Listing
above.
Additional figures may be generated if the user allows the procedure debug hyst( be called
by the compiler in Line 11 of file example main.C; in that case, call the function cpp gen.m
inside Matlab/Octave.

5.7.2 Example Code
The source code for the example is composed of 5 files: example main.C (Listing 5.68),
example likelihood.h and example likelihood.C (Listings 5.69 and 5.70), example compute.h
and example compute.C (Listings 5.71 and 5.72), and finally example hyst.h and example hyst.C,
which contain the Hysteretic model properly said.
Note that in line 11 of Listings 5.68 the ‘#if 1’ directive tells the compiler that the
application will call compute(), which internally uses QUESO and the Multilevel algorithm.
On the contrary, the user may calculate the hysteretic force without uncertainty by changing
the directive to ‘#if 0’, which can assist the analysis of the resulting data.
#i n c l u d e 

5

10

int main ( int argc , char * argv [])
{
// Initialize environment
MPI_Init (& argc ,& argv ) ;
QUESO :: Fu ll En v ir on me n t * env =
new QUESO :: Fu ll En v ir on me n t ( MPI_COMM_WORLD , argv [1] , " " , NULL ) ;
// Compute
#i f 1
compute (* env ) ;

CHAPTER 5. QUESO EXAMPLES

15

#e l s e
debug_hyst (* env ) ;
#e n d i f
// Finalize environment
delete env ;
MPI_Finalize () ;

20
return 0;
}

Listing 5.68: File example main.C.
#i f n d e f
#d e f i n e

EX LIKELIHOOD H
EX LIKELIHOOD H

#i n c l u d e 
struct
likelihoodRoutine_DataType
{
std :: vector < std :: vector < double >* > floor ;
std :: vector < double >
accel ;
};
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector &
const QUESO :: GslVector *
const void *
QUESO :: GslVector *
QUESO :: GslMatrix *
QUESO :: GslVector *

paramValues ,
paramDirection ,
functionDataPtr ,
gradVector ,
hessianMatrix ,
hessianEffect ) ;

#e n d i f

Listing 5.69: File example likelihood.h.
#i n c l u d e < e x a m p l e l i k e l i h o o d . h>
#i n c l u d e 
double l i k e l i h o o d R o u t i n e (
const QUESO :: GslVector & paramValues ,
const QUESO :: GslVector * paramDirection ,
const void *
functionDataPtr ,
QUESO :: GslVector *
gradVector ,
QUESO :: GslMatrix *
hessianMatrix ,
QUESO :: GslVector *
hessianEffect )
{
const QUESO :: B as eE n vi ro nm e nt & env = paramValues . env () ;
U Q _ F A T A L _ T E S T _ M A C R O ( paramValues . sizeLocal () != 15 ,
env . fullRank () ,
" e x a m p l e _ l i k e l i h o o d () " ,
" invalid parameter size " ) ;
const std :: vector < std :: vector < double >* >&
floor = (( l i k e l i h o o d R o u t i n e _ D a t a T y p e *) fu n ct io nD a ta Pt r ) -> floor ;
const std :: vector < double >&
accel = (( l i k e l i h o o d R o u t i n e _ D a t a T y p e *) fu n ct io nD a ta Pt r ) -> accel ;
unsigned int numFloors

= floor . size () ;

155

CHAPTER 5. QUESO EXAMPLES

156

unsigned int numTimeSteps = accel . size () ;
U Q _ F A T A L _ T E S T _ M A C R O (( numFloors != 4) ,
env . fullRank () ,
" e x a m p l e _ l i k e l i h o o d () " ,
" invalid ’ numFloors ’ " ) ;
U Q _ F A T A L _ T E S T _ M A C R O (( numTimeSteps != 401) ,
env . fullRank () ,
" e x a m p l e _ l i k e l i h o o d () " ,
" invalid ’ numTimeSteps ’ " ) ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
U Q _ F A T A L _ T E S T _ M A C R O ( floor [ i ] - > size () != numTimeSteps ,
env . fullRank () ,
" e x a m p l e _ l i k e l i h o o d () " ,
" invalid number of steps " ) ;
}
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix > floorSpace ( env , " floor_ " , numFloors ,
NULL ) ;
double sigmaSq = paramValues [0];
QUESO :: GslVector kVec ( floorSpace . zeroVector () ) ;
kVec [0] = 2.20 e +7 * exp ( paramValues [1]) ;
kVec [1] = 2.00 e +7 * exp ( paramValues [2]) ;
kVec [2] = 1.70 e +7 * exp ( paramValues [3]) ;
kVec [3] = 1.45 e +7 * exp ( paramValues [4]) ;
QUESO :: GslVector
rVec [0] = 1.0 e -1
rVec [1] = 1.0 e -1
rVec [2] = 1.0 e -1
rVec [3] = 1.0 e -1

rVec ( floorSpace . zeroVector () ) ;
* exp ( paramValues [5]) ;
* exp ( paramValues [6]) ;
* exp ( paramValues [7]) ;
* exp ( paramValues [8]) ;

QUESO :: GslVector
uVec [0] = 8.0 e -3
uVec [1] = 8.0 e -3
uVec [2] = 7.0 e -3
uVec [3] = 7.0 e -3

uVec ( floorSpace . zeroVector () ) ;
* exp ( paramValues [9]) ;
* exp ( paramValues [10]) ;
* exp ( paramValues [11]) ;
* exp ( paramValues [12]) ;

double rho

= 7.959 e -1 * exp ( paramValues [13]) ;

double gamma = 2.500 e -3 * exp ( paramValues [14]) ;
std :: vector < double > t ( numTimeSteps ,0.) ;
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // absolute displacement
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // velocity
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // acceleration
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // restoring force
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // relative displacement
QUESO :: GslVector massVec ( floorSpace . zeroVector () ) ;
massVec . cwSet (2.0 e +4) ;
h ys te re t ic Mo de l ( env ,
massVec ,
kVec ,
rVec ,

u

( floorSpace , numTimeSteps ,

ud

( floorSpace , numTimeSteps ,

udd

( floorSpace , numTimeSteps ,

resfor ( floorSpace , numTimeSteps ,
ru

( floorSpace , numTimeSteps ,

CHAPTER 5. QUESO EXAMPLES
uVec ,
rho ,
gamma ,
accel ,
t , // output
u,
ud ,
udd ,
resfor ,
ru ) ;
QUESO :: GslVector auxVec ( floorSpace . zeroVector () ) ;
double sum = 0.;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
udd . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
sum += ((* floor [ i ]) [ j ] - auxVec [ i ] - accel [ j ]) *((* floor [ i ]) [ j ] - auxVec [ i ] - accel [ j ]) ;
}
}
double result = -0.5*(( double ) numFloors ) *(( double ) numTimeSteps ) * log (2.* M_PI * sigmaSq ) 0.5* sum / sigmaSq ;
return result ;
}

Listing 5.70: File example likelihood.C.
#i f n d e f
#d e f i n e

EX COMPUTE H
EX COMPUTE H

#i n c l u d e 
void compute
( const QUESO :: F u ll En vi r on me nt & env ) ;
void debug_hyst ( const QUESO :: F u ll En vi r on me n t & env ) ;
#e n d i f

Listing 5.71: File example compute.h.
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e
#i n c l u d e


< e x a m p l e l i k e l i h o o d . h>









void compute ( const QUESO :: Fu l lE nv ir o nm en t & env ) {
struct timeval timevalNow ;
gettimeofday (& timevalNow , NULL ) ;
std :: cout << std :: endl << " Beginning run of ’ Hysteretic ’ example at "
<< ctime (& timevalNow . tv_sec ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 1 of 5: Instantiate the parameter space

157

CHAPTER 5. QUESO EXAMPLES
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpaceA ( env , " paramA_ " , 1 , NULL ) ;
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpaceB ( env , " paramB_ " , 14 , NULL ) ;
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix >
paramSpace ( env , " param_ " , 15 , NULL ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 2 of 5: Instantiate the parameter domain
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUESO :: GslVector paramMinsA ( paramSpaceA . zeroVector () ) ;
paramMinsA . cwSet (0) ;
QUESO :: GslVector paramMaxsA ( paramSpaceA . zeroVector () ) ;
paramMaxsA . cwSet (5) ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomainA ( " paramA_ " , paramSpaceA , paramMinsA , paramMaxsA ) ;
QUESO :: GslVector paramMinsB ( paramSpaceB . zeroVector () ) ;
paramMinsB . cwSet ( - INFINITY ) ;
QUESO :: GslVector paramMaxsB ( paramSpaceB . zeroVector () ) ;
paramMaxsB . cwSet ( INFINITY ) ;
QUESO :: BoxSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomainB ( " paramB_ " , paramSpaceB , paramMinsB , paramMaxsB ) ;
QUESO :: ConcatenationSubset < QUESO :: GslVector , QUESO :: GslMatrix >
paramDomain ( " " , paramSpace , paramDomainA , paramDomainB ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 3 of 5: Instantiate the likelihood function object
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - std :: cout << " \ tI nstantia ting the Likelihood ; calling internally the hysteretic model "
<< std :: endl ;
likelihoodRoutine_DataType likelihoodRoutine_Data ;
l i k e l i h o o d R o u t i n e _ D a t a . floor . resize (4 , NULL ) ;
unsigned int numTimeSteps = 401;
for ( unsigned int i = 0; i < 4; ++ i ) {
l i k e l i h o o d R o u t i n e _ D a t a . floor [ i ] = new std :: vector < double >( numTimeSteps ,0.) ;
}
l i k e l i h o o d R o u t i n e _ D a t a . accel . resize ( numTimeSteps ,0.) ;
FILE * inp ;
inp = fopen ( " an . txt " ," r " ) ;
unsigned int nu mO bs e rv at io n s = 0;
double tmpA ;
while ( fscanf ( inp , " % lf " ,& tmpA ) != EOF ) {
l i k e l i h o o d R o u t i n e _ D a t a . accel [ n um Ob s er va t io ns ] = tmpA ;
n um Ob se r va ti on s ++;
}
n um Ob se r va ti on s =0;
FILE * inp1_1 ;
inp1_1 = fopen ( " m e a s u r e d _ d a ta 1 _ 1 . txt " ," r " ) ;
while ( fscanf ( inp1_1 , " % lf " ,& tmpA ) != EOF ) {
(* l i k e l i h o o d R o u t i n e _ D a t a . floor [0]) [ n um O bs er va t io ns ]= tmpA ;
n um Ob se r va ti on s ++;
}
n um Ob se r va ti on s =0;
FILE * inp1_2 ;
inp1_2 = fopen ( " m e a s u r e d _ d a ta 1 _ 2 . txt " ," r " ) ;
while ( fscanf ( inp1_2 , " % lf " ,& tmpA ) != EOF ) {
(* l i k e l i h o o d R o u t i n e _ D a t a . floor [1]) [ n um O bs er va t io ns ]= tmpA ;
n um Ob se r va ti on s ++;
}

158

CHAPTER 5. QUESO EXAMPLES

n um Ob se r va ti on s =0;
FILE * inp1_3 ;
inp1_3 = fopen ( " m e a s u r e d _ d a ta 1 _ 3 . txt " ," r " ) ;
while ( fscanf ( inp1_3 , " % lf " ,& tmpA ) != EOF ) {
(* l i k e l i h o o d R o u t i n e _ D a t a . floor [2]) [ n um O bs er va t io ns ]= tmpA ;
n um Ob se r va ti on s ++;
}
n um Ob se r va ti on s =0;
FILE * inp1_4 ;
inp1_4 = fopen ( " m e a s u r e d _ d a ta 1 _ 4 . txt " ," r " ) ;
while ( fscanf ( inp1_4 , " % lf " ,& tmpA ) != EOF ) {
(* l i k e l i h o o d R o u t i n e _ D a t a . floor [3]) [ n um O bs er va t io ns ]= tmpA ;
n um Ob se r va ti on s ++;
}
QUESO :: GenericScalarFunction < QUESO :: GslVector , QUESO :: GslMatrix >
l i k e l i h o o d F u n c t i o n O b j ( " like_ " ,
paramDomain ,
likelihoodRoutine ,
( void *) & likelihoodRoutine_Data ,
true ) ; // routine computes [ ln ( function ) ]
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 4 of 5: Instantiate the inverse problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - std :: cout << " \ tI nstantia ting the SIP " << std :: endl ;
QUESO :: UniformVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRvA ( " priorA_ " , paramDomainA ) ;
QUESO :: GslVector meanVec ( paramSpaceB . zeroVector () ) ;
QUESO :: GslVector diagVec ( paramSpaceB . zeroVector () ) ;
diagVec . cwSet (0.6*0.6) ;
QUESO :: GslMatrix covMatrix ( diagVec ) ;
QUESO :: GaussianVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRvB ( " priorB_ " , paramDomainB , meanVec , covMatrix ) ;
QUESO :: ConcatenatedVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
priorRv ( " prior_ " , priorRvA , priorRvB , paramDomain ) ;
QUESO :: GenericVectorRV < QUESO :: GslVector , QUESO :: GslMatrix >
postRv ( " post_ " , paramSpace ) ;
QUESO :: StatisticalInverseProblem < QUESO :: GslVector , QUESO :: GslMatrix >
ip ( " " , NULL , priorRv , likelihoodFunctionObj , postRv ) ;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Step 5 of 5: Solve the inverse problem
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - std :: cout << " \ tSolving the SIP with Multilevel method " << std :: endl ;
ip . s o l v e W i t h B a y e s M L S a m p l i n g () ;
gettimeofday (& timevalNow , NULL ) ;
std :: cout << " Ending run of ’ Hysteretic ’ example at "
<< ctime (& timevalNow . tv_sec ) << std :: endl ;
return ;
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

159

CHAPTER 5. QUESO EXAMPLES

160

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - void debug_hyst ( const QUESO :: F u ll En vi r on me n t & env ) {
unsigned int numFloors = 4;
unsigned int numTimeSteps = 401;
std :: vector < double > accel ( numTimeSteps ,0.) ;
FILE * inp ;
inp = fopen ( " an . txt " ," r " ) ;
unsigned int nu mO bs e rv at io n s = 0;
double tmpA ;
while ( fscanf ( inp , " % lf " ,& tmpA ) != EOF ) {
U Q _ F A T A L _ T E S T _ M A C R O (( n um Ob s er va ti o ns >= accel . size () ) ,
env . fullRank () ,
" debug_hyst () " ,
" input file has too many lines " ) ;
accel [ n um O bs er va t io ns ] = tmpA ;
n um Ob se r va ti on s ++;
}
U Q _ F A T A L _ T E S T _ M A C R O (( n um O bs er va t io ns != accel . size () ) ,
env . fullRank () ,
" debug_hyst () " ,
" input file has a smaller number of observations than expected " ) ;
QUESO :: VectorSpace < QUESO :: GslVector , QUESO :: GslMatrix > floorSpace ( env , " floor_ " , numFloors ,
NULL ) ;
QUESO :: GslVector kVec ( floorSpace . zeroVector () ) ;
kVec [0] = 2.20 e +7;
kVec [1] = 2.00 e +7;
kVec [2] = 1.70 e +7;
kVec [3] = 1.45 e +7;
QUESO :: GslVector rVec ( floorSpace . zeroVector () ) ;
rVec [0] = 0.1;
rVec [1] = 0.1;
rVec [2] = 0.1;
rVec [3] = 0.1;
QUESO :: GslVector uVec ( floorSpace . zeroVector () ) ;
uVec [0] = 0.008;
uVec [1] = 0.008;
uVec [2] = 0.007;
uVec [3] = 0.007;
double rho
= 7.959 e -1 ;//0.1976;
double gamma = 2.500 e -3 ; //0.0038;
std :: vector < double > t ( numTimeSteps ,0.) ;
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // absolute displacement
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // velocity
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // acceleration
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // restoring force
QUESO :: SequenceOfVectors < QUESO :: GslVector , QUESO :: GslMatrix >
" " ) ; // relative displacement
u. setPositionValues
(0 , floorSpace . zeroVector () ) ;
ud . s e t P o s i t i o n V a l u e s
(0 , floorSpace . zeroVector () ) ;
udd . s e t P o s i t i o n V a l u e s
(0 , floorSpace . zeroVector () ) ;
resfor . s e t P o s i t i o n V a l u e s (0 , floorSpace . zeroVector () ) ;
ru . s e t P o s i t i o n V a l u e s
(0 , floorSpace . zeroVector () ) ;

u

( floorSpace , numTimeSteps ,

ud

( floorSpace , numTimeSteps ,

udd

( floorSpace , numTimeSteps ,

resfor ( floorSpace , numTimeSteps ,
ru

( floorSpace , numTimeSteps ,

CHAPTER 5. QUESO EXAMPLES

QUESO :: GslVector massVec ( floorSpace . zeroVector () ) ;
massVec . cwSet (2.0 e +4) ;
h ys te re t ic Mo de l ( env ,
massVec ,
kVec ,
rVec ,
uVec ,
rho ,
gamma ,
accel ,
t , // output
u,
ud ,
udd ,
resfor ,
ru ) ;
std :: set < unsigned int > auxSet ;
auxSet . insert (0) ;
// Writing some data to the file ’ outputData / cpp_output .m ’
std :: ofstream myFile ;
myFile . open ( " outputData / cpp_output . m " ) ;
// Write ’ t_cpp ’
myFile << " t_cpp = zeros ( " << 1 << " ," << numTimeSteps << " ) ;\ n "
<< " t_cpp = [ " ;
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
myFile << t [ j ] << " " ;
}
myFile << " ]; " << std :: endl ;
// Write ’ a_cpp ’
myFile << " a_cpp = zeros ( " << 1 << " ," << numTimeSteps << " ) ;\ n "
<< " a_cpp = [ " ;
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
myFile << accel [ j ] << " " ;
}
myFile << " ]; " << std :: endl ;
QUESO :: GslVector auxVec ( floorSpace . zeroVector () ) ;
// Write ’ u_cpp ’
myFile << " u_cpp = zeros ( " << numFloors << " ," << numTimeSteps << " ) ;\ n "
<< " u_cpp = [ " ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
u . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
myFile << auxVec [ i ] << " " ;
}
myFile << std :: endl ;
}
myFile << " ]; " << std :: endl ;
// Write ’ ud_cpp ’
myFile << " ud_cpp = zeros ( " << numFloors << " ," << numTimeSteps << " ) ;\ n "
<< " ud_cpp = [ " ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
ud . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
myFile << auxVec [ i ] << " " ;
}
myFile << std :: endl ;

161

CHAPTER 5. QUESO EXAMPLES
}
myFile << " ]; " << std :: endl ;
// Write ’ udd_cpp ’
myFile << " udd_cpp = zeros ( " << numFloors << " ," << numTimeSteps << " ) ;\ n "
<< " udd_cpp = [ " ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
udd . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
myFile << auxVec [ i ] << " " ;
}
myFile << std :: endl ;
}
myFile << " ]; " << std :: endl ;
// Write ’ resfor_cpp ’
myFile << " resfor_cpp = zeros ( " << numFloors << " ," << numTimeSteps << " ) ;\ n "
<< " resfor_cpp = [ " ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
resfor . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
myFile << auxVec [ i ] << " " ;
}
myFile << std :: endl ;
}
myFile << " ]; " << std :: endl ;
// Write ’ ru_cpp ’
myFile << " ru_cpp = zeros ( " << numFloors << " ," << numTimeSteps << " ) ;\ n "
<< " ru_cpp = [ " ;
for ( unsigned int i = 0; i < numFloors ; ++ i ) {
for ( unsigned int j = 0; j < numTimeSteps ; ++ j ) {
ru . g e t P o s i t i o n V a l u e s (j , auxVec ) ;
myFile << auxVec [ i ] << " " ;
}
myFile << std :: endl ;
}
myFile << " ]; " << std :: endl ;
myFile . close () ;
return ;
}

Listing 5.72: File example compute.C.

5.7.3 Input File
The options used for solving this example are displayed in Listing 5.73.
###############################################
# UQ E n v i r o n m e n t
###############################################
#e n v h e l p
= anything
env_numSubEnvironments
= 1
env_subDisplayFileName
= outputData / display
env_subDisplayAllowAll
= 0
env_subDisplayAllowedSet = 0
env_displayVerbosity
= 0
env_syncVerbosity
= 0

162

CHAPTER 5. QUESO EXAMPLES
env_seed

163

= 0

###############################################
# S t a t i s t i c a l i n v e r s e problem ( i p )
###############################################
#i p h e l p
= anything
ip_computeSolution
= 1
ip_dataOutputFileName
= outputData / sipOutput
ip_dataOutputAllowedSet = 0
###############################################
# ’ ip ’ : information for Multilevel algorithm
###############################################
#i p m l h e l p
= anything
ip_ml_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_dataOutputAllowedSet = 0 1
###############################################
# All levels , unless otherwise specified
###############################################
i p _ m l _ d e f a u l t _ m i n E f f e c t i v e S i z e R a t i o = 0.49
i p _ m l _ d e f a u l t _ m a x E f f e c t i v e S i z e R a t i o = 0.51
i p _ m l _ d e f a u l t _ r a w C h a i n _ s i z e = 1000
#i p m l d e f a u l t r a w C h a i n d a t a O u t p u t F i l e N a m e = o u t p u t D a t a / r a w C h a i n m l
#i p m l 0 r a w C h a i n d a t a O u t p u t F i l e N a m e = o u t p u t D a t a / r a w C h a i n m l
#i p m l d e f a u l t s c a l e C o v M a t r i x
#i p m l d e f a u l t d r m a x N u m E x t r a S t a g e s
#i p m l d e f a u l t d r l i s t O f S c a l e s F o r E x t r a S t a g e s

= 0
= 2
= 10. 25.

###############################################
# Last l e v e l ( l e v e l 4 for ’ example gsl ’ executable )
###############################################
ip_ml_last_dataOutputFileName
= outputData / sipOutput_ml
ip_ml_last_dataOutputAllowedSet
= 0 1
ip_ml_last_rawChain_size
= 5000
ip_ml_last_rawChain_computeStats
= 1
ip_ml_last_rawChain_dataOutputFileName
= outputData / rawChain_ml
#i p m l l a s t s c a l e C o v M a t r i x
#i p m l l a s t d r m a x N u m E x t r a S t a g e s
#i p m l l a s t d r l i s t O f S c a l e s F o r E x t r a S t a g e s
ip_ml_last_rawChain_stats_kde_compute
ip_ml_last_rawChain_stats_kde_numEvalPositions
ip_ml_last_rawChain_stats_covMatrix_compute
ip_ml_last_rawChain_stats_corrMatrix_compute

= 0
= 2
= 10. 25.
=
=
=
=

1
250
1
1

Listing 5.73: Options for QUESO library used in application code (Listings 5.68-5.72).

5.7.4 Create your own Makefile
Similarly to the other examples presented in this user’s manual and also available with QUESO
distribution, a user-created makefile is available: ‘Makefile hysteretic violeta’ which may
personalized to each user’s computer settings and used to compile the code and create the
executable hysteretic_gsl.
Thus to compile, build and execute the code, commands similar to the following should
be entered:

CHAPTER 5. QUESO EXAMPLES

164

$ cd $HOME / LIBRARIES / QUESO -0.50.0/ examples / hysteretic /
$ export L D_ L IB RA RY _ PA TH = $ L D _ L I B R A R Y _ P A T H :\
$HOME / LIBRARIES / gsl -1.15/ lib /:\
$HOME / LIBRARIES / boost -1.53.0/ lib /:\
$HOME / LIBRARIES / hdf5 -1.8.10/ lib :\
$HOME / LIBRARIES / QUESO -0.50.0/ lib
$ make -f M a k e f i l e _ h y s t e r e t i c _ v i o l e t a
$ ./ hyster etic_gs l example . inp

Again, the ‘export’ instruction above is only necessary if the user has not saved the path
for the libraries used during QUESO installation in his/her .bashrc file.

5.7.5 Data Post-Processing and Visualization
According to the specifications of the input file in Listing 5.73, both a folder named outputData
and a the following files should be generated:
rawChain_ml.m
display_sub0.txt
Note that in this hysteretic problem a total of 13 levels are required for the Multilevel
method (e.g. see the contents of file rawChain ml.m).
The sequence of Matlab commands is identical to the ones presented in Sections 5.1.5,
5.2.5, 5.3.8 and 5.4.7; therefore, are omitted here. The reader is invited to explore the Matlab
files plot all.m and/or cpp gen.m, for details of how the figures have been generated.

5.7.5.1 KDE Plots
Figure 5.7.4 presents the KDE plots of each parameter θi , i = 1, . . . , 15. The Multilevel
method also provides data about the logarithm of the likelihood function as well as of the
target PDF. Figure 5.7.5 presents the KDE plots of both the likelihood function and of its
logarithm.

5.7.5.2 Autocorrelation and CDF Plots
Figure 5.7.6a combines the CDF of all parameters θi , i = 1, . . . , 15 into a single plot. Figure 5.7.6b presents their autocorrelations.

CHAPTER 5. QUESO EXAMPLES

Figure 5.7.4: KDE plots of parameter θ at the last level.

165

CHAPTER 5. QUESO EXAMPLES

(a) log(f (y|θ))

166

(b) f (y|θ)

Figure 5.7.5: KDE plots of the likelihood function, given by Eq. (5.7.3), and of its logarithm,
at the last level.

(a) CDF

(b) Autocorrelation

Figure 5.7.6: CDF and autocorrelation plots of parameter θ at the last level.

Bibliography

[1] Diagrams for Interactive Learning. http://interactagram.com/. Accessed on August
12th, 2012.
[2] TACC: Texas Advanced Computing Center. http://www.tacc.utexas.edu/, 2001-2013.
[3] J. L. Beck and S.-K. Au. Bayesian updating of structural models and reliability using
Markov Chain Monte Carlo simulation. Journal Of Engineering Mechanics, 128:380–391,
2002.
[4] D. Calvetti and E. Somersalo. Introduction to Bayesian Scientific Computing, volume 2
of Surveys and Tutorials in the Applied Mathematical Sciences. Springer, 2007.
[5] B. P. Carlin and T. A. Louis. Bayesian Methods for Data Analysis. Texts in Statistical
Science. CRS Press, 3rd edition, 2006.
[6] S. H. Cheung. Stochastic analysis, model and reliability updating of complex systems
with applications to structural dynamics. PhD thesis. Jan 2009, California Institute of
Technology., 2009.
[7] S. H. Cheung, Todd A. Oliver, E. E. Prudencio, Serge Prudhomme, and Robert D.
Moser. Bayesian uncertainty analysis with applications to turbulence modeling. Reliability
Engineering & System Safety, 96(9, SI):1137–1149, 2011.
[8] S. H. Cheung and E. E. Prudencio. Parallel adaptive multilevel sampling algorithms for
the Bayesian analysis of mathematical models. International Journal for Uncertainty
Quantification, 2(3):215237, 2012.
[9] J. Ching and Y. Chen. Transitional Markov Chain Monte Carlo method for Bayesian
model updating, model class selection, and model averaging. Journal Of Engineering
Mechanics, 133(7):816832, 2007.
167

BIBLIOGRAPHY

168

[10] Committee on Mathematical Foundations of Verification, Validation, and Uncertainty
Quantification; Board on Mathematical Sciences and Their Applications, Division on
Engineering and Physical Sciences, National Research Council. Assessing the Reliability
of Complex Models: Mathematical and Statistical Foundations of Verification, Validation,
and Uncertainty Quantification. The National Academies Press, 2012. http://www.nap.
edu/openbook.php?record_id=13395.
[11] A. DasGupta. Asymptotic Theory of Statistics and Probability. Springer Texts in Statistics. Springer, 2008.
[12] R. Durret. Probability: Theory and Examples. Duxbury Advanced Series. Thomson
Brooks/Cole, 3rd edition, 2005.
[13] Mark Galassi, James Theiler, Brian Gough, Gerard Jungman, and many others. GNU
Scientific Library. http://www.gnu.org/software/gsl/, 1996-2011.
[14] A. Gelman, J. B. Carlin, H. S. Stern, and D. B. Rubin. Bayesian Data Analysis. Texts
in Statistical Science. Chapman & Hall/CRC, 2nd edition, 2004.
[15] P. J. Green and A. Mira. Delayed rejection in reversible jump Metropolis-Hastings.
BIOMETRIKA, 88(4):1035–1053, 2001.
[16] The HDF Group. HDF5 (Hierarchical Data Format 5). http://www.hdfgroup.org/
HDF5/, 2000–2012.
[17] The MathWorks Group. MATLABr. http://www.mathworks.com/products/matlab/,
2013.
[18] H. Haario, M. Laine, A. Mira, and E. Saksman. DRAM: Efficient adaptive MCMC. Stat.
Comput., 16:339–354, 2006.
[19] H. Haario, E. Saksman, and J. Tamminen. An adaptive Metropolis algorithm. Bernoulli,
7(2):223–242, 2001.
[20] W. K. Hastings. Monte Carlo sampling methods using Markov chains and their applications. BIOMETRIKA, 57(1):97–109, 1970.
[21] Michael Heroux. Trilinos. http://trilinos.sandia.gov/, 2013.
[22] Michael A. Heroux, Roscoe A. Bartlett, Vicki E. Howle, Robert J. Hoekstra, Jonathan J.
Hu, Tamara G. Kolda, Richard B. Lehoucq, Kevin R. Long, Roger P. Pawlowski, Eric T.
Phipps, Andrew G. Salinger, Heidi K. Thornquist, Ray S. Tuminaro, James M. Willenbring, Alan Williams, and Kendall S. Stanley. An overview of the Trilinos project. ACM
Trans. Math. Softw., 31(3):397–423, 2005.
[23] X. Huan and Y. Marzouk. Optimal Bayesian experimental design for combustion kinetics. In 49th AIAA Aerospace Sciences Meeting including the New Horizons Forum and
Aerospace Exposition, number AIAA 2011-513, Orlando, Florida, 2011.

BIBLIOGRAPHY

169

[24] Silicon Graphics International. STL: Standard Template Library. http://www.sgi.com/
tech/stl/, 2000-2011.
[25] J. Jacod and P. Protter. Probability Essentials. Springer, 2nd edition, 2004.
[26] E. T. Jaynes. Probability Theory: The Logic of Science. Cambridge University Press,
2003.
[27] N. M. Josuttis. The C++ Standard Library, A Tutorial and Reference. Addison Wesley,
1st edition, 1999.
[28] J. Kaipio and E. Somersalo. Statistical and Computational Inverse Problems, volume 160
of Applied Mathematical Sciences. Springer, 2005.
[29] M. Laine. DRAM - Delayed Rejection Adaptive Metropolis. http://helios.fmi.fi/
~lainema/dram/, 2006-2008. Accessed on October 8th, 2013.
[30] M. Laine. MCMC Toolbox for Matlab. helios.fmi.fi/~lainema/mcmc/, 2006-2008.
Accessed on March 28th, 2013.
[31] M. Laine. Adaptive MCMC methods with applications in environmental and geophysical
models. PhD thesis, Lappeenranta University of Technology, Lappeenranta, Finland,
2008.
[32] S. B. Lippman, J. Lajoie, and B. E. Moo. C++ Primer. Addison Wesley, 4th edition,
2005.
[33] Andrew Makhorin and GLKP Development Team. GLPK (GNU Linear Programming
Kit). http://www.gnu.org/software/glpk/, 2000-2012.
[34] N. Metropolis, A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. Teller. Equations of state calculations by fast computing machines. Journal of Chemical Physics,
21(6):1087–1092, 1953.
[35] A. Mira. On Metropolis-Hastings algorithms with delayed rejection. Metron - International Journal of Statistics, 59(3-4):231–241, 2001.
[36] E. E. Prudencio and K. W. Schulz. The Parallel C++ Statistical Library ‘QUESO’:
Quantification of Uncertainty for Estimation, Simulation and Optimization. In Euro-Par
2011: Parallel Processing Workshops, volume 7155 of Lecture Notes in Computer Science,
pages 398–407. Springer Berlin / Heidelberg, 2012.
[37] C. P. Robert. The Bayesian Choice. Springer Verlag, 2nd edition, 2004.
[38] C. P. Robert and G. Casella. Monte Carlo Statistical Methods. Springer Verlag, 2nd
edition, 2005.

BIBLIOGRAPHY

170

[39] B. W. Silverman. Density Estimation for Statistics and Data Analysis. Number 26 in
Monographs on Statistics & Applied Probability. Chapman & Hall/CRC, 1986.
[40] Boost Development Team. Boost C++ Libraries. http://www.boost.org/, 1998-2013.
[41] GCC Team. GCC, the GNU compiler collection. http://gcc.gnu.org/, 1987-2013.
[42] GNU Development Team. GNU build system (autotools). http://www.gnu.org/
software/software.html, ?–2013. Retrieved August 4th, 2013.
[43] GRVY Development Team. The groovy toolkit (GRVY). https://red.ices.utexas.
edu/projects/software/wiki/GRVY, 1996-2009.
[44] IntelrTeam. Intel c++ compiler. http://software.intel.com/en-us/c-compilers,
1987-2013. Retrieved August 4th, 2013.
[45] MPICH Development Team. MPICH: High-Performance Portable MPI. http://www.
mpich.org/, 2001-2013.
[46] Octave Development Team. GNU Octave. http://www.gnu.org/software/octave/,
1988–2013.
[47] Open MPI Development Team. Open MPI: Open source high performance computing.
http://www.open-mpi.org/, 2008-2012.
[48] Dimitri van Heesch. Doxygen. http://www.doxygen.org/, 2009-2013.
[49] http://en.wikipedia.org/wiki/Ablation. Accessed on August 12th, 2012.

APPENDIX

A

Free Software Needs Free Documentation

The following article was written by Richard Stallman, founder of the GNU Project.
The biggest deficiency in the free software community today is not in the software−it is
the lack of good free documentation that we can include with the free software. Many of
our most important programs do not come with free reference manuals and free introductory
texts. Documentation is an essential part of any software package; when an important free
software package does not come with a free manual and a free tutorial, that is a major gap.
We have many such gaps today.
Consider Perl, for instance. The tutorial manuals that people normally use are nonfree. How did this come about? Because the authors of those manuals published them with
restrictive terms−no copying, no modification, source files not available−which exclude them
from the free software world.
That wasn’t the first time this sort of thing happened, and it was far from the last. Many
times we have heard a GNU user eagerly describe a manual that he is writing, his intended
contribution to the community, only to learn that he had ruined everything by signing a
publication contract to make it non-free.
Free documentation, like free software, is a matter of freedom, not price. The problem
with the non-free manual is not that publishers charge a price for printed copies−that in itself
is fine. (The Free Software Foundation sells printed copies of manuals, too.) The problem is
the restrictions on the use of the manual. Free manuals are available in source code form, and
give you permission to copy and modify. Non-free manuals do not allow this.
The criteria of freedom for a free manual are roughly the same as for free software. Redistribution (including the normal kinds of commercial redistribution) must be permitted, so
that the manual can accompany every copy of the program, both on-line and on paper.
171

APPENDIX A. FREE SOFTWARE NEEDS FREE DOCUMENTATION

172

Permission for modification of the technical content is crucial too. When people modify the
software, adding or changing features, if they are conscientious they will change the manual
too−so they can provide accurate and clear documentation for the modified program. A
manual that leaves you no choice but to write a new manual to document a changed version
of the program is not really available to our community.
Some kinds of limits on the way modification is handled are acceptable. For example,
requirements to preserve the original author’s copyright notice, the distribution terms, or the
list of authors, are ok. It is also no problem to require modified versions to include notice that
they were modified. Even entire sections that may not be deleted or changed are acceptable,
as long as they deal with nontechnical topics (like this one). These kinds of restrictions are
acceptable because they don’t obstruct the community’s normal use of the manual.
However, it must be possible to modify all the technical content of the manual, and then
distribute the result in all the usual media, through all the usual channels. Otherwise, the
restrictions obstruct the use of the manual, it is not free, and we need another manual to
replace it.
Please spread the word about this issue. Our community continues to lose manuals to
proprietary publishing. If we spread the word that free software needs free reference manuals
and free tutorials, perhaps the next person who wants to contribute by writing documentation will realize, before it is too late, that only free manuals contribute to the free software
community.
If you are writing documentation, please insist on publishing it under the GNU Free
Documentation License or another free documentation license. Remember that this decision
requires your approval−you don’t have to let the publisher decide. Some commercial publishers will use a free license if you insist, but they will not propose the option; it is up to you
to raise the issue and say firmly that this is what you want. If the publisher you are dealing
with refuses, please try other publishers. If you’re not sure whether a proposed license is free,
write to lice

APPENDIX

B

GNU General Public License

Copyright © 2007 Free Software Foundation, Inc. http://fsf.org/
Everyone is permitted to copy and distribute verbatim copies of this license document,
but changing it is not allowed.

Preamble
The GNU General Public License is a free, copyleft license for software and other kinds of
works.
The licenses for most software and other practical works are designed to take away your
freedom to share and change the works. By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change all versions of a program–to make
sure it remains free software for all its users. We, the Free Software Foundation, use the GNU
General Public License for most of our software; it applies also to any other work released this
way by its authors. You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General
Public Licenses are designed to make sure that you have the freedom to distribute copies of
free software (and charge for them if you wish), that you receive source code or can get it if
you want it, that you can change the software or use pieces of it in new free programs, and
that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or asking
you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies
of the software, or if you modify it: responsibilities to respect the freedom of others.
173

APPENDIX B. GNU GENERAL PUBLIC LICENSE

174

For example, if you distribute copies of such a program, whether gratis or for a fee, you
must pass on to the recipients the same freedoms that you received. You must make sure that
they, too, receive or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright
on the software, and (2) offer you this License giving you legal permission to copy, distribute
and/or modify it.
For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified
versions be marked as changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of the
software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern
of such abuse occurs in the area of products for individuals to use, which is precisely where
it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the
practice for those products. If such problems arise substantially in other domains, we stand
ready to extend this provision to those domains in future versions of the GPL, as needed to
protect the freedom of users.
Finally, every program is threatened constantly by software patents. States should not
allow patents to restrict development and use of software on general-purpose computers, but
in those that do, we wish to avoid the special danger that patents applied to a free program
could make it effectively proprietary. To prevent this, the GPL assures that patents cannot
be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.

Terms and Conditions
0. Definitions
“This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of works, such as
semiconductor masks.
“The Program” refers to any copyrightable work licensed under this License. Each licensee
is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work in a fashion
requiring copyright permission, other than the making of an exact copy. The resulting work
is called a “modified version” of the earlier work or a work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based on the Program.
To “propagate” a work means to do anything with it that, without permission, would
make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying,

APPENDIX B. GNU GENERAL PUBLIC LICENSE

175

distribution (with or without modification), making available to the public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other parties to make or
receive copies. Mere interaction with a user through a computer network, with no transfer of
a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright
notice, and (2) tells the user that there is no warranty for the work (except to the extent that
warranties are provided), that licensees may convey the work under this License, and how to
view a copy of this License. If the interface presents a list of user commands or options, such
as a menu, a prominent item in the list meets this criterion.

1. Source Code
The “source code” for a work means the preferred form of the work for making modifications
to it. “Object code” means any non-source form of a work.
A “Standard Interface” means an interface that either is an official standard defined by a
recognized standards body, or, in the case of interfaces specified for a particular programming
language, one that is widely used among developers working in that language.
The “System Libraries” of an executable work include anything, other than the work as a
whole, that (a) is included in the normal form of packaging a Major Component, but which
is not part of that Major Component, and (b) serves only to enable use of the work with
that Major Component, or to implement a Standard Interface for which an implementation
is available to the public in source code form. A “Major Component”, in this context, means
a major essential component (kernel, window system, and so on) of the specific operating
system (if any) on which the executable work runs, or a compiler used to produce the work,
or an object code interpreter used to run it.
The “Corresponding Source” for a work in object code form means all the source code
needed to generate, install, and (for an executable work) run the object code and to modify
the work, including scripts to control those activities. However, it does not include the work’s
System Libraries, or general-purpose tools or generally available free programs which are used
unmodified in performing those activities but which are not part of the work. For example,
Corresponding Source includes interface definition files associated with source files for the
work, and the source code for shared libraries and dynamically linked subprograms that the
work is specifically designed to require, such as by intimate data communication or control
flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

176

2. Basic Permissions
All rights granted under this License are granted for the term of copyright on the Program, and
are irrevocable provided the stated conditions are met. This License explicitly affirms your
unlimited permission to run the unmodified Program. The output from running a covered
work is covered by this License only if the output, given its content, constitutes a covered
work. This License acknowledges your rights of fair use or other equivalent, as provided by
copyright law.
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to
others for the sole purpose of having them make modifications exclusively for you, or provide
you with facilities for running those works, provided that you comply with the terms of this
License in conveying all material for which you do not control copyright. Those thus making
or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted
material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the conditions stated
below. Sublicensing is not allowed; section 10 makes it unnecessary.

3. Protecting Users’ Legal Rights From Anti-Circumvention Law
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20
December 1996, or similar laws prohibiting or restricting circumvention of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of
technological measures to the extent such circumvention is effected by exercising rights under
this License with respect to the covered work, and you disclaim any intention to limit operation
or modification of the work as a means of enforcing, against the work’s users, your or third
parties’ legal rights to forbid circumvention of technological measures.

4. Conveying Verbatim Copies
You may convey verbatim copies of the Program’s source code as you receive it, in any medium,
provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms
added in accord with section 7 apply to the code; keep intact all notices of the absence of any
warranty; and give all recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer
support or warranty protection for a fee.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

177

5. Conveying Modified Source Versions
You may convey a work based on the Program, or the modifications to produce it from the
Program, in the form of source code under the terms of section 4, provided that you also meet
all of these conditions:
(a) The work must carry prominent notices stating that you modified it, and giving a relevant
date.
(b) The work must carry prominent notices stating that it is released under this License
and any conditions added under section 7. This requirement modifies the requirement in
section 4 to “keep intact all notices”.
(c) You must license the entire work, as a whole, under this License to anyone who comes into
possession of a copy. This License will therefore apply, along with any applicable section
7 additional terms, to the whole of the work, and all its parts, regardless of how they are
packaged. This License gives no permission to license the work in any other way, but it
does not invalidate such permission if you have separately received it.
(d) If the work has interactive user interfaces, each must display Appropriate Legal Notices;
however, if the Program has interactive interfaces that do not display Appropriate Legal
Notices, your work need not make them do so.
A compilation of a covered work with other separate and independent works, which are not
by their nature extensions of the covered work, and which are not combined with it such as
to form a larger program, in or on a volume of a storage or distribution medium, is called an
“aggregate” if the compilation and its resulting copyright are not used to limit the access or
legal rights of the compilation’s users beyond what the individual works permit. Inclusion of
a covered work in an aggregate does not cause this License to apply to the other parts of the
aggregate.

6. Conveying Non-Source Forms
You may convey a covered work in object code form under the terms of sections 4 and 5,
provided that you also convey the machine-readable Corresponding Source under the terms
of this License, in one of these ways:
(a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical
medium customarily used for software interchange.
(b) Convey the object code in, or embodied in, a physical product (including a physical
distribution medium), accompanied by a written offer, valid for at least three years and
valid for as long as you offer spare parts or customer support for that product model,
to give anyone who possesses the object code either (1) a copy of the Corresponding

APPENDIX B. GNU GENERAL PUBLIC LICENSE

178

Source for all the software in the product that is covered by this License, on a durable
physical medium customarily used for software interchange, for a price no more than your
reasonable cost of physically performing this conveying of source, or (2) access to copy
the Corresponding Source from a network server at no charge.
(c) Convey individual copies of the object code with a copy of the written offer to provide the
Corresponding Source. This alternative is allowed only occasionally and noncommercially,
and only if you received the object code with such an offer, in accord with subsection 6b.
(d) Convey the object code by offering access from a designated place (gratis or for a charge),
and offer equivalent access to the Corresponding Source in the same way through the same
place at no further charge. You need not require recipients to copy the Corresponding
Source along with the object code. If the place to copy the object code is a network server,
the Corresponding Source may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain clear directions next to
the object code saying where to find the Corresponding Source. Regardless of what server
hosts the Corresponding Source, you remain obligated to ensure that it is available for as
long as needed to satisfy these requirements.
(e) Convey the object code using peer-to-peer transmission, provided you inform other peers
where the object code and Corresponding Source of the work are being offered to the
general public at no charge under subsection 6d.
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code
work.
A “User Product” is either (1) a “consumer product”, which means any tangible personal
property which is normally used for personal, family, or household purposes, or (2) anything
designed or sold for incorporation into a dwelling. In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, “normally used” refers to a typical or common use of
that class of product, regardless of the status of the particular user or of the way in which the
particular user actually uses, or expects or is expected to use, the product. A product is a
consumer product regardless of whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant mode of use of the product.
“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered
work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in
no case prevented or interfered with solely because modification has been made.
If you convey an object code work under this section in, or with, or specifically for use
in, a User Product, and the conveying occurs as part of a transaction in which the right of
possession and use of the User Product is transferred to the recipient in perpetuity or for
a fixed term (regardless of how the transaction is characterized), the Corresponding Source

APPENDIX B. GNU GENERAL PUBLIC LICENSE

179

conveyed under this section must be accompanied by the Installation Information. But this
requirement does not apply if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has been installed in ROM).
The requirement to provide Installation Information does not include a requirement to
continue to provide support service, warranty, or updates for a work that has been modified
or installed by the recipient, or for the User Product in which it has been modified or installed.
Access to a network may be denied when the modification itself materially and adversely affects
the operation of the network or violates the rules and protocols for communication across the
network.
Corresponding Source conveyed, and Installation Information provided, in accord with
this section must be in a format that is publicly documented (and with an implementation
available to the public in source code form), and must require no special password or key for
unpacking, reading or copying.

7. Additional Terms
“Additional permissions” are terms that supplement the terms of this License by making
exceptions from one or more of its conditions. Additional permissions that are applicable to
the entire Program shall be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions apply only to part of the
Program, that part may be used separately under those permissions, but the entire Program
remains governed by this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option remove any additional
permissions from that copy, or from any part of it. (Additional permissions may be written
to require their own removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work, for which you have or
can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you add to a covered
work, you may (if authorized by the copyright holders of that material) supplement the terms
of this License with terms:
(a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16
of this License; or
(b) Requiring preservation of specified reasonable legal notices or author attributions in that
material or in the Appropriate Legal Notices displayed by works containing it; or
(c) Prohibiting misrepresentation of the origin of that material, or requiring that modified
versions of such material be marked in reasonable ways as different from the original
version; or
(d) Limiting the use for publicity purposes of names of licensors or authors of the material;
or

APPENDIX B. GNU GENERAL PUBLIC LICENSE

180

(e) Declining to grant rights under trademark law for use of some trade names, trademarks,
or service marks; or
(f) Requiring indemnification of licensors and authors of that material by anyone who conveys
the material (or modified versions of it) with contractual assumptions of liability to the
recipient, for any liability that these contractual assumptions directly impose on those
licensors and authors.
All other non-permissive additional terms are considered “further restrictions” within the
meaning of section 10. If the Program as you received it, or any part of it, contains a notice
stating that it is governed by this License along with a term that is a further restriction,
you may remove that term. If a license document contains a further restriction but permits
relicensing or conveying under this License, you may add to a covered work material governed
by the terms of that license document, provided that the further restriction does not survive
such relicensing or conveying.
If you add terms to a covered work in accord with this section, you must place, in the
relevant source files, a statement of the additional terms that apply to those files, or a notice
indicating where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the form of a separately
written license, or stated as exceptions; the above requirements apply either way.

8. Termination
You may not propagate or modify a covered work except as expressly provided under this
License. Any attempt otherwise to propagate or modify it is void, and will automatically
terminate your rights under this License (including any patent licenses granted under the
third paragraph of section 11).
However, if you cease all violation of this License, then your license from a particular
copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the copyright holder fails to notify
you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the
copyright holder notifies you of the violation by some reasonable means, this is the first time
you have received notice of violation of this License (for any work) from that copyright holder,
and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties
who have received copies or rights from you under this License. If your rights have been
terminated and not permanently reinstated, you do not qualify to receive new licenses for the
same material under section 10.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

181

9. Acceptance Not Required for Having Copies
You are not required to accept this License in order to receive or run a copy of the Program.
Ancillary propagation of a covered work occurring solely as a consequence of using peer-topeer transmission to receive a copy likewise does not require acceptance. However, nothing
other than this License grants you permission to propagate or modify any covered work.
These actions infringe copyright if you do not accept this License. Therefore, by modifying or
propagating a covered work, you indicate your acceptance of this License to do so.

10. Automatic Licensing of Downstream Recipients
Each time you convey a covered work, the recipient automatically receives a license from the
original licensors, to run, modify and propagate that work, subject to this License. You are
not responsible for enforcing compliance by third parties with this License.
An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation
of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor
in interest had or could give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if the predecessor has it
or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the rights granted or affirmed
under this License. For example, you may not impose a license fee, royalty, or other charge for
exercise of rights granted under this License, and you may not initiate litigation (including a
cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making,
using, selling, offering for sale, or importing the Program or any portion of it.

11. Patents
A “contributor” is a copyright holder who authorizes use under this License of the Program
or a work on which the Program is based. The work thus licensed is called the contributor’s
“contributor version”.
A contributor’s “essential patent claims” are all patent claims owned or controlled by the
contributor, whether already acquired or hereafter acquired, that would be infringed by some
manner, permitted by this License, of making, using, or selling its contributor version, but do
not include claims that would be infringed only as a consequence of further modification of
the contributor version. For purposes of this definition, “control” includes the right to grant
patent sublicenses in a manner consistent with the requirements of this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under
the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise
run, modify and propagate the contents of its contributor version.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

182

In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to
practice a patent or covenant not to sue for patent infringement). To “grant” such a patent
license to a party means to make such an agreement or commitment not to enforce a patent
against the party.
If you convey a covered work, knowingly relying on a patent license, and the Corresponding
Source of the work is not available for anyone to copy, free of charge and under the terms of
this License, through a publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to
deprive yourself of the benefit of the patent license for this particular work, or (3) arrange,
in a manner consistent with the requirements of this License, to extend the patent license to
downstream recipients. “Knowingly relying” means you have actual knowledge that, but for
the patent license, your conveying the covered work in a country, or your recipient’s use of
the covered work in a country, would infringe one or more identifiable patents in that country
that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or arrangement, you convey, or
propagate by procuring conveyance of, a covered work, and grant a patent license to some of
the parties receiving the covered work authorizing them to use, propagate, modify or convey a
specific copy of the covered work, then the patent license you grant is automatically extended
to all recipients of the covered work and works based on it.
A patent license is “discriminatory” if it does not include within the scope of its coverage,
prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that
are specifically granted under this License. You may not convey a covered work if you are a
party to an arrangement with a third party that is in the business of distributing software,
under which you make payment to the third party based on the extent of your activity of
conveying the work, and under which the third party grants, to any of the parties who would
receive the covered work from you, a discriminatory patent license (a) in connection with copies
of the covered work conveyed by you (or copies made from those copies), or (b) primarily for
and in connection with specific products or compilations that contain the covered work, unless
you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting any implied license or
other defenses to infringement that may otherwise be available to you under applicable patent
law.

12. No Surrender of Others’ Freedom
If conditions are imposed on you (whether by court order, agreement or otherwise) that
contradict the conditions of this License, they do not excuse you from the conditions of this
License. If you cannot convey a covered work so as to satisfy simultaneously your obligations
under this License and any other pertinent obligations, then as a consequence you may not
convey it at all. For example, if you agree to terms that obligate you to collect a royalty for
further conveying from those to whom you convey the Program, the only way you could satisfy

APPENDIX B. GNU GENERAL PUBLIC LICENSE

183

both those terms and this License would be to refrain entirely from conveying the Program.

13. Use with the GNU Affero General Public License
Notwithstanding any other provision of this License, you have permission to link or combine
any covered work with a work licensed under version 3 of the GNU Affero General Public
License into a single combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through
a network will apply to the combination as such.

14. Revised Versions of this License
The Free Software Foundation may publish revised and/or new versions of the GNU General
Public License from time to time. Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies that a
certain numbered version of the GNU General Public License “or any later version” applies to
it, you have the option of following the terms and conditions either of that numbered version
or of any later version published by the Free Software Foundation. If the Program does not
specify a version number of the GNU General Public License, you may choose any version
ever published by the Free Software Foundation.
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version
permanently authorizes you to choose that version for the Program.
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing
to follow a later version.

15. Disclaimer of Warranty
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS”
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

184

16. Limitation of Liability
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES
OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

17. Interpretation of Sections 15 and 16
If the disclaimer of warranty and limitation of liability provided above cannot be given local
legal effect according to their terms, reviewing courts shall apply local law that most closely
approximates an absolute waiver of all civil liability in connection with the Program, unless
a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

End of Terms and Conditions

How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest possible use to the public,
the best way to achieve this is to make it free software which everyone can redistribute and
change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the
start of each source file to most effectively state the exclusion of warranty; and each file should
have at least the “copyright” line and a pointer to where the full notice is found.

Copyright (C) 



This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

APPENDIX B. GNU GENERAL PUBLIC LICENSE

185

You should have received a copy of the GNU General Public License
along with this program. If not, see .

Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short notice like this when it
starts in an interactive mode:


Copyright (C) 



This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
This is free software, and you are welcome to redistribute it
under certain conditions; type ‘show c’ for details.

The hypothetical commands show w and show c should show the appropriate parts of the
General Public License. Of course, your program’s commands might be different; for a GUI
interface, you would use an “about box”.
You should also get your employer (if you work as a programmer) or school, if any, to sign
a “copyright disclaimer” for the program, if necessary. For more information on this, and how
to apply and follow the GNU GPL, see http://www.gnu.org/licenses/.
The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful
to permit linking proprietary applications with the library. If this is what you want to do,
use the GNU Lesser General Public License instead of this License. But first, please read
http://www.gnu.org/philosophy/why-not-lgpl.html.

APPENDIX

C

GNU Free Documentation License

Version 1.3, 3 November 2008
Copyright© 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies of this license document,
but changing it is not allowed.

0. Preamble
The purpose of this License is to make a manual, textbook, or other functional and useful
document “free” in the sense of freedom: to assure everyone the effective freedom to copy
and redistribute it, with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way to get credit for their
work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document
must themselves be free in the same sense. It complements the GNU General Public License,
which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free
software needs free documentation: a free program should come with manuals providing the
same freedoms that the software does. But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works whose purpose is instruction
or reference.
186

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

187

1. Applicability and Definitions
This License applies to any manual or other work, in any medium, that contains a notice
placed by the copyright holder saying it can be distributed under the terms of this License.
Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The “Document”, below, refers to any such manual
or work. Any member of the public is a licensee, and is addressed as “you”. You accept
the license if you copy, modify or distribute the work in a way requiring permission under
copyright law.
A “Modified Version” of the Document means any work containing the Document or a
portion of it, either copied verbatim, or with modifications and/or translated into another
language.
A “Secondary Section” is a named appendix or a front-matter section of the Document
that deals exclusively with the relationship of the publishers or authors of the Document
to the Document’s overall subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document is in part a textbook of
mathematics, a Secondary Section may not explain any mathematics.) The relationship could
be a matter of historical connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as
being those of Invariant Sections, in the notice that says that the Document is released under
this License. If a section does not fit the above definition of Secondary then it is not allowed
to be designated as Invariant. The Document may contain zero Invariant Sections. If the
Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts
or Back-Cover Texts, in the notice that says that the Document is released under this License.
A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in
a format whose specification is available to the general public, that is suitable for revising
the document straightforwardly with generic text editors or (for images composed of pixels)
generic paint programs or (for drawings) some widely available drawing editor, and that is
suitable for input to text formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise Transparent file format
whose markup, or absence of markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is not Transparent if used for
any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup,
Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD,
and standard-conforming simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include
proprietary formats that can be read and edited only by proprietary word processors, SGML
or XML for which the DTD and/or processing tools are not generally available, and the

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

188

machine-generated HTML, PostScript or PDF produced by some word processors for output
purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages
as are needed to hold, legibly, the material this License requires to appear in the title page.
For works in formats which do not have any title page as such, “Title Page” means the text
near the most prominent appearance of the work’s title, preceding the beginning of the body
of the text.
The “publisher” means any person or entity that distributes copies of the Document to
the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is
precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another
language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such
a section when you modify the Document means that it remains a section “Entitled XYZ”
according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this
License applies to the Document. These Warranty Disclaimers are considered to be included
by reference in this License, but only as regards disclaiming warranties: any other implication
that these Warranty Disclaimers may have is void and has no effect on the meaning of this
License.

2. Verbatim Copying
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct
or control the reading or further copying of the copies you make or distribute. However, you
may accept compensation in exchange for copies. If you distribute a large enough number of
copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly
display copies.

3. Copying in Quantity
If you publish printed copies (or copies in media that commonly have printed covers) of the
Document, numbering more than 100, and the Document’s license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts:
Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
must also clearly and legibly identify you as the publisher of these copies. The front cover
must present the full title with all words of the title equally prominent and visible. You may

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

189

add other material on the covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the
first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100,
you must either include a machine-readable Transparent copy along with each Opaque copy,
or state in or with each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option,
you must take reasonably prudent steps, when you begin distribution of Opaque copies in
quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well
before redistributing any large number of copies, to give them a chance to provide you with
an updated version of the Document.

4. Modifications
You may copy and distribute a Modified Version of the Document under the conditions of
sections 2 and 3 above, provided that you release the Modified Version under precisely this
License, with the Modified Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of it. In addition, you
must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document,
and from those of previous versions (which should, if there were any, be listed in the History
section of the Document). You may use the same title as a previous version if the original
publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship
of the modifications in the Modified Version, together with at least five of the principal
authors of the Document (all of its principal authors, if it has fewer than five), unless they
release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright
notices.

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

190

F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the
Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts
given in the Document’s license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating
at least the title, year, new authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled “History” in the Document, create one stating
the title, year, authors, and publisher of the Document as given on its Title Page, then
add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document
for previous versions it was based on. These may be placed in the “History” section. You
may omit a network location for a work that was published at least four years before the
Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the
section, and preserve in the section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their
titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled “Endorsements”. Such a section may not be included in the
Modified Version.
N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title
with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this, add their titles to the list of
Invariant Sections in the Modified Version’s license notice. These titles must be distinct from
any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties–for example, statements of peer review or
that the text has been approved by an organization as the authoritative definition of a standard.

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

191

You may add a passage of up to five words as a Front-Cover Text, and a passage of up
to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified
Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by
(or through arrangements made by) any one entity. If the Document already includes a cover
text for the same cover, previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may replace the old one, on
explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to
use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. Combining Documents
You may combine the Document with other documents released under this License, under
the terms defined in section 4 above for modified versions, provided that you include in the
combination all of the Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its license notice, and that you
preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical
Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections
with the same name but different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original author or publisher of that
section if known, or else a unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various
original documents, forming one section Entitled “History”; likewise combine any sections
Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all
sections Entitled “Endorsements”.

6. Collections of Documents
You may make a collection consisting of the Document and other documents released under
this License, and replace the individual copies of this License in the various documents with a
single copy that is included in the collection, provided that you follow the rules of this License
for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually
under this License, provided you insert a copy of this License into the extracted document,
and follow this License in all other respects regarding verbatim copying of that document.

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

192

7. Aggregation with Independent Works
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate”
if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in
an aggregate, this License does not apply to the other works in the aggregate which are not
themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document,
then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts
may be placed on covers that bracket the Document within the aggregate, or the electronic
equivalent of covers if the Document is in electronic form. Otherwise they must appear on
printed covers that bracket the whole aggregate.

8. Translation
Translation is considered a kind of modification, so you may distribute translations of the
Document under the terms of section 4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may include translations of some or
all Invariant Sections in addition to the original versions of these Invariant Sections. You
may include a translation of this License, and all the license notices in the Document, and
any Warranty Disclaimers, provided that you also include the original English version of this
License and the original versions of those notices and disclaimers. In case of a disagreement
between the translation and the original version of this License or a notice or disclaimer, the
original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”,
the requirement (section 4) to Preserve its Title (section 1) will typically require changing the
actual title.

9. Termination
You may not copy, modify, sublicense, or distribute the Document except as expressly provided
under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular
copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the copyright holder fails to notify
you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the
copyright holder notifies you of the violation by some reasonable means, this is the first time

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

193

you have received notice of violation of this License (for any work) from that copyright holder,
and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who
have received copies or rights from you under this License. If your rights have been terminated
and not permanently reinstated, receipt of a copy of some or all of the same material does not
give you any rights to use it.

10. Future Revisions of This License
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the
present version, but may differ in detail to address new problems or concerns. See http:
//www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document
specifies that a particular numbered version of this License “or any later version” applies to
it, you have the option of following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the Free Software Foundation.
If the Document does not specify a version number of this License, you may choose any version
ever published (not as a draft) by the Free Software Foundation. If the Document specifies
that a proxy can decide which future versions of this License can be used, that proxy’s public
statement of acceptance of a version permanently authorizes you to choose that version for
the Document.

11. Relicensing
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web
server that publishes copyrightable works and also provides prominent facilities for anybody
to edit those works. A public wiki that anybody can edit is an example of such a server.
A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of
copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published
by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published
by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of
another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that
were first published under this License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.

APPENDIX C. GNU FREE DOCUMENTATION LICENSE

194

The operator of an MMC Site may republish an MMC contained in the site under CCBY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for
relicensing.

ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the
document and put the following copyright and license notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ‘‘GNU
Free Documentation License’’.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with
... Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the
three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing
these examples in parallel under your choice of free software license, such as the GNU General
Public License, to permit their use in free software.



File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 206
Page Mode                       : UseOutlines
Author                          : Kemelli C. Estacio-Hiroms
Title                           : QUESO user's manual
Subject                         : The QUESO Library – Quantification of Uncertainty for Estimation, Simulation, and Optimization
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.14
Keywords                        : research, uncertainty quantification, statistical inverse and statistical forward problems, validation.
Create Date                     : 2014:05:06 14:12:08-05:00
Modify Date                     : 2014:05:06 14:12:08-05:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013) kpathsea version 6.1.1