org.simulator.sbml
Class SBMLinterpreter

java.lang.Object
  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: 332 $

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.

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

double	compileReaction(int reactionIndex)
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()
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.
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)
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

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

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)

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)

Parameters:

reactionIndex - index of the reaction

Returns:

the current reaction velocity of a specific reaction