libRoadRunner C++ API  1.3
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Public Member Functions | Static Public Member Functions | List of all members
rr::RoadRunner Class Reference

#include <rrRoadRunner.h>

Public Member Functions

 RoadRunner ()
 
 RoadRunner (const std::string &uriOrSBML, const Dictionary *options=0)
 
 RoadRunner (const std::string &compiler, const std::string &tempDir, const std::string &supportCodeDir)
 
virtual ~RoadRunner ()
 
int getInstanceID ()
 
int getInstanceCount ()
 
std::string getInfo ()
 
class CompilergetCompiler ()
 
void setCompiler (const std::string &compiler)
 
Integrator * getIntegrator ()
 
Integrator * getIntegratorByName (const std::string &name)
 
Integrator * makeIntegrator (std::string name)
 
SteadyStateSolver * getSteadyStateSolver ()
 
std::string getModelName ()
 
bool clearModel ()
 Clears the currently loaded model and all associated memory. More...
 
double integrate (double t0, double tf, const SimulateOptions *options=0)
 
double oneStep (double currentTime, double stepSize, bool reset=true)
 
const ls::DoubleMatrix * simulate (const Dictionary *options=0)
 
const ls::DoubleMatrix * getSimulationData () const
 
SimulateOptionsgetSimulateOptions ()
 
RoadRunnerOptionsgetOptions ()
 
std::string getSBML (int level=0, int version=0)
 
std::string getCurrentSBML (int level=0, int version=0)
 
void reset ()
 
void reset (int options)
 
ExecutableModelgetModel ()
 
void load (const std::string &uriOrSBML, const Dictionary *options=0)
 
rr::SelectionRecord createSelection (const std::string &str)
 
std::vector
< rr::SelectionRecord > & 
getSelections ()
 
double getValue (const std::string &sel)
 
std::vector< double > getSelectedValues ()
 
void getIds (int types, std::list< std::string > &ids)
 
std::vector< std::string > getIndependentFloatingSpeciesIds ()
 Gets the ids for all independent floating species. More...
 
std::vector< std::string > getDependentFloatingSpeciesIds ()
 Gets the ids for all dependent floating species. More...
 
std::vector< std::string > getFloatingSpeciesInitialConcentrationIds ()
 Gets the ids for all initial floating species concentrations. More...
 
int getSupportedIdTypes ()
 
void setValue (const std::string &id, double value)
 
ls::DoubleMatrix getFloatingSpeciesAmounts ()
 Returns the floating species amounts as a named array. More...
 
ls::DoubleMatrix getFloatingSpeciesConcentrations ()
 Returns the floating species concentrations as a named array. More...
 
ls::DoubleMatrix getFullJacobian ()
 
ls::DoubleMatrix getReducedJacobian (double h=-1.0)
 
std::vector< ls::Complex > getFullEigenValues ()
 
std::vector< ls::Complex > getReducedEigenValues ()
 
ls::DoubleMatrix getNrMatrix ()
 
ls::DoubleMatrix getKMatrix ()
 
ls::DoubleMatrix getReducedStoichiometryMatrix ()
 
ls::DoubleMatrix getFullStoichiometryMatrix ()
 
std::vector< std::string > getEigenValueIds ()
 
double getUnscaledParameterElasticity (const string &reactionName, const string &parameterName)
 
void setConservedMoietyAnalysis (bool value)
 
bool getConservedMoietyAnalysis ()
 
double getDiffStepSize () const
 Set the differential step size used in MCA routines like getCC. More...
 
void setDiffStepSize (double val)
 Set the differential step size used in MCA routines like getCC. More...
 
double getSteadyStateThreshold () const
 Get the steady state threshold used in getCC. More...
 
void setSteadyStateThreshold (double val)
 Set the steady state threshold used in getCC. More...
 
double getuCC (const std::string &variableName, const std::string &parameterName)
 
double getCC (const std::string &variableName, const std::string &parameterName)
 
double getuEE (const std::string &reactionName, const std::string &parameterName)
 
double getuEE (const std::string &reactionName, const std::string &parameterName, bool computeSteadystate)
 
double getEE (const std::string &reactionName, const std::string &parameterName)
 
double getEE (const std::string &reactionName, const std::string &parameterName, bool computeSteadyState)
 
ls::DoubleMatrix getUnscaledElasticityMatrix ()
 
ls::DoubleMatrix getScaledElasticityMatrix ()
 
double getScaledFloatingSpeciesElasticity (const std::string &reactionName, const std::string &speciesName)
 
double getUnscaledSpeciesElasticity (int reactionId, int speciesIndex)
 
double steadyState (const Dictionary *dict=0)
 
ls::DoubleMatrix steadyStateNamedArray (const Dictionary *dict=0)
 
std::vector
< rr::SelectionRecord > & 
getSteadyStateSelections ()
 
void setSteadyStateSelections (const std::vector< std::string > &steadyStateSelections)
 
void setSteadyStateSelections (const std::vector< rr::SelectionRecord > &steadyStateSelections)
 
std::vector< double > getSteadyStateValues ()
 
std::vector< std::string > getSteadyStateSelectionStrings () const
 
ls::DoubleMatrix getSteadyStateValuesNamedArray ()
 
std::vector< double > getConservedMoietyValues ()
 Returns the sum of each conserved cycle. More...
 

Static Public Member Functions

static std::string getParamPromotedSBML (const std::string &sArg)
 
static std::vector< std::string > getRegisteredIntegratorNames ()
 
static std::vector< std::string > getRegisteredSteadyStateSolverNames ()
 
static void ensureSolversRegistered ()
 
static std::string getExtendedVersionInfo ()
 

Detailed Description

The main RoadRunner class.

The RoadRunner class is responsible for loading and simulating SBML models.

MemoryManagment: Any pointer returned by a get... method is owned by the RoadRunner object and does NOT have to be deleted.

Constructor & Destructor Documentation

rr::RoadRunner::RoadRunner ( )

create an empty RoadRunner object.

rr::RoadRunner::RoadRunner ( const std::string &  uriOrSBML,
const Dictionary options = 0 
)

load an sbml document from anywhere.

same arguments as load.

If options is not null, then the RoadRunner::computeAndAssignConservationLaws flag is set to whatever value is specified in the options struct.

Parameters
uriOrSBMLa URI, local path or sbml document contents.
optionsan options struct, if null, default values are used.
rr::RoadRunner::RoadRunner ( const std::string &  compiler,
const std::string &  tempDir,
const std::string &  supportCodeDir 
)

All three of the RoadRunner options default to the empty string, in this case, the default values are used.

Parameters
compilerIf LLVM build is enabled, the compiler defaults to LLVM.
tempDirIf the old external C compiler is used, this is the where the C files are written to.
supportCodeDirIf the old external C compiler is used, this is the location where roadrunner C include files are.
virtual rr::RoadRunner::~RoadRunner ( )
virtual

free any memory this class allocated

Member Function Documentation

bool rr::RoadRunner::clearModel ( )

Clears the currently loaded model and all associated memory.

Deletes jitted code and libStruct data

Returns
True if memory was freed, false if no model was loaded in the first place
rr::SelectionRecord rr::RoadRunner::createSelection ( const std::string &  str)

create a selection record. This record can be used to select values.

static void rr::RoadRunner::ensureSolversRegistered ( )
static

Ensures all integrators and steady state solvers are registered

double rr::RoadRunner::getCC ( const std::string &  variableName,
const std::string &  parameterName 
)

Get scaled control coefficient with respect to a global parameter

The variableName must be either a reaction id, or a floating species id.

The parameterName must be either a global parameter, boundary species, or conserved sum.

class Compiler* rr::RoadRunner::getCompiler ( )

The Compiler that the ModelGenerator is using to compile / interpret sbml code.

bool rr::RoadRunner::getConservedMoietyAnalysis ( )

is conservation analysis enabled. This is set

std::vector<double> rr::RoadRunner::getConservedMoietyValues ( )

Returns the sum of each conserved cycle.

Author
MTK, JKM
std::string rr::RoadRunner::getCurrentSBML ( int  level = 0,
int  version = 0 
)

Returns the SBML with the current model parameters. This is different than getSBML which returns the orginal SBML.

This may optionally up or downconvert the document to a different version, if the level and version arguments are non-zero.

If both arguments are zero, then the document is left alone and the original version is returned.

std::vector<std::string> rr::RoadRunner::getDependentFloatingSpeciesIds ( )

Gets the ids for all dependent floating species.

Author
JKM

See getIndependentFloatingSpeciesIds for an explanation of independent vs. dependent.

double rr::RoadRunner::getDiffStepSize ( ) const

Set the differential step size used in MCA routines like getCC.

Author
JKM
double rr::RoadRunner::getEE ( const std::string &  reactionName,
const std::string &  parameterName 
)

Get scaled elasticity coefficient with respect to a global parameter or species

