Forward UQ

The scripts in apps/uqpc/ propagate input parameter uncertainties to model outputs via Polynomial Chaos (PC) expansions. As the most common use-case, they construct a PC surrogate for a multi-output computational model treated as a black-box simulation code, and then perform global sensitivity analysis of the outputs with respect to the input parameters.

The folder contains:

uq_pc.py — the main driver script.
plot.py — post-processing visualisations.
model.x — an example black-box model (awk script).
workflow_uqpc.x — an example end-to-end workflow shell script.

Workflow overview

A typical UQPC session follows five steps:

Setup inputs — Define uncertain input parameters by specifying marginal PCs, a parameter domain, or samples. Use pc_prep.py (see Polynomial Chaos) to produce the input PC coefficient file pcf.txt.
Generate samples — Draw training (and optionally testing) realisations from the input PC. In online regimes this is done automatically; in offline mode the user supplies ptrain.txt, qtrain.txt, ytrain.txt (and test counterparts) beforehand.
Evaluate the model — Either call a built-in benchmark (online_example), execute a user-supplied black-box executable model.x (online_bb), or load pre-computed outputs (offline).
Build the PC surrogate — Fit an output PC expansion via analytical projection (anl), least-squares (lsq), or Bayesian Compressed Sensing (bcs), and compute Sobol sensitivity indices.
Post-process — Visualise results with plot.py.

The example workflow workflow_uqpc.x demonstrates all five steps with commented alternatives.

uq_pc.py

Main driver for the forward-UQ pipeline.

uq_pc.py supports three run regimes:

online_example — uses a built-in benchmark function (Ishigami by default) defined inside the script.
online_bb — calls a user-supplied black-box executable model.x that maps an input file to an output file.
offline — reads pre-computed training (and testing) data from ptrain.txt, qtrain.txt, ytrain.txt (and their test counterparts).

The script constructs input PC representations, generates or reads training/testing samples, fits a PC surrogate, computes Sobol sensitivity indices, and bundles everything into results.pk.

Outputs:

results.pk — Pickled dictionary with the surrogate (pcrv), training/testing data, and sensitivity indices.
ptrain.txt, qtrain.txt, ytrain.txt — Training data (parameters, PC germs, model outputs).
ptest.txt, qtest.txt, ytest.txt — Testing data (when -v > 0).

Examples:

# Built-in Ishigami example, analytical projection, 7-pt quadrature
python uq_pc.py -r online_example -t 3 -n 7 -m anl

# Black-box model, random sampling, BCS fit
python uq_pc.py -r online_bb -c pcf.txt -x LU -d 3 -o 1 -m bcs -s rand -n 100 -v 30 -t 4

# Offline data, least-squares fit
python uq_pc.py -r offline -c pcf.txt -x HG -d 3 -o 1 -m lsq -n 111 -v 33 -t 3

Arguments:

Flag	Default	Description
`-r, --regime`	`online_example`	Run regime: `online_example`, `online_bb`, or `offline`.
`-p, --pdom`	`None`	Parameter domain file (two columns: lower, upper bound per row). If given, `-o` and `-x` are overwritten to `1` and `LU`.
`-c, --pcfile`	`None`	Input PC coefficient file (e.g. `pcf.txt` from `pc_prep.py`).
`-d, --pcdim`	`None`	Stochastic dimensionality of the input PC. Required with `-c`.
`-x, --pctype`	`LU`	PC basis type (`LU`, `HG`, `LU_N`, `LG`, `JB`, `SW`).
`-o, --pcord`	`1`	Input PC order.
`-m, --method`	`anl`	Fitting method: `anl` (analytical/projection), `lsq` (least-squares), or `bcs` (Bayesian Compressed Sensing).
`-s, --sampl`	`quad`	Sampling method: `quad` (quadrature) or `rand` (random).
`-n, --nqd`	`7`	Number of quadrature points per dimension (`quad`) or total number of training points (`rand`).
`-v, --ntst`	`0`	Number of testing points (0 = no testing).
`-t, --outord`	`3`	Output PC order.
`-e, --tol`	`1e-3`	Tolerance for BCS (only used when `-m bcs`).
`-z, --seed`	`None`	Random seed for reproducibility.

Note

Exactly one of -p (domain file), -c (PC coefficient file), or -d (dimensionality) should be provided. If none are given, a 2-dimensional default is used. Providing both -p and -c, or both -p and -d, is an error.

model.x

An example black-box model supplied as a Bash/AWK script.

It reads an input matrix file and writes an output matrix file:

./model.x ptrain.txt ytrain.txt

The default implementation maps 3 inputs to 5 outputs. Users should replace this with their own simulation code.

plot.py

Visualise results stored in results.pk after surrogate construction.

Parameter and output names are read from pnames.txt and outnames.txt when present; otherwise generic names are used.

Examples:

python plot.py sens main            # main Sobol sensitivity bar chart
python plot.py sens total           # total Sobol sensitivity bar chart
python plot.py dm training testing  # model-vs-surrogate parity plots
python plot.py fit training         # per-sample fit overlays
python plot.py 1d training          # 1-D surrogate slices with training data
python plot.py 2d                   # 2-D surrogate contour plots
python plot.py pdf                  # output PDFs
python plot.py joy                  # joy (ridge-line) plots
python plot.py jsens                # circular joint-sensitivity plot
python plot.py sensmat main         # sensitivity heat-map matrix

Sub-commands:

Command	Description
`sens`	Bar chart of Sobol sensitivity indices. Takes a second argument `main` or `total`.
`jsens`	Circular joint-sensitivity plots for all outputs and their average.
`sensmat`	Sensitivity matrix heatmap for the most important inputs. Takes `main` or `total`.
`dm`	Model-vs-surrogate parity (diagonal) plots for each output. Takes `training`, `testing`, or both.
`fit`	Per-sample model-vs-surrogate overlays. Takes `training`, `testing`, or both.
`1d`	1-D surrogate slices along each input dimension (remaining parameters at nominal or integrated out). Optionally overlay `training` and/or `testing` data.
`2d`	2-D surrogate contour plots for all input pairs and outputs.
`pdf`	Probability density plots of the surrogate output distribution.
`joy`	Joy (ridge-line) plots of the surrogate output distribution.

workflow_uqpc.x

An annotated Bash script that demonstrates the complete workflow.

It shows four alternative ways to define uncertain inputs (normal marginals, uniform marginals, multivariate normal, or samples), then walks through sampling, model evaluation, surrogate fitting, data visualisation, and post-processing. Users can adapt this script as a template for their own problems.

Run it from the apps/uqpc/ directory:

bash workflow_uqpc.x