Package org.evoludo.simulator

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 enum 
    EvoLudo.ColorModelType
    Coloring methods for multiple continuous traits.
    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.
    static final CLOption.Category
    catGlobal
    The category for global options.
    static final CLOption.Category
    catGUI
    The category for user interface specific options.
    static final CLOption.Category
    catModel
    The category for model specific options.
    static final CLOption.Category
    catModule
    The category for module specific options.
    static final CLOption.Category
    catSimulation
    The category for simulation specific options.
    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)
    final CLOption
    cloDelay
    Command line option to set the delay between subsequent updates.
    final CLOption
    cloHelp
    Command line option to print help message for available command line options.
    final CLOption
    cloModel
    Command line option to set the type of model (see Type).
    final CLOption
    cloModule
    Command line option to set module.
    final CLOption
    cloRNG
    Command line option to perform test of random number generator on launch.
    final CLOption
    cloRun
    Command line option to request that the EvoLudo model immediately starts running after loading.
    final CLOption
    cloSeed
    Command line option to set seed of random number generator.
    final CLOption
    cloTraitColorScheme
    Command line option to set color scheme for coloring continuous traits.
    final CLOption
    cloTrajectoryColor
    Command line option to set the color for trajectories.
    final CLOption
    cloVerbose
    Command line option to set verbosity level of logging.
    protected EvoLudo.ColorModelType
    colorModelType
    The coloring method type.
    static final String
    COPYRIGHT
    The copyright string.
    (package private) double
    cpu
    Starting time of CPU sampling (negative if not sampling).
    (package private) double
    cpuMean
    Mean time of CPU sampling.
    (package private) int
    cpuSamples
    Number of CPU time samples
    (package private) double
    cpuVar
    Variance of time of CPU sampling.
    protected int
    delay
    Delay between subsequent updates in milliseconds when model is running.
    private 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
    private boolean
    doPrev
    Flag to indicate if a backstep is in progress.
    boolean
    hasTouch
    The flag to indicate whether the current device/program supports touch events
    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.
    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 Logger
    logger
    The logger for keeping track of and reporting events and issues.
    protected List<MilestoneListener>
    milestoneListeners
    List of engine listeners that get notified when the state of the population changed, for example after population reset or completed an update step.
    protected HashMap<String,Module>
    modules
    The lookup table for all available modules.
    protected CLOParser
    parser
    The parser for command line options.
    protected ChangeListener.PendingAction
    pendingAction
    The action that is pending (if any).
    private boolean
    reparseCLO
    The flag to indicate whether the module reqiuires a full reparsing of the command line options.
    private 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 int
    snapLayoutTimeout
    timeout for layout process of snapshots in msec.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    EvoLudo()
    Create an instance of the EvoLudo controller.
    protected
    EvoLudo(boolean loadModules)
    Constructor to instantiate a new 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
    addMilestoneListener(MilestoneListener newListener)
    Add a milestone listener to the list of listeners that get notified when the model reaches milestones.
    void
    addModule(Module module)
    Add module to lookup table of modules using the module's key.
    void
    collectCLO(CLOParser prsr)
    All providers of command line options must implement this method to collect their options.
    Model
    createIBS(Module module)
    Creates individual based simulation model for module.
    abstract Network2D
    createNetwork2D(Geometry geometry)
    Generate 2D network.
    abstract Network3D
    createNetwork3D(Geometry geometry)
    Generate 3D network.
    Model
    createODE(Module module)
    Creates ordinary differential equation model for module.
    Model
    createPDE(Module module)
    Creates partial differential equation model for module.
    Model
    createSDE(Module module)
    Creates stochastic differential equation model for module.
    void
    debug()
    Advances the EvoLudo model by a single debugging step.
    void
    decreaseDelay()
    Decrease delay between subsequent updates by fixed factor.
    void
    dumpEnd()
    Concluding words for report (currently JRE only).
    void
    dumpParameters()
    Report all parameter settings to output (currently JRE only).
    abstract int
    elapsedTimeMsec()
    Calculate elapsed time since instantiation in milliseconds.
    String
    encodeState()
    Encode current state of EvoLudo model as XML string (plist format).
    protected void
    endCPUSample()
    Finish sampling CPU time.
    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.
    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.
    EvoLudo.ColorModelType
    getColorModelType()
    Get the type of color model for translating continuous traits into colors.
    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.
    boolean
    loadModel(Type type)
    Set model type and loads the corresponding frameworks for individual based simulations or numerical integration of ODE/SDE/PDE models.
    Module
    loadModule(String newModuleKey)
    Load new module with key newModuleKey.
    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.
    boolean
    parseCLO()
    Parse command line options.
    protected boolean
    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 method for handling model changed events and processes 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
    removeMilestoneListener(MilestoneListener obsoleteListener)
    Remove the milestone listener from the list of listeners that get notified when the model reaches milestones.
    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.
    protected void
    resetCPUSample()
    Resets sampling of CPU time.
    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
    setColorModelType(EvoLudo.ColorModelType colorModelType)
    Set the type of the color model for translating continuous traits into colors.
    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.
    protected void
    startCPUSample()
    Starts sampling CPU time.
    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 MilestoneListener's.
    void
    unloadModule()
    Unload current module to free up resources.

    Methods inherited from class Object

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

    Methods inherited from interface CLOProvider

    adjustCLO

  • Field Details

    • isGWT

      public 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.

    • hasTouch

      public boolean hasTouch
      The flag to indicate whether the current device/program supports touch events

      Note: cannot be static or final to allow disabling touch events for debugging (see EvoLudoGWT.cloGUIFeatures).

    • 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:

    • 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:

    • modules

      protected HashMap<String,Module> modules
      The lookup table for all available modules.

    • activeModel

      protected Model activeModel
      The active model

    • resetRequested

      private 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 types/strategies.

    • reparseCLO

      private boolean reparseCLO
      The flag to indicate whether the module reqiuires a full reparsing of the command line options.

    • milestoneListeners

      protected List<MilestoneListener> milestoneListeners
      List of engine listeners that get notified when the state of the population changed, for example after population reset or completed an update step.

    • changeListeners

      protected List<ChangeListener> changeListeners
      List of change listeners that get notified when the model changes.

    • cpu

      double cpu
      Starting time of CPU sampling (negative if not sampling).

    • cpuMean

      double cpuMean
      Mean time of CPU sampling.

    • cpuVar

      double cpuVar
      Variance of time of CPU sampling.

    • cpuSamples

      int cpuSamples
      Number of CPU time samples

    • clo

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

    • 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 cloRun).

    • DELAY_MIN

      public static final double DELAY_MIN
      Minimum delay between subsequent updates for speed slider Slider
      See Also:

    • DELAY_MAX

      public static final double DELAY_MAX
      Maximum delay between subsequent updates for speed slider Slider
      See Also:

    • DELAY_INIT

      public static final double DELAY_INIT
      Initial delay between subsequent updates for speed slider Slider
      See Also:

    • DELAY_INCR

      private static final double DELAY_INCR
      Delay decrement for speed slider Slider
      See Also:

    • delay

      protected int delay
      Delay between subsequent updates in milliseconds when model is running.

    • activeModule

      protected Module activeModule
      The active module.

    • isRunning

      protected boolean isRunning
      The flag to indicate whether the active model is running.

    • doPrev

      private boolean doPrev
      Flag to indicate if a backstep is in progress.

    • pendingAction

      protected ChangeListener.PendingAction pendingAction
      The action that is pending (if any).

    • snapLayoutTimeout

      protected int snapLayoutTimeout
      timeout for layout process of snapshots in msec.

    • parser

      protected CLOParser parser
      The parser for command line options.

    • catGlobal

      public static final CLOption.Category catGlobal
      The category for global options.

    • catModule

      public static final CLOption.Category catModule
      The category for module specific options.

    • catModel

      public static final CLOption.Category catModel
      The category for model specific options.

    • catSimulation

      public static final CLOption.Category catSimulation
      The category for simulation specific options.

    • catGUI

      public static final CLOption.Category catGUI
      The category for user interface specific options.

    • cloModule

      public final CLOption cloModule
      Command line option to set module.

    • cloModel

      public final CLOption cloModel
      Command line option to set the type of model (see Type).

    • cloSeed

      public final CLOption cloSeed
      Command line option to set seed of random number generator.

    • cloRun

      public final CLOption cloRun
      Command line option to request that the EvoLudo model immediately starts running after loading.

    • cloDelay

      public final CLOption cloDelay
      Command line option to set the delay between subsequent updates.

    • cloTrajectoryColor

      public final CLOption cloTrajectoryColor
      Command line option to set the color for trajectories. For example, this affects the display in S3 or Phase2D.

    • cloTraitColorScheme

      public final CLOption cloTraitColorScheme
      Command line option to set color scheme for coloring continuous traits.
      See Also:

    • cloRNG

      public final CLOption cloRNG
      Command line option to perform test of random number generator on launch. This takes approximately 10-20 seconds. The test reports (1) whether the generated sequence of random numbers is consistent with the reference implementation of MersenneTwister and (2) the performance of MersenneTwister compared to Random.

    • cloVerbose

      public final CLOption cloVerbose
      Command line option to set verbosity level of logging.

    • cloHelp

      public final CLOption cloHelp
      Command line option to print help message for available command line options.

    • colorModelType

      protected EvoLudo.ColorModelType colorModelType
      The coloring method type.

  • Constructor Details

    • EvoLudo

      public 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.

    • EvoLudo

      protected EvoLudo(boolean loadModules)
      Constructor to instantiate a new EvoLudo controller. If loadModules == true, load all available modules. Otherwise a specific module needs to be loaded by the caller.
      Parameters:
      loadModules - the flag to indicate whether to load modules

  • 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:

    • createODE

      public Model createODE(Module module)
      Creates ordinary differential equation model for module.

      Note: by default returns RungeKutta model. Override to provide custom implementation of ODE model.

      Parameters:
      module - the interaction Module
      Returns:
      the ODE model for module

    • createSDE

      public Model createSDE(Module module)
      Creates stochastic differential equation model for module.

      Note: by default returns SDE model. Override to provide custom implementation of SDE model.

      Parameters:
      module - the interaction Module
      Returns:
      the SDE model for module

    • createPDE

      public Model createPDE(Module module)
      Creates partial differential equation model for module.

      Note: by default returns PDE model. Override to provide custom implementation of PDE model.

      Parameters:
      module - the interaction Module
      Returns:
      the PDE model for module

    • createIBS

      public Model createIBS(Module module)
      Creates individual based simulation model for module.

      Note: by default returns IBSD for Discrete models and IBSC for Continuous models. Override to provide custom implementation of IBS model.

      Parameters:
      module - the interaction Module
      Returns:
      the IBS model for module

    • createNetwork2D

      public abstract Network2D createNetwork2D(Geometry 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(Geometry 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 boolean loadModel(Type type)
      Set model type and loads the corresponding frameworks for individual based simulations or numerical integration of ODE/SDE/PDE models. Notifies all registered MilestoneListener's of any changes.
      Parameters:
      type - the type of Model to load
      Returns:
      true if model type changed

    • 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.

    • addMilestoneListener

      public void addMilestoneListener(MilestoneListener newListener)
      Add a milestone listener to the list of listeners that get notified when the model reaches milestones.
      Parameters:
      newListener - the new milestone listener

    • removeMilestoneListener

      public void removeMilestoneListener(MilestoneListener obsoleteListener)
      Remove the milestone listener from the list of listeners that get notified when the model reaches milestones.
      Parameters:
      obsoleteListener - the listener to remove from list of milestone 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

    • unloadModel

      public void unloadModel()
      Unload model framework. Notifies all registered MilestoneListener's.

    • unloadModel

      public void unloadModel(boolean quiet)
      Unload model framework and, if requested, notifies all registered MilestoneListener's.
      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

    • resetCPUSample

      protected void resetCPUSample()
      Resets sampling of CPU time.

    • startCPUSample

      protected void startCPUSample()
      Starts sampling CPU time.

    • endCPUSample

      protected void endCPUSample()
      Finish sampling CPU time.

    • 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:

    • 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:

    • 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 Module loadModule(String newModuleKey)
      Load new module with key newModuleKey. If necessary first unload current module.
      Parameters:
      newModuleKey - the key of the module to load
      Returns:
      true if new module was loaded

    • 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

    • 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:

    • 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 MilestoneListeners.

    • fireModuleUnloaded

      public void fireModuleUnloaded()
      Called whenever the current module has finished unloading. Notifies all registered MilestoneListeners.

    • 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 MilestoneListeners.
      See Also:

    • fireModelLoaded

      public void fireModelLoaded()
      Called whenever a new model has finished loading. Notifies all registered MilestoneListeners.

    • fireModelUnloaded

      public void fireModelUnloaded()
      Called whenever a new model has finished loading. Notifies all registered MilestoneListeners.

    • fireModelRunning

      public void fireModelRunning()
      Called whenever the model starts its calculations. Fires only when starting to run. Notifies all registered MilestoneListeners.

    • 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 Model.MilestoneListeners.
      See Also:

    • 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 MilestoneListeners.
      See Also:

    • processPendingAction

      void processPendingAction()
      Helper method for handling model changed events and processes pending actions.
      See Also:

    • fireModelInit

      public void fireModelInit()
      Called after the model has been re-initialized. Notifies all registered MilestoneListeners.

    • fireModelReset

      public void fireModelReset()
      Called after the model has been reset. Notifies all registered MilestoneListeners.

    • fireModelRelaxed

      public void fireModelRelaxed()
      Called after the model completed its relaxation. Notifies all registered MilestoneListeners.

    • fireModelStopped

      public void fireModelStopped()
      Called after the population has reached an absorbing state (or has converged to an equilibrium state). Notifies all registered MilestoneListeners.

    • 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:

    • elapsedTimeMsec

      public abstract int elapsedTimeMsec()
      Calculate elapsed time since instantiation in milliseconds.

      Hide GWT/JRE differences in measuring execution time.

      Specified by:
      elapsedTimeMsec in interface MersenneTwister.Chronometer
      Returns:
      time in milliseconds
      See Also:

    • 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

    • dumpParameters

      public void dumpParameters()
      Report all parameter settings to output (currently JRE only).

    • dumpEnd

      public void dumpEnd()
      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:

    • 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:

    • 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:

    • parseCLO

      public boolean parseCLO()
      Parse command line options.
      Returns:
      true if parsing successful and false if problems occurred
      See Also:

    • parseCLO

      protected boolean parseCLO(String[] cloarray)
      Pre-process and parse array of command line arguments.
      Parameters:
      cloarray - string array of command line arguments
      Returns:
      true if parsing successful and false if problems occurred
      See Also:

    • 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 maintains a reference to the parser (prsr and parser must be identical).

      Specified by:
      collectCLO in interface CLOProvider
      Parameters:
      prsr - the reference to parser that manages command line options
      See Also:

    • getColorModelType

      public EvoLudo.ColorModelType getColorModelType()
      Get the type of color model for translating continuous traits into colors.
      Returns:
      the type of color model
      See Also:

    • setColorModelType

      public void setColorModelType(EvoLudo.ColorModelType colorModelType)
      Set the type of the color model for translating continuous traits into colors.
      Parameters:
      colorModelType - the new type of color model
      See Also:

    • 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