Package org.simulator.sbml

Class SBMLinterpreter

java.lang.Object

org.simulator.sbml.SBMLinterpreter

All Implemented Interfaces:

Serializable, org.apache.commons.math.ode.FirstOrderDifferentialEquations, DelayedDESystem, DelayValueHolder, DESystem, EventDESystem, FastProcessDESystem, RichDESystem, SBMLValueHolder

public class SBMLinterpreter
extends Object
implements DelayedDESystem, EventDESystem, FastProcessDESystem, RichDESystem, SBMLValueHolder

This differential equation system (DESystem) takes a model in SBML format and maps it to a data structure that is understood by the AbstractDESSolver. Therefore, this class implements all necessary functions expected by SBML.

Since:

0.9

Version:

$Rev$

Author:

Alexander Dörr, Andreas Dräger, Roland Keller, Dieudonné Motsou Wouamba

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected org.sbml.jsbml.Reaction	currentReaction	This field is necessary to also consider local parameters of the current reaction because it is not possible to access these parameters from the model.
protected double[]	initialValues	An array, which stores all computed initial values of the model.
protected org.sbml.jsbml.Model	model	The model to be simulated.
protected Map<String,Double>	stoichiometricCoefHash	This Map saves the current stoichiometric coefficients for those SpeciesReference objects that are a target to an Assignment .
static String	TEMP_VALUE	Key to memorize user objects in ASTNode
protected double[]	v	An array of the velocities of each reaction within the model system.
protected double[]	Y	An array of the current concentration of each species within the model system.

Constructor Summary

Constructors

Constructor	Description
SBMLinterpreter(org.sbml.jsbml.Model model)	This constructs a new DESystem for the given SBML Model.
SBMLinterpreter(org.sbml.jsbml.Model model, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue)
SBMLinterpreter(org.sbml.jsbml.Model model, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue, Map<String,Boolean> amountHash)	Creates a new SBMLinterpreter

Method Summary

Modifier and Type	Method	Description
boolean	addConstraintListener(ConstraintListener listener)	Adds the given ConstraintListener to this interpreter's list of listeners.
double	compileReaction(int reactionIndex)
double	computeDelayedValue(double time, String id, DESystem DES, double[] initialValues, int yIndex)	Returns the value for the element with the given id at a time point in the past, where the time gives the amount of time in the past.
void	computeDerivatives(double time, double[] Y, double[] changeRate)
boolean	containsEventsOrRules()	This method is used to check if this differential equation system contains any events or rules that would require a special treatment by the numerical solver.
boolean	containsFastProcesses()
int	getAdditionalValueCount()	Gives the number of intermediate results that are computed by this class.
String[]	getAdditionalValueIds()	This provides the column/row identifiers of all intermediate results: one identifier per result.
double[]	getAdditionalValues(double t, double[] Y)	Computes and/or delivers the intermediate results at the given time and for the given results from the previous time step.
int	getConstraintListenerCount()
double	getCurrentCompartmentSize(String id)	Returns the size of the compartment with the given id.
double	getCurrentCompartmentValueOf(String speciesId)	Checks if the given symbol id refers to a Species and returns the value of its Compartment or 1d otherwise
double	getCurrentParameterValue(String id)	Returns the value of the parameter with the given id.
double	getCurrentSpeciesValue(String id)	Returns the value of the species with the given id.
double	getCurrentStoichiometry(String id)	Returns the value of the stoichiometry of the species reference with the given id.
double	getCurrentTime()	Returns the timepoint where the simulation is currently situated
double	getCurrentValueOf(int position)	Returns the current value of the Y vector at the given position.
double	getCurrentValueOf(String id)	Returns the current value of the SBase with the given id.
int	getDimension()
int	getEventCount()	Counts the number of events in this system.
String[]	getIdentifiers()	Delivers an array of Strings that describe the content of each dimension of the resulting array of this DESystem.
double[]	getInitialValues()	Returns the initial values of the model to be simulated.
org.sbml.jsbml.Model	getModel()	Returns the model that is used by this object.
EventInProgress	getNextEventAssignments(double t, double previousTime, double[] Y)	Returns a list with event assignments for the events triggered either by the time t or by the concentrations of the species stored in Y.
boolean	getNoDerivatives()
int	getParameterCount()	This method tells you the complete number of parameters within the model.
int	getPositionOfParameters()
int	getPositiveValueCount()
int	getRuleCount()	Counts the number of rules to be evaluated in each time point.
void	init()	This method initializes the differential equation system for simulation.
void	init(boolean refreshTree)	This method initializes the differential equation system for simulation.
void	init(boolean renewTree, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue)	This method initializes the differential equation system for simulation.
void	init(boolean renewTree, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue, Map<String,Boolean> amountHash)	This method initializes the differential equation system for simulation.
boolean	processAssignmentRules(double t, double[] Y)	Calculates the changes or assignments that are defined by all rules in the system at the given simulation time point.
void	processInitialAssignments(double time, double[] Y)	Processes the initial assignments
boolean	processRules(double time, double[] changeRate, double[] Y, boolean initialCalculations)	Processes the rules
protected void	processVelocities(double[] changeRate, double time)	This method computes the multiplication of the stoichiometric matrix of the given model system with the reaction velocities vector passed to this method.
void	registerDelayValueHolder(DelayValueHolder dvh)
ConstraintListener	removeConstraintListener(int index)	Removes the ConstraintListener with the given index from this interpreter.
boolean	removeConstraintListener(ConstraintListener listener)	Removes the given ConstraintListener from this interpreter.
void	setDelaysIncluded(boolean delaysIncluded)
void	setFastProcessComputation(boolean isProcessing)
void	setParameters(double[] params)	This method allows us to set the parameters of the model to the specified values in the given array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TEMP_VALUE

public static final String TEMP_VALUE

Key to memorize user objects in ASTNode

See Also:

Constant Field Values

currentReaction

protected org.sbml.jsbml.Reaction currentReaction

This field is necessary to also consider local parameters of the current reaction because it is not possible to access these parameters from the model. Hence we have to memorize an additional reference to the Reaction and thus to the list of these parameters.

initialValues

protected double[] initialValues

An array, which stores all computed initial values of the model. If this model does not contain initial assignments, the initial values will only be taken once from the information stored in the model. Otherwise they have to be computed again as soon as the parameter values of this model are changed, because the parameters may influence the return values of the initial assignments.

model

protected org.sbml.jsbml.Model model

The model to be simulated.

v

protected double[] v

An array of the velocities of each reaction within the model system. Holding this globally saves many new memory allocations during simulation time.

stoichiometricCoefHash

protected Map<String,Double> stoichiometricCoefHash

This Map saves the current stoichiometric coefficients for those SpeciesReference objects that are a target to an Assignment .

Y

protected double[] Y

An array of the current concentration of each species within the model system.

Constructor Detail

SBMLinterpreter

public SBMLinterpreter(org.sbml.jsbml.Model model)
                throws org.sbml.jsbml.validator.ModelOverdeterminedException,
                       org.sbml.jsbml.SBMLException

This constructs a new DESystem for the given SBML Model. Note that only a maximum of Integer.MAX_VALUE Species can be simulated. If the model contains more Species, this class is not applicable.

Note that currently, units are not considered.

Parameters:

model -

Throws:

org.sbml.jsbml.validator.ModelOverdeterminedException

org.sbml.jsbml.SBMLException

SBMLinterpreter

public SBMLinterpreter(org.sbml.jsbml.Model model,
                       double defaultSpeciesValue,
                       double defaultParameterValue,
                       double defaultCompartmentValue)
                throws org.sbml.jsbml.SBMLException,
                       org.sbml.jsbml.validator.ModelOverdeterminedException

Parameters:

model -

defaultSpeciesValue -

defaultParameterValue -

defaultCompartmentValue -

Throws:

org.sbml.jsbml.SBMLException

org.sbml.jsbml.validator.ModelOverdeterminedException

SBMLinterpreter

public SBMLinterpreter(org.sbml.jsbml.Model model,
                       double defaultSpeciesValue,
                       double defaultParameterValue,
                       double defaultCompartmentValue,
                       Map<String,Boolean> amountHash)
                throws org.sbml.jsbml.SBMLException,
                       org.sbml.jsbml.validator.ModelOverdeterminedException

Creates a new SBMLinterpreter

Parameters:

model - the model to interpret

defaultSpeciesValue - the default value for species, if no value is given

defaultParameterValue - the default value for parameters, if no value is given

defaultCompartmentValue - the default value for compartments, if no value is given

amountHash - a hash that states for the species in the model, whether their amount or their concentration should be computed

Throws:

org.sbml.jsbml.SBMLException

org.sbml.jsbml.validator.ModelOverdeterminedException

Method Detail

addConstraintListener

public boolean addConstraintListener(ConstraintListener listener)

Adds the given ConstraintListener to this interpreter's list of listeners.

Parameters:

listener - the element to be added.

Returns:

true if this operation was successful, false otherwise.

Throws:

NullPointerException

See Also:

List.add(Object)

removeConstraintListener

public boolean removeConstraintListener(ConstraintListener listener)

Removes the given ConstraintListener from this interpreter.

Parameters:

listener - the element to be removed.

Returns:

true if this operation was successful, false otherwise.

Throws:

NullPointerException

See Also:

List.remove(Object)

removeConstraintListener

public ConstraintListener removeConstraintListener(int index)

Removes the ConstraintListener with the given index from this interpreter.

Parameters:

index - of the ConstraintListener to be removed.

Returns:

true if this operation was successful, false otherwise.

Throws:

IndexOutOfBoundsException

See Also:

List.remove(int)

getConstraintListenerCount

public int getConstraintListenerCount()

Returns:

the number of ConstraintListeners currently assigned to this interpreter.

containsFastProcesses

public boolean containsFastProcesses()

Specified by:

containsFastProcesses in interface FastProcessDESystem

Returns:

flag that is true if fast processes are contained.

getAdditionalValueIds

public String[] getAdditionalValueIds()

Description copied from interface: RichDESystem

This provides the column/row identifiers of all intermediate results: one identifier per result. This means, the length of the returned String array must equal the length of the array returned by RichDESystem.getAdditionalValues(double, double[]).

Specified by:

getAdditionalValueIds in interface RichDESystem

Returns:

The identifiers of all intermediate results computed during evaluation.

getAdditionalValues

public double[] getAdditionalValues(double t,
                                    double[] Y)
                             throws org.apache.commons.math.ode.DerivativeException

Description copied from interface: RichDESystem

Computes and/or delivers the intermediate results at the given time and for the given results from the previous time step.

Specified by:

getAdditionalValues in interface RichDESystem

Parameters:

t - The time point for which intermediate results are to be computed.

Y - The result vector from the previous time step.

Returns:

An array of intermediate results. Simulators should call this method after computation of the next time point to avoid unnecessary re-computation. Implementing classes should store interesting intermediate results to be accessible in case time and Y are the same values than those just used for the actual computation.

Throws:

org.apache.commons.math.ode.DerivativeException - If the system cannot be solved for the given configuration or no intermediate results can be computed in this step.

getCurrentCompartmentValueOf

public double getCurrentCompartmentValueOf(String speciesId)

Checks if the given symbol id refers to a Species and returns the value of its Compartment or 1d otherwise

Specified by:

getCurrentCompartmentValueOf in interface SBMLValueHolder

Parameters:

speciesId -

Returns:

compartmentValue

getCurrentCompartmentSize

public double getCurrentCompartmentSize(String id)

Description copied from interface: SBMLValueHolder

Returns the size of the compartment with the given id.

Specified by:

getCurrentCompartmentSize in interface SBMLValueHolder

Returns:

compartmentSize

getCurrentParameterValue

public double getCurrentParameterValue(String id)

Description copied from interface: SBMLValueHolder

Returns the value of the parameter with the given id.

Specified by:

getCurrentParameterValue in interface SBMLValueHolder

Returns:

parameterValue

getCurrentSpeciesValue

public double getCurrentSpeciesValue(String id)

Description copied from interface: SBMLValueHolder

Returns the value of the species with the given id.

Specified by:

getCurrentSpeciesValue in interface SBMLValueHolder

Returns:

speciesValue

getCurrentStoichiometry

public double getCurrentStoichiometry(String id)

Description copied from interface: SBMLValueHolder

Returns the value of the stoichiometry of the species reference with the given id.

Specified by:

getCurrentStoichiometry in interface SBMLValueHolder

Returns:

stoichiometry

getDimension

public int getDimension()

Specified by:

getDimension in interface org.apache.commons.math.ode.FirstOrderDifferentialEquations

getNextEventAssignments

public EventInProgress getNextEventAssignments(double t,
                                               double previousTime,
                                               double[] Y)
                                        throws org.apache.commons.math.ode.DerivativeException

Description copied from interface: EventDESystem

Returns a list with event assignments for the events triggered either by the time t or by the concentrations of the species stored in Y.

Specified by:

getNextEventAssignments in interface EventDESystem

Parameters:

t - The current simulation time.

Y - The current change of the system.

Returns:

Returns a list with event assignments for the events triggered

Throws:

org.apache.commons.math.ode.DerivativeException

getIdentifiers

public String[] getIdentifiers()

Description copied from interface: DESystem

Delivers an array of Strings that describe the content of each dimension of the resulting array of this DESystem.

Specified by:

getIdentifiers in interface DESystem

Returns:

An array of Strings which has the same length than the number given by FirstOrderDifferentialEquations.getDimension(). Each String describes the content of the given dimension.

getInitialValues

public double[] getInitialValues()

Returns the initial values of the model to be simulated.

Returns:

Returns the initial values of the model to be simulated.

getModel

public org.sbml.jsbml.Model getModel()

Returns the model that is used by this object.

Returns:

Returns the model that is used by this object.

getAdditionalValueCount

public int getAdditionalValueCount()

Description copied from interface: RichDESystem

Gives the number of intermediate results that are computed by this class. The number returned here must equal the length of the arrays returned by the methods RichDESystem.getAdditionalValueIds() and RichDESystem.getAdditionalValues(double, double[]).

Specified by:

getAdditionalValueCount in interface RichDESystem

Returns:

The number of intermediate values that are computed in each time step.

getEventCount

public int getEventCount()

Description copied from interface: EventDESystem

Counts the number of events in this system.

Specified by:

getEventCount in interface EventDESystem

Returns:

The number of events that are to be checked and potentially evaluated in each time point.

getParameterCount

public int getParameterCount()

This method tells you the complete number of parameters within the model. It counts the global model parameters and all local parameters (parameters within a kinetic law).

Returns:

The total number of model parameters. Note that this number is limited to an int value, whereas the SBML model may contain int values.

getRuleCount

public int getRuleCount()

Description copied from interface: EventDESystem

Counts the number of rules to be evaluated in each time point.

Specified by:

getRuleCount in interface EventDESystem

Returns:

The number of rules in the system.

getPositionOfParameters

public int getPositionOfParameters()

getCurrentTime

public double getCurrentTime()

Returns the timepoint where the simulation is currently situated

Specified by:

getCurrentTime in interface SBMLValueHolder

Returns:

time

computeDerivatives

public void computeDerivatives(double time,
                               double[] Y,
                               double[] changeRate)
                        throws org.apache.commons.math.ode.DerivativeException

Specified by:

computeDerivatives in interface org.apache.commons.math.ode.FirstOrderDifferentialEquations

Throws:

org.apache.commons.math.ode.DerivativeException

getCurrentValueOf

public double getCurrentValueOf(String id)

Description copied from interface: SBMLValueHolder

Returns the current value of the SBase with the given id.

Specified by:

getCurrentValueOf in interface SBMLValueHolder

Returns:

value

init

public void init()
          throws org.sbml.jsbml.validator.ModelOverdeterminedException,
                 org.sbml.jsbml.SBMLException

This method initializes the differential equation system for simulation. In more detail: the initial amounts or concentration will be assigned to every Species or InitialAssignments if any are executed.

To save computation time the results of this method should be stored in an array. Hence this method must only be called once. However, if the SBML model to be simulated contains initial assignments, this can lead to wrong simulation results because initial assignments may depend on current parameter values.

Throws:

org.sbml.jsbml.validator.ModelOverdeterminedException

org.sbml.jsbml.SBMLException

See Also:

init(boolean, double, double, double)

init

public void init(boolean refreshTree)
          throws org.sbml.jsbml.validator.ModelOverdeterminedException,
                 org.sbml.jsbml.SBMLException

This method initializes the differential equation system for simulation. The user can tell whether the tree of ASTNodes has to be refreshed.

Parameters:

refreshTree -

Throws:

org.sbml.jsbml.validator.ModelOverdeterminedException

org.sbml.jsbml.SBMLException

init

public void init(boolean renewTree,
                 double defaultSpeciesValue,
                 double defaultParameterValue,
                 double defaultCompartmentValue)
          throws org.sbml.jsbml.validator.ModelOverdeterminedException,
                 org.sbml.jsbml.SBMLException

This method initializes the differential equation system for simulation. The user can tell whether the tree of ASTNodes has to be refreshed and give some default values.

Parameters:

renewTree -

defaultSpeciesValue -

defaultParameterValue -

defaultCompartmentValue -

Throws:

org.sbml.jsbml.validator.ModelOverdeterminedException

org.sbml.jsbml.SBMLException

init

public void init(boolean renewTree,
                 double defaultSpeciesValue,
                 double defaultParameterValue,
                 double defaultCompartmentValue,
                 Map<String,Boolean> amountHash)
          throws org.sbml.jsbml.validator.ModelOverdeterminedException,
                 org.sbml.jsbml.SBMLException

This method initializes the differential equation system for simulation. The user can tell whether the tree of ASTNodes has to be refreshed, give some default values and state whether a Species is seen as an amount or a concentration.

Parameters:

renewTree -

defaultSpeciesValue -

defaultParameterValue -

defaultCompartmentValue -

amountHash -

Throws:

org.sbml.jsbml.validator.ModelOverdeterminedException

org.sbml.jsbml.SBMLException

processAssignmentRules

public boolean processAssignmentRules(double t,
                                      double[] Y)
                               throws org.apache.commons.math.ode.DerivativeException

Description copied from interface: EventDESystem

Calculates the changes or assignments that are defined by all rules in the system at the given simulation time point.

Specified by:

processAssignmentRules in interface EventDESystem

Parameters:

t - The current simulation time.

Y - The current change of the system.

Returns:

flag that is true if there has been a change in the Y vector caused by the rules.

Throws:

org.apache.commons.math.ode.DerivativeException

processInitialAssignments

public void processInitialAssignments(double time,
                                      double[] Y)
                               throws org.sbml.jsbml.SBMLException

Processes the initial assignments

Parameters:

time - the ASTNode time

Y - the Y vector

Throws:

org.sbml.jsbml.SBMLException

processRules

public boolean processRules(double time,
                            double[] changeRate,
                            double[] Y,
                            boolean initialCalculations)
                     throws org.sbml.jsbml.SBMLException

Processes the rules

Parameters:

time - the current time

changeRate - the changeRate vector

Y - the Y vector

initialCalculations -

Returns:

flag that is true if there has been some change caused by any rule

Throws:

org.sbml.jsbml.SBMLException

processVelocities

protected void processVelocities(double[] changeRate,
                                 double time)
                          throws org.sbml.jsbml.SBMLException

This method computes the multiplication of the stoichiometric matrix of the given model system with the reaction velocities vector passed to this method. Note, the stoichiometric matrix is only constructed implicitly by running over all reactions and considering all participating reactants and products with their according stoichiometry or stoichiometric math.

Parameters:

changeRate - An array containing the rates of change for each species in the model system of this class.

time -

Throws:

org.sbml.jsbml.SBMLException

setFastProcessComputation

public void setFastProcessComputation(boolean isProcessing)

Specified by:

setFastProcessComputation in interface FastProcessDESystem

Parameters:

isProcessing - Should there be a splitting of fast and slow reactions in the simulation?

setParameters

public void setParameters(double[] params)

This method allows us to set the parameters of the model to the specified values in the given array.

Parameters:

params - An array of parameter values to be set for this model. If the number of given parameters does not match the number of model parameters, an exception will be thrown.

containsEventsOrRules

public boolean containsEventsOrRules()

Description copied from interface: DESystem

This method is used to check if this differential equation system contains any events or rules that would require a special treatment by the numerical solver.

Specified by:

containsEventsOrRules in interface DESystem

Returns:

flag that is true if any events or rules are contained in the differential equation system.

getCurrentValueOf

public double getCurrentValueOf(int position)

Description copied from interface: SBMLValueHolder

Returns the current value of the Y vector at the given position.

Specified by:

getCurrentValueOf in interface SBMLValueHolder

Returns:

value

getPositiveValueCount

public int getPositiveValueCount()

Specified by:

getPositiveValueCount in interface DESystem

Returns:

the number of values in Y that have to be positive.

registerDelayValueHolder

public void registerDelayValueHolder(DelayValueHolder dvh)

Specified by:

registerDelayValueHolder in interface DelayedDESystem

Parameters:

dvh - the delay value holder to be registered

computeDelayedValue

public double computeDelayedValue(double time,
                                  String id,
                                  DESystem DES,
                                  double[] initialValues,
                                  int yIndex)

Description copied from interface: DelayValueHolder

Returns the value for the element with the given id at a time point in the past, where the time gives the amount of time in the past.

Specified by:

computeDelayedValue in interface DelayValueHolder

Parameters:

time - the time point (in the past) at which the value is to be computed for the element with the given id.

id - the id of the delayed value

DES - the DESystem

initialValues - the initialValues of the DES

yIndex - the index corresponding to the id in the vector of the DES

Returns:

the computed value for the element with the given identifier at the time point in the past.

getNoDerivatives

public boolean getNoDerivatives()

Specified by:

getNoDerivatives in interface EventDESystem

Returns:

flag that is true, if the change vector is always zero in the system.

compileReaction

public double compileReaction(int reactionIndex)

Parameters:

reactionIndex - index of the reaction

Returns:

the current reaction velocity of a specific reaction

setDelaysIncluded

public void setDelaysIncluded(boolean delaysIncluded)

Specified by:

setDelaysIncluded in interface DESystem

Parameters:

delaysIncluded - Determines whether delay expression should be included in the calculation.