double rr::RoadRunner::getEE ( const std::string &  reactionName,
const std::string &  parameterName,
bool  computeSteadyState 
)

Get scaled elasticity coefficient with respect to a global parameter or species. Optionally the model is brought to steady state after the computation.

std::vector<std::string> rr::RoadRunner::getEigenValueIds ( )

returns the list of floating species, but with a "eigen(...)" string wrapped around them.

static std::string rr::RoadRunner::getExtendedVersionInfo ( )
static

getVersion plus info about dependent libs versions..

ls::DoubleMatrix rr::RoadRunner::getFloatingSpeciesAmounts ( )

Returns the floating species amounts as a named array.

Author
JKM
ls::DoubleMatrix rr::RoadRunner::getFloatingSpeciesConcentrations ( )

Returns the floating species concentrations as a named array.

Author
JKM
std::vector<std::string> rr::RoadRunner::getFloatingSpeciesInitialConcentrationIds ( )

Gets the ids for all initial floating species concentrations.

See getIndependentFloatingSpeciesIds for an explanation of independent vs. dependent.

std::vector<ls::Complex> rr::RoadRunner::getFullEigenValues ( )

Returns the eigenvalues of the full jacobian.

If the eigenvalues are all real, this returns a N x 1 matrix, if complex, returns an N x 2 matrix where the first column is the real values and the second is the imaginary part.

ls::DoubleMatrix rr::RoadRunner::getFullJacobian ( )

compute the full Jacobian at the current operating point

ls::DoubleMatrix rr::RoadRunner::getFullStoichiometryMatrix ( )

Get the stoichiometry matrix that coresponds to the full model, even it it was converted via conservation conversion.

void rr::RoadRunner::getIds ( int  types,
std::list< std::string > &  ids 
)

populates a given list with all the ids that this class can accept.

std::vector<std::string> rr::RoadRunner::getIndependentFloatingSpeciesIds ( )

Gets the ids for all independent floating species.

Author
JKM

Independent means (in this case) that the species is unique up to a conserved cycle, i.e. each conserved cycle counts for only one species. See Sauro, Systems Biology: Introduction to Pathway Modeling, 1st ed. pp. 60.

std::string rr::RoadRunner::getInfo ( )

information about the current state of this object.

int rr::RoadRunner::getInstanceCount ( )

Number of currently running RoadRunner instances.

int rr::RoadRunner::getInstanceID ( )

When there are multiple instances of RoadRunner, this is the instance id.

Integrator* rr::RoadRunner::getIntegrator ( )

get a pointer to the integrator which is currently being used to time evolve the system.

Integrator* rr::RoadRunner::getIntegratorByName ( const std::string &  name)

Get an integrator by name without switching the current integrator

ls::DoubleMatrix rr::RoadRunner::getKMatrix ( )

Returns the K matrix (right nullspace of Nr) The K matrix has the structure, [I K0]'

ExecutableModel* rr::RoadRunner::getModel ( )

get a pointer to the ExecutableModel owned by the RoadRunner object.

std::string rr::RoadRunner::getModelName ( )

returns the model name if a model is loaded, empty string otherwise.

ls::DoubleMatrix rr::RoadRunner::getNrMatrix ( )

get the reduced stochiometry matrix. If conservation conversion is enabled, this is the matrix that coresponds to the independent species.

A synonym for getReducedStoichiometryMatrix().

RoadRunnerOptions& rr::RoadRunner::getOptions ( )

Get a reference to the options that determine how this class should behave.

These are general options. For options specific for loading or simulationg,

See also
getSimulateOptions.
static std::string rr::RoadRunner::getParamPromotedSBML ( const std::string &  sArg)
static

given an sbml document, this method moves all the local parameters to global parameters.

std::vector<ls::Complex> rr::RoadRunner::getReducedEigenValues ( )

Returns the eigenvalues of the reduced jacobian.

If the eigenvalues are all real, this returns a N x 1 matrix, if complex, returns an N x 2 matrix where the first column is the real values and the second is the imaginary part.

ls::DoubleMatrix rr::RoadRunner::getReducedJacobian ( double  h = -1.0)

Compute the reduced Jacobian at the current operating point.

Parameters
hThe step sized used for central difference method. If negative, the default value from the config file is used.
ls::DoubleMatrix rr::RoadRunner::getReducedStoichiometryMatrix ( )

get the reduced stochiometry matrix. If conservation conversion is enabled, this is the matrix that coresponds to the independent species.

A synonym for getNrMatrix().

static std::vector<std::string> rr::RoadRunner::getRegisteredIntegratorNames ( )
static

