sa
==

**sa** is a sensitivity analysis toolkit written in C.

Requirements
------------

- C99 compiler (tested with clang and gcc)
- `gsl` (tested with v2.5)
- `gnuplot` for plots
- `awk` for rescaling (any, but `mawk` is the best)

Tools
-----

- `./sa-plot`:
  gnuplot script plotting a 2D grid of points (expects to be piped to a PNG
  file)
- `./sa-rescale`:
  awk script for rescaling columns from `[0,1]` interval to any other uniform
  region
- `./sa-sample-random N D`:
  N points from uniform PRNG, reshaped to N by D matrix
- `./sa-sample-sobol N D`:
  N points from the Sobol' sequence in D dimensions
- `./sa-sample-saltelli N D`:
  N points from the Saltelli sapling in D dimensions (`(N+2)*d` entries); it
  generates 2 Sobol' sequences, A and B, sub-samples them into AB, and
  concatenates vertically, as per saltelli2010
- `./sa-sample-halton N D`:
  N points from D-dimensional Halton sequence
- `./sa-sample-niederreiter N D`:
  N points from D-dimensional Niederreiter sequence
- `./sa-sample-recurrent N D`:
  generates N points from a D-dimensional Kronecker recurrence relation with
  seed 0.5 and precision 10 (implementation based on Matrin Roberts)

A simple `Dockerfile` is included.


Usage
-----

To generate 20 random points in a 4D space using a PRNG seeded with seed 10 (if
GSL_RNG_SEED is not defined, it is 0 by default):

	GSL_RNG_SEED=10 ./sa-sample-random 20 4

To generate 10 points of a 2D Sobol' sequence, and rescale x-axis to `[-1,1]`:

	./sa-sample-sobol 10 2 | ./sa-rescale

Note that `sa-rescale` needs to be edited to include the line in the `NR==1`
block:

	x[1,1] = -1; x[1,2] = 1;

To reproduce Saltelli sampling example from Wikipedia:

	./sa-sample-saltelli 4 3

To run sensitivity analysis on Ishigami function with default a & b values,
using 1000 points in Saltelli sequence (remember to change sa-rescale values to
[-pi, pi] ranges):

	./sa-sample-saltelli 1000 3 |
		./sa-rescale |
		./sa-eval-ishigami 7 0.05 |
		./sa-analyse-saltelli 1000 3

To reproduce Figure 1. from "Unreasonable Effectiveness of Quasirandom Sequences":

	./sa-sample-recurrent    620 2 | ./sa-plot > recurrent.png
	./sa-sample-halton       620 2 | ./sa-plot > halton.png
	./sa-sample-niederreiter 620 2 | ./sa-plot > niederreiter.png
	./sa-sample-sobol        620 2 | ./sa-plot > sobol.png
	./sa-sample-random       620 2 | ./sa-plot > random.png

Note that the Kronecker sequence needs different recurrence parameters, and is
not implemented for now.


References
----------

- https://en.wikipedia.org/wiki/Variance-based_sensitivity_analysis
- http://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/
- https://salib.github.io/SALib/
- https://www.gnu.org/software/gsl/doc/html/