Class EvoLudo

Object

EvoLudo

All Implemented Interfaces:

MersenneTwister.Chronometer, CLOProvider

Direct Known Subclasses:

EvoLudoGWT

public abstract class EvoLudo
extends Object
implements CLOProvider, MersenneTwister.Chronometer

Interface with the outside world. Deals with command line options, help, encoding/restoring state, logging, printing of result, etc. GWT/JRE neutral abstract implementation of interface between EvoLudo core and GUI interface. JRE specific code relegated to EvoLudoJRE and GWT specific code to EvoLudoGWT. Two distinct implementations are required e.g. because of significant differences in input/output routines.

Author:

Christoph Hauert

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	EvoLudo.Directive	The interface to execute commands in a manner that is agnostic to the implementation details regarding GWT or JRE environments.

Field Summary

Fields

Modifier and Type	Field	Description
protected Model	activeModel	The active model
protected Module<?>	activeModule	The active module.
protected List<ChangeListener>	changeListeners	List of change listeners that get notified when the model changes.
protected String	clo	The command line options (raw string provided in URL, HTML tag, TextArea or command line)
protected final CLOController	cloController	Controller for command line option parsing.
final CLOption	cloRun	Command-line option controlling the number of model runs.
final CLOption	cloSeed	Command-line option controlling the RNG seed.
static final String	COPYRIGHT	The copyright string.
protected static final double	DELAY_INCR	Delay decrement for speed slider Slider
static final double	DELAY_INIT	Initial delay between subsequent updates for speed slider Slider
static final double	DELAY_MAX	Maximum delay between subsequent updates for speed slider Slider
static final double	DELAY_MIN	Minimum delay between subsequent updates for speed slider Slider
final int	ID	Unique ID of EvoLudo instance.
private static int	IDcounter	The loggers of each EvoLudo lab instance need to have unique names to keep the logs separate.
(package private) static boolean	isGWT	The flag to indicate whether EvoLudo is running in a web browser (or ePub) using javascript generated by GWT or in the java JRE.
protected boolean	isRunning	The flag to indicate whether the active model is running.
protected boolean	isSuspended	The flag to indicate whether running of the model is suspended.
protected final LifecycleController	lifecycleController	Controller for lifecycle listeners.
protected Logger	logger	The logger for keeping track of and reporting events and issues.
protected HashMap<String, Module<?>>	modules	The lookup table for all available modules.
protected ChangeListener.PendingAction	pendingAction	The action that is pending (if any).
protected boolean	resetRequested	The flag to indicate whether a reset of the active model has been requested.
protected RNGDistribution	rng	The shared random number generator to ensure reproducibility of results.
protected final RunController	runController	Controller for run listeners.
protected List<SampleListener>	sampleListeners	List of change listeners that get notified when the model changes.
protected int	snapLayoutTimeout	timeout for layout process of snapshots in msec.
protected final StateEncoder	stateEncoder	Responsible for encoding/restoring state and handling version reporting.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	EvoLudo()	Create an instance of the EvoLudo controller.

Method Summary