Return a vector of the names of all registered integrators

static std::vector<std::string> rr::RoadRunner::getRegisteredSteadyStateSolverNames ( )
static

Return a vector of the names of all registered integrators

std::string rr::RoadRunner::getSBML ( int  level = 0,
int  version = 0 
)

get the originally loaded sbml document as a string.

This may optionally up or downconvert the document to a different version, if the level and version arguments are non-zero.

If both arguments are zero, then the document is left alone and the

ls::DoubleMatrix rr::RoadRunner::getScaledElasticityMatrix ( )

Compute the unscaled elasticity matrix at the current operating point

double rr::RoadRunner::getScaledFloatingSpeciesElasticity ( const std::string &  reactionName,
const std::string &  speciesName 
)

Compute the scaled elasticity for a given reaction and given species

std::vector<double> rr::RoadRunner::getSelectedValues ( )

returns the values selected with SimulateOptions for the current model time / timestep")

std::vector<rr::SelectionRecord>& rr::RoadRunner::getSelections ( )

Returns the currently selected columns that will be returned by calls to simulate() or simulateEx(,,).

SimulateOptions& rr::RoadRunner::getSimulateOptions ( )

get a reference to the SimulateOptions that were set either by setSimulateOptions or simulate.

const ls::DoubleMatrix* rr::RoadRunner::getSimulationData ( ) const

RoadRunner keeps a copy of the simulation data around until the next call to simulate. This matrix can be obtained here.

std::vector<rr::SelectionRecord>& rr::RoadRunner::getSteadyStateSelections ( )

returns the current set of steady state selections.

std::vector<std::string> rr::RoadRunner::getSteadyStateSelectionStrings ( ) const

Returns a vector of the steady state selection strings

SteadyStateSolver* rr::RoadRunner::getSteadyStateSolver ( )

get a pointer to the current steady state solver

double rr::RoadRunner::getSteadyStateThreshold ( ) const

Get the steady state threshold used in getCC.

Author
JKM

In the MCA routines, RoadRunner will keep trying to converge to a steady state until this threshold is met

std::vector<double> rr::RoadRunner::getSteadyStateValues ( )

Performs a steady state calculation (evolves the system to a steady state), then calculates and returns the set of values specifed by the steady state selections.

ls::DoubleMatrix rr::RoadRunner::getSteadyStateValuesNamedArray ( )

Like getSteadyStateValues but returns a named array

int rr::RoadRunner::getSupportedIdTypes ( )

returns a bit field of the ids that this class supports.

double rr::RoadRunner::getuCC ( const std::string &  variableName,
const std::string &  parameterName 
)

Get unscaled control coefficient with respect to a global parameter

variableName must be either a reaction or floating species.

parameterName must be eithe a global parameter, boundary species, or conserved sum.

double rr::RoadRunner::getuEE ( const std::string &  reactionName,
const std::string &  parameterName 
)

Get unscaled elasticity coefficient with respect to a global parameter or species

double rr::RoadRunner::getuEE ( const std::string &  reactionName,
const std::string &  parameterName,
bool  computeSteadystate 
)

Get unscaled elasticity coefficient with respect to a global parameter or species. Optionally the model is brought to steady state after the computation.

ls::DoubleMatrix rr::RoadRunner::getUnscaledElasticityMatrix ( )

Compute the unscaled species elasticity matrix at the current operating point

double rr::RoadRunner::getUnscaledParameterElasticity ( const string &  reactionName,
const string &  parameterName 
)

Returns the unscaled elasticity for a named reaction with respect to a named parameter

double rr::RoadRunner::getUnscaledSpeciesElasticity ( int  reactionId,
int  speciesIndex 
)

Get a single species elasticity value IMPORTANT: Assumes that the reaction rates have been precomputed at the operating point !!

double rr::RoadRunner::getValue ( const std::string &  sel)

Creates a new selection based on the selection string, and returns the value it queries.

double rr::RoadRunner::integrate ( double  t0,
double  tf,
const SimulateOptions options = 0 
)

Carry out a single integration step using a stepsize as indicated in the method call.

Parameters
t0starting time
tffinal time
optionsoverride current options.
void rr::RoadRunner::load ( const std::string &  uriOrSBML,
const Dictionary options = 0 
)

load an sbml document from anywhere.

If options is not null, then the RoadRunner::computeAndAssignConservationLaws flag is set to whatever value is specified in the options struct.

WARNING, will no longer return a value in next version.

Parameters
uriOrSBMLa URI, local path or sbml document contents.
optionsan options struct, if null, default values are used.
Integrator* rr::RoadRunner::makeIntegrator ( std::string  name)

Make an integrator for the given name

double rr::RoadRunner::oneStep ( double  currentTime,
double  stepSize,
bool  reset = true 
)
Deprecated:
, use integrate instead.
void rr::RoadRunner::reset ( )

Picks up default options from config.

The current default is SelectionRecord::TIME | SelectionRecord::RATE | SelectionRecord::FLOATING.

void rr::RoadRunner::reset ( int  options)

reset the model accordign to a bitfield specified by the SelectionRecord::SelectionType values.

Note, this would make more sense as an unsigned, however SWIG has issues mapping an enum to an unsigned, but seems to map enums just fine to an int.

For example, to reset the floating species, time and rate rule values:

r.reset(SelectionRecord::TIME | SelectionRecord::RATE | SelectionRecord::FLOATING);
Parameters
optionsa bitmask made from the SelectionRecord::SelectionTypes values.
void rr::RoadRunner::setCompiler ( const std::string &  compiler)

Set the name of the externa compiler to use. Some ModelGenerators may have no use for this value.

An exception is raised if the string is invalid.

void rr::RoadRunner::setConservedMoietyAnalysis ( bool  value)

This method turns on / off the computation and adherence to conservation laws.

void rr::RoadRunner::setDiffStepSize ( double  val)

Set the differential step size used in MCA routines like getCC.

Author
JKM
void rr::RoadRunner::setSteadyStateSelections ( const std::vector< std::string > &  steadyStateSelections)

parses the given list of strings and generates selections records which will be used for the steady state selections.

void rr::RoadRunner::setSteadyStateSelections ( const std::vector< rr::SelectionRecord > &  steadyStateSelections)

makes a copy of an existing list of selection records. These will be saved and used for selection values in getSteadyStateValues().

void rr::RoadRunner::setSteadyStateThreshold ( double  val)

Set the steady state threshold used in getCC.

Author
JKM

In the MCA routines, RoadRunner will keep trying to converge to a steady state until this threshold is met

void rr::RoadRunner::setValue ( const std::string &  id,
double  value 
)

sets the value coresponding to the given selection string

raises an exception in the selection string is invalid.

const ls::DoubleMatrix* rr::RoadRunner::simulate ( const Dictionary options = 0)

Simulate the current SBML model.

If options is null, then the current simulation settings (start time, end time, n steps) are used. If options is not null, then the current simulation settings are set to the values specified by options and they are used.

The options Dictionary may contain a large number of options, for a complete list of all available options for each integrator type,

See also
IntegratorFactory,
SimulateOptions.

For example, to perform a simulation from time 0 to 10 with 1000 steps, using a stiff integtator, you would:

RoadRunner r = RoadRunner("someFile.xml");
BasicDictionary opt;
opt.setItem("start", 0);
opt.setItem("duration", 10);
opt.setItem("steps", 1000);
opt.setItem("stiff", true);
const DoubleMatrix *result = r.simulate(&opt);

Similarly, if one wants to use a stochastic integrator, such as the Gillespie integrator, this is set via the "integrator" key, i.e.

RoadRunner r = RoadRunner("someFile.xml");
BasicDictionary opt;
opt.setItem("integrator", "gillespie");
opt.setItem("start", 0);
opt.setItem("duration", 10);
opt.setItem("steps", 1000);
opt.setItem("stiff", true);
opt.setItem("seed", 12345);
const DoubleMatrix *result = r.simulate(&opt);

Here, the "integrator" specifies the integrator to use. The "stiff" key is only used by the deterministic solvers, and it is safely ignored by the stochastic solvers. Also, the "seed" sets the random seed that the integrator uses. For more information about all of the avaialble options for each integrator,

See also
IntegratorFactory::getIntegratorOptions".
Exceptions
anstd::exception if any options are invalid.
Returns
a borrowed reference to a DoubleMatrix object if successfull.
double rr::RoadRunner::steadyState ( const Dictionary dict = 0)

Compute the steady state of the model, returns the sum of squares of the solution

The steady state solver and whatever options it needs may be specified via the given dictionary. For a list of all available steady state solvers,

See also
SteadyStateSolverFactory.
Parameters
dicta pointer to a dictionary which has the steady state options. May be NULL, in this case the existing options are used.
ls::DoubleMatrix rr::RoadRunner::steadyStateNamedArray ( const Dictionary dict = 0)

Like steadyState but returns a named array of the steady state values


The documentation for this class was generated from the following file: