Simulation Core Library

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: 454 $
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  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.
SBMLinterpreter(Model model, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue)
           
SBMLinterpreter(Model model, double defaultSpeciesValue, double defaultParameterValue, double defaultCompartmentValue, Map<String,Boolean> amountHash)
          Creates a new SBMLinterpreter
 
Method Summary
 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.
 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)
           
 boolean removeConstraintListener(ConstraintListener listener)
          Removes the given ConstraintListener from this interpreter.
 ConstraintListener removeConstraintListener(int index)
          Removes the ConstraintListener with the given index 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 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 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

SBMLinterpreter

public SBMLinterpreter(Model model,
                       double defaultSpeciesValue,
                       double defaultParameterValue,
                       double defaultCompartmentValue)
                throws SBMLException,
                       ModelOverdeterminedException
Parameters:
model -
defaultSpeciesValue -
defaultParameterValue -
defaultCompartmentValue -
Throws:
SBMLException
ModelOverdeterminedException

SBMLinterpreter

public SBMLinterpreter(Model model,
                       double defaultSpeciesValue,
                       double defaultParameterValue,
                       double defaultCompartmentValue,
                       Map<String,Boolean> amountHash)
                throws SBMLException,
                       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:
SBMLException
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 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:
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 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 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 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 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:
value

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

init

public void init(boolean renewTree,
                 double defaultSpeciesValue,
                 double defaultParameterValue,
                 double defaultCompartmentValue,
                 Map<String,Boolean> amountHash)
          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, give some default values and state whether a Species is seen as an amount or a concentration.

Parameters:
renewTree -
defaultSpeciesValue -
defaultParameterValue -
defaultCompartmentValue -
amountHash -
Throws:
ModelOverdeterminedException
SBMLException

processAssignmentRules

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

processInitialAssignments

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

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

processRules

public boolean processRules(double time,
                            double[] changeRate,
                            double[] Y,
                            boolean initialCalculations)
                     throws 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:
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:
changeRate - An array containing the rates of change for each species in the model system of this class.
time -
Throws:
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.

Generated at March 17 2014
Version 1.4 Revision 453