Package org.evoludo.simulator.models

Class Model

Object

Model

All Implemented Interfaces:

CLOProvider

Direct Known Subclasses:

IBS, ODE

public abstract class Model
extends Object
implements CLOProvider

Interface for EvoLudo models to interact with Modules, which define interactions (or games), and the engine EvoLudo, which manages the (un)loading and execution of different models based on what model types the module supports.

Author:

Christoph Hauert

Field Summary

Fields

Modifier and Type	Field	Description
final CLOption	cloSamples	Command line option to set the number of samples to take for statistical measurements.
final CLOption	cloTimeRelax	Command line option to set the number of generations to relax the model from the initial configuration.
final CLOption	cloTimeStep	Command line option to set the number of generations between reports for EvoLudo.modelNext().
final CLOption	cloTimeStop	Command line option to set the number of generations after which to stop the model calculations.
protected boolean	connect	Flag to indicate whether the current data point belongs to the same time series.
protected boolean	converged	Flag to indicate whether the model has converged.
protected EvoLudo	engine	The pacemaker of all models.
protected FixationData	fixData	The container for collecting statistics samples.
protected boolean	isMultispecies	Flag to indicate whether the model entertains multiple species, i.e.
(package private) boolean	isRelaxing	The flag to indicate whether the model is currently relaxing the initial configuration.
protected Logger	logger	Logger for keeping track of and reporting events and issues.
protected Mode	mode	Indicates current mode of IBS model.
protected double	nSamples	The number of statistical samples to collect before returning the results.
protected int	nSpecies	The number of species in multi-species models.
protected int	nStatisticsFailed	Number of failed statistics samples.
protected int	nStatisticsSamples	Number of statistics samples collected.
protected RNGDistribution	rng	The shared random number generator to ensure reproducibility of results.
protected ArrayList<? extends Module>	species	Short-cut to the list of species modules.
protected boolean	statisticsSampleNew	The flag to indicate whether to start new statistics sample.
protected double	time	Keeps track of the time elapsed.
protected double	timeRelax	The relaxation time for simulations measured in generations.
protected double	timeStep	Indicates the interval (measured in generations) after which models report updates on their current state.
protected double	timeStop	Running simulations are halted when time ≥ timeStop holds for the first time.
(package private) Type	type	The type of the model: IBS, ODE, SDE, or PDE.

Constructor Summary

Constructors

Constructor	Description
Model(EvoLudo engine)	Creates a model.

Method Summary

