Package org.evoludo.simulator.models

Class IBS

Object
Model
IBS
All Implemented Interfaces:
CLOProvider
Direct Known Subclasses:
IBSC, IBSD
public abstract class IBS extends Model
Base class for individual based simulation models, IBS. This class deals with multiple species, handles the milestone events and delegates to the different populations as appropriate.
Author:
Christoph Hauert

  • Field Details

    • ephrng

      protected RNGDistribution ephrng
      The random number generator to display states with ephemeral payoffs. In order to ensure reproducibility of results this cannot be the same random number generator as for running the simulations.
      See Also:

    • distrMutation

      protected RNGDistribution.Geometric distrMutation
      Geometric (exponential) waiting time distribution for optimizations of homogeneous populations.
      See Also:

    • population

      protected IBSPopulation population
      Short-cut to species.get(0).getIBSPopulation() for single species models; null in multi-species models. Convenience field.

    • realtime

      protected double realtime
      Keeps track of the elapsed time, taking into account the fitness of the population. For example, less time passes between reproductive events in populations with high fitness, while more time passes in low fitness populations because there are fewer reproduction events per unit time. If individual scores can be negative realtime is set to Double#POSITIVE_INFINITY to indicate that the measure is meaningless.

      Note: Requires non-negative individual scores.

    • optimizeHomo

      public boolean optimizeHomo
      true if optimizations for homogeneous populations requested.

      Note:

      • optimizations can be requested with the command line option --optimize, see IBSD.cloOptimize.
      • currently restricted to discrete traits where homogeneous population states can be skipped by deterministically introducing new mutant after an geometrically (exponentially) distributed waiting time (see IBSD).
      • requires small mutation rates.
      • does not work for variable population sizes.

    • isSynchronous

      boolean isSynchronous
      Flag to indicate whether the population updates are synchronous. In multi-species models this requires that all species are updated synchronously. Helper variable for ibsStep(double).
      See Also:

    • debugFocalSpecies

      IBSPopulation debugFocalSpecies
      Pointer to focal species for debugging.

    • speciesUpdate

      public SpeciesUpdate speciesUpdate
      Type of species update (multi-species models only).

    • nextSpeciesIdx

      private int nextSpeciesIdx
      Index for turn-based-selection to determine which species to pick next. Simply cycles through species array.

    • cloAccumulatedScores

      public final CLOption cloAccumulatedScores
      Command line option to set whether player scores from interactions are accumulated or averaged (default).

      Note: Accumulated scores can be tricky because they are essentially unbounded... On regular structures the two variants merely amount to a rescaling of the selection strength.

      See Also:

    • cloScoringType

      public final CLOption cloScoringType
      Command line option to set method for resetting the scores of individuals.
      See Also:

    • cloInteractions

      public final CLOption cloInteractions
      Command line option to set whether players interact with all their neighbours or a random subsample.

    • cloReferences

      public final CLOption cloReferences
      Command line option to set the method for choosing references/models among the neighbours of a player for updating their trait.

    • cloMigration

      public final CLOption cloMigration
      Command line option to set the migration types and probabilities of players.

    • cloGeometryInteraction

      public final CLOption cloGeometryInteraction
      Command line option to set the interaction geometry. This overrides the Module.cloGeometry settings.
      See Also:

    • cloGeometryCompetition

      public final CLOption cloGeometryCompetition
      Command line option to set the competition geometry. This overrides the Module.cloGeometry settings.
      See Also:

    • cloGeometryRewire

      public final CLOption cloGeometryRewire
      Command line option to set the fraction of links to rewire. If graph is undirected it is preserved and if graph is directed, rewiring is done for directed links (where undirected links count as two directed links), which potentially breaks undirected ones.

    • cloGeometryAddwire

      public final CLOption cloGeometryAddwire
      Command line option to set the fraction of links to add. If graph is undirected only undirected links are added and if graph is directed only directed links are added.

    • cloConsistency

      public final CLOption cloConsistency
      Command line option to enable consistency checks.

    • statisticsSettings

      IBS.Statistics statisticsSettings
      The settings for statistics mode.

  • Constructor Details

    • IBS

      public IBS(EvoLudo engine)
      Creates a population of individuals for IBS simulations.
      Parameters:
      engine - the pacemaker for running the model

  • Method Details

    • permitsSampleStatistics

      public boolean permitsSampleStatistics()
      Description copied from class: Model
      Check if the current model settings permit sample statistics. Fixation probabilities and times are examples of statistics based on samples.
      Overrides:
      permitsSampleStatistics in class Model
      Returns:
      true if sample statistics are permitted

    • permitsUpdateStatistics

      public boolean permitsUpdateStatistics()
      Description copied from class: Model
      Check if the current model settings permit update statistics. Sojourn times are an example of statistics based on updates.
      Overrides:
      permitsUpdateStatistics in class Model
      Returns:
      true if update statistics are permitted

    • load

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

      Loads the IBS model and instantiates the IBSPopulations representing the different species, if applicable.

      Overrides:
      load in class Model
      See Also:

    • unload

      public void unload()
      Description copied from class: Model
      Milestone: Unload this model and free resources (if applicable).
      Overrides:
      unload in class Model
      See Also:

    • check

      public boolean check()
      Description copied from class: Model
      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.
      Overrides:
      check in class Model
      Returns:
      true if reset required
      See Also:

    • reset

      public void reset()
      Description copied from class: Model
      Milestone: Reset this model
      Overrides:
      reset in class Model
      See Also:

    • init

      public void init()
      Description copied from class: Model
      Milestone: Initialize this model
      Overrides:
      init in class Model
      See Also:

    • init

      public void init(boolean soft)
      Initializes the IBS model. soft initializations adjust parameters but do not touch the current state of the IBS population(s).

      Note: Method must be public because of subclasses in org.evoludo.simulator.

      Parameters:
      soft - the flag to indicate whether this should be a soft initialization.

    • update

      public void update()
      Description copied from class: Model
      Update this model. For example called after initialization and when parameters changed.
      Specified by:
      update in class Model
      See Also:

    • next

      public boolean next()
      Description copied from class: Model
      Advance model by one step. The details of what happens during one step depends on the models Type as well as its Mode.
      Specified by:
      next in class Model
      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:

    • ibsStep

      public boolean ibsStep(double stepDt)
      Advances the IBS model by a step of size stepDt. The actual time increment may be shorter, e.g. upon reaching an absorbing state or homogeneous state, if requested.

      Note: the time increment returned is negative if the IBS converged/absorbed (individual based simulations cannot reverse time).

      Parameters:
      stepDt - the time increment requested for advancing the IBS model
      Returns:
      true if ibsStep(double) can be called again. Typically false is returned if the simulation requires attention, such as the following conditions:
      • the population(s) have reached an absorbing state
      • the population(s) turned monomorphic (stops only if requested)
      • the population(s) went extinct
      See Also:

    • permitsDebugStep

      public boolean permitsDebugStep()
      Description copied from class: Model
      Checks if debugging single steps is supported. By default returns false. Only few models support debugging of single update steps.
      Overrides:
      permitsDebugStep in class Model
      Returns:
      true if stepwise debuggin is permissible.

    • debugStep

      public void debugStep()
      Description copied from class: Model
      Perform single debug step in models that allow it.
      Overrides:
      debugStep in class Model

    • getIBSPopulation

      IBSPopulation getIBSPopulation(int id)
      Helper routine to retrieve the IBSPopulation associated with module with id.
      Parameters:
      id - the id of the module
      Returns:
      the IBSPopulation

    • getMinScore

      public double getMinScore(int id)
      Description copied from class: Model
      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.
      Specified by:
      getMinScore in class Model
      Parameters:
      id - the id of the population for multi-species models
      Returns:
      the minimum score
      See Also:

    • getMaxScore

      public double getMaxScore(int id)
      Description copied from class: Model
      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.
      Specified by:
      getMaxScore in class Model
      Parameters:
      id - the id of the population for multi-species models
      Returns:
      the maximum score
      See Also:

    • getMinFitness

      public double getMinFitness(int id)
      Description copied from class: Model
      Calculates and returns the absolute fitness minimum. This is important to
      1. determine probabilities or rates for adopting the trait of another player,
      2. optimize fitness based picking of individuals, and
      3. scaling graphical output.
      Specified by:
      getMinFitness in class Model
      Parameters:
      id - the id of the population for multi-species models
      Returns:
      the minimum fitness
      See Also:

    • getMaxFitness

      public double getMaxFitness(int id)
      Description copied from class: Model
      Calculates and returns the absolute fitness maximum. This is important to
      1. determine probabilities or rates for adopting the trait of another player,
      2. optimize fitness based picking of individuals, and
      3. scaling graphical output.
      Specified by:
      getMaxFitness in class Model
      Parameters:
      id - the id of the population for multi-species models
      Returns:
      the maximum fitness
      See Also:

    • getStatus

      public String getStatus()
      Description copied from class: Model
      Returns status message from model. Typically this is a string summarizing the current state of the simulation. For example, models with discrete traits (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.

      Specified by:
      getStatus in class Model
      Returns:
      status of active model

    • getCounter

      public String getCounter()
      Description copied from class: Model
      Gets a formatted string summarizing the elapsed time.
      Overrides:
      getCounter in class Model
      Returns:
      elapsed time as string

    • getRealtime

      public double getRealtime()
      Gets the elapsed time in real time units. The real time increments of microscopic updates depends on the fitness of the population. In populations with high fitness many events happen per unit time and hence the increments are smaller. In contrast in populations with low fitness fewer events happen and consequently more time elapses between subsequent events. By default no distinction between real time and generation time is made.
      Returns:
      elapsed real time

    • getNMean

      public int getNMean()
      Description copied from class: Model
      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
      Specified by:
      getNMean in class Model
      Returns:
      the number of mean values for all species

    • getNMean

      public int getNMean(int id)
      Description copied from class: Model
      Return the number of mean trait values for species with ID id.
      Specified by:
      getNMean in class Model
      Parameters:
      id - the species identifier
      Returns:
      the number of mean values for species id

    • getMeanTraits

      public boolean getMeanTraits(double[] mean)
      Description copied from class: Model
      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.

      Specified by:
      getMeanTraits in class Model
      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 boolean getMeanTraits(int id, double[] mean)
      Description copied from class: Model
      Return mean trait values for species with ID id.
      Specified by:
      getMeanTraits in class Model
      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.

    • getTraitNameAt

      public String getTraitNameAt(int id, int idx)
      Description copied from class: Model
      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.

      Overrides:
      getTraitNameAt in class Model
      Parameters:
      id - the species identifier
      idx - the index of the location
      Returns:
      description of traits at idx

    • getTraitData

      public <T> void getTraitData(int id, T[] colors, ColorMap<T> colorMap)
      Description copied from class: Model
      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.
      Specified by:
      getTraitData in class 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 boolean getMeanFitness(double[] mean)
      Description copied from class: Model
      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.

      Specified by:
      getMeanFitness in class Model
      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 boolean getMeanFitness(int id, double[] mean)
      Description copied from class: Model
      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.
      Specified by:
      getMeanFitness in class Model
      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.

    • getFitnessNameAt

      public String getFitnessNameAt(int id, int idx)
      Description copied from class: Model
      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.

      Overrides:
      getFitnessNameAt in class Model
      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)
      Description copied from class: Model
      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.

      Overrides:
      getScoreNameAt in class Model
      Parameters:
      id - the species identifier
      idx - the index of the location
      Returns:
      the score as a formatted string

    • getFitnessData

      public <T> void getFitnessData(int id, T[] colors, ColorMap.Gradient1D<T> colorMap)
      Description copied from class: Model
      Translates fitness data into colors using ColorMap colorMap. Used by GUI to visualize current state of model.
      Specified by:
      getFitnessData in class 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 void getFitnessHistogramData(int id, double[][] bins)
      Description copied from class: Model
      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.
      Specified by:
      getFitnessHistogramData in class Model
      Parameters:
      id - the species identifier
      bins - the array for storing histogram. For Discrete modules this is always one dimensional

    • getTagNameAt

      public String getTagNameAt(int id, int idx)
      Gets formatted tag of individual at location idx for species with ID id. The formatting may include HTML tags. Used by GUI for example to show tags in tooltips. Opportunity to track ancestry through tags.

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

      Parameters:
      id - the species identifier
      idx - the index of the location
      Returns:
      the formatted tag

    • getInteractionsAt

      public int getInteractionsAt(int id, int idx)
      Gets the number of interactions at location idx for species with ID id. Used by GUI for example to show interaction counts in tooltips.

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

      Parameters:
      id - the species identifier
      idx - the index of the location
      Returns:
      the interaction count

    • mouseHitNode

      public boolean mouseHitNode(int id, int hit, boolean alt)
      Used by GUI to interact with Model. Called whenever a mouse click/tap was registered by a node.
      Parameters:
      id - the species identifier
      hit - the index of the node hit by mouse
      alt - true if Alt-key pressed
      Returns:
      false if no actions taken

    • getSpeciesUpdate

      public SpeciesUpdate getSpeciesUpdate()
      Get species update type.
      Returns:
      the species update type

    • pickFocalSpecies

      public IBSPopulation pickFocalSpecies()
      Pick focal population according to the selected scheme.
      Returns:
      the focal population
      See Also:

    • pickFocalSpecies

      private IBSPopulation pickFocalSpecies(double[] rates, double total)
      Pick focal species with a probability proportional to the entries in rates.
      Parameters:
      rates - the rates with which to pick the focal species
      total - the sum of the rates
      Returns:
      the focal population or null if all populations extinct

    • pickFocalSpecies

      private IBSPopulation pickFocalSpecies(int skip)
      Pick next focal species. For a previous focal species with index idx the next focal species is (idx + skip) % nSpecies. Extinct populations are skipped.
      Parameters:
      skip - the number of species to skip
      Returns:
      the focal population or null all populations extinct

    • pickEvent

      protected IBS.Event pickEvent(IBSPopulation pop)
      Pick type of next event in focal population.
      Parameters:
      pop - the focal population
      Returns:
      the next event

    • 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
      Overrides:
      collectCLO in class Model
      Parameters:
      parser - the reference to parser that manages command line options
      See Also:

    • encodeState

      public void encodeState(StringBuilder plist)
      Description copied from class: Model
      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!
      Specified by:
      encodeState in class Model
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreState

      public boolean restoreState(Plist plist)
      Description copied from class: Model
      Restore the state encoded in the plist inspired map of key, value-pairs.
      Specified by:
      restoreState in class Model
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also:

    • random0n

      public int random0n(int n)
      random integer number from interval [0, n).
      Parameters:
      n - the upper limit of interval (exclusive)
      Returns:
      the random integer number in [0, n).

    • random01

      public double random01()
      Random number from interval [0, 1) with 32bit resolution. This is the default.
      Returns:
      the random number in [0, 1).