Class Module<T extends Module<T>>

Object
Module<T>
Type Parameters:
T - the type of the module (self-referential generic)
All Implemented Interfaces:
Runnable, LifecycleListener, RunListener, Features, CLOProvider
Direct Known Subclasses:
Continuous, Discrete
public abstract class Module<T extends Module<T>> extends Object implements Features, LifecycleListener, RunListener, 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<T extends Module<T>> 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.

    • opponent

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

    • ibspop

      IBSPopulation<?,?> ibspop
      The field point to the IBSPopulation that represents this module in individual based simulations. null for all other model types.

    • VACANT_NAME

      public static final String VACANT_NAME
      The default name of the vacant type (empty site).
      See Also:

    • VACANT_COLOR

      public static final Color VACANT_COLOR
      The default name of the vacant type (empty site).

    • vacantIdx

      protected int vacantIdx
      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.

    • structure

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

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

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

    • cloPhase2DAxes

      public final CLOption cloPhase2DAxes
      Command line option to set the traits on phase plane axes.

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

  • Constructor Details

    • Module

      protected Module(EvoLudo engine, T 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 final 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 List<double[]> getMarkers()
      Get the list of markers. This serves to mark special values in different kinds of graphs.
      Returns:
      the list of markers

    • add

      public boolean add(T pop)
      Add pop to list of species. Duplicate entries are ignored. Allocate new list if necessary. Assign generic name to species if none provided.
      Parameters:
      pop - the module to add to species list.
      Returns:
      true if dpop successfully added; false adding failed or already included in list.

    • createModel

      public Model createModel(ModelType type)
      Creates a model of type type for module.

      Note: Override to provide custom model implementations.

      Important: any custom model implementations that involve random numbers, must use the shared random number generator for reproducibility

      Parameters:
      type - the type of Model to create
      Returns:
      the model for module or null if the module does not support the requested model type
      See Also:

    • 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

    • getOpponent

      public T 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(T opponent)
      Sets the opponent of this module/population. By default, for intra-species interactions, opponent == this holds.
      Parameters:
      opponent - the opponent of this population

    • getSpecies

      public T 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 List<T> 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

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

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

      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 ModelType[] 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

    • createIBSPopulation

      public IBSPopulation<?,?> createIBSPopulation()
      Opportunity to supply custom individual based simulations.
      Returns:
      the custom IBSPopulation or null to use default.

    • getVacantIdx

      public int getVacantIdx()
      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

    • hasVacant

      public boolean hasVacant()
      Check if module admits vacant type (empty sites).
      Returns:
      true if module admits vacant sites

    • 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 number of 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

    • setNTraits

      public void setNTraits(int nTraits, int vacantIdx)
      Sets the number of traits and the index of the vacant type (empty site).
      Parameters:
      nTraits - the number of traits
      vacantIdx - the index of the vacant type

    • 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

    • nameTrait

      private String nameTrait(int trait)
      Get default name for trait with index trait.
      Parameters:
      trait - the index of the trait
      Returns:
      the default name for the trait

    • 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 colors is null default colors are used until exhausted and then complemented by random colors. Otherwise the number of colors must equal nTraits or 2 * nTraits. For modules that have vacant sites, the length may be nTraits - 1 or 2 * (nTraits - 1), respectively. In the latter case the default colors for vacant sites are used.

      Note:The meaning of the second set of nTraits colors depends on the module type:

      Discrete
      the colors of individuals that switched traits 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 if colors successfuly set
      See Also:

    • 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 <M> ColorMap<M> processColorMap(ColorMap<M> 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:
      M - the type of the color map
      Parameters:
      colorMap - the color map
      Returns:
      the processed color map
      See Also:

    • getGeometry

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

    • 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

    • getMap2Fitness

      public Map2Fitness getMap2Fitness()
      Default implementation of Payoffs interface.
      Returns:
      the score-to-fitness map
      See Also:

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