#### Previous topic

User’s Guide and Tutorial

#### Next topic

Monte Carlo Sampling

# Getting Started¶

PUQ works on Linux and MacOSX.

## nanoHUB Workspaces¶

~> which puq
~> use -e puq-2.2.1
~> which puq
/apps/share64/debian7/puq/puq-2.2.1/build-debian7/bin/puq


Type ‘use’ without arguments to see a list of packages. You should use the latest version of PUQ.

## Installing from PyPI¶

PUQ uses distutils, which is the default way of installing python modules. Simply do:

pip install puq


The installer might ask you to install some other packages first. Just use ‘pip’ to install them. For the Mac, we have very successfully used Anaconda, a free Python distribution containing all the required components to install PUQ. https://store.continuum.io/cshop/anaconda/

## Building and Installing from Sources¶

If you are a developer and have a local copy of the sources,

To install in your home directory, use:

python setup.py install --user


To install for all users on Unix/Linux or Mac:

python setup.py build
sudo python setup.py install


To test that everything is set up properly, just try the puq command without any arguments. Correct output should look something like this:

> puq

This program does parameter sweeps for uncertainty
quantification and optimization.

Usage: puq [-q|-v] [start|stop|status|resume|analyze|plot]
Options:
-q                           Quiet.  Useful for scripts.

-k                           Keep temporary directories.

start script[.py] [args]     Start PUQ using script 'script'

status [id]                  Returns the number of jobs remaining in the sweep.

resume [id]                  Resumes execution of sweep 'id'.

analyze [options] [id]       Does post-processing.

plot [options] [id]          Plots output pdf(s) or response surface. Type
'puq plot -h' for options.

json file, csv file, or URI.  Visualize, modify, and save it.

strip                        PUQ keeps all stdout from every job.  This command
removes output lines not containing data and
repacks the HDF5 file, reducing its size.

dump                         Dumps output data in CSV format.


## Requirements¶

### The Control Script¶

To get started, you will need to write a control script. This script is actually a small Python function. Other parameter sweep frameworks usually use text file or XML for this. However by using Python, we can have much more flexibility. You will not have to know much about Python to create a simple control script.

The control script must declare three objects:

1. At least one parameter, which will be swept by the run.
2. A test program which takes the parameter(s) as a command line argument.
3. A host, which right now is either the local host running interactively,
or the PBS batch scheduler, running locally.


These three objects are combined to form a Sweep object which the UQ system will use. Each of the above objects will be explained in detail.

Good examples of control script are found in puq/examples.

### Parameters¶

Parameters represent inputs to our test program. Parameters are values that will be changing in different runs of our test program.

For scaling sweeps or optimization runs, the parameter represents values that can be changed for different runs.

For uncertainty quantification, parameters are random variables which can be discrete or continuous.

A discrete parameter has a finite number of values.

Continuous parameters can be aleatoric or epistemic.

• Aleatoric parameters are variables that contain inherent randomness that cannot be reduced by better data. They are specified by a PDF (Probability Density Function).
• Epistemic parameters are values that are uncertain due to a lack of data or understanding. You may choose to represent this uncertainty about their value as a PDF and treat them as aleatoric. However, there are other ways to model uncertainty of epistemic parameters which will be supported in the future.

Parameters are represented as PDFs. They might be approximated by a standard PDF, such as uniform, or gaussian (normal). Or they can be created from the results of experiments or measurements.