<commit_before>\chapter{Installation}\label{ch-install}
\thispagestyle{headings}
\markboth{Chapter \ref{ch-install}: Installation}{Chapter \ref{ch-install}: Installation}

%This chapter describes how to install QUESO, test it and use it to create your application.

  
This chapter covers the basic steps that a user will need follow when beginning to use QUESO: 
how to obtain, configure, 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 his/her 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 Page\footnote{\Quesoweb}.



        
\section{Pre-QUESO Installation Steps}\label{sec:Pre_Queso}


Herein, suppose you want to install QUESO and its dependencies on the following directory:
\begin{lstlisting}
$HOME/LIBRARIES/
\end{lstlisting}
%
so that you will not need root access rights. The directory above is referred  to  as \Queso{} installation directory (tree).

There are two main steps to prepare your LINUX computing system  for  the QUESO Library: obtain and install \Queso{} dependencies, and to define a number of environmental variables. These steps are discussed bellow.


\subsection{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:
\begin{enumerate}%{itemize}

  \item \textbf{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~\cite{STL}. % The STL is a generic library, meaning that its components are heavily parameterized: almost every component in the STL is a template. You should make sure that you understand how templates work in C++ before you use the STL.

  \item \textbf{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. E.g. GSL 1.12~\cite{Gsl}. %There are over 1000 functions in total with an extensive test suite.

  \item \textbf{Boost}: Boost provides free peer-reviewed portable C++ source libraries, which can be used with the C++ Standard Library. E.g. Boost 1.37.0~\cite{Boost}.

  \item \textbf{MPI}: The Message Passing Interface is a standard for parallel programming using the message passing model. E.g. Open MPI~\cite{Openmpi} or MPICH~\cite{Mpich}. \Queso{} requires MPI during the compilation step; however, you may run it in serial mode (e.g. in one single processor) if you wish. 

  \item \textbf{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. E.g. GRVY 0.31.0 ~\cite{grvy}.

\end{enumerate}%{itemize}

\Queso{} also works with the following optional libraries:

\begin{enumerate}%{itemize}
\item \textbf{HDF5}: The Hierarchical Data Format 5 is a technology suite that makes possible the management of extremely large and complex data collections. E.g. e.g. HDF5  5-1.8.8~\cite{HDF5}.

\item \textbf{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~\cite{GLPK}. 
% 
% \item \textbf{PETSc}: The Portable, Extensible Toolkit for Scientific Computation (PETSc) is a suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations, including parallel linear and nonlinear solvers~\cite{Petsc}.
% 
% \item \textbf{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.  E.g. Trilinos 9.0.2~\cite{Trilinos}.
\end{enumerate}%{itemize}

             

% \paragraph*{Note:}
% The basic steps to install GRYV are: 
% \begin{verbatim}
% $ ./configure --prefix=$HOME/LIBRARIES/grvy_0_31_0 \
%   --with-boost=$HOME/LIBRARIES/boost_1_37_0
% $ make 
% $ make install
% \end{verbatim}
% %
% The directory \texttt{$HOME/LIBRARIES/grvy\_0\_31\_0} does not need to exist in advance, since it will be created by the command 'make install' above.



\subsection{Prepare your LINUX Environment}\label{sec:prepare}

% Step one may differ whether your installation will performed in a stand-alone machine or in a network system which comprises Environment Modules\footnote{\url{http://www.modules.sourceforge.net}}~\footnote{\url{http://www.ices.utexas.edu/sysdocs/linux/modules.html}} to provide easy access to software, such as the one employed in ICES.


Before using QUESO, the user must first set a number of environmental variables, and indicate the full path
of the QUESO's dependencies: GSL, Boost and GRVY. 

For example, under the UNIX C shell (csh) a command of the form
%export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/home/kemelli/LIBRARIES/QUESO_0.45.0/lib
\begin{lstlisting}
$ setenv LD_LIBRARY_PATH \$LD_LIBRARY_PATH:
		$HOME/LIBRARIES/gsl_1_12/lib:
		$HOME/LIBRARIES/boost_1_37_0/lib:
		$HOME/LIBRARIES/grvy_0_31_0/lib
\end{lstlisting}
can be placed in the user's \verb+.cshrc+ or other startup file. 
Under UNIX bash shell, {\tt.cshrc} is replaced with a startup file such as {\tt.bashrc}, and the command {\tt setenv} with \texttt{export}.

In addition, the user must set the following environmental
variables:
\begin{lstlisting}
$ setenv CC gcc
$ setenv CXX g++
$ setenv MPICC mpicc
$ setenv MPICXX mpic++
$ setenv F77 f77
$ setenv FC gfortran 
\end{lstlisting}

% \footnote{Under UNIX bash shell, {\tt.cshrc} shall be replaced by startup file such as {\tt.bashrc}, and the command {\tt setenv} with \texttt{export}.}


\section{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 \Quesoweb{}.

Supposing you have downloaded the file `\verb+queso-0.45.3.tar.gz+' into \texttt{\$HOME/queso\_download/}, follow the commands to expand the tarball:
\begin{lstlisting}
$ cd $HOME/queso_download/
$ gunzip < queso-0.45.3.tar.gz  | tar xf -
$ cd $HOME/queso_download/queso-0.45.3   	#enter the directory 
\end{lstlisting}

Naturally, for versions of \Queso{} other than 0.45.3, the file names in the above commands must be adjusted.


\subsection{Recommended Build Directory Structure}\label{sec:Queso_tree}

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 \ref{sec:summary}).
To start, we defined three useful terms:

\begin{description}
 \item [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.%, or by checking out a copy of the \Queso{} repository.
 \item [Build tree] %- The directory structure where object and library files %, as well as executables 
%are located.
- 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 \texttt{configure, make}, etc. to build and install \Queso{}. 
 \item [Installation tree] - The tree where \Queso{} is installed. It is typically the \texttt{prefix} argument given to \Queso{}'s configure script; it is the directory from which you run installed \Queso{} executables.
\end{description}

Although it is possible to run \verb+./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~\cite{Trilinos}. 
%For example, both serial and parallel libraries can be built. This approach also eliminates problems with configuring in a `dirty' directory (one that has already been configured in).


\section{Configure QUESO Building Environment}\label{sec:Queso_configure}

\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:
\begin{lstlisting}
$ ./configure  --help  
\end{lstlisting}
%
from the top level of the source tree. 

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 a package that is not currently built by default, HDF5, append \texttt{--with-hdf5=DIR}, where \texttt{DIR} is the root directory of HDF5 installation,  to the configure invocation line. 

\Queso{} default installation location is `\texttt{/usr/local}', which requires superuser privileges. To use a path
        other than `\texttt{/usr/local}', specify the path with the `\texttt{--prefix=PATH}' switch. For instance, `\verb+--prefix=$HOME/LIBRARIES+'.



The basic steps to configure QUESO using GRVY, Boost and GSL for installation at `\verb+$HOME/LIBRARIES/queso_0_45_3+' are:
\begin{lstlisting}
$ ./configure --prefix=$HOME/LIBRARIES/queso_0_45_3 \
  --with-boost=$HOME/LIBRARIES/boost_1_37_0 \
  --with-gsl-prefix=$HOME/LIBRARIES/gsl_1_12 \
  --with-gvry=$HOME/LIBRARIES/grvy_0_31_0
\end{lstlisting}

Note: the directory `\verb+$HOME/LIBRARIES/queso_0_45_3+' does not need to exist in advance, since it will be created by the command \verb+make install+ described in Section \ref{sec:install_Queso_make}.


\section{Compile, Check and Install \Queso{}}\label{sec:install_Queso_make}
%
In order to build, check and install the library, the user must enter the following three commands sequentially:
\begin{lstlisting}
$ make
$ make check       # optional
$ make install 
\end{lstlisting}

Here, \verb+make+ builds the library, confidence tests, and programs;  \verb+ make check+ conducts various test suites in order to check the compiled source; and \verb+make install+ installs \Queso{} library, include files, and support programs

The files are installed under the installation tree (refer to Section \ref{sec:Queso_tree}), e.g. the directory specified with `\texttt{--prefix=DIR}' in Section \ref{sec:Queso_configure}. The directory, if not existing, will be created automatically.%, provided the mkdir command supports the -p  option.

% The library, confidence tests, and programs can be built by entering:
% \begin{lstlisting}
% $ make
% \end{lstlisting}
% 
% \Queso{} comes with various test suites in order to check the compiled source. To run the tests, do:
% \begin{lstlisting}
% $ make check
% \end{lstlisting}
% 
% Finally, the \Queso{} library, include files, and support programs can be installed by (more comments in Section \ref{sc-installed-dir-structure}):
% \begin{lstlisting}
% $ make install 
% \end{lstlisting}
% 
% The files are installed under the installation tree (refer to Section \ref{sec:Queso_tree}), e.g. the directory specified with `\texttt{--prefix=DIR}' in Section \ref{sec:Queso_configure}. The directory, if not existing, will be created automatically.%, provided the mkdir command supports the -p  option.
% 

%\subsection{Checking the compiled source} \label{sc-checks}

By running \texttt{make check}, several printouts appear in the screen and you should see messages such as:
\begin{lstlisting}
--------------------------------------------------------------------
(rtest): PASSED: Test 1 (TGA Validation Cycle)
--------------------------------------------------------------------
\end{lstlisting}

The last four tests printed in  the screen are tests under your QUESO build tree, i.e., they are located at the  directory \verb+$HOME/queso_download/queso-0.45.3/test+ (see Section \ref{sc-source-dir-structure} for the complete list of the directories under QUESO build tree).      %\texttt{test/t01\_valid\_cycle/}, \linebreak \texttt{test/t02\_sip\_sfp/}, \texttt{test/t03\_sequence/}, and  \texttt{test/t04\_bimodal/}. 
These tests are 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.



\section{\Queso{} Developer's Documentation}\label{sec:Queso_docs}



\Queso{} code documentation is written using Doxygen~\cite{Doxygen}, and can be regenerated by typing in the build tree:
\begin{lstlisting}
$ make docs
\end{lstlisting}

A directory named \verb+docs+ will be created in \verb+$HOME/queso_download/queso-0.45.3+ (the build tree; your current path) and you may access the code documentation in two different ways:
\begin{enumerate}
 \item HyperText Markup Language (HTML)  format: \verb+docs/html/index.html+, and the browser of your choice can be used to walk through the HTML documentation.
% \begin{verbatim}
% $ cd docs/html
% $ firefox 
% \end{verbatim}

\item Portable Document Format (PDF) format: \verb+docs/queso.pdf+, which can be accessed thought any PDF viewer.
% \begin{verbatim}
% $ cd docs
% $ acroread queso.pdf
% \end{verbatim}
\end{enumerate}
% 
% Obviously the two steps above assume you have \verb+firefox+ and \verb+acroread+ installed in your computer.

\section{Summary of Installation Steps}\label{sec:summary}


Supposing you have downloaded the file `queso-0.45.3.tar.gz' into \texttt{\$HOME/queso\_download/}.
%
The basic steps to configure QUESO using GRVY, Boost and GSL for installation at \linebreak 
`\verb+$HOME/LIBRARIES/queso_0_45_3+'  are:

\begin{lstlisting}
$ cd $HOME/queso_download/               #enter source dir
$ gunzip < queso-0.45.3.tar.gz  | tar xf -
$ cd $HOME/queso_download/queso-0.45.3   #enter the build dir
$ ./configure --prefix=$HOME/LIBRARIES/queso_0_45_3 \
  --with-boost=$HOME/LIBRARIES/boost_1_37_0 \
  --with-gsl-prefix=$HOME/LIBRARIES/gsl_1_12 \
  --with-gvry=$HOME/LIBRARIES/grvy_0_31_0 
$ make 
$ make check
$ make install 
$ make docs
$ ls $HOME/LIBRARIES/queso_0_45_3 #listing QUESO installation dir
>>  bin  include  lib  examples
\end{lstlisting}

% 
% \paragraph*{Note:} According to  Section \ref{sec:Queso_tree}, \texttt{\$HOME/queso\_download/} is the source tree, \\ \verb+$HOME/queso_download/queso-0.45.3+ is the build tree, and \newline
% \verb+$HOME/LIBRARIES/queso_0_45_3+ is the installation tree.
% 


\section{The Build Directory Structure} \label{sc-source-dir-structure}

The QUESO build directory contains three main directories, \texttt{src}, \texttt{examples} and \texttt{test}. They are listed below and more specific
information about them can be obtained with the Developer's documentation from Section \ref{sec:Queso_docs} above:
\begin{enumerate}
\item \texttt{src}, with five subdirectories:
\begin{enumerate}
\item \texttt{src/basic/}: with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/core/}:  with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/misc/}:  with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/stats/}: with \texttt{inc} and \texttt{src} subdirectories, and
\item \texttt{src/contrib/}.
\end{enumerate}

\item \texttt{examples}, with five subdirectories:
\begin{enumerate}
\item \texttt{examples/statisticalForwardProblem/},
\item \texttt{examples/statisticalInverseProblem/},
\item \texttt{examples/validationCycle/}, 
\item \texttt{examples/validationCycle2/},
\item \texttt{examples/infoTheoryProblem/}.
\end{enumerate}

\item  \texttt{test}, with five subdirectories:
\begin{enumerate}
\item \texttt{test/t01\_valid\_cycle/},
\item \texttt{test/t02\_sip\_sfp/},
\item \texttt{test/t03\_sequence/}, 
\item \texttt{test/t04\_bimodal/}, and
\item \texttt{test/gsl\_tests}.
\end{enumerate}

\end{enumerate}

The \verb+src+ directory contains the library itself; thus it has an entire chapter dedicated to its description (see Chapter \ref{ch-classes}).

The executables under \verb+examples+ are examples of application codes that use QUESO to solve either SIP or SFP, or both. The following section presents the steps for running two of them, \verb+statisticalInverseProblem+ and \verb+statisticalForwardProblem+; the user is invited to run them and understand their purpose (the codes are well documented and self-explanatory). The examples \verb+validationCycle+ and \verb+validationCycle2+ present a combination of SIP and SFP to solve the same problem; the main difference between them is that the first has the majority of its code in *.h files, with templated routines, whereas the latter has the majority of its code in *.C files.


The executables under \verb+tests+ are 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 \ref{sec:install_Queso_make}.


% 
% The executables under \texttt{test/t02\_sip\_sfp/},  \texttt{test/t03\_sequence/}, \texttt{test/t04\_bimodal/},   \texttt{test/gsl\_tests}, and \texttt{examples/validationCycle2/}, have the majority of their codes in *.C files.
% Thus, it might be easier to understand them than the other executables in  \texttt{examples} and \texttt{test/t01\_valid\_cycle/}, which
% have the majority of their codes in *.h files, with templated routines.
% It should be clear, though, that all executables might be implemented in either *.h or *.C files: it is a matter of how generic you want your application to be.


\subsection{Running QUESO Examples} \label{sc-running-execs}

This section assumes that you have successfully executed steps described in Sections \ref{sec:Pre_Queso} through \ref{sec:Queso_docs} above.
The codes listed in this section are quite self-explanatory and print messages during execution to make clearer which problem they are solving and how. 


The two following subsections illustrate how to run the executables provided under the \verb+examples/statisticalInverseProblem/+ and \verb+examples/statisticalForwardProblem/+. For the remaining three examples, the steps should be analogous, except for \verb+infoTheoryProblem+, which requires QUESO to be compiled with ANN library \cite{ANN}.


Is worth noting presence of an argument passed to the executable in the examples. 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 QUESO classes, and is presented throughout Chapter~\ref{ch-classes}. 

A complete example of an application that uses QUESO to solve a combination of a SIP and a SFP is in presented in Chapter \ref{ch-appl-example}. The chapter presents the mathematical models for both the SIP and SFP , the application code, the options input file and the Makefile to link the code  with QUESO library.


\subsubsection{A Simple Statistical Inverse Problem}\label{sec:executable_sip}

This example it is located at `\verb+examples/statisticalInverseProblem+ and consists of a set  of three files to illustrate the use of QUESO library to solve a simple inverse problem with four parameters.

To run the executable provided, enter the following commands:
\begin{lstlisting}[label={},caption={}]
$ cd $HOME/queso_download/queso-0.45.3/
$ cd examples/statisticalInverseProblem/tests/test_2009_02_03/
$ rm outputData/*
$ ../../src/exStatisticalInverseProblem_gsl sip.inp    #this may take some time (seconds)
$ matlab
   $ sip_plot	           # inside matlab
   # press the left button of the mouse at each picture displayed by 'sip_plot.m', in order to display the next picture
   $ exit	               # inside matlab
$ ls -l outputData/*.png
>>  parameters_samples_plane.png  parameters_PDF.png
\end{lstlisting}

As a result, the user should have created a couple of PNG plots for both marginal posterior PDFs of all four parameters and samples of first two parameters on the plane.

\subsubsection{A Simple Statistical Forward Problem}

This example consists of a set of three files to illustrate the use of QUESO library to solve a simple forward problem and it is located at `\texttt{examples/statisticalForwardProblem/}'. %Some details about the files structure are presented in Section \ref{sec:Examples_sfp}.

To run the executable provided, enter the following commands:
\begin{lstlisting}[label={},caption={}]
$ cd $HOME/queso_download/queso-0.45.3/
$ cd examples/statisticalForwardProblem/tests/test_2009_02_11/
$ rm outputData/*
$ ../../src/exstatisticalForwardProblem_gsl sfp.inp  #this will take some seconds
$ matlab
   $ sfp_plot       # inside matlab
   # press the left button of the mouse at a picture displayed by 'sfp_plot.m', in order to display the next picture
   $ exit           # inside matlab
$ ls -l outputData/*.png
>>  QoI_autocorrelation.png  QoI_CDF.png  QoI_PDF.png  
\end{lstlisting}


In this case, the user should have created a few PNG plots for the QoI kernel density estimation, cumulative distribution function and autocorrelation.


\section{The Installed Directory Structure} \label{sc-installed-dir-structure}

After having successfully executed steps described in \textsection{}\ref{sec:Pre_Queso} through \textsection{}\ref{sec:install_Queso_make}, the QUESO installed directory will contain four subdirectories:
\begin{enumerate}
 \item \verb+bin+: contains the executable \verb+queso_version+, which provides information about the installed library.
 \item \verb+lib+: contains the static and dynamic versions of the library. The full path should be added to the users \verb+LD_LIBRARY_PATH+ environmental variable in order to use QUESO.
 \item \verb+include+: contains the \verb+*.h+ files.
\end{enumerate}


\section{Create your Application with the Installed QUESO} \label{sc-use-queso}

Prepare your environment by either running or saving the following command in your \verb+.cshrc+ file (or \verb+.bashrc+ file depending whether you have a C or a bash shell):

\begin{lstlisting}[label={},caption={}]
setenv LD_LIBRARY_PATH \$LD_LIBRARY_PATH:
       $HOME/LIBRARIES/queso_0_45_3/lib
\end{lstlisting}


Supposing your application code together consists of the files: \linebreak \verb+example_main.C+, \verb+example_qoi.C+,  \verb+example_likelihood.C, example_compute.C+ and respective \verb+.h+ files. Your application code may be linked with QUESO library through a Makefile such as the one displayed as follows:

\begin{lstlisting}[label={},caption={},deletekeywords={export,rm}]
QUESO_DIR = $HOME/LIBRARIES/queso_0_45_3/
BOOST_DIR = $HOME/LIBRARIES/boost_1_37_0/
GSL_DIR = $HOME/LIBRARIES/gsl_1_12/
GRVY_DIR = $HOME/LIBRARIES/grvy_0_31_0

INC_PATHS = \
	-I. \
	-I$(QUESO_DIR)/include \
	-I$(BOOST_DIR)/include/boost_1_37_0 \
	-I$(GSL_DIR)/include \
	-I$(GRVY_DIR)/include 

LIBS = \
	-L$(QUESO_DIR)/lib \
	-lqueso \
	-L$(BOOST_DIR)/lib \
	-lboost_program_options \
	-L$(GSL_DIR)/lib \
	-lgsl \
	-L$(GRVY_DIR)/lib \
	-lgrvy 

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 example_likelihood.o example_qoi.o example_compute.o
	$(CXX) example_main.o example_likelihood.o example_qoi.o \
	       example_compute.o -o example_gsl $(LIBS)

%.o: %.C
	$(CXX) $(INC_PATHS) $(CXXFLAGS) $<
\end{lstlisting}
% 
% More documentation is provided in Chapter \ref{ch-appl-example}.
<commit_msg>[manual]: fix le more typos<commit_after>\chapter{Installation}\label{ch-install}
\thispagestyle{headings}
\markboth{Chapter \ref{ch-install}: Installation}{Chapter \ref{ch-install}: Installation}

%This chapter describes how to install QUESO, test it and use it to create your application.

  
This chapter covers the basic steps that a user will need follow when beginning to use QUESO: 
how to obtain, configure, 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 his/her 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 Page\footnote{\Quesoweb}.



        
\section{Pre-QUESO Installation Steps}\label{sec:Pre_Queso}


Herein, suppose you want to install QUESO and its dependencies on the following directory:
\begin{lstlisting}
$HOME/LIBRARIES/
\end{lstlisting}
%
so that you will not need root 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  the QUESO Library: obtain and install \Queso{} dependencies, and to define a number of environmental variables. These steps are discussed bellow.


\subsection{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:
\begin{enumerate}%{itemize}

  \item \textbf{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~\cite{STL}. % The STL is a generic library, meaning that its components are heavily parameterized: almost every component in the STL is a template. You should make sure that you understand how templates work in C++ before you use the STL.

  \item \textbf{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. E.g. GSL 1.12~\cite{Gsl}. %There are over 1000 functions in total with an extensive test suite.

  \item \textbf{Boost}: Boost provides free peer-reviewed portable C++ source libraries, which can be used with the C++ Standard Library. E.g. Boost 1.37.0~\cite{Boost}.

  \item \textbf{MPI}: The Message Passing Interface is a standard for parallel programming using the message passing model. E.g. Open MPI~\cite{Openmpi} or MPICH~\cite{Mpich}. \Queso{} requires MPI during the compilation step; however, you may run it in serial mode (e.g. in one single processor) if you wish. 

  \item \textbf{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. E.g. GRVY 0.31.0 ~\cite{grvy}.

\end{enumerate}%{itemize}

\Queso{} also works with the following optional libraries:

\begin{enumerate}%{itemize}
\item \textbf{HDF5}: The Hierarchical Data Format 5 is a technology suite that makes possible the management of extremely large and complex data collections. E.g. e.g. HDF5  5-1.8.8~\cite{HDF5}.

\item \textbf{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~\cite{GLPK}. 
% 
% \item \textbf{PETSc}: The Portable, Extensible Toolkit for Scientific Computation (PETSc) is a suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations, including parallel linear and nonlinear solvers~\cite{Petsc}.
% 
% \item \textbf{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.  E.g. Trilinos 9.0.2~\cite{Trilinos}.
\end{enumerate}%{itemize}

             

% \paragraph*{Note:}
% The basic steps to install GRYV are: 
% \begin{verbatim}
% $ ./configure --prefix=$HOME/LIBRARIES/grvy_0_31_0 \
%   --with-boost=$HOME/LIBRARIES/boost_1_37_0
% $ make 
% $ make install
% \end{verbatim}
% %
% The directory \texttt{$HOME/LIBRARIES/grvy\_0\_31\_0} does not need to exist in advance, since it will be created by the command 'make install' above.



\subsection{Prepare your LINUX Environment}\label{sec:prepare}

% Step one may differ whether your installation will performed in a stand-alone machine or in a network system which comprises Environment Modules\footnote{\url{http://www.modules.sourceforge.net}}~\footnote{\url{http://www.ices.utexas.edu/sysdocs/linux/modules.html}} to provide easy access to software, such as the one employed in ICES.


Before using QUESO, the user must first set a number of environmental variables, and indicate the full path
of the QUESO's dependencies: GSL, Boost and GRVY. 

For example, under the UNIX C shell (csh) a command of the form
%export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/home/kemelli/LIBRARIES/QUESO_0.45.0/lib
\begin{lstlisting}
$ setenv LD_LIBRARY_PATH \$LD_LIBRARY_PATH:
		$HOME/LIBRARIES/gsl_1_12/lib:
		$HOME/LIBRARIES/boost_1_37_0/lib:
		$HOME/LIBRARIES/grvy_0_31_0/lib
\end{lstlisting}
can be placed in the user's \verb+.cshrc+ or other startup file. 
Under UNIX bash shell, {\tt.cshrc} is replaced with a startup file such as {\tt.bashrc}, and the command {\tt setenv} with \texttt{export}.

In addition, the user must set the following environmental
variables:
\begin{lstlisting}
$ setenv CC gcc
$ setenv CXX g++
$ setenv MPICC mpicc
$ setenv MPICXX mpic++
$ setenv F77 f77
$ setenv FC gfortran 
\end{lstlisting}

% \footnote{Under UNIX bash shell, {\tt.cshrc} shall be replaced by startup file such as {\tt.bashrc}, and the command {\tt setenv} with \texttt{export}.}


\section{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 \Quesoweb{}.

Supposing you have downloaded the file `\verb+queso-0.45.3.tar.gz+' into \texttt{\$HOME/queso\_download/}, follow the commands to expand the tarball:
\begin{lstlisting}
$ cd $HOME/queso_download/
$ gunzip < queso-0.45.3.tar.gz  | tar xf -
$ cd $HOME/queso_download/queso-0.45.3   	#enter the directory 
\end{lstlisting}

Naturally, for versions of \Queso{} other than 0.45.3, the file names in the above commands must be adjusted.


\subsection{Recommended Build Directory Structure}\label{sec:Queso_tree}

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 \ref{sec:summary}).
To start, we defined three useful terms:

\begin{description}
 \item [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.%, or by checking out a copy of the \Queso{} repository.
 \item [Build tree] %- The directory structure where object and library files %, as well as executables 
%are located.
- 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 \texttt{configure, make}, etc. to build and install \Queso{}. 
 \item [Installation tree] - The tree where \Queso{} is installed. It is typically the \texttt{prefix} argument given to \Queso{}'s configure script; it is the directory from which you run installed \Queso{} executables.
\end{description}

Although it is possible to run \verb+./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~\cite{Trilinos}. 
%For example, both serial and parallel libraries can be built. This approach also eliminates problems with configuring in a `dirty' directory (one that has already been configured in).


\section{Configure QUESO Building Environment}\label{sec:Queso_configure}

\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:
\begin{lstlisting}
$ ./configure  --help  
\end{lstlisting}
%
from the top level of the source tree. 

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 a package that is not currently built by default, HDF5, append \texttt{--with-hdf5=DIR}, where \texttt{DIR} is the root directory of HDF5 installation,  to the configure invocation line. 

\Queso{} default installation location is `\texttt{/usr/local}', which requires superuser privileges. To use a path
        other than `\texttt{/usr/local}', specify the path with the `\texttt{--prefix=PATH}' switch. For instance, `\verb+--prefix=$HOME/LIBRARIES+'.



The basic steps to configure QUESO using GRVY, Boost and GSL for installation at `\verb+$HOME/LIBRARIES/queso_0_45_3+' are:
\begin{lstlisting}
$ ./configure --prefix=$HOME/LIBRARIES/queso_0_45_3 \
  --with-boost=$HOME/LIBRARIES/boost_1_37_0 \
  --with-gsl-prefix=$HOME/LIBRARIES/gsl_1_12 \
  --with-gvry=$HOME/LIBRARIES/grvy_0_31_0
\end{lstlisting}

Note: the directory `\verb+$HOME/LIBRARIES/queso_0_45_3+' does not need to exist in advance, since it will be created by the command \verb+make install+ described in Section \ref{sec:install_Queso_make}.


\section{Compile, Check and Install \Queso{}}\label{sec:install_Queso_make}
%
In order to build, check and install the library, the user must enter the following three commands sequentially:
\begin{lstlisting}
$ make
$ make check       # optional
$ make install 
\end{lstlisting}

Here, \verb+make+ builds the library, confidence tests, and programs;  \verb+ make check+ conducts various test suites in order to check the compiled source; and \verb+make install+ installs \Queso{} library, include files, and support programs

The files are installed under the installation tree (refer to Section \ref{sec:Queso_tree}), e.g. the directory specified with `\texttt{--prefix=DIR}' in Section \ref{sec:Queso_configure}. The directory, if not existing, will be created automatically.%, provided the mkdir command supports the -p  option.

% The library, confidence tests, and programs can be built by entering:
% \begin{lstlisting}
% $ make
% \end{lstlisting}
% 
% \Queso{} comes with various test suites in order to check the compiled source. To run the tests, do:
% \begin{lstlisting}
% $ make check
% \end{lstlisting}
% 
% Finally, the \Queso{} library, include files, and support programs can be installed by (more comments in Section \ref{sc-installed-dir-structure}):
% \begin{lstlisting}
% $ make install 
% \end{lstlisting}
% 
% The files are installed under the installation tree (refer to Section \ref{sec:Queso_tree}), e.g. the directory specified with `\texttt{--prefix=DIR}' in Section \ref{sec:Queso_configure}. The directory, if not existing, will be created automatically.%, provided the mkdir command supports the -p  option.
% 

%\subsection{Checking the compiled source} \label{sc-checks}

By running \texttt{make check}, several printouts appear in the screen and you should see messages such as:
\begin{lstlisting}
--------------------------------------------------------------------
(rtest): PASSED: Test 1 (TGA Validation Cycle)
--------------------------------------------------------------------
\end{lstlisting}

The last four tests printed in  the screen are tests under your QUESO build tree, i.e., they are located at the  directory \verb+$HOME/queso_download/queso-0.45.3/test+ (see Section \ref{sc-source-dir-structure} for the complete list of the directories under QUESO build tree).      %\texttt{test/t01\_valid\_cycle/}, \linebreak \texttt{test/t02\_sip\_sfp/}, \texttt{test/t03\_sequence/}, and  \texttt{test/t04\_bimodal/}. 
These tests are 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.



\section{\Queso{} Developer's Documentation}\label{sec:Queso_docs}



\Queso{} code documentation is written using Doxygen~\cite{Doxygen}, and can be regenerated by typing in the build tree:
\begin{lstlisting}
$ make docs
\end{lstlisting}

A directory named \verb+docs+ will be created in \verb+$HOME/queso_download/queso-0.45.3+ (the build tree; your current path) and you may access the code documentation in two different ways:
\begin{enumerate}
 \item HyperText Markup Language (HTML)  format: \verb+docs/html/index.html+, and the browser of your choice can be used to walk through the HTML documentation.
% \begin{verbatim}
% $ cd docs/html
% $ firefox 
% \end{verbatim}

\item Portable Document Format (PDF) format: \verb+docs/queso.pdf+, which can be accessed thought any PDF viewer.
% \begin{verbatim}
% $ cd docs
% $ acroread queso.pdf
% \end{verbatim}
\end{enumerate}
% 
% Obviously the two steps above assume you have \verb+firefox+ and \verb+acroread+ installed in your computer.

\section{Summary of Installation Steps}\label{sec:summary}


Supposing you have downloaded the file `queso-0.45.3.tar.gz' into \texttt{\$HOME/queso\_download/}.
%
The basic steps to configure QUESO using GRVY, Boost and GSL for installation at \linebreak 
`\verb+$HOME/LIBRARIES/queso_0_45_3+'  are:

\begin{lstlisting}
$ cd $HOME/queso_download/               #enter source dir
$ gunzip < queso-0.45.3.tar.gz  | tar xf -
$ cd $HOME/queso_download/queso-0.45.3   #enter the build dir
$ ./configure --prefix=$HOME/LIBRARIES/queso_0_45_3 \
  --with-boost=$HOME/LIBRARIES/boost_1_37_0 \
  --with-gsl-prefix=$HOME/LIBRARIES/gsl_1_12 \
  --with-gvry=$HOME/LIBRARIES/grvy_0_31_0 
$ make 
$ make check
$ make install 
$ make docs
$ ls $HOME/LIBRARIES/queso_0_45_3 #listing QUESO installation dir
>>  bin  include  lib  examples
\end{lstlisting}

% 
% \paragraph*{Note:} According to  Section \ref{sec:Queso_tree}, \texttt{\$HOME/queso\_download/} is the source tree, \\ \verb+$HOME/queso_download/queso-0.45.3+ is the build tree, and \newline
% \verb+$HOME/LIBRARIES/queso_0_45_3+ is the installation tree.
% 


\section{The Build Directory Structure} \label{sc-source-dir-structure}

The QUESO build directory contains three main directories, \texttt{src}, \texttt{examples} and \texttt{test}. They are listed below and more specific
information about them can be obtained with the Developer's documentation from Section \ref{sec:Queso_docs} above:
\begin{enumerate}
\item \texttt{src}, with five subdirectories:
\begin{enumerate}
\item \texttt{src/basic/}: with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/core/}:  with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/misc/}:  with \texttt{inc} and \texttt{src} subdirectories,
\item \texttt{src/stats/}: with \texttt{inc} and \texttt{src} subdirectories, and
\item \texttt{src/contrib/}.
\end{enumerate}

\item \texttt{examples}, with five subdirectories:
\begin{enumerate}
\item \texttt{examples/statisticalForwardProblem/},
\item \texttt{examples/statisticalInverseProblem/},
\item \texttt{examples/validationCycle/}, 
\item \texttt{examples/validationCycle2/},
\item \texttt{examples/infoTheoryProblem/}.
\end{enumerate}

\item  \texttt{test}, with five subdirectories:
\begin{enumerate}
\item \texttt{test/t01\_valid\_cycle/},
\item \texttt{test/t02\_sip\_sfp/},
\item \texttt{test/t03\_sequence/}, 
\item \texttt{test/t04\_bimodal/}, and
\item \texttt{test/gsl\_tests}.
\end{enumerate}

\end{enumerate}

The \verb+src+ directory contains the library itself; thus it has an entire chapter dedicated to its description (see Chapter \ref{ch-classes}).

The executables under \verb+examples+ are examples of application codes that use QUESO to solve either SIP or SFP, or both. The following section presents the steps for running two of them, \verb+statisticalInverseProblem+ and \verb+statisticalForwardProblem+; the user is invited to run them and understand their purpose (the codes are well documented and self-explanatory). The examples \verb+validationCycle+ and \verb+validationCycle2+ present a combination of SIP and SFP to solve the same problem; the main difference between them is that the first has the majority of its code in *.h files, with templated routines, whereas the latter has the majority of its code in *.C files.


The executables under \verb+tests+ are 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 \ref{sec:install_Queso_make}.


% 
% The executables under \texttt{test/t02\_sip\_sfp/},  \texttt{test/t03\_sequence/}, \texttt{test/t04\_bimodal/},   \texttt{test/gsl\_tests}, and \texttt{examples/validationCycle2/}, have the majority of their codes in *.C files.
% Thus, it might be easier to understand them than the other executables in  \texttt{examples} and \texttt{test/t01\_valid\_cycle/}, which
% have the majority of their codes in *.h files, with templated routines.
% It should be clear, though, that all executables might be implemented in either *.h or *.C files: it is a matter of how generic you want your application to be.


\subsection{Running QUESO Examples} \label{sc-running-execs}

This section assumes that you have successfully executed steps described in Sections \ref{sec:Pre_Queso} through \ref{sec:Queso_docs} above.
The codes listed in this section are quite self-explanatory and print messages during execution to make clearer which problem they are solving and how. 


The two following subsections illustrate how to run the executables provided under the \verb+examples/statisticalInverseProblem/+ and \verb+examples/statisticalForwardProblem/+. For the remaining three examples, the steps should be analogous, except for \verb+infoTheoryProblem+, which requires QUESO to be compiled with ANN library \cite{ANN}.


Is worth noting presence of an argument passed to the executable in the examples. 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 QUESO classes, and is presented throughout Chapter~\ref{ch-classes}. 

A complete example of an application that uses QUESO to solve a combination of a SIP and a SFP is in presented in Chapter \ref{ch-appl-example}. The chapter presents the mathematical models for both the SIP and SFP , the application code, the options input file and the Makefile to link the code  with QUESO library.


\subsubsection{A Simple Statistical Inverse Problem}\label{sec:executable_sip}

This example it is located at `\verb+examples/statisticalInverseProblem+ and consists of a set  of three files to illustrate the use of QUESO library to solve a simple inverse problem with four parameters.

To run the executable provided, enter the following commands:
\begin{lstlisting}[label={},caption={}]
$ cd $HOME/queso_download/queso-0.45.3/
$ cd examples/statisticalInverseProblem/tests/test_2009_02_03/
$ rm outputData/*
$ ../../src/exStatisticalInverseProblem_gsl sip.inp    #this may take some time (seconds)
$ matlab
   $ sip_plot	           # inside matlab
   # press the left button of the mouse at each picture displayed by 'sip_plot.m', in order to display the next picture
   $ exit	               # inside matlab
$ ls -l outputData/*.png
>>  parameters_samples_plane.png  parameters_PDF.png
\end{lstlisting}

As a result, the user should have created a couple of PNG plots for both marginal posterior PDFs of all four parameters and samples of first two parameters on the plane.

\subsubsection{A Simple Statistical Forward Problem}

This example consists of a set of three files to illustrate the use of QUESO library to solve a simple forward problem and it is located at `\texttt{examples/statisticalForwardProblem/}'. %Some details about the files structure are presented in Section \ref{sec:Examples_sfp}.

To run the executable provided, enter the following commands:
\begin{lstlisting}[label={},caption={}]
$ cd $HOME/queso_download/queso-0.45.3/
$ cd examples/statisticalForwardProblem/tests/test_2009_02_11/
$ rm outputData/*
$ ../../src/exstatisticalForwardProblem_gsl sfp.inp  #this will take some seconds
$ matlab
   $ sfp_plot       # inside matlab
   # press the left button of the mouse at a picture displayed by 'sfp_plot.m', in order to display the next picture
   $ exit           # inside matlab
$ ls -l outputData/*.png
>>  QoI_autocorrelation.png  QoI_CDF.png  QoI_PDF.png  
\end{lstlisting}


In this case, the user should have created a few PNG plots for the QoI kernel density estimation, cumulative distribution function and autocorrelation.


\section{The Installed Directory Structure} \label{sc-installed-dir-structure}

After having successfully executed steps described in \textsection{}\ref{sec:Pre_Queso} through \textsection{}\ref{sec:install_Queso_make}, the QUESO installed directory will contain four subdirectories:
\begin{enumerate}
 \item \verb+bin+: contains the executable \verb+queso_version+, which provides information about the installed library.
 \item \verb+lib+: contains the static and dynamic versions of the library. The full path should be added to the users \verb+LD_LIBRARY_PATH+ environmental variable in order to use QUESO.
 \item \verb+include+: contains the \verb+*.h+ files.
\end{enumerate}


\section{Create your Application with the Installed QUESO} \label{sc-use-queso}

Prepare your environment by either running or saving the following command in your \verb+.cshrc+ file (or \verb+.bashrc+ file depending whether you have a C or a bash shell):

\begin{lstlisting}[label={},caption={}]
setenv LD_LIBRARY_PATH \$LD_LIBRARY_PATH:
       $HOME/LIBRARIES/queso_0_45_3/lib
\end{lstlisting}


Supposing your application code together consists of the files: \linebreak \verb+example_main.C+, \verb+example_qoi.C+,  \verb+example_likelihood.C, example_compute.C+ and respective \verb+.h+ files. Your application code may be linked with QUESO library through a Makefile such as the one displayed as follows:

\begin{lstlisting}[label={},caption={},deletekeywords={export,rm}]
QUESO_DIR = $HOME/LIBRARIES/queso_0_45_3/
BOOST_DIR = $HOME/LIBRARIES/boost_1_37_0/
GSL_DIR = $HOME/LIBRARIES/gsl_1_12/
GRVY_DIR = $HOME/LIBRARIES/grvy_0_31_0

INC_PATHS = \
	-I. \
	-I$(QUESO_DIR)/include \
	-I$(BOOST_DIR)/include/boost_1_37_0 \
	-I$(GSL_DIR)/include \
	-I$(GRVY_DIR)/include 

LIBS = \
	-L$(QUESO_DIR)/lib \
	-lqueso \
	-L$(BOOST_DIR)/lib \
	-lboost_program_options \
	-L$(GSL_DIR)/lib \
	-lgsl \
	-L$(GRVY_DIR)/lib \
	-lgrvy 

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 example_likelihood.o example_qoi.o example_compute.o
	$(CXX) example_main.o example_likelihood.o example_qoi.o \
	       example_compute.o -o example_gsl $(LIBS)

%.o: %.C
	$(CXX) $(INC_PATHS) $(CXXFLAGS) $<
\end{lstlisting}
% 
% More documentation is provided in Chapter \ref{ch-appl-example}.

{'fraction_non_alphanumeric': 0.09673664433916027, 'fraction_numerical': 0.009230517889233786, 'mean_word_length': 4.37884446397188, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 32, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4715147', 'n_tokens_mistral': 14994, 'n_tokens_neox': 14221, 'n_words': 5787}