Package org.evoludo.simulator.modules

Class Module

Object
Module
All Implemented Interfaces:
Runnable, MilestoneListener, Features, CLOProvider
Direct Known Subclasses:
Continuous, Discrete
public abstract class Module extends Object implements Features, MilestoneListener, CLOProvider, Runnable
Parent class of all EvoLudo modules.
Author:
Christoph Hauert

  • Field Details

    • name

      protected String name
      The name of the species. Mainly used in multi-species modules.

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

    • model

      protected Model model
      Reference to current model.

    • species

      ArrayList<? extends Module> species
      List with all species in module including this one.

      Important:

      List should be shared with other populations (to simplify bookkeeping) but the species list CANNOT be static! Otherwise it is impossible to run multiple instances of modules/models concurrently!

    • ID

      final int ID
      In multi-species modules each species is represented by a Module, see species. The ID provides a unique identifier for each species.

    • markers

      protected Markers markers
      Markers for annotating graphical represenations of the state of the model.

    • ibs

      IBSPopulation ibs
      The field point to the IBSPopulation that represents this module in individual based simulations. null for all other model types.

    • VACANT

      public int VACANT
      The index for the vacant type (empty site) or -1 if Module does not admit empty sites.

    • nTraits

      protected int nTraits
      The number of traits in this module

    • active

      boolean[] active
      The array indicating which traits are active.

    • nActive

      protected int nActive
      The number of active traits. nActive &lt;= nTraits must hold.

    • traitName

      String[] traitName
      Names of traits.

    • defaultColor

      protected static Color[] defaultColor
      The array with default colors for traits. Important: if defaultColor is set already here (static allocation), headless mode for simulations is prevented. In order to avoid this, simply allocate and assign the colors in the constructor.

    • traitColor

      protected Color[] traitColor
      The array with trait colors. Important: if traitColor is set already here (static allocation), headless mode for simulations is prevented. In order to avoid this, simply allocate and assign the colors in the constructor.

    • trajectoryColor

      protected Color trajectoryColor
      Color for trajectories. Important: if trajectoryColor is set already here, headless mode for simulations is prevented. In order to avoid this, simply allocate and assign the colors in the constructor.

    • opponent

      Module opponent
      Reference to Module of opponent. For Modules referring to intra-species interactions opponent == this must hold.

    • structure

      protected Geometry structure
      The geometry of population (interaction and competition graphs are the same)

    • interaction

      protected Geometry interaction
      The geometry of interaction structure

    • competition

      protected Geometry competition
      The geometry of competition structure

    • speciesUpdateRate

      protected double speciesUpdateRate
      Update rate for this species. Only used in multi-species modules.

    • nPopulation

      protected int nPopulation
      The population size.

    • deathRate

      protected double deathRate
      Death rate for ecological population updates.

    • map2fitness

      protected Map2Fitness map2fitness
      Map to convert score/payoff to fitness

    • playerUpdate

      protected PlayerUpdate playerUpdate
      Map to convert score/payoff to fitness

    • nGroup

      protected int nGroup
      The interaction group size.

    • cloSpeciesUpdateRate

      public final CLOption cloSpeciesUpdateRate
      Command line option to set the relative rate for updating each population/species. Only relevant for multi-species interactions.

    • cloGeometry

      public final CLOption cloGeometry
      Command line option to set the geometry (interaction and competition graphs identical).
      See Also:

    • cloNPopulation

      public final CLOption cloNPopulation
      Command line option to set the population size.

    • cloDeathRate

      public final CLOption cloDeathRate
      Command line option to set death rate for ecological population updates.

    • cloNGroup

      public final CLOption cloNGroup
      Command line option to set the size of interaction groups.

    • cloTraitDisable

      public final CLOption cloTraitDisable
      Command line option to disable individual traits. Any module offering this capability needs to add cloTrai to the set of available options. By default all traits are activated.

    • cloTraitColors

      public final CLOption cloTraitColors
      Command line option to set the color of traits.

    • cloTraitNames

      public final CLOption cloTraitNames
      Command line option to assign trait names.

    • cloPhase2DAxis

      public final CLOption cloPhase2DAxis
      Command line option to set the traits on phase plane axis.

      Note: option not automatically added. Modules that supports multiple traits should load it in collectCLO(CLOParser).

  • Constructor Details

    • Module

      protected Module(EvoLudo engine, Module partner)
      Instantiate a new Module with engine and partner. If partner == null this is a single species module and interactions within species (opponent == this holds).
      Parameters:
      engine - the pacemaker for running the model
      partner - the module of the partner species or null for single species modules

  • Method Details

    • getName

      public String getName()
      Gets the name of this species
      Returns:
      the name of the species

    • setName

      public void setName(String name)
      Sets the name of this species. If name == null the name is cleared.
      Parameters:
      name - the new name of the species

    • getID

      public int getID()
      Gets unique identifier ID of species.
      Returns:
      the unique identifier of the species.

    • getMarkers

      public ArrayList<double[]> getMarkers()
      Get the list of markers. This serves to mark special values in different kinds of graphs.
      Returns:
      the list of markers

    • setModel

      public void setModel(Model model)
      Set the current model. This is available before the model get loaded. Useful for custom implementations of models.
      Parameters:
      model - the current model

    • getSpecies

      public Module getSpecies(int idx)
      Gets module of species at index idx.
      Parameters:
      idx - the index of species to retrieve
      Returns:
      the module of species

    • getSpecies

      public ArrayList<? extends Module> getSpecies()
      Gets list with all species.
      Returns:
      the list with all species

    • getNSpecies

      public int getNSpecies()
      Gets the number of different species in this module.
      Returns:
      the number of species in this module

    • getKey

      public String getKey()
      Returns identifier of the active module. For example, 2x2 games in TBT return "2x2". This corresponds to the argument for the --module option to load a particular module. The default is to use the class name.
      Returns:
      the identifying key of this module

    • getAuthors

      public String getAuthors()
      Returns a string with information about the authors of the module.
      Returns:
      the names of the authors

    • getTitle

      public abstract String getTitle()
      Returns title of active module, e.g. 2x2 games in TBT returns "2x2 Games".
      Returns:
      the title of active module

    • load

      public void load()
      Load new module and perform basic initializations.
      See Also:

    • unload

      public void unload()
      Unload module and free all resources.
      See Also:

    • check

      public boolean check()
      Check all parameters. After this call all parameters must be consistent. If parameter adjustments require a reset then this method must return true.

      Note: All parameter changes that don't require a reset can be made on the fly, in particular also while a model is running.

      Returns:
      true to trigger reset
      See Also:

    • init

      public void init()
      Initialize Module based on current parameters. This requires that parameters are consistent, i.e. check() has been called before.

      Note: The difference between init() and reset() is that init() leaves population structures untouched and only initializes the strategies.

      See Also:

    • reset

      public void reset()
      Reset Module based on current parameters. This requires that parameters are consistent, i.e. check() has been called before.

      Note: The difference between init() and reset() is that init() leaves population structures untouched and only initializes the strategies.

      See Also:

    • run

      public void run()

      Default run-loop for modules. Opportunity to override in subclasses for running customized simulations. Currently only called from EvoLudoJRE.simulation() if custom simulation class is specified in jar file.

      Specified by:
      run in interface Runnable

    • getModelTypes

      public Type[] getModelTypes()
      Return array of Model types that this Module supports.
      Returns:
      the array of supported Model types

    • setIBSPopulation

      public void setIBSPopulation(IBSPopulation ibs)
      Sets the reference to the IBSPopulation that represents this module in individual based simulations.
      Parameters:
      ibs - the individual based population

    • getIBSPopulation

      public IBSPopulation getIBSPopulation()
      Gets the IBSPopulation that represents this module in individual based simulations or null for all other types of models.
      Returns:
      the IBSPopulation that represents this module or null

    • createIBSPop

      public IBSPopulation createIBSPop()
      Opportunity to supply custom individual based simulations.
      Returns:
      the custom IBSPopulation or null to use default.

    • getVacant

      public int getVacant()
      Get the index for the vacant type or -1 if Module does not admit empty sites. In Discrete modules this is the index of the vacant type e.g. in the name or color vectors. Currently unused in Continuous modules.
      Returns:
      the index of the vacant type

    • getDependent

      public int getDependent()
      Get the index of dependent type or -1 if Module does not have an dependent type.

      Notes:

      • Dependent types are used by replicator type models where the frequencies of all types must sum up to one. Currently only used by Discrete modules.
      • Density modules do not have dependent types.
      • By default use vacant type as the dependent
      Returns:
      the index of the vacant type

    • getNTraits

      public int getNTraits()
      Gets the number of traits in this Module. For example, in 2x2 Games TBT this returns 2.
      Returns:
      the number of traits

    • getNRoles

      public int getNRoles()
      Gets the numberof roles that an individual can adopt. For example the role of a proposer or a responder in the Ultimatum game or the first or second movers in the Centipede game.
      Returns:
      the number of roles of an individual

    • setNTraits

      public void setNTraits(int nTraits)
      Sets the number of traits in this Module.

      Note:

      Changing the number of traits is a fairly involved change because it requires re-allocating most memory. Most Modules set nTraits early on and leave it unchanged.
      Parameters:
      nTraits - the number of traits

    • setActiveTraits

      public void setActiveTraits(boolean[] active)
      Sets which traits are currently active.
      Parameters:
      active - the array indicating active traits (or null if all traits are active)

    • getActiveTraits

      public boolean[] getActiveTraits()
      Gets an array indicating which traits are active.
      Returns:
      the array of active traits

    • getNActive

      public int getNActive()
      Gets the number of active traits.
      Returns:
      the number of active traits

    • getTraitName

      public String getTraitName(int trait)
      Gets the name of the trait with index trait.
      Parameters:
      trait - the index of the trait
      Returns:
      the name of the trait

    • getTraitNames

      public String[] getTraitNames()
      Gets the names of all traits. By default returns { "Trait A", "Trait B",...}.
      Returns:
      the array with the names of all traits

    • setTraitNames

      public void setTraitNames(String[] names)
      Set trait names. Underscores, '_', are converted to spaces.

      Note: If names == null or names.length &lt; nTraits then additional traits are named "Trait A", "Trait B", etc. If names.length &gt; nTraits then excess names are ignored.

      Parameters:
      names - the names of the traits

    • getTraitColor

      public Color getTraitColor(int trait)
      Gets the color for the trait with index trait.
      Parameters:
      trait - the index of the trait
      Returns:
      the color of the trait

    • getTraitColors

      public Color[] getTraitColors()
      Gets the colors for all traits.
      Returns:
      the array of trait colors

    • getMeanColors

      public Color[] getMeanColors()
      Gets the colors for the mean values of traits. By default this is the same as the trait colors. Opportunity for subclasses to return different sets of colors for plotting mean values.
      Returns:
      the array of mean value colors

    • setTraitColors

      public boolean setTraitColors(Color[] colors)
      Sets trait colors specified in colors. If less than nTraits colors are specified, additional traits are colored using the default colors. If still not enough, random colors are generated. Both Discrete and Continuous modules require 2*nTraits colors. The meaning of the second set of nTraits colors depends on the trait type:
      discrete
      the colors of individuals that switched strategy since the last update
      continuous
      the colors for the mean ± standard deviation, see e.g. Mean.
      Specifying the second set of colors is optional. By default they are automatically generated as lighter versions of the base colors.
      Parameters:
      colors - the array of colors for the different traits
      Returns:
      true always signal that colors have changed (too difficult and of too little importance to check whether colors remained the same)

    • getTrajectoryColor

      public Color getTrajectoryColor()
      Gets the color of trajectories.
      Returns:
      the trajectory color (defaults to black)

    • setTrajectoryColor

      public boolean setTrajectoryColor(Color color)
      Sets color of trajectories. Default color is black. If color is null reverts to default.

      Note: Using transparent colors is useful for models with noise (simulations or SDE's) to identify regions of attraction (e.g. stochastic limit cycles) as darker shaded areas because the population spends much of its time there while less frequently visited areas of the phase space are lighter in color.

      Parameters:
      color - the color for the trajectories
      Returns:
      true if color changed

    • processColorMap

      public <T> ColorMap<T> processColorMap(ColorMap<T> colorMap)
      Opportunity for modules to make adjustments to the color map in graphs such as Pop2D or Pop3D. By default no changes are made.
      Type Parameters:
      T - the type of the color map
      Parameters:
      colorMap - the color map
      Returns:
      the processed color map
      See Also:

    • getMinGameScore

      public abstract double getMinGameScore()
      Calculates and returns the minimum payoff/score of an individual. This value is important for converting payoffs/scores into probabilities, for scaling graphical output and some optimizations.
      Returns:
      the minimum payoff/score
      See Also:

    • getMaxGameScore

      public abstract double getMaxGameScore()
      Calculates and returns the maximum payoff/score of an individual. This value is important for converting payoffs/scores into probabilities, for scaling graphical output and some optimizations.
      Returns:
      the maximum payoff/score
      See Also:

    • getMinMonoGameScore

      public abstract double getMinMonoGameScore()
      Calculates and returns the minimum payoff/score of individuals in monomorphic populations.
      Returns:
      the minimum payoff/score in monomorphic populations

    • getMaxMonoGameScore

      public abstract double getMaxMonoGameScore()
      Calculates and returns the maximum payoff/score of individuals in monomorphic populations.
      Returns:
      the maximum payoff/score in monomorphic populations

    • isNeutral

      public boolean isNeutral()
      Checks whether dynamic is neutral, i.e. no selection acting on the different traits.
      Returns:
      true if all payoffs identical

    • getOpponent

      public Module getOpponent()
      Gets the opponent of this module/population. By default, for intra-species interactions, simply returns this module/population, i.e opponent == this.
      Returns:
      the opponent of this population

    • setOpponent

      public void setOpponent(Module opponent)
      Sets the opponent of this module/population. By default, for intra-species interactions, opponent == this holds.
      Parameters:
      opponent - the opponent of this population

    • getGeometry

      public Geometry getGeometry()
      Gets the geometry of the population.
      Returns:
      the geometry of the population

    • createGeometry

      public Geometry createGeometry()
      Opportunity to supply Geometry, in case interaction and competition graphs are the same.
      Returns:
      the new geometry

    • setGeometries

      public void setGeometries(Geometry interaction, Geometry competition)
      Sets different geometries for interactions and competition.
      Parameters:
      interaction - the geometry for interactions
      competition - the geometry for competition
      See Also:

    • getInteractionGeometry

      public Geometry getInteractionGeometry()
      Gets the interaction geometry.
      Returns:
      the interaction geometry
      See Also:

    • getCompetitionGeometry

      public Geometry getCompetitionGeometry()
      Gets the competition geometry.
      Returns:
      the competition geometry
      See Also:

    • setSpeciesUpdateRate

      public boolean setSpeciesUpdateRate(double rate)
      Sets the species update rate to rate. Only used in multi-species modules. Determines the relative rate at which this species is picked as compared to others.
      Parameters:
      rate - the update rate of this species
      Returns:
      true if species update rate changed
      See Also:

    • getSpeciesUpdateRate

      public double getSpeciesUpdateRate()
      Gets the update rate of this species. Only used in multi-species modules. Determines the relative rate at which this species is picked as compared to others.
      Returns:
      the species update rate
      See Also:

    • setNPopulation

      public boolean setNPopulation(int size)
      Sets the population size. For models with vacancies this is the maximum population size. Currently this only affects IBS and SDE models. For SDE's it determines the magnitude of noise. For IBS this is a fundamental change, which mandates requesting to reset the model.
      Parameters:
      size - the population size
      Returns:
      true if population size changed
      See Also:

    • getNPopulation

      public int getNPopulation()
      Gets the population size.

      Note: Without vacant sites the population size is fixed. For ecological models with vacant sites this corresponds to the maximum population size.

      Returns:
      the population size

    • setDeathRate

      public boolean setDeathRate(double rate)
      Sets the death rate for ecological population updates.
      Parameters:
      rate - the death rate
      Returns:
      true if the death rate changed

    • getDeathRate

      public double getDeathRate()
      Gets the death rate for ecological population updates.
      Returns:
      the death rate

    • getMutation

      public abstract Mutation getMutation()
      Gets the mutation type.
      Returns:
      the mutation type

    • getMapToFitness

      public Map2Fitness getMapToFitness()
      Gets the score/payoff to fitness map.
      Returns:
      the score-to-fitness map

    • getPlayerUpdate

      public PlayerUpdate getPlayerUpdate()
      Gets the score/payoff to fitness map.
      Returns:
      the score-to-fitness map

    • setNGroup

      public boolean setNGroup(int size)
      Sets the interaction group size. Changes trigger a request to reset the module.
      Parameters:
      size - the interaction group size
      Returns:
      true if the group size changed

    • getNGroup

      public int getNGroup()
      Gets the interaction group size.
      Returns:
      the interaction group size

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