Modifier and Type	Method	Description
void	addChangeListener(ChangeListener newListener)	Add a change listener to the list of listeners that get notified when the model changes.
void	addCLOProvider(CLOProvider provider)	Register clo as a provider of command line options.
void	addLifecycleListener(LifecycleListener newListener)	Add a lifecycle listener to the list of listeners that get notified when the model reaches lifecycle milestones.
void	addModule(Module<?> module)	Add module to lookup table of modules using the module's key.
void	addRunListener(RunListener newListener)	Add a run listener to the list of listeners that get notified about model run state changes.
void	addSampleListener(SampleListener newListener)	Add a change listener to the list of listeners that get notified when the model changes.
void	collectCLO(CLOParser prsr)	All providers of command line options must implement this method to collect their options.
abstract Network2D	createNetwork2D(AbstractGeometry geometry)	Generate 2D network.
abstract Network3D	createNetwork3D(AbstractGeometry geometry)	Generate 3D network.
void	debug()	Advances the EvoLudo model by a single debugging step.
void	decreaseDelay()	Decrease delay between subsequent updates by fixed factor.
String	encodeState()	Encode current state of EvoLudo model as XML string (plist format).
abstract void	execute(EvoLudo.Directive directive)	Execute directive in JRE or GWT environments.
abstract void	exportState()	Export the current state of the engine using the appropriate means available in the current environment (GWT/JRE).
void	fatal(String msg)	Report error and stop model execution, if running.
void	fireModelChanged()	Called whenever the state of the model has changed.
void	fireModelInit()	Called after the model has been re-initialized.
void	fireModelLoaded()	Called whenever a new model has finished loading.
void	fireModelRelaxed()	Called after the model completed its relaxation.
void	fireModelReset()	Called after the model has been reset.
void	fireModelRunning()	Called whenever the model starts its calculations.
boolean	fireModelSample(boolean success)	Called after the population has reached an absorbing state (or has converged to an equilibrium state).
void	fireModelStopped()	Called after the population has reached an absorbing state (or has converged to an equilibrium state).
void	fireModelUnloaded()	Called whenever a new model has finished loading.
void	fireModuleLoaded()	Called whenever a new module has finished loading.
void	fireModuleRestored()	Called after the state of the model has been restored either through drag'n'drop with the GWT GUI or through the --restore command line argument.
void	fireModuleUnloaded()	Called whenever the current module has finished unloading.
void	fireSettingsChanged()	Called whenever the settings of the model have changed.
String	getCLO()	Get the raw command line options, as provided in URL, HTML tag, settings TextArea or command line.
String	getCLOHelp()	Format, encode and output help on command line options.
CLOption	getCloModuleOption()	Access the module command line option.
int	getDelay()	Get delay between subsequent updates.
abstract String	getGit()	Gets current git version of code base.
abstract String	getGitDate()	Gets the compilation date of the current git version.
String	getJavaVersion()	Get version of JRE (if not running in browser).
Logger	getLogger()	Note: Instead of sharing logging system, EvoLudo could implement helper routines for logging notifications.
Model	getModel()	Get the active model.
Module<?>	getModule()	Gets the active Module.
RNGDistribution	getRNG()	Get the shared random number generator to ensure the reproducibility of results.
int	getSnapLayoutTimeout()	Gets the timeout for the layout process of snapshots in msec.
String[]	getSplitCLO()	Get the command line options split into an array with option names followed by their arguments (if applicable).
String	getVersion()	Return version string of current model.
abstract PDESupervisor	hirePDESupervisor(PDE charge)	Hire supervisor for managing PDE calculations.
void	increaseDelay()	Increase delay between subsequent updates by fixed factor.
boolean	isRunning()	Check if the active model is running.
boolean	isSuspended()	Check whether the current model is suspended.
void	layoutComplete()	Notification from GUI that layout process has finished.
void	loadModel(ModelType type)	Set model type and loads the corresponding frameworks for individual based simulations or numerical integration of ODE/SDE/PDE models.
boolean	loadModule(String newModuleKey)	Load new module with key newModuleKey.
void	loadModules()	Load all available modules.
void	logError(String msg)	Convenience method to log errors of simulations.
void	logMessage(String msg)	Convenience method to log messages of simulations.
abstract void	logProgress(String msg)	Utility method to log progress of simulations.
void	logWarning(String msg)	Convenience method to log warnings of simulations.
final boolean	modelCheck()	Check consistency of parameters in all populations.
final void	modelInit()	Initialize all populations and notify all listeners.
final void	modelInit(boolean quiet)	Initialize all populations and notify all listeners if requested.
final boolean	modelNext()	Advance model by one step (reportFreq updates) and notify all listeners.
final boolean	modelNextDone(boolean cont)	Called after the calculations of the next state of the model have finished.
final boolean	modelRelax()	Relax model by timeRelax steps and notify all listeners when done.
final boolean	modelRelax(boolean quiet)	Relax model by timeRelax steps and notify all listeners if requested.
final void	modelReset()	Reset all populations and notify all listeners.
final void	modelReset(boolean quiet)	Reset all populations and notify all listeners if requested.
abstract void	next()	Advances the EvoLudo model by a single step.
boolean	paramsDidChange()	Called after parameters have changed.
int	parseCLO()	Parse command line options.
protected int	parseCLO(String[] cloarray)	Pre-process and parse array of command line arguments.
protected String[]	preprocessCLO(String[] cloarray)	Pre-process array of command line arguments.
void	prev()	Attempts to backtrack a single step of the EvoLudo model.
(package private) void	processPendingAction()	Helper to process pending actions.
void	removeChangeListener(ChangeListener obsoleteListener)	Remove the change listener from the list of listeners that get notified when the model changes.
void	removeCLOProvider(CLOProvider provider)	Unregister clo as a provider of command line options.
void	removeLifecycleListener(LifecycleListener obsoleteListener)	Remove the lifecycle listener from the list of listeners that get notified when the model reaches lifecycle milestones.
void	removeRunListener(RunListener obsoleteListener)	Remove the run listener from the list of listeners that get notified when the model run state changes.
void	removeSampleListener(SampleListener obsoleteListener)	Remove the change listener from the list of listeners that get notified when the model changes.
void	requestAction(ChangeListener.PendingAction action)	Requests a ChangeListener.PendingAction to be processed on the next opportunity.
void	requestAction(ChangeListener.PendingAction action, boolean now)	Requests a ChangeListener.PendingAction to be processed on the next opportunity.
void	requestParseCLO()	Request full reparsing of the command line options.
void	requiresReset(boolean reset)	Request reset the active model, e.g.
abstract boolean	restoreFromFile()	Restore state of EvoLudo model from saved plist, which encodes engine state.
boolean	restoreState(Plist plist)	Restore state of EvoLudo model from pre-processed plist, which encodes engine state (see encodeState()).
abstract void	run()	Start the EvoLudo model and calculate the dynamics one step at a time.
void	setCLO(String clo)	Set the raw command line options, as shown e.g.
void	setDelay(int delay)	Set delay between subsequent updates.
void	setSuspended(boolean suspend)	Set the flag indicating whether the model is suspended.
abstract void	showHelp()	Show help on command line options.
void	simulation()	Run simulation.
void	startStop()	Start or stop EvoLudo model.
void	stop()	Requests halting of a running Model on the next opportunity.
void	unloadModel()	Unload model framework.
void	unloadModel(boolean quiet)	Unload model framework and, if requested, notifies all registered LifecycleListeners.
void	unloadModule()	Unload current module to free up resources.
void	writeFooter()	Concluding words for report (currently JRE only).
void	writeHeader()	Write header of report to output (currently JRE only).

