broadwick.stochastic

Class StochasticSimulator

java.lang.Object

broadwick.stochastic.StochasticSimulator

Direct Known Subclasses:

AbstractTauLeapingBase, GillespieSimple

public abstract class StochasticSimulator
extends Object

Base class for stochastic simulators. Extending classes just have to implement performStep which gets invoked as long as the simulation is running. They also may override init but should in that case call super.init() to avoid unwanted effects.

Simulators also should handle the special time theta: is is a moment in time when doThetaEvent is supposed to be invoked (e.g. to measure species populations at this moment). Consider this, if you want to implement a simulator.

The doEvent are supposed to be invoked when a simulator causes a reaction to fire.

If an extending class sticks to these conventions, it can take full benefit of the observers system: One or more Observer can be registered at a simulator and observe certain aspects of the simulation (see the Observers javadoc for more information).

Note that this class is NOT thread-safe. Consequently, if a simulation program uses multiple threads, it should acquire a lock on a simulator (using a synchronized block) before accessing its state. Note however, that one can launch many simulations in parallel with as many threads, as long as each thread has its own Simulator.

This class is mostly copied from the FERN projects stochastic classes and modified to fit into this framework.

See Also:

http://www.bio.ifi.lmu.de/FERN/

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	StochasticSimulator.ThetaQueue Manages the registered theta events.

Field Summary

Fields

Modifier and Type	Field and Description
private AmountManager	amountManager
private SimulationController	controller
private double	currentTime
private Set<Observer>	observers
protected boolean	reverseTime
private int	startTime
private StochasticSimulator.ThetaQueue	thetaQueue
private TransitionKernel	transitionKernel

Constructor Summary

Constructors

Constructor and Description
StochasticSimulator(AmountManager amountManager, TransitionKernel transitionKernel) Creates a new simulator using a given amount manager.
StochasticSimulator(AmountManager amountManager, TransitionKernel transitionKernel, boolean reverseTime) Creates a new simulator.

Method Summary

Modifier and Type	Method and Description
void	addObserver(Observer observer) Add an observer to the engines list of observers.
protected void	doEvent(SimulationEvent mu, double t) Fires a reaction.
protected void	doEvent(SimulationEvent event, double t, int n) Perform an event by informing the subscribed observers and the amountManager.
protected void	doThetaEvent() Gets called when the simulator reaches the predetermined time of a theta event.
Observer	getDefaultObserver() Get the default observer for the stochastic process.
abstract String	getName() Gets the name of the algorithm.
double	getNextThetaEventTime() Theta defines a moment, where the simulator has to invoke theta of a observers.
void	init() Initializes the algorithm.
abstract void	performStep() Performs one simulation step.
void	registerNewTheta(Observer obs, double thetaTime, Object event) Register a new theta event that is triggered at a given time.
abstract void	reinitialize() Reset propensities when a event has been executed.
void	run() Start the simulation with the given SimulationController.
void	run(double time) Starts the simulation up to a given time.
abstract void	setRngSeed(int seed) Seed the RNG if required.

Methods inherited from class java.lang.Object

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

Field Detail

startTime

private int startTime

transitionKernel

private TransitionKernel transitionKernel

amountManager

private AmountManager amountManager

currentTime

private double currentTime

controller

private SimulationController controller

thetaQueue

private StochasticSimulator.ThetaQueue thetaQueue

observers

private final Set<Observer> observers

reverseTime

protected boolean reverseTime

Constructor Detail

StochasticSimulator

public StochasticSimulator(AmountManager amountManager,
                           TransitionKernel transitionKernel)

Creates a new simulator using a given amount manager.

Parameters:

amountManager - the amount manager used in the simulator.

transitionKernel - the transition kernel to be used with the stochastic solver.

StochasticSimulator

public StochasticSimulator(AmountManager amountManager,
                           TransitionKernel transitionKernel,
                           boolean reverseTime)

Creates a new simulator.

Parameters:

amountManager - the amount manager used in the simulator.

transitionKernel - the transition kernel to be used with the stochastic solver.

reverseTime - true if we wish to go backwards in time.

Method Detail

run

public final void run(double time)

Starts the simulation up to a given time. It just uses a DefaultController and calls StochasticSimulator#start(SimulationController).

Parameters:

time - simulation time

run

public final void run()

Start the simulation with the given SimulationController.

init

public final void init()

Initializes the algorithm.

• set currentTime=0
• reset the AmountManager
• recalculate the propensities

Gets called at the very beginning of start

doEvent

protected final void doEvent(SimulationEvent mu,
                             double t)

Fires a reaction. It calls the observers and the AmountManager.

Parameters:

mu - reaction to be fired.

t - time at which the firing occurs.

doEvent

protected final void doEvent(SimulationEvent event,
                             double t,
                             int n)

Perform an event by informing the subscribed observers and the amountManager.

Parameters:

event - event to be performed.

t - time at which the firing occurs.

n - the number of times mu is to be fired.

doThetaEvent

protected final void doThetaEvent()

Gets called when the simulator reaches the predetermined time of a theta event. All the observers for the events that are configured for this time are notified and given a list of events that are triggered.

addObserver

public final void addObserver(Observer observer)

Add an observer to the engines list of observers.

Parameters:

observer - the observer.

getNextThetaEventTime

public final double getNextThetaEventTime()

Theta defines a moment, where the simulator has to invoke theta of a observers. It is used e.g. to determine the amounts of species at one moments. Extending class just have to call Simulator#doThetaEvent() which basically calls the observers.

Returns:

the theta

registerNewTheta

public final void registerNewTheta(Observer obs,
                                   double thetaTime,
                                   Object event)

Register a new theta event that is triggered at a given time.

Parameters:

obs - the observers which is registering.

thetaTime - the time the theta event occurs.

event - the theta event.

getDefaultObserver

public final Observer getDefaultObserver()

Get the default observer for the stochastic process. The default observer is first one defined.

Returns:

the default observer.

reinitialize

public abstract void reinitialize()

Reset propensities when a event has been executed.

performStep

public abstract void performStep()

Performs one simulation step. Between steps the terminating condition is checked. The simulators controller is passed, if an extending class wants to check it within one step. Implementing algorithms cannot be sure that the propensities are correct at the beginning of a step (e.g. if the volume changed). They should override Simulator#setAmount(int, long) and Simulator#setVolume(double) if they need correct values!

getName

public abstract String getName()

Gets the name of the algorithm.

Returns:

name of the algorithm

setRngSeed

public abstract void setRngSeed(int seed)

Seed the RNG if required.

Parameters:

seed - the RNG seed.