RoadRunner is package for loading, JIT compilation, simulation and analysis of SBML systems biology models.
RoadRunner 1.0
Up to date documentation can be found on http://libroadrunner.org/ Also the static documentation home page provides an introduction.
libRoadRunner is free and open source. Licensing and Distribution Terms can be found in the LICENCE.txt file in the root directory of the distribution.
Copyright (C) 2012-2013 University of Washington, Seattle, WA, USA
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0.html
The libRoadRunner package uses two fundametal objects e.g. rr of class RoadRunner and e.g. rr.model of class ExecutableModel.
The Python API is a very clean simple interface that uses all native Python objects. All the returned types are structured Numpy arrays.
Transcript from an Python session to demonstrate libRoadRunner use on this interactive Python console.
Import roardrunner and numpy:
import roadrunner
import roadrunner.testing
import numpy as n
import numpy.linalg as lin
Load an SBML model:
rr = roadrunner.RoadRunner()
rr.load(roadrunner.testing.get_data('Test_1.xml'))
True
Get the model, the model object has all the accessors sbml elements, names, values:
m = rr.getModel()
Use the built in RR function to get the Jacobian, notice this is returned as a native numpy matrix, and display it:
jac = rr.getFullJacobian()
jac
array([[-0.2 , 0.067, 0. ],
[ 0.15 , -0.467, 0.09 ],
[ 0. , 0.4 , -0.64 ]])
Get a vector of floating species amounts, and display it:
amt = m.getFloatingSpeciesAmounts()
amt
array([ 0.1 , 0.25, 0.1 ])
Look at the floating species ids:
m.getFloatingSpeciesIds()
['S1', 'S2', 'S3']
Numpy has a huge amount of numeric capability, here we calculate the eigensystem from the Jacobian.:
lin.eig(jac)
(array([-0.15726345, -0.38237134, -0.76736521]),
array([[ 0.77009381, -0.19510707, 0.03580588],
[ 0.49121122, 0.53107368, -0.30320915],
[ 0.40702219, 0.82455683, 0.95225109]]))
Suppose we wanted to calculate the matrix vector product of the jacobian with the floating species amounts, its a single statement, since we use native types.:
n.dot(jac, amt)
array([-0.00325, -0.09275, 0.036 ])
Finally, you can of course simulate over time. The first column in result is time, the rest are whatever is selected. The easies way to plot is to use roadrunner.plot:
results = rr.simulate()
roadrunner.plot(results)
See also
To get numpy unstructured array, see: Plotting Data
Using libRoadRunner in IPython you can get documentation easily using a ? after the object or method:
rr.simulate?
Type: instancemethod
String Form:<bound method RoadRunner.simulate of <roadrunner.RoadRunner() { this = 03D2E6F0 }>>
File: c:\python27\lib\site-packages\roadrunner\roadrunner.py
Definition: rr.simulate(self, *args)
Docstring:
RoadRunner.simulate(*args)
Simulate the current SBML model.
There are a number of ways to call simulate.
1. With no arguments. In this case, the current set of `SimulateOptions` will
be used for the simulation. The current set may be changed either directly
via setSimulateOptions() or with one of the two alternate ways of calling
simulate.
2: With single `SimulateOptions` argument. In this case, all of the settings
in the given options are copied and will be used for the current and future
simulations.
3: With the three positions arguments, `timeStart`, `timeEnd`, `steps`. In this case
these three values are copied and will be used for the current and future simulations.
The options given in the 2nd and 3rd forms will remain in effect until changed. So, if
one calls::
rr.simulate (0, 3.14, 100)
The start time of 0, end time of 3.14 and steps of 100 will remain in effect, so that if this
is followed by a call to::
rr.simulate()
This simulation will use the previous values.
:returns: a numpy array with each selected output timeseries being a
column vector, and the 0'th column is the simulation time.
:rtype: numpy.ndarray
| [1] | Much of the time, the Numpy array just holds a pointer to a block of data owned by RoadRunner, for example, the array returned by rr.simulate() just has a pointer to the results matrix which is owned by the RoadRunner, so there is NO COPYING involved. If you have no need for the result, just ignore it, it costs virtually nothing to return it. |
| [2] | Current State of the System Group When using the LLVM back end, all model state calculation are automatically performed using a techinque called lazy evaluation. If one sets the concentration of a species, the amount of of that species is automatically available without having to perform any addition operations. Similarly with any other value in the model. If an SBML parameter is defined by an assigment rule or function and its value then depends on a number of other values, simply setting to other values automatically cause the value of the most dependent variable to be set. This is identical how one operates in a spredsheet such as Microsoft Excel. For example, if one has a cell with an equation that depends on other cell, and those other cell depend on other values, setting the value of any upstream cell automatically causes that value to cascade down to the terminal cells. The LLVM back end roadruner function identically. |