hSimulator.library
Class Simulator

java.lang.Object
  extended by hSimulator.library.Simulator

public class Simulator
extends Object

This object implements an optimized, multithread model simulator. Optimized multithreading implementation of many simulation algorithms are provided (exact stochastic, deterministic and hybrid).

Version:
1.0
Author:
Luca Marchetti

Constructor Summary
Simulator(Model m)
          Creates a new model simulator.
Simulator(Model m, int nThreads)
          Creates a new model simulator.
 
Method Summary
 double getCompletedPercentage()
          Returns the percentage of calculation that has been completed on average by each simulation task.
 int getMaxNumberOfSteps()
          Returns the maximum number of steps that the simulator can compute.
 boolean isSimulationPaused()
          Returns if the simulation process has been paused.
 void pauseSimulation()
          Pauses a simulation process before its completion.
 void resumeSimulation()
          Resumes a (paused) simulation process.
 void setMaxNumberOfSteps(int maxN)
          Sets the maximum number of steps that the simulator can compute.
 void shutDown()
          Shuts down the java service used for parallel computing.
 SimulatedTS simDM(int nSim, int tMax, double tsSampling)
          Simulates the model according to the Gillespie Direct Method (DM).
 SimulatedTS simDM(int nSim, List<String> varsToBeSaved, int tMax, double tsSampling)
          Simulates the model according to the Gillespie Direct Method (DM).
 SimulatedTS simEuler(int tMax, double dT, double tsSampling)
          Simulates the model according to the Euler deterministic algorithm.
 SimulatedTS simEuler(List<String> varsToBeSaved, int tMax, double dT, double tsSampling)
          Simulates the model according to the Euler deterministic algorithm.
 SimulatedTS simHRSSA(int nSim, int tMax, double delta, int epsilon, int gamma, int theta, double dT, double tsSampling)
          Simulates the model according to the Hybrid Rejection-based Stochastic Simulation Algorithm (HRSSA).
 SimulatedTS simHRSSA(int nSim, List<String> varsToBeSaved, int tMax, double delta, int epsilon, int gamma, int theta, double dT, double tsSampling)
          Simulates the model according to the Hybrid Rejection-based Stochastic Simulation Algorithm (HRSSA).
 SimulatedTS simRK45(int tMax, double initialDT, double maxErr, double tsSampling)
          Simulates the model according to the Runge-Kutta-Fehlberg (RK45) deterministic algorithm.
 SimulatedTS simRK45(List<String> varsToBeSaved, int tMax, double initialDT, double maxErr, double tsSampling)
          Simulates the model according to the Runge-Kutta-Fehlberg (RK45) deterministic algorithm.
 SimulatedTS simRSSA(int nSim, int tMax, double delta, int epsilon, double tsSampling)
          Simulates the model according to the Rejection-based Stochastic Simulation Algorithm (RSSA).
 SimulatedTS simRSSA(int nSim, List<String> varsToBeSaved, int tMax, double delta, int epsilon, double tsSampling)
          Simulates the model according to the Rejection-based Stochastic Simulation Algorithm (RSSA).
 void stopSimulation()
          Stops a simulation process before its completion.
 String toString()
          Returns the textual specification of the model that is simulated.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Simulator

public Simulator(Model m)
Creates a new model simulator. The size of the thread pool used for parallel computation is equal to the number of available processors.

Parameters:
m - the model that will be simulated
See Also:
Model

Simulator

public Simulator(Model m,
                 int nThreads)
Creates a new model simulator.

Parameters:
m - the model that will be simulated
nThreads - size of the thread pool used for parallel computation
See Also:
Model
Method Detail

shutDown

public void shutDown()
Shuts down the java service used for parallel computing. This method should be called when this object instance will be not used anymore.


setMaxNumberOfSteps

public void setMaxNumberOfSteps(int maxN)
Sets the maximum number of steps that the simulator can compute. This value can be used to prevent deadlocks. The default value is Integer.MAX_VALUE

Parameters:
maxN - the maximum number of steps

getMaxNumberOfSteps

public int getMaxNumberOfSteps()
Returns the maximum number of steps that the simulator can compute.

Returns:
the maximum number of steps

toString

public String toString()
Returns the textual specification of the model that is simulated.

Overrides:
toString in class Object
Returns:
the textual representation

getCompletedPercentage

public double getCompletedPercentage()
Returns the percentage of calculation that has been completed on average by each simulation task.

Returns:
the percentage of calculation

simEuler

public SimulatedTS simEuler(int tMax,
                            double dT,
                            double tsSampling)
                     throws ExecutionException,
                            SimulationStoppedException
Simulates the model according to the Euler deterministic algorithm. The returned SimulatedTS object will store all the computed time series.

Parameters:
tMax - maximum time instant to be simulated
dT - discretization step
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simEuler

public SimulatedTS simEuler(List<String> varsToBeSaved,
                            int tMax,
                            double dT,
                            double tsSampling)
                     throws ExecutionException,
                            SimulationStoppedException
Simulates the model according to the Euler deterministic algorithm. Variable IDs has to be indicated according to the following notation: variableName + Model.variableCompartmentSeparator + compartmentName.

Parameters:
varsToBeSaved - the list of variable IDs whose time series will be stored in the SimulatedTS object
tMax - maximum time instant to be simulated
dT - discretization step
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simRK45

public SimulatedTS simRK45(int tMax,
                           double initialDT,
                           double maxErr,
                           double tsSampling)
                    throws ExecutionException,
                           SimulationStoppedException
Simulates the model according to the Runge-Kutta-Fehlberg (RK45) deterministic algorithm. The returned SimulatedTS object will store all the computed time series.

Parameters:
tMax - maximum time instant to be simulated
initialDT - initial discretization step
maxErr - maximum error admitted during the computation of the dynamics
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simRK45

public SimulatedTS simRK45(List<String> varsToBeSaved,
                           int tMax,
                           double initialDT,
                           double maxErr,
                           double tsSampling)
                    throws ExecutionException,
                           SimulationStoppedException
Simulates the model according to the Runge-Kutta-Fehlberg (RK45) deterministic algorithm. Variable IDs has to be indicated according to the following notation: variableName + Model.variableCompartmentSeparator + compartmentName.

Parameters:
varsToBeSaved - the list of variable IDs whose time series will be stored in the SimulatedTS object
tMax - maximum time instant to be simulated
initialDT - initial discretization step
maxErr - maximum error admitted during the computation of the dynamics
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simDM

public SimulatedTS simDM(int nSim,
                         int tMax,
                         double tsSampling)
                  throws ExecutionException,
                         SimulationStoppedException
Simulates the model according to the Gillespie Direct Method (DM). The returned SimulatedTS object will store all the computed time series.

Parameters:
nSim - number of parallel simulations that will be computed
tMax - maximum time instant to be simulated
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simDM

public SimulatedTS simDM(int nSim,
                         List<String> varsToBeSaved,
                         int tMax,
                         double tsSampling)
                  throws ExecutionException,
                         SimulationStoppedException
Simulates the model according to the Gillespie Direct Method (DM). Variable IDs has to be indicated according to the following notation: variableName + Model.variableCompartmentSeparator + compartmentName.

Parameters:
nSim - number of parallel simulations that will be computed
varsToBeSaved - the list of variable IDs whose time series will be stored in the SimulatedTS object
tMax - maximum time instant to be simulated
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simRSSA

public SimulatedTS simRSSA(int nSim,
                           int tMax,
                           double delta,
                           int epsilon,
                           double tsSampling)
                    throws ExecutionException,
                           SimulationStoppedException
Simulates the model according to the Rejection-based Stochastic Simulation Algorithm (RSSA). The returned SimulatedTS object will store all the computed time series.

Parameters:
nSim - number of parallel simulations that will be computed
tMax - maximum time instant to be simulated
delta - delta for calculating the fluctuation interval of variable states
epsilon - minimum size of fluctuation intervals
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simRSSA

public SimulatedTS simRSSA(int nSim,
                           List<String> varsToBeSaved,
                           int tMax,
                           double delta,
                           int epsilon,
                           double tsSampling)
                    throws ExecutionException,
                           SimulationStoppedException
Simulates the model according to the Rejection-based Stochastic Simulation Algorithm (RSSA). Variable IDs has to be indicated according to the following notation: variableName + Model.variableCompartmentSeparator + compartmentName.

Parameters:
nSim - number of parallel simulations that will be computed
varsToBeSaved - the list of variable IDs whose time series will be stored in the SimulatedTS object
tMax - maximum time instant to be simulated
delta - delta for calculating the fluctuation interval of variable states
epsilon - minimum size of fluctuation intervals
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simHRSSA

public SimulatedTS simHRSSA(int nSim,
                            int tMax,
                            double delta,
                            int epsilon,
                            int gamma,
                            int theta,
                            double dT,
                            double tsSampling)
                     throws ExecutionException,
                            SimulationStoppedException
Simulates the model according to the Hybrid Rejection-based Stochastic Simulation Algorithm (HRSSA). The returned SimulatedTS object will store all the computed time series.

Parameters:
nSim - number of parallel simulations that will be computed
tMax - maximum time instant to be simulated
delta - delta for calculating the fluctuation interval of variable states
epsilon - minimum size of fluctuation intervals
gamma - minimum molecule number of fast reactions
theta - minimum number of reaction firing of fast reactions
dT - discretization step used to simulate fast reactions
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

simHRSSA

public SimulatedTS simHRSSA(int nSim,
                            List<String> varsToBeSaved,
                            int tMax,
                            double delta,
                            int epsilon,
                            int gamma,
                            int theta,
                            double dT,
                            double tsSampling)
                     throws ExecutionException,
                            SimulationStoppedException
Simulates the model according to the Hybrid Rejection-based Stochastic Simulation Algorithm (HRSSA). Variable IDs has to be indicated according to the following notation: variableName + Model.variableCompartmentSeparator + compartmentName.

Parameters:
nSim - number of parallel simulations that will be computed
varsToBeSaved - the list of variable IDs whose time series will be stored in the SimulatedTS object
tMax - maximum time instant to be simulated
delta - delta for calculating the fluctuation interval of variable states
epsilon - minimum size of fluctuation intervals
gamma - minimum molecule number of fast reactions
theta - minimum number of reaction firing of fast reactions
dT - discretization step used to simulate fast reactions
tsSampling - the time sampling used for storing time series in the SimulatedTS object
Returns:
the time series of computed dynamics (average of the dynamics computed by each simulation task)
Throws:
ExecutionException - if an error occurred during the simulation process
SimulationStoppedException - if the simulation process has been prematurely stopped by means of the stopSimulation() method

stopSimulation

public void stopSimulation()
Stops a simulation process before its completion.


pauseSimulation

public void pauseSimulation()
Pauses a simulation process before its completion. A paused simulation can be resumed by means of the method resumeSimulation() or definitively stopped by means of the method stopSimulation().


isSimulationPaused

public boolean isSimulationPaused()
Returns if the simulation process has been paused.

Returns:
a boolean indicating if the simulation process has been paused

resumeSimulation

public void resumeSimulation()
Resumes a (paused) simulation process.