py4sci

Table Of Contents

Previous topic

User’s Guide and Tutorial

Next topic

Monte Carlo Sampling

This Page

Getting Started

PUQ works on Linux and MacOSX.

nanoHUB Workspaces

If you have access to a nanoHUB workspace, PUQ is already installed. If ‘puq’ is not in your path, use the ‘use’ command to load it.

~> 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

For more information: https://pypi.python.org/pypi/puq/ and https://github.com/martin-hunt/puq


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.

-v                           Verbose. Show even more information.

-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.

extend [id]                  Extend a sweep by adding additional jobs.

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

read                         Read a parameter or PDF from a python input script,
                             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.

See also

Parameters

Test Program

The test program is a function (typically a simulation) that takes inputs and generates outputs. PUQ requires that the test program take numerical parameters on the command line. If you have a test program that reads parameters some other way, it may be necessary to create a wrapper script for it.

Host

Jobs can be run sequentially or in parallel on an interactive scheduler. This would be the typical desktop or workstation. PBS, TORQUE, and HUBzero submit are also supported for use in cluster environments.