Modifier and Type	Method	Description
boolean	check()	Check consistency of parameters and adjust if necessary (and possible).
void	collectCLO(CLOParser parser)	All providers of command line options must implement this method to collect their options.
void	debugStep()	Perform single debug step in models that allow it.
abstract void	encodeState(StringBuilder plist)	Encode the state of the model in a plist inspired XML string.
String	getCounter()	Gets a formatted string summarizing the elapsed time.
abstract <T> void	getFitnessData(int id, T[] colors, ColorMap.Gradient1D<T> colorMap)	Translates fitness data into colors using ColorMap colorMap.
abstract void	getFitnessHistogramData(int id, double[][] bins)	Generates a histogram of fitness data and returns the result in the provided array bins.
String	getFitnessNameAt(int id, int idx)	Gets the fitness at location idx for species with ID id as a formatted string.
FixationData	getFixationData()	Gets the statistics sample of the fixation data.
abstract void	getInitialTraits(double[] init)	Collect and return initial trait values for all species.
abstract void	getInitialTraits(int id, double[] init)	Return initial trait values for species with ID id.
Logger	getLogger()	Return the logger for reporting information.
abstract double	getMaxFitness(int id)	Calculates and returns the absolute fitness maximum.
abstract double	getMaxScore(int id)	Returns the maximum score that individuals of species with ID id can achieve in this model.
abstract boolean	getMeanFitness(double[] mean)	Gets the mean fitness values for traits in all species.
abstract boolean	getMeanFitness(int id, double[] mean)	Gets the mean fitness values for species with ID id.
double[]	getMeanFitnessAt(int id, int idx)	Gets the mean fitness(es) of this model at location idx.
String	getMeanName(int index)	Return the name of the mean trait with index index or null if index is invalid.
String[]	getMeanNames()	Return the names of the mean traits of this model.
double[]	getMeanTraitAt(int id, int idx)	Return mean trait values at location idx for species with ID id.
abstract boolean	getMeanTraits(double[] mean)	Collect and return mean trait values for all species.
abstract boolean	getMeanTraits(int id, double[] mean)	Return mean trait values for species with ID id.
abstract double	getMinFitness(int id)	Calculates and returns the absolute fitness minimum.
abstract double	getMinScore(int id)	Returns the minimum score that individuals of species with ID id can achieve in this model.
Mode	getMode()	Gets the Mode of the model.
double	getNextHalt()	Gets the next generation for which stopping the model execution has been requested.
abstract int	getNMean()	Return the number of mean values for this model including all species (for traits or fitness).
abstract int	getNMean(int id)	Return the number of mean trait values for species with ID id.
double	getNSamples()	Gets the number of statistical samples after which the active Model is halted.
int	getNSpecies()	Return the number of species in this model.
int	getNStatisticsFailed()	Gets the number of failed statistics samples.
int	getNStatisticsSamples()	Gets the number of statistics samples collected so far.
String	getScoreNameAt(int id, int idx)	Gets the score at location idx for species with ID id as a formatted string.
Module	getSpecies(int id)	Return the species with ID id.
abstract String	getStatus()	Returns status message from model.
double	getTime()	Gets the elapsed time in model.
double	getTimeRelax()	Gets the number of generations to relax the initial configuration of the active Model.
double	getTimeStep()	Get the interval between subsequent reports to the GUI or the simulation controller measured in generations (or fractions thereof).
double	getTimeStop()	Gets the number of generations after which the active Model is halted.
abstract <T> void	getTraitData(int id, T[] colors, ColorMap<T> colorMap)	Gets the trait data for species with ID id and translates them into colors using the colorMap.
String	getTraitNameAt(int id, int idx)	Gets the formatted trait names at location idx for species with ID id.
Type	getType()	Gets the type of the model.
boolean	hasConverged()	Checks if model has converged.
void	init()	Milestone: Initialize this model
void	initStatisticsFailed()	Clear statistics sample and get ready to collect next sample.
void	initStatisticsSample()	Clear statistics sample and get ready to collect next sample.
boolean	isConnected()	Checks if the current data point should be connected to the previous one.
boolean	isContinuous()	Checks if model deals with continuous traits.
boolean	isDE()	Checks if model is of type ODE/SDE/PDE.
boolean	isIBS()	Checks if model is of type IBS.
boolean	isODE()	Checks if model is of type ODE.
boolean	isPDE()	Checks if model is of type PDE.
boolean	isRelaxing()	Check if EvoLudo model is in the process of relaxing.
boolean	isSDE()	Checks if model is of type SDE.
boolean	isTimeReversed()	Checks if time is reversed.
boolean	isType(Type aType)	Checks if model is of type aType.
void	load()	Milestone: Load this model and allocate resources (if applicable).
abstract boolean	next()	Advance model by one step.
boolean	permitsDebugStep()	Checks if debugging single steps is supported.
boolean	permitsMode(Mode test)	Check if current model implements mode test; by default only Mode.DYNAMICS is permitted.
boolean	permitsSampleStatistics()	Check if the current model settings permit sample statistics.
boolean	permitsTimeReversal()	Checks if time reversal is permitted.
boolean	permitsUpdateStatistics()	Check if the current model settings permit update statistics.
void	readStatisticsSample()	Signal that statistics sample is ready to process.
boolean	relax()	Relax the initial configuration of the model over timeRelax generations.
boolean	requestMode(Mode newmode)	Request a change of the Mode of the model.
void	reset()	Milestone: Reset this model
void	resetStatisticsSample()	Reset statistics and get ready to start new collection.
abstract boolean	restoreState(Plist map)	Restore the state encoded in the plist inspired map of key, value-pairs.
boolean	setInitialTraits(double[] init)	Set initial traits in one or all species.
boolean	setInitialTraits(int id, double[] init)	Set initial trait values for species with ID id.
boolean	setMode(Mode mode)	Sets the Mode of model/simulator.
void	setNSamples(double nSamples)	Sets the number of statistical samples taken after which the active Model is halted.
void	setTimeRelax(double relax)	Sets the number of generations to relax the initial configuration of the active Model.
void	setTimeReversed(boolean reversed)	Request time reversal if reversed==true.
void	setTimeStep(double aValue)	Set the report interval, i.e.
void	setTimeStop(double timeStop)	Sets the number of generations after which the active Model is halted.
void	unload()	Milestone: Unload this model and free resources (if applicable).
abstract void	update()	Update this model.
boolean	useScheduling()	GWT models run asynchronously and long running tasks require scheduling to maintain responsive user interface.

