Quick start

This is a guide to get you up and running sensitivity analysis for a simple example as quickly as possible.

---

INSTALL:

To install, download the SPSens compressed file .tgz and unzip from the command line:

tar -zxvf SPSens<versionname>.tgz</versionname>

From here on out, we'll assume that this was unpacked into a directory called SPSens. Open the terminal console and change to this directory

cd SPSens

---

BUILD THE PROBLEM:

For the purposes of the quick start, we'll start with a simple birth-death example. Other examples can be built by changing the "PROB_NAME=" macro when calling make. The birth-death problem is defined in 'SPSens/examples/prob_birthdeath.c'.

To build (serial) simulation program:

make sim PROB_NAME=birthdeath

Build (serial) sensitivity program:

make sens PROB_NAME=birthdeath

If everything went smoothly, then you should see two new files:

examples/birthdeath_sim
examples/birthdeath_sens

---

GENERATING A SINGLE SAMPLE PATH:

It's quite useful to first generate a single trajectory. This is easy with SPSens. Just type the following once you've built the simulation program:

examples/birthdeath_sim -r 1 -t 10 --save-paths --out-name test --no-stats --no-data

If things went well, you should see something similar to the following output:

>>>>> Simulation complete! <<<<<
>>>>> (Elapsed_time = 0.000766) <<<<<

This generated 1 trajectory (-r 1) starting at time t=0 and ending at final time T=10 (-t 10); stored the entire trajectory (--save-paths) to the file "examples/test_sp0.txt" (--out-name simtest); did not compute any statistics (--no-stats) or save data (--no-data) since all that is desired is a single trajectory.
Two output text files will be created after calling this:
'test_path0.txt' and 'test_sim_summary.txt' in your current directory.
'test_path0.txt' should have two columns: the first with the simulation time, the second with the population of the single species at that time.
'test_sim_summary.txt' contains some information about the run.

---

RUNNING YOUR FIRST SENSITIVITY ANALYSIS:
Suppose you would like to compute the sensitivity of the expected value of the species population at time T=10 with respect to both system parameters.

We will compute this first using an efficient finite difference method, the Common Reaction Path (CRP) method (--sens-alg 3) with perturbation sizes 1% of the nominal parameter values (--fd-size 0.1 0.005), generating 1000 samples (-r 1000) to get accurate statistics, by typing the following command:

examples/birthdeath_sens -r 1000 -t 10 --out-name testCRP --sens-alg 3 --fd-size 0.1 0.005

If run successfully, should return a message similar to the following:

Using CRP finite difference algorithm
>>>>> Sensitivity Analysis Complete! <<<<<
>>>>> (Elapsed_time = 0.039009) <<<<<

Four output files will be created in your current directory:

• 'testCRP_sens_data.txt' : The data containing the sensitivity sampled from each of the -r 1000 runs. The first column is the sensitivity with respect to the first parameter (birth rate), and the second column is the sensitivity with respect to the second parameter (death rate). (To suppress, add the following when calling: --no-data)

• 'testCRP_sens_mean.txt' : The mean estimate of the parameter sensitivities at the times specified. The first column is the time, the second column is the sensitivity with respect to c1, and the third column is the sensitivity with respect to c2. (To suppress, add the following when calling: --no-stats)

• 'testCRP_sens_variance.txt' : The variance of the parameter sensitivities at the times specified. Note that the standard error of the mean estimate is the square root of the variance divided by the square root of the number of samples. The first column is the time, the second column is the sensitivity variance with respect to c1, and the third column is the sensitivity variance with respect to c2. (To suppress, add the following when calling: --no-stats)

• 'testCRP_sens_summary.txt' : a summary of some relevant settings used in the estimation. (To suppress, add the following when calling: --no-summary)

Next, you can compare the CRP estimates with estimates using other methods. Compute the sensitivities using the Girsanov likelihood ratio method (--sens-alg 2), the Regularized pathwise derivative method with window half-width of 0.5 (--sens-alg 1 --rpd-size 0.5), and the coupled finite difference method with perturbation sizes 0.01*the nominal values (--sens-alg 4 --fd-size 0.1 0.005), respectively, using the following commands:

examples/birthdeath_sens -r 1000 -t 10 --out-name testGLR --sens-alg 2
examples/birthdeath_sens -r 1000 -t 10 --out-name testRPD --sens-alg 1 --rpd-size 0.5
examples/birthdeath_sens -r 1000 -t 10 --out-name testCFD --sens-alg 4 --fd-size 0.1 0.005

---

RUNNING AN ENSEMBLE OF SIMULATIONS:

To estimate the expected value at time T=10, you can simulate the system a large number of times (here we'll use 1000) and take the Monte Carlo average. This is done using the following command:

examples/birthdeath_sim -r 1000 -t 10 --out-name test --no-data --no-summary

The option (--no-data) suppresses printing out the individual data points from each simulation, but if this was omitted an additional file called 'test_sim_data.txt' would have been created. The option --no-summary suppresses printing a summary of the settings used.

---

PARALLEL BUILDS:

To run this in parallel using MPI, make the parallel sensitivity analysis and simulation programs, respectively, using the following commands:

make sens_par PROB_NAME=birthdeath
make sim_par PROB_NAME=birthdeath

To estimate the expected value from 1000 samples of the system using 4 parallel nodes, do the following:

mpirun -np 4 examples/birthdeath_simpar -r 1000 -t 10 --out-name testpar

mpirun -np 4 examples/birthdeath_senspar -r 1000 -t 10 --out-name testpar --sens-alg 3 --fd-size 0.1 0.005

---

QUICK TIPS:

If you want to see possible options for running the program, call the executable program without any arguments.