org.simulator.sbml
Class SBMLinterpreter

java.lang.Object
  extended by org.simulator.sbml.SBMLinterpreter
All Implemented Interfaces:
Serializable, 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: 203 $
Author:
Alexander Dörr, Andreas Dräger, Roland Keller, Dieudonné Motsou Wouamba
See Also:
Serialized Form

Field Summary
protected  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  List<Double>[] listOfContraintsViolations
          An array, which stores for each constraint the list of times, in which the constraint was violated during the simulation.
protected  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
SBMLinterpreter(Model model)
           This constructs a new DESystem for the given SBML Model.
 
Method Summary
 double compileReaction(int reactionIndex)
          Returns the current reaction velocity of a specific reaction
 double computeDelayedValue(double time, String id)
          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()
           
 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.
 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.
 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 getNumAdditionalValues()
          Gives the number of intermediate results that are computed by this class.
 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.
 boolean processAssignmentRules(double t, double[] Y)
           
 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)
           
 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 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.


listOfContraintsViolations

protected List<Double>[] listOfContraintsViolations
An array, which stores for each constraint the list of times, in which the constraint was violated during the simulation.


model

protected 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(Model model)
                throws ModelOverdeterminedException,
                       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:
ModelOverdeterminedException
SBMLException
Method Detail

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 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 (#getValue(double, double[], double[])) 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:
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 -
val -
Returns:

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:

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:

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:

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:

getDimension

public int getDimension()
Specified by:
getDimension in interface FirstOrderDifferentialEquations

getNextEventAssignments

public EventInProgress getNextEventAssignments(double t,
                                               double previousTime,
                                               double[] Y)
                                        throws 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:
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 #getDESystemDimension(). 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 Model getModel()
Returns the model that is used by this object.

Returns:
Returns the model that is used by this object.

getNumAdditionalValues

public int getNumAdditionalValues()
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:
getNumAdditionalValues 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:

computeDerivatives

public void computeDerivatives(double time,
                               double[] Y,
                               double[] changeRate)
                        throws DerivativeException
Specified by:
computeDerivatives in interface FirstOrderDifferentialEquations
Throws:
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:

init

public void init()
          throws ModelOverdeterminedException,
                 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:
ModelOverdeterminedException
SBMLException

init

public void init(boolean refreshTree)
          throws ModelOverdeterminedException,
                 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:
ModelOverdeterminedException
SBMLException

init

public void init(boolean renewTree,
                 double defaultSpeciesValue,
                 double defaultParameterValue,
                 double defaultCompartmentValue)
          throws ModelOverdeterminedException,
                 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:
ModelOverdeterminedException
SBMLException

processAssignmentRules

public boolean processAssignmentRules(double t,
                                      double[] Y)
                               throws DerivativeException
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:
DerivativeException

processInitialAssignments

public void processInitialAssignments(double time,
                                      double[] Y)
                               throws SBMLException
Processes the initial assignments

Parameters:
the - ASTNode time
the - Y vector
Throws:
SBMLException

processRules

public boolean processRules(double time,
                            double[] changeRate,
                            double[] Y,
                            boolean initialCalculations)
                     throws SBMLException
Processes the rules

Parameters:
the - current time
the - changeRate vector
the - Y vector
Returns:
flag that is true if there has been some change caused by any rule
Throws:
SBMLException

processVelocities

protected void processVelocities(double[] changeRate,
                                 double time)
                          throws 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:
velocities - An array of reaction velocities at the current time.
Y -
Throws:
SBMLException

setFastProcessComputation

public void setFastProcessComputation(boolean isProcessing)
Specified by:
setFastProcessComputation in interface FastProcessDESystem

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:

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

computeDelayedValue

public double computeDelayedValue(double time,
                                  String id)
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
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)
Returns the current reaction velocity of a specific reaction

Parameters:
index - of the reaction
Returns: