SPSens : Stochastic parameter sensitivity analysis for chemical networks
Release : SPSensbeta.3.4
Date : 19 Oct 2012
Author : Patrick W. Sheppard
For detailed instructions, view the UserGuide provided with the package
and also available on the project webpage.
-----------------------------------
1. Licensing
-----------------------------------
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-----------------------------------
2. SUPPORTED PLATFORMS
-----------------------------------
Linux : tested
Mac OS X: tested on 10.6.8
Windows: No native support yet; must use cigwyn or MinGW linux-like
environments
-----------------------------------
3. INSTALLATION
-----------------------------------
Install by unzipping the archive into the desired
directory. This can be done from the command line as follows:
tar -xvzf SPSensbeta.3.4.tgz
We will assume the unpacked directory is named:
'path/SPSens'
-----------------------------------
4. TESTING
-----------------------------------
4.1 COMMAND LINE
-----------------------------------
Some perl scripts are included in the main directory.
To compile and run all the serial programs, type:
perl test_serial.pl
To compile and run all the parallel programs, type:
perl test_parallel.pl
To compile and run a single example included in the 'SPSens/examples'
directory, type:
perl Build_examples.pl
4.2 MATLAB
-----------------------------------
To test the matlab interface, from within Matlab, type the following:
>> cd path/SPSens/mex/
>> example_spsens_mex
OR
>> example_spsens_mex_interactive
-----------------------------------
5. TO BUILD A PROBLEM MANUALLY:
-----------------------------------
As a simple example consider the birth-death reactions system,
(0-> X, rate c1, X-> 0, rate c2*x(t)),
the problem is defined in 'path/SPSens/prob_birthdeath.c'.
5.1 BUILD USING PERL SCRIPT
-----------------------------------
You can use the perl script 'Build_problem.pl' to specify a problem
file to build and run. From the main directory, type:
perl Build_problem.pl
and you will see some messages and then a prompt asking you for the file:
>> examples/prob_birthdeath.c
Next, when prompted tell the script what to name the problem
(birthdeath), where to build the programs, whether to build simulation
and/or sensitivity programs, whether to build serial or parallel
versions, and whether to run the programs. See UserGuide for more
details.
5.2 BUILD USING MAKE
-----------------------------------
To make the executable for sensitivity analysis for this example, go to
SPSens directory and make:
cd SPSens
make sens PROB_NAME=birthdeath
If it compiles correctly, you should now see the following file:
'SPSens/examples/birthdeath_sens'
Call it with no arguments to get help:
examples/birthdeath_sens
To run your first sensitivity analysis, type:
examples/birthdeath_sens -r 100 -t 10 --sens-alg 3 --out-name test
'-t 10' : tells it to compute sensitivities at time 10 (if you want more
times type e.g. '-t 2 4 6 8 10' or specify '-i #' and it will return #
intervals between 0 and 10)
'-r 100' : tells it to compute 100 samples
'--sens-alg 3' : tells it to use the CRP sensitivity algorithm (run it
without arguments to see the other options)
--out-name test : tells it to return all outputs beginning with
the name "test" (if this is omitted, it will automatically generate
files of the form "result_sens_<*>.txt")
After it's run, it should return 5 files in the directory where you
called it:
'test_sens_data.txt' - Each row is a sample from 1 run; first column
is sensitivity wrt c1, second column sensitivity wrt c2
'test_sens_summary.txt' - a summary of the run that might be useful
'test_sens_mean.txt' - first column: time, then means of the estimate
wrt parameter c1, then wrt parameter c2
'test_sens_variance.txt' - first column: time, then variances of
the estimates same order
'test_sens_confint.txt' - first column: time, then apprximate 95%
confidence intervals of the estimates in the same order
Suppose instead only the sensitivity with respect to the death rate
(second parameter) is desired, can call instead with, and that you want
to use a perturbation of size 1% of the nominal parameter value. To do
this, use the following command:
examples/birthdeath_sens -r 100 -t 10 --sens-alg 3\
--out-name test --sens-params 1 --fd-size 0.01
If you want to use it for your own problem, it is recommended to modify
one of the problems in 'SPSens/examples/' and to rename it as desired.
Make sure you correctly tell it how many sensitivity parameters and
which output to compute as specified before. An extensive example
showing how to specify the problem is included in the UserGuide.
-----------------------------------
6. Additional information
-----------------------------------
See the Wiki on sourceforge.net/projects/spsens/ or the UserGuide
included with this distribution for more instructions.
------------------------------------
7. Feedback and bug reporting
------------------------------------
Send any comments, questions, or bugs to StochasticSensitivity@gmail.com.