Methods inherited from class Object

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

Methods inherited from interface CLOProvider

adjustCLO

Field Details

engine

protected EvoLudo engine

The pacemaker of all models. Interface with the outside world.

logger

protected Logger logger

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:

• EvoLudo.getRNG()

time

protected double time

Keeps track of the time elapsed. Time is measured in number of generations. In IBS models this corresponds to one Monte-Carlo step, such that in a population of size N one generation corresponds to N updates, which translates to N events (birth, death, imitation, etc.). Notes:

1. generation==0 after reset() and at the beginning of a simulation run.
2. generation is incremented before the next event is processed, to reflect the time at which the event occurs.
3. generally differs from 'real time'.
4. may be negative for models that admit time reversal (e.g. integrating ODE backwards).

See Also:

• permitsTimeReversal()
• IBS.realtime

species

protected ArrayList<? extends Module> species

Short-cut to the list of species modules. Convenience field.

nSpecies

protected int nSpecies

The number of species in multi-species models.

isMultispecies

protected boolean isMultispecies

Flag to indicate whether the model entertains multiple species, i.e. nSpecies>1. Convenience field.

converged

protected boolean converged

Flag to indicate whether the model has converged. Once a model has converged the model execution automatically stops.

connect

protected boolean connect

Flag to indicate whether the current data point belongs to the same time series. This is used by the GUI to decide whether to connect the data points or not. Typically this is false only after init(), reset(), restoreState(Plist) or similar.

isRelaxing

boolean isRelaxing

The flag to indicate whether the model is currently relaxing the initial configuration.

mode

protected Mode mode

Indicates current mode of IBS model.

statisticsSampleNew

protected boolean statisticsSampleNew

The flag to indicate whether to start new statistics sample.

nStatisticsSamples

protected int nStatisticsSamples

Number of statistics samples collected.

nStatisticsFailed

protected int nStatisticsFailed

Number of failed statistics samples.

fixData

protected FixationData fixData

The container for collecting statistics samples.

type

Type type

The type of the model: IBS, ODE, SDE, or PDE.

timeStep

protected double timeStep

Indicates the interval (measured in generations) after which models report updates on their current state. for example, the GUI gets updated whenever timeStep generations (or fractions thereof) have elapsed.

Note: timeStep<0 disables reporting; timeStep=0 reports every single update.

cloTimeStep

public final CLOption cloTimeStep

Command line option to set the number of generations between reports for EvoLudo.modelNext().

timeRelax

protected double timeRelax

The relaxation time for simulations measured in generations.

Note: timeRelax is set with the command line option --timerelax

See Also:

• cloTimeRelax

cloTimeRelax

public final CLOption cloTimeRelax

Command line option to set the number of generations to relax the model from the initial configuration. After relaxation the model is assumed to be close to its (thermal) equilibrium. In particular, the system should be ready for measurements such as the strategy abundances, their fluctuations or the local strategy configurations in structured populations.

timeStop

protected double timeStop

Running simulations are halted when time ≥ timeStop holds for the first time. This is useful to indicate the end of simulations or to generate (graphical) snapshots in the GUI after a specified amount of time has elapsed.

Note: timeStop is set with the command line option --timestop (or -g),

See Also:

• cloTimeStop

cloTimeStop

public final CLOption cloTimeStop

Command line option to set the number of generations after which to stop the model calculations. Model execution can be resumed afterwards.

nSamples

protected double nSamples

The number of statistical samples to collect before returning the results.

Note: nSamples is set with the command line option --samples

See Also:

• cloSamples

cloSamples

public final CLOption cloSamples

Command line option to set the number of samples to take for statistical measurements.

Constructor Details

Model

public Model(EvoLudo engine)

Creates a model.

Parameters:

engine - the pacemaker for running the model

Method Details

load

public void load()

Milestone: Load this model and allocate resources (if applicable).

See Also:

• MilestoneListener.modelLoaded()

unload

public void unload()

Milestone: Unload this model and free resources (if applicable).

See Also:

• MilestoneListener.modelUnloaded()

check

public boolean check()

Check consistency of parameters and adjust if necessary (and possible). All issues and modifications should be reported through logger. Some parameters can be adjusted while the model remains active or even while running, whereas others require a reset. An example of the former category is in general simple adjustments of payoffs, while an example of the latter category is a change of the population structure.

Returns:

true if reset required

See Also:

• Logger

reset

public void reset()

Milestone: Reset this model

See Also:

• MilestoneListener.modelDidReset()

init

public void init()

Milestone: Initialize this model

See Also:

• MilestoneListener.modelDidInit()

update

public abstract void update()

Update this model. For example called after initialization and when parameters changed.

See Also:

• ChangeListener.modelChanged(ChangeListener.PendingAction)

next

public abstract boolean next()

Advance model by one step. The details of what happens during one step depends on the models Type as well as its Mode.

Returns:

true if next() can be called again. Typically false is returned if the model requires attention, such as the following conditions:

• the model has converged
• the model turned monomorphic (stops only if requested)
• a statistics sample is available
• a preset time has been reached

See Also:

• ChangeListener.modelChanged(ChangeListener.PendingAction)
• Discrete.setMonoStop(boolean)

relax

public boolean relax()

Relax the initial configuration of the model over timeRelax generations. During relaxation the method isRelaxing() must return true.

Returns:

true if converged during relaxation

See Also:

• isRelaxing()
• next()
• cloTimeRelax

isRelaxing

public boolean isRelaxing()

Check if EvoLudo model is in the process of relaxing.

Returns:

true if model is currently relaxing

See Also:

• relax()

hasConverged

public boolean hasConverged()

Checks if model has converged.

Returns:

true if model has converged.

See Also:

• IBSDPopulation.checkConvergence()
• ODE.setAccuracy(double)

getSpecies

public Module getSpecies(int id)

Return the species with ID id.

Parameters:

id - the species identifier

Returns:

the species

getNSpecies

public int getNSpecies()

Return the number of species in this model.

Returns:

the number of species

requestMode

public boolean requestMode(Mode newmode)

Request a change of the Mode of the model. Returns false if newmode is not supported.

Parameters:

newmode - the requested mode

Returns:

true if mode supported

See Also:

• EvoLudo.requestAction(ChangeListener.PendingAction)

permitsMode

public boolean permitsMode(Mode test)

Check if current model implements mode test; by default only Mode.DYNAMICS is permitted.

Parameters:

test - the mode to test

Returns:

true if test is available in current model

setMode

public boolean setMode(Mode mode)

Sets the Mode of model/simulator. Returns false if mode is already active or not supported.

Note: Do not set mode directly. Changes of the execution mode should be coordinated by the engine through requests.

Parameters:

mode - change mode of model to mode

Returns:

true if mode changed

See Also:

• requestMode(Mode)

getMode

public Mode getMode()

Gets the Mode of the model.

Returns:

mode of model

permitsSampleStatistics

public boolean permitsSampleStatistics()

Check if the current model settings permit sample statistics. Fixation probabilities and times are examples of statistics based on samples.

Returns:

true if sample statistics are permitted

permitsUpdateStatistics

public boolean permitsUpdateStatistics()

Check if the current model settings permit update statistics. Sojourn times are an example of statistics based on updates.

Returns:

true if update statistics are permitted

resetStatisticsSample

public void resetStatisticsSample()

Reset statistics and get ready to start new collection.

initStatisticsSample

public void initStatisticsSample()

Clear statistics sample and get ready to collect next sample.

initStatisticsFailed

public void initStatisticsFailed()

Clear statistics sample and get ready to collect next sample.

readStatisticsSample

public void readStatisticsSample()

Signal that statistics sample is ready to process.

getNStatisticsSamples

public int getNStatisticsSamples()

Gets the number of statistics samples collected so far.

Returns:

the number of samples

getNStatisticsFailed

public int getNStatisticsFailed()

Gets the number of failed statistics samples.

Returns:

the number of samples

getFixationData

public FixationData getFixationData()

Gets the statistics sample of the fixation data.

Returns:

the statistics sample

isContinuous

public boolean isContinuous()

Checks if model deals with continuous traits.

Returns:

true if traits are continuous

getType

public Type getType()

Gets the type of the model.

Returns:

the type of the model

isType

public boolean isType(Type aType)

Checks if model is of type aType.

Parameters:

aType - the type to check

Returns:

true for models of type aType

isIBS

public boolean isIBS()

Checks if model is of type IBS.

Returns:

true for IBS models

isODE

public boolean isODE()

Checks if model is of type ODE.

Returns:

true for ODE models

isSDE

public boolean isSDE()

Checks if model is of type SDE.

Returns:

true for SDE models

isPDE

public boolean isPDE()

Checks if model is of type PDE.

Returns:

true for PDE models

isDE

public boolean isDE()

Checks if model is of type ODE/SDE/PDE.

Returns:

true for differential equations models

useScheduling

public boolean useScheduling()

GWT models run asynchronously and long running tasks require scheduling to maintain responsive user interface. In contrast, JRE provides a multi-threaded environment, which allows to run multiple threads synchronously. This parallel execution results in an significant speed-boost (for PDE calculations).

Returns:

true if model calculations are asynchronous

getLogger

public Logger getLogger()

Return the logger for reporting information.

Returns:

the logger

getMinScore

public abstract double getMinScore(int id)

Returns the minimum score that individuals of species with ID id can achieve in this model. Takes into account potential adjustments due to population structure and payoff accounting.

Parameters:

id - the id of the population for multi-species models

Returns:

the minimum score

See Also:

• Module.getMinGameScore()

getMaxScore

public abstract double getMaxScore(int id)

Returns the maximum score that individuals of species with ID id can achieve in this model. Takes into account potential adjustments due to population structure and payoff accounting.

Parameters:

id - the id of the population for multi-species models

Returns:

the maximum score

See Also:

• Module.getMaxGameScore()

getMinFitness

public abstract double getMinFitness(int id)

Calculates and returns the absolute fitness minimum. This is important to

1. determine probabilities or rates for adopting the strategy of another player,
2. optimize fitness based picking of individuals, and
3. scaling graphical output.

Parameters:

id - the id of the population for multi-species models

Returns:

the minimum fitness

See Also:

• getMinScore(int id)

getMaxFitness

public abstract double getMaxFitness(int id)

Calculates and returns the absolute fitness maximum. This is important to

1. determine probabilities or rates for adopting the strategy of another player,
2. optimize fitness based picking of individuals, and
3. scaling graphical output.

Parameters:

id - the id of the population for multi-species models

Returns:

the maximum fitness

See Also:

• getMaxScore(int id)

getStatus

public abstract String getStatus()

Returns status message from model. Typically this is a string summarizing the current state of the simulation. For example, models with discrete strategy sets (such as 2x2 games, see TBT) return the average frequencies of each strategy type in the population(s), see IBSDPopulation. Similarly, models with continuous strategies (such as continuous snowdrift games, see CSD) return the mean, minimum and maximum trait value(s) in the population(s), see IBSMCPopulation. The status message is displayed along the bottom of the GUI.

Note: if the model runs into difficulties, problems should be reported through the logging mechanism. Messages with severity Level.WARNING or higher are displayed in the status of the GUI and override status messages returned here.

Returns:

status of active model

getCounter

public String getCounter()

Gets a formatted string summarizing the elapsed time.

Returns:

elapsed time as string

getTime

public double getTime()

Gets the elapsed time in model. Time is measured in generations.

Returns:

elapsed time

See Also:

• time

setInitialTraits

public boolean setInitialTraits(double[] init)

Set initial traits in one or all species.

NOTE: this is a convenience method for multi-species modules to set inital states efficiently for interactions with GUI.

Parameters:

init - the array with the initial trait values

Returns:

true if initial traits successfully set

getInitialTraits

public abstract void getInitialTraits(double[] init)

Collect and return initial trait values for all species.

NOTE: this is a convenience method for multi-species modules to retrieve states efficiently for further processing or visualization.

Parameters:

init - the array for storing the initial trait values

setInitialTraits

public boolean setInitialTraits(int id,
 double[] init)

Set initial trait values for species with ID id.

Parameters:

id - the species identifier

init - the array with the initial trait values

Returns:

true if initial traits successfully set

getInitialTraits

public abstract void getInitialTraits(int id,
 double[] init)

Return initial trait values for species with ID id.

Parameters:

id - the species identifier

init - the array for storing the initial trait values

getNMean

public abstract int getNMean()

Return the number of mean values for this model including all species (for traits or fitness). By default this returns the number of traits in the module. Models that report a different number of mean traits must override this method

Returns:

the number of mean values for all species

getNMean

public abstract int getNMean(int id)

Return the number of mean trait values for species with ID id.

Parameters:

id - the species identifier

Returns:

the number of mean values for species id

getMeanNames

public String[] getMeanNames()

Return the names of the mean traits of this model.

Returns:

the names of the mean traits

getMeanName

public String getMeanName(int index)

Return the name of the mean trait with index index or null if index is invalid.

Parameters:

index - the index of the mean trait

Returns:

the name of mean trait with index index

getMeanTraits

public abstract boolean getMeanTraits(double[] mean)

Collect and return mean trait values for all species.

NOTE: this is a convenience method for multi-species modules to retrieve states efficiently for further processing or visualization.

Parameters:

mean - the array for storing the mean trait values

Returns:

true if this and previous data point should be connected, i.e. no reset had been requested in the mean time.

getMeanTraits

public abstract boolean getMeanTraits(int id,
 double[] mean)

Return mean trait values for species with ID id.

Parameters:

id - the species identifier

mean - the array for storing the mean trait values

Returns:

true if this and the previous data point should be connected, i.e. no reset had been requested in the mean time.

getMeanTraitAt

public double[] getMeanTraitAt(int id,
 int idx)

Return mean trait values at location idx for species with ID id.

Note: optional implementation; currently makes sense only for local dynamics in PDE models.

IMPORTANT: the returned array is live and should not be altered.

Parameters:

id - the species identifier

idx - the index of the location

Returns:

array of mean trait values

getTraitNameAt

public String getTraitNameAt(int id,
 int idx)

Gets the formatted trait names at location idx for species with ID id. The formatting may include HTML tags. Used by GUI for example to show trait names in tooltips.

Note: optional implementation. Currently makes sense only for IBS models and local dynamics in PDE models.

Parameters:

id - the species identifier

idx - the index of the location

Returns:

description of traits at idx

getTraitData

public abstract <T> void getTraitData(int id,
 T[] colors,
 ColorMap<T> colorMap)

Gets the trait data for species with ID id and translates them into colors using the colorMap. The result is stored and returned in colors. Used by GUI to visualize the current state of the model.

Type Parameters:

T - color data type. Color for PopGraph2D and PopGraph2D as well as MeshLambertMaterial for PopGraph3D

Parameters:

id - the species identifier

colors - the array for storing the colors for individuals

colorMap - the map for translating individual traits into colors

getMeanFitness

public abstract boolean getMeanFitness(double[] mean)

Gets the mean fitness values for traits in all species. The result is stored and returned in mean. Used by GUI to visualize the current the state of the model.

Note: this is a convenience method for multi-species modules to retrieve states efficiently for further processing or visualization.

Parameters:

mean - the array for storing the mean fitness values

Returns:

true if this and the previous data point should be connected, i.e. no reset had been requested in the mean time.

getMeanFitness

public abstract boolean getMeanFitness(int id,
 double[] mean)

Gets the mean fitness values for species with ID id. The result is stored and returned in mean. Used by GUI to visualize local dynamics at idx.

Parameters:

id - the species identifier

mean - the array for storing the mean fitness values

Returns:

true if this and the previous data point should be connected, i.e. no reset had been requested in the mean time.

getMeanFitnessAt

public double[] getMeanFitnessAt(int id,
 int idx)

Gets the mean fitness(es) of this model at location idx. Used by GUI to visualize local dynamics at idx.

Note: optional implementation. Currently makes sense only for local dynamics in PDE models.

IMPORTANT: the returned array is live and should not be altered.

Parameters:

id - the species identifier

idx - the location of the fitness values

Returns:

the array of mean fitness values

getFitnessNameAt

public String getFitnessNameAt(int id,
 int idx)

Gets the fitness at location idx for species with ID id as a formatted string. The formatting may include HTML tags. Used by GUI for example to show fitness in tooltips.

Note: optional implementation. Currently makes sense only for IBS and PDE models.

Parameters:

id - the species identifier

idx - the index of the location

Returns:

the fitness as a formatted string

getScoreNameAt

public String getScoreNameAt(int id,
 int idx)

Gets the score at location idx for species with ID id as a formatted string. The formatting may include HTML tags. Used by GUI for example to show scores in tooltips.

Note: optional implementation. Currently makes sense only for IBS and PDE models.

Parameters:

id - the species identifier

idx - the index of the location

Returns:

the score as a formatted string

getFitnessData

public abstract <T> void getFitnessData(int id,
 T[] colors,
 ColorMap.Gradient1D<T> colorMap)

Translates fitness data into colors using ColorMap colorMap. Used by GUI to visualize current state of model.

Type Parameters:

T - color data type. Color for PopGraph2D and PopGraph2D as well as MeshLambertMaterial for PopGraph3D

Parameters:

id - the species identifier

colors - the array for storing color values

colorMap - the map to use for translating traits to colors

getFitnessHistogramData

public abstract void getFitnessHistogramData(int id,
 double[][] bins)

Generates a histogram of fitness data and returns the result in the provided array bins. For Discrete modules a fitness histogram is returned for each trait separately. For Continuous modules there is, in general, only a single fitness dimension.

Parameters:

id - the species identifier

bins - the array for storing histogram. For Discrete modules this is always one dimensional

isConnected

public boolean isConnected()

Checks if the current data point should be connected to the previous one. For example, returns false after a model has been reset and subsequent data points no longer refer to the same time series.

Returns:

true if data points are connected.

permitsTimeReversal

public boolean permitsTimeReversal()

Checks if time reversal is permitted. By default returns false. Only few models are capable of time reversal.

Returns:

true if time reversal permissible.

See Also:

• setTimeReversed(boolean)

isTimeReversed

public boolean isTimeReversed()

Checks if time is reversed. By default returns false. Only few models are capable of time reversal.

Returns:

true if time is reversed

See Also:

• setTimeReversed(boolean)

setTimeReversed

public void setTimeReversed(boolean reversed)

Request time reversal if reversed==true. The model may not be able to honour the request. However, some models allow to travel back in time. In general, this is only possible for ODE and SDE models and even for those it may not be feasible due to details of the dynamics, such as dissipative terms in the differential equations. For example, in

invalid reference

org.evoludo.simulator.modules.CG

the ecological dynamics of the patch quality prevents time reversal, i.e. results are numerically unstable due to exponential amplification of deviations in dissipative systems.

Parameters:

reversed - the request whether time should be reversed.

See Also:

• ODE.setTimeReversed
• SDE.setTimeReversed

permitsDebugStep

public boolean permitsDebugStep()

Checks if debugging single steps is supported. By default returns false. Only few models support debugging of single update steps.

Returns:

true if stepwise debuggin is permissible.

debugStep

public void debugStep()

Perform single debug step in models that allow it.

getNextHalt

public double getNextHalt()

Gets the next generation for which stopping the model execution has been requested.

Returns:

the next requested stop

setTimeStep

public void setTimeStep(double aValue)

Set the report interval, i.e. number of updates in one step (see EvoLudo.modelNext() measured in generations (or fractions thereof).

Parameters:

aValue - the new report interval

getTimeStep

public double getTimeStep()

Get the interval between subsequent reports to the GUI or the simulation controller measured in generations (or fractions thereof).

Returns:

the report interval

setTimeRelax

public void setTimeRelax(double relax)

Sets the number of generations to relax the initial configuration of the active Model. In interactive mode (with GUI) the active Model starts running upon launch and stop after timeRelax.

Parameters:

relax - the number of generations

See Also:

• timeRelax

getTimeRelax

public double getTimeRelax()

Gets the number of generations to relax the initial configuration of the active Model.

Returns:

the number of generations

See Also:

• timeRelax

setTimeStop

public void setTimeStop(double timeStop)

Sets the number of generations after which the active Model is halted.

Parameters:

timeStop - the number of generations

See Also:

• timeStop

getTimeStop

public double getTimeStop()

Gets the number of generations after which the active Model is halted.

Returns:

the number of generations

See Also:

• timeStop

setNSamples

public void setNSamples(double nSamples)

Sets the number of statistical samples taken after which the active Model is halted.

Parameters:

nSamples - the number of samples

See Also:

• nSamples

getNSamples

public double getNSamples()

Gets the number of statistical samples after which the active Model is halted.

Returns:

the number of statistical samples

See Also:

• nSamples

collectCLO

public void collectCLO(CLOParser parser)

Description copied from interface: CLOProvider

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.

Specified by:

collectCLO in interface CLOProvider

Parameters:

parser - the reference to parser that manages command line options

See Also:

• CLOParser.addCLO(CLOption)

encodeState

public abstract void encodeState(StringBuilder plist)

Encode the state of the model in a plist inspired XML string. This allows to save the state and restore later with the exact same results as when continuing to run the model. This even allows to switch from JRE to GWT or back and obtain identical results!

Parameters:

plist - the StringBuilder to write the encoded state to

See Also:

• Plist
• XMLCoder

restoreState

public abstract boolean restoreState(Plist map)

Restore the state encoded in the plist inspired map of key, value-pairs.

Parameters:

map - the map of key, value-pairs

Returns:

true if successful

See Also:

• Plist
• PlistReader
• PlistParser