Methods inherited from class Object

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

Methods inherited from interface CLOProvider

adjustCLO

Methods inherited from interface MersenneTwister.Chronometer

elapsedTimeMsec

Field Details

isGWT

static boolean isGWT

The flag to indicate whether EvoLudo is running in a web browser (or ePub) using javascript generated by GWT or in the java JRE. Special characters in strings can result in headaches when running in an ePub (or, worse still, in XHTML pages).

true when running as GWT application; false for JRE applications.

IDcounter

private static int IDcounter

The loggers of each EvoLudo lab instance need to have unique names to keep the logs separate. Use IDcounter to generate unique ID's.

ID

public final int ID

Unique ID of EvoLudo instance.

See Also:

• IDcounter

logger

protected Logger logger

The logger for keeping track of and reporting events and issues.

rng

protected RNGDistribution rng

The shared random number generator to ensure reproducibility of results.

See Also:

• getRNG()

modules

protected HashMap<String, Module<?>> modules

The lookup table for all available modules.

activeModel

protected Model activeModel

The active model

resetRequested

protected boolean resetRequested

The flag to indicate whether a reset of the active model has been requested. This is necessary after certain parameter changes. For example, changing the population size (see IBSPopulation.nPopulation) requires a reset to (re)generate population geometries and initialize traits.

cloController

protected final CLOController cloController

Controller for command line option parsing.

cloSeed

public final CLOption cloSeed

Command-line option controlling the RNG seed.

cloRun

public final CLOption cloRun

Command-line option controlling the number of model runs.

lifecycleController

protected final LifecycleController lifecycleController

Controller for lifecycle listeners.

runController

protected final RunController runController

Controller for run listeners.

changeListeners

protected List<ChangeListener> changeListeners

List of change listeners that get notified when the model changes.

sampleListeners

protected List<SampleListener> sampleListeners

List of change listeners that get notified when the model changes.

clo

protected String clo

The command line options (raw string provided in URL, HTML tag, TextArea or command line)

DELAY_MIN

public static final double DELAY_MIN

Minimum delay between subsequent updates for speed slider Slider

See Also:

• Constant Field Values

DELAY_MAX

public static final double DELAY_MAX

Maximum delay between subsequent updates for speed slider Slider

See Also:

• Constant Field Values

DELAY_INIT

public static final double DELAY_INIT

Initial delay between subsequent updates for speed slider Slider

See Also:

• Constant Field Values

DELAY_INCR

protected static final double DELAY_INCR

Delay decrement for speed slider Slider

See Also:

• Constant Field Values

isSuspended

protected boolean isSuspended

The flag to indicate whether running of the model is suspended. For example while parameters are being applied. If the changes do not require a reset of the model the calculations are resumed after new parameters are applied. Also used when command line options are set to immediately start running after loading (see CLOController.cloRun).

activeModule

protected Module<?> activeModule

The active module.

isRunning

protected boolean isRunning

The flag to indicate whether the active model is running.

pendingAction

protected ChangeListener.PendingAction pendingAction

The action that is pending (if any).

COPYRIGHT

public static final String COPYRIGHT

The copyright string.

See Also:

• Constant Field Values

stateEncoder

protected final StateEncoder stateEncoder

Responsible for encoding/restoring state and handling version reporting.

snapLayoutTimeout

protected int snapLayoutTimeout

timeout for layout process of snapshots in msec.

Constructor Details

EvoLudo

protected EvoLudo()

Create an instance of the EvoLudo controller. EvoLudo manages different module/model implementations and the connection between simulations/numerical calculations and the GUI interface as well as the execution environment. This includes logging (verbosity and output channels), restoring previously saved engine states as well saving the current state of the engine, export its data or graphical snapshots.

Method Details

logProgress

public abstract void logProgress(String msg)

Utility method to log progress of simulations. For implementation details see EvoLudoJRE and EvoLudoGWT

Parameters:

msg - progress message

logMessage

public void logMessage(String msg)

Convenience method to log messages of simulations.

Parameters:

msg - information message

logWarning

public void logWarning(String msg)

Convenience method to log warnings of simulations.

Parameters:

msg - warning message

logError

public void logError(String msg)

Convenience method to log errors of simulations.

Parameters:

msg - error message

getRNG

public RNGDistribution getRNG()

Get the shared random number generator to ensure the reproducibility of results. This is the only RNG that MUST be used for all calculation, i.e. must be shared with all models including distributions (e.g. for mutations, migration...)

Important:

1. Must be used for any random numbers related to the modelling.
2. Must not be used for anything else, e.g. shared with layout procedures for networks (although it may be desirable to set a seed for the layout routines in a consistent manner if one was set for the simulations, to also ensure visual reproducibility).
3. If the number of random numbers drawn changes, any corresponding test fails almost certainly. Tests pass only if the results are identical.

Returns:

the one and only random number generator for modelling

See Also:

• RNGDistribution

createNetwork2D

public abstract Network2D createNetwork2D(AbstractGeometry geometry)

Generate 2D network. This is the factory method to provide different implementations for GWT and JRE. More specifically, the layouting process in GWT uses scheduling (asynchronous execution) to prevent the GUI from stalling, while JRE implementations take advantage of multiple threads for significantly faster execution due to parallelization.

Parameters:

geometry - the geometry backing the 2D network

Returns:

new instance of a 2D network

createNetwork3D

public abstract Network3D createNetwork3D(AbstractGeometry geometry)

Generate 3D network. This is the factory method to provide different implementations for GWT and JRE. More specifically, the layouting process in GWT uses scheduling (asynchronous execution) to prevent the GUI from stalling, while JRE implementations take advantage of multiple threads for significantly faster execution due to parallelization.

Note: The java3d package is obsolete. At present no 3D implementation for java exists.

Parameters:

geometry - the geometry backing the 3D network

Returns:

new instance of a 3D network

loadModel

public void loadModel(ModelType type)

Set model type and loads the corresponding frameworks for individual based simulations or numerical integration of ODE/SDE/PDE models. Notifies all registered LifecycleListeners of any changes.

Parameters:

type - the type of Model to load

getModel

public Model getModel()

Get the active model.

Returns:

the active model

requiresReset

public void requiresReset(boolean reset)

Request reset the active model, e.g. after change of parameters.

Parameters:

reset - true if reset is requested

requestParseCLO

public void requestParseCLO()

Request full reparsing of the command line options. This is necessary if the command line options have changed in a fundamental way, for example if the number of traits in a module has changed.

addLifecycleListener

public void addLifecycleListener(LifecycleListener newListener)

Add a lifecycle listener to the list of listeners that get notified when the model reaches lifecycle milestones.

Parameters:

newListener - the new lifecycle listener

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener obsoleteListener)

Remove the lifecycle listener from the list of listeners that get notified when the model reaches lifecycle milestones.

Parameters:

obsoleteListener - the listener to remove from list of lifecycle listeners

addRunListener

public void addRunListener(RunListener newListener)

Add a run listener to the list of listeners that get notified about model run state changes.

Parameters:

newListener - the new run listener

removeRunListener

public void removeRunListener(RunListener obsoleteListener)

Remove the run listener from the list of listeners that get notified when the model run state changes.

Parameters:

obsoleteListener - the listener to remove from list of run listeners

addChangeListener

public void addChangeListener(ChangeListener newListener)

Add a change listener to the list of listeners that get notified when the model changes.

Parameters:

newListener - the new change listener

removeChangeListener

public void removeChangeListener(ChangeListener obsoleteListener)

Remove the change listener from the list of listeners that get notified when the model changes.

Parameters:

obsoleteListener - the listener to remove from the list of change listeners

addSampleListener

public void addSampleListener(SampleListener newListener)

Add a change listener to the list of listeners that get notified when the model changes.

Parameters:

newListener - the new change listener

removeSampleListener

public void removeSampleListener(SampleListener obsoleteListener)

Remove the change listener from the list of listeners that get notified when the model changes.

Parameters:

obsoleteListener - the listener to remove from the list of change listeners

unloadModel

public void unloadModel()

Unload model framework. Notifies all registered LifecycleListeners.

unloadModel

public void unloadModel(boolean quiet)

Unload model framework and, if requested, notifies all registered LifecycleListeners.

Parameters:

quiet - set to true to skip notifying listeners

modelCheck

public final boolean modelCheck()

Check consistency of parameters in all populations.

Note: in multi-species interactions optimizations seem sensible only if all populations involved approve of them.

Returns:

true if reset is required

modelReset

public final void modelReset()

Reset all populations and notify all listeners.

modelReset

public final void modelReset(boolean quiet)

Reset all populations and notify all listeners if requested.

Note: if quiet == true statistics are preserved.

Parameters:

quiet - set to true to skip notifying listeners

modelInit

public final void modelInit()

Initialize all populations and notify all listeners.

modelInit

public final void modelInit(boolean quiet)

Initialize all populations and notify all listeners if requested. In contrast to modelReset(boolean) this method does not re-generate the population structures.

Parameters:

quiet - set to true to skip notifying listeners

modelRelax

public final boolean modelRelax()

Relax model by timeRelax steps and notify all listeners when done. If model converged during relaxation notify listeners that model has stopped.

Returns:

true if converged

See Also:

• Model.relax()

modelRelax

public final boolean modelRelax(boolean quiet)

Relax model by timeRelax steps and notify all listeners if requested.

Parameters:

quiet - set to true to skip notifying listeners

Returns:

true if converged

See Also:

• Model.relax()

modelNext

public final boolean modelNext()

Advance model by one step (reportFreq updates) and notify all listeners.

Returns:

true if not converged, i.e. if modelNext() can be called again.

modelNextDone

public final boolean modelNextDone(boolean cont)

Called after the calculations of the next state of the model have finished. For GWT this method serves as a callback for the asynchronous model computations. For JRE this runs in a separate thread from the GUI and modelNext() directly calls this.

Parameters:

cont - false if converged or halting time reached

Returns:

true if not converged, i.e. if modelNext() can be called again.

paramsDidChange

public boolean paramsDidChange()

Called after parameters have changed. Checks new settings and resets population(s) (and/or GUI) if necessary.

Returns:

true if reset was necessary

getCLO

public String getCLO()

Get the raw command line options, as provided in URL, HTML tag, settings TextArea or command line.

Returns:

command line options

getSplitCLO

public String[] getSplitCLO()

Get the command line options split into an array with option names followed by their arguments (if applicable).

Returns:

array command line options and arguments

setCLO

public void setCLO(String clo)

Set the raw command line options, as shown e.g. in the settings TextArea.

Parameters:

clo - the new command line option string

isSuspended

public boolean isSuspended()

Check whether the current model is suspended.

Returns:

true if model is suspended

setSuspended

public void setSuspended(boolean suspend)

Set the flag indicating whether the model is suspended. A suspended model resumes execution as soon as possible. For example after a new set parameters has been checked.

Parameters:

suspend - true to indicate that model is suspended.

setDelay

public void setDelay(int delay)

Set delay between subsequent updates.

Parameters:

delay - in milliseconds

getDelay

public int getDelay()

Get delay between subsequent updates.

Returns:

the delay in milliseconds

increaseDelay

public void increaseDelay()

Increase delay between subsequent updates by fixed factor.

decreaseDelay

public void decreaseDelay()

Decrease delay between subsequent updates by fixed factor.

loadModule

public boolean loadModule(String newModuleKey)

Load new module with key newModuleKey. If necessary first unload current module. Upon successful loading of a new module the method returns true. If newModuleKey is not found but an active module is present, the active module is kept and the method returns true. Without an active module the method returns false.

Parameters:

newModuleKey - the key of the module to load

Returns:

false if newModuleKey not found and no active module present; true otherwise

unloadModule

public void unloadModule()

Unload current module to free up resources.

Implementation note:

Called from loadModule(java.lang.String) to first unload the active module or triggered by GWT's EvoLudoWeb.onUnload(), i.e. when unloading the GWT application.

getModule

public Module<?> getModule()

Gets the active Module.

Returns:

the active module

getCloModuleOption

public CLOption getCloModuleOption()

Access the module command line option.

Returns:

the module option

addModule

public void addModule(Module<?> module)

Add module to lookup table of modules using the module's key. If a GUI is present, add GUI as a listener of module to get notified about state changes.

Parameters:

module - the module to add to lookup table

execute

public abstract void execute(EvoLudo.Directive directive)

Execute directive in JRE or GWT environments.

Parameters:

directive - the directive to execute in appropriate GWT or JRE manners

isRunning

public boolean isRunning()

Check if the active model is running.

Returns:

true if model is running

layoutComplete

public void layoutComplete()

Notification from GUI that layout process has finished. Opportunity for taking snapshots.

stop

public void stop()

Requests halting of a running Model on the next opportunity.

run

public abstract void run()

Start the EvoLudo model and calculate the dynamics one step at a time.

next

public abstract void next()

Advances the EvoLudo model by a single step. Called when pressing the 'Step' button, the 'n' or 'right-arrow' key.

startStop

public void startStop()

Start or stop EvoLudo model. If model is running wait until next update is completed to prevent unexpected side effects.

prev

public void prev()

Attempts to backtrack a single step of the EvoLudo model. Called when pressing the 'Prev' button, the 'p' or 'left-arrow' key.

debug

public void debug()

Advances the EvoLudo model by a single debugging step. Called when pressing the 'Debug' button or 'D' key.

simulation

public void simulation()

Run simulation. Currently only implemented by EvoLudoJRE. Returns control to caller only if the arguments in clo do not match requirements for running a simulation.

See Also:

• setCLO(String)
• EvoLudoJRE.simulation()

requestAction

public void requestAction(ChangeListener.PendingAction action)

Requests a ChangeListener.PendingAction to be processed on the next opportunity. If model is not running the action is processed immediately.

Parameters:

action - the action requested

requestAction

public void requestAction(ChangeListener.PendingAction action,
 boolean now)

Requests a ChangeListener.PendingAction to be processed on the next opportunity. If model is not running or now is set to true the action is processed immediately.

Parameters:

action - the action requested

now - true to processes action immediately

fireModuleLoaded

public void fireModuleLoaded()

Called whenever a new module has finished loading. Notifies all registered LifecycleListeners.

fireModuleUnloaded

public void fireModuleUnloaded()

Called whenever the current module has finished unloading. Notifies all registered LifecycleListeners.

fireModuleRestored

public void fireModuleRestored()

Called after the state of the model has been restored either through drag'n'drop with the GWT GUI or through the --restore command line argument. Notifies all registered LifecycleListeners.

See Also:

• restoreFromFile()
• restoreState(Plist)

fireModelLoaded

public void fireModelLoaded()

Called whenever a new model has finished loading. Notifies all registered LifecycleListeners.

fireModelUnloaded

public void fireModelUnloaded()

Called whenever a new model has finished loading. Notifies all registered LifecycleListeners.

fireModelRunning

public void fireModelRunning()

Called whenever the model starts its calculations. Fires only when starting to run. Notifies all registered RunListeners.

fireModelChanged

public void fireModelChanged()

Called whenever the state of the model has changed. For example, to trigger the update of the state displayed in the GUI. Processes pending actions and notifies all registered RunListeners.

See Also:

• RunListener
• ChangeListener.PendingAction

processPendingAction

void processPendingAction()

Helper to process pending actions. Delegates to RunController but exposed for subclasses that need to hook additional behavior.

fireModelSample

public boolean fireModelSample(boolean success)

Called after the population has reached an absorbing state (or has converged to an equilibrium state). Notifies all registered RunListeners.

Parameters:

success - true if sample completed successfully

Returns:

true to continue with next sample

See Also:

• SampleListener

fireSettingsChanged

public void fireSettingsChanged()

Called whenever the settings of the model have changed. For example, to trigger the range of values or markers in the GUI. Notifies all registered RunListeners.

See Also:

• RunListener

fireModelInit

public void fireModelInit()

Called after the model has been re-initialized. Notifies all registered RunListeners.

fireModelReset

public void fireModelReset()

Called after the model has been reset. Notifies all registered RunListeners.

fireModelRelaxed

public void fireModelRelaxed()

Called after the model completed its relaxation. Notifies all registered RunListeners.

fireModelStopped

public void fireModelStopped()

Called after the population has reached an absorbing state (or has converged to an equilibrium state). Notifies all registered RunListeners.

getLogger

public Logger getLogger()

Note: Instead of sharing logging system, EvoLudo could implement helper routines for logging notifications. However, when logging notifications with a severity of Level.WARNING or higher the default logging message includes the name of the calling routine and hence would always refer to the (unhelpful) helper routines.

Returns:

logger of this EvoLudo controller

hirePDESupervisor

public abstract PDESupervisor hirePDESupervisor(PDE charge)

Hire supervisor for managing PDE calculations. This is the factory method provide different implementations For GWT and JRE. More specifically, GWT uses asynchronous execution to prevent the GUI from stalling, while JRE implementations take advantage of multiple threads for significantly faster execution due to parallelization.

Parameters:

charge - the PDE model to supervise

Returns:

supervisor for coordinating PDE calculations

See Also:

• EvoLudoGWT#hirePDESupervisor(PDERD)
• EvoLudoJRE#hirePDESupervisor(PDERD)
• PDESupervisor
• PDESupervisorGWT
• PDESupervisorJRE

getVersion

public String getVersion()

Return version string of current model. Version must include reference to git commit to ensure reproducibility of results.

Returns:

the version string

getJavaVersion

public String getJavaVersion()

Get version of JRE (if not running in browser).

Returns:

the java version string

getGit

public abstract String getGit()

Gets current git version of code base.

Returns:

the git version string

getGitDate

public abstract String getGitDate()

Gets the compilation date of the current git version.

Returns:

the git compilation date as a string

getSnapLayoutTimeout

public int getSnapLayoutTimeout()

Gets the timeout for the layout process of snapshots in msec.

Returns:

timeout in msec

writeHeader

public void writeHeader()

Write header of report to output (currently JRE only). The information should include items like the version of the EvoLudo code, the current date and the string of command line options for reproducibility.

writeFooter

public void writeFooter()

Concluding words for report (currently JRE only).

exportState

public abstract void exportState()

Export the current state of the engine using the appropriate means available in the current environment (GWT/JRE).

See Also:

• EvoLudoGWT.exportState()
• EvoLudoJRE.exportState()

encodeState

public String encodeState()

Encode current state of EvoLudo model as XML string (plist format).

Returns:

encoded state

restoreFromFile

public abstract boolean restoreFromFile()

Restore state of EvoLudo model from saved plist, which encodes engine state.

Returns:

true on successfully restoring state

See Also:

• encodeState()

restoreState

public boolean restoreState(Plist plist)

Restore state of EvoLudo model from pre-processed plist, which encodes engine state (see encodeState()).

Note: the appropriate model must already have been loaded and the command line arguments specified with the key CLO in the plist must also have been processed already.

In JRE the options in plist are merged with any other command line arguments (albeit the ones in plist have priority to minimize the chance of complications). In GWT restoreState(Plist) is overridden to first deal with the command line arguments.

Parameters:

plist - the lookup table with key value pairs

Returns:

true on successfully restoring state

addCLOProvider

public void addCLOProvider(CLOProvider provider)

Register clo as a provider of command line options. Initialize command line parser if necessary.

Parameters:

provider - the option provider to add

removeCLOProvider

public void removeCLOProvider(CLOProvider provider)

Unregister clo as a provider of command line options.

Parameters:

provider - the option provider to remove

preprocessCLO

protected String[] preprocessCLO(String[] cloarray)

Pre-process array of command line arguments. Some arguments need priority treatment. Examples include the options --module, --verbose or --restore.

--module

load module and remove option

--verbose

set verbosity level effective immediately. This ensures that issues when parsing the remaining command line options are already properly reported

Parameters:

cloarray - array of command line arguments

Returns:

pre-processed array of command line options

See Also:

• EvoLudoJRE#preprocessCLO(String[])
• EvoLudoGWT#preprocessCLO(String[])

parseCLO

public int parseCLO()

Parse command line options.

Returns:

the number of issues that have occurred durin parsing

See Also:

• parseCLO(String[])

parseCLO

protected int parseCLO(String[] cloarray)

Pre-process and parse array of command line arguments.

Parameters:

cloarray - string array of command line arguments

Returns:

the number of issues that have occurred durin parsing

See Also:

• preprocessCLO(String[])
• CLOParser.parseCLO(String[])

getCLOHelp

public String getCLOHelp()

Format, encode and output help on command line options.

Returns:

the help string

showHelp

public abstract void showHelp()

Show help on command line options.

collectCLO

public void collectCLO(CLOParser prsr)

All providers of command line options must implement this method to collect their options.

Each command line option is (uniquely) identified by it's name (see CLOption.getName()), which corresponds to the long version of the option. If an attempt is made to add an option with a name that already exists, the parser issues a warning and ignores the option. Thus, in general, implementing subclasses should first register their options and call super.collectCLO(CLOParser) at the end such that subclasses are able to override command line options specified in a parental class.

Override this method in subclasses to add further command line options. Subclasses must make sure that they include a call to super.

Note: In contrast to other providers of command line options, the EvoLudo class delegates collection to the controller which maintains the shared parser.

Specified by:

collectCLO in interface CLOProvider

Parameters:

prsr - the reference to parser that manages command line options

See Also:

• CLOParser.addCLO(CLOption)

fatal

public void fatal(String msg)

Report error and stop model execution, if running.

IMPORTANT: Does not return control to caller.

Parameters:

msg - the error message

loadModules

public void loadModules()

Load all available modules. Specific modules are the responsibility of the caller.