Build a Shared Library

library(uqsa)

This is a short summary of how to make a loadable shared library file for a model intended for use with the simulators in the rgsl package:

	Steps	tl;dr
1	convert SBtab to ODE	biology => math
2	convert the ODE to sources	math => code
3	convert sources to shared library	code => .so

The GSL solvers that rgsl uses will load this .so file (myModel.so).

RPN-derivative calculates derivatives or offloads that work on maxima or yacas, install them if you want to use the --maxima or --yacas options.

Create a Vector Field for ODE solvers

Here we assume that you wrote your own model in SBtab (here we use TSV files). For testing you can also download one of our example models. The SBtabVFGEN package contains a file called sbtab_to_vfgen (it runs via Rscript, R is needed). This has been made only for convenience:

./sbtab_to_vfgen *.tsv

This script loads the SBtabVFGEN package and executes all commands needed to process an SBtab model into an ODE.

Afterwards, the directory should also contain a .vf file as well as an sbml .xml file and a zip file (with essentially the same content as the vf file).

The same thing in R

# be in the right folder, where your tsv files are
stopifnot(require(SBtabVFGEN))
f <- dir(pattern='[.]tsv$') # everything that ends in .tsv
sb <- sbtab_from_tsv(f)     # a list of data.frames
if (sbtab.valid(sb)){
    cl <- sbtab_to_vfgen(sb)
    print(cl) # these are conservation laws found by sbtab_to_vfgen
}

The above code will create a vf file as well as a tar.gz file and a zip file. Dependeing on what you wrote in the SBtab file, these three may contain mathematically valid content that can be processed further.

The vf file can be read and used by the vfgen tool (but we don’t use that).

Make Source Code for your Model

To convert the ordinary differential equations into code for solvers, we need to calculate the appropriate expressions for the jacobian. To do these calculations you should either download the contents of the sh directory in the icpm-kth/RPN-derivative, or clone the entire repository (and optionally make install) as covered in the installation instructions. The short version:

Assuming that .local/bin is in your PATH, this will make a symbolic link to the ode.sh script.

git clone https://github.com/icpm-kth/RPN-derivative && cd RPN-derivative/sh
pushd -n `pwd`
mkdir -p "$HOME/.local/bin" && cd "$HOME/.local/bin"
ln -s "`dirs -0`/ode.sh" ode
popd

[ `echo "$PATH" | grep "$HOME/[.]local/bin"` ] && echo "OK" || echo "put ~/.local/bin in your PATH"

If you only want to try out the script, as a temporary measure, make an alias instead:

git clone https://github.com/icpm-kth/RPN-derivative && cd RPN-derivative/sh
alias ode="`pwd`/sh/ode.sh"

If you did one of those things and have maxima installed:

MODEL="`ls -1 *.vf | head -n 1`"
MODELC="`basename $MODEL .vf`_gvf.c"
MODELSO="`basename $MODEL .vf`.so"
echo "we are trying to turn '$MODEL' into '$MODELSO'"
[ -f "$MODEL" ] && ode -C --maxima "$MODEL" > "$MODELC"
[ -f "$MODELC" ] && gcc -shared -fPIC -O2 -o "$MODELSO" "$MODELC"

Now you have a _gvf.c source file and a shared library .so (unless an error occurred). The shared library is what the ODE solver actually loads to simulate the model. You can read the C source, check that it looks correct and even change what the model does if SBtab was not expressive enough.

Note on sh code

All code in this section is meant to be run in a terminal (emulator) with a POSIX compliant shell (bash, zsh, dash, ash) should all work.

Please be aware that some of the scripts use awk, sed and perl -p (i.e. perl in sed mode), which may differ on different platforms (there is one true awk, GNU gawk, mawk, etc. – there is no consensus on how any of them should behave exactly).

They differ in options they accept and regular expressions they understand. One example is that BSD sed uses [:<:] to mean left word boundary and gawk uses \< for the same thing. In such cases we use perl -p.

Summary

Here you can find code blocks for each storage format. With simplified assumptions on where you downloaded the git repositories.

SBtab as TSV

This is a summary of the code in the previous section:

alias sbtab_to_vfgen='~/SBtabVFGEN/sbtab_to_vfgen'
alias ode='~/RPN-derivative/sh/ode.sh'
sbtab_to_vfgen *.tsv
ode -C myModel.vf > myModel_gvf.c
ode -R myModel.vf > myModel.R
[ -f myModel_gvf.c ] && gcc -shared -fPIC -O2 -o myModel.so myModel_gvf.c

SBtab as XLSX

Here the same procedure applies, but we alias sbtab_to_vfgen rather than copying it this time. Also, this time we use yacas to calculate the derivatives, rather than maxima. We create both C code and R code this time.

alias sbtab_to_vfgen='~/SBtabVFGEN/sbtab_to_vfgen'
alias ode='~/RPN-derivative/sh/ode.sh'
sbtab_to_vfgen myModel.xlsx
ode -C --yacas myModel.vf > myModel_gvf.c
ode -R --yacas myModel.vf > myModel.R
[ -f myModel_gvf.c ] && gcc -shared -fPIC -O2 -o myModel.so myModel_gvf.c

SBtab as ODS

We repeat the same procedure as with XLSX, but the model name is a variable, and the C compiler is whatever target cc links to:

modelName='myModel'
alias sbtab_to_vfgen='~/SBtabVFGEN/sbtab_to_vfgen'
alias ode='~/RPN-derivative/sh/ode.sh'
sbtab_to_vfgen ${modelName}.ods
ode -C --yacas ${modelName}.vf > ${modelName}_gvf.c
ode -R --yacas ${modelName}.vf > ${modelName}.R
[ -f ${modelName}_gvf.c ] && cc -shared -fPIC -O2 -o ${modelName}.so ${modelName}_gvf.c

Comments

Now you should have C sources and a shared library, or error messages about the SBtab content (if the files contain errors).

The simulator can use the shared library directly. But take into account that ${modelName}.so is machine specific and will not work if you copy it onto a completely different kind of machine (it may work if the two are similar enough).

Please take time to open and inspect the C sources and try to spot obvious mistakes.

RPN-derivative

The RPN-derivative package can also work without maxima or yacas, but needs to be compiled for this to work. Do this in the RPN-derivative’s root directory:

make
make test
sudo make install

If you get error messages about pkg-config not being found, install it (you are probably on MAC: brew install pkg-config). If you get error messages about missing directories, make them (mkdir /path/to/missing/directory).