Package org.evoludo.simulator.modules

Class ATBT

Object
Module
Discrete
TBT
ATBT
All Implemented Interfaces:
Runnable, IBS.HasIBS, IBS.HasIBS.DPairs, MilestoneListener, ODE.HasDE, ODE.HasODE, PDE.HasPDE, SDE.HasSDE, Features, Features.Pairs, HasHistogram, HasHistogram.Degree, HasHistogram.Fitness, HasHistogram.StatisticsProbability, HasHistogram.StatisticsStationary, HasHistogram.StatisticsTime, HasMean, HasMean.Fitness, HasMean.Strategy, HasPhase2D, HasPop2D, HasPop2D.Fitness, HasPop2D.Strategy, HasPop3D, HasPop3D.Fitness, HasPop3D.Strategy, HasS3, CLOProvider
public class ATBT extends TBT implements IBS.HasIBS.DPairs, ODE.HasODE, SDE.HasSDE, PDE.HasPDE, HasPop2D.Strategy, HasPop3D.Strategy, HasMean.Strategy, HasS3, HasPhase2D, HasPop2D.Fitness, HasPop3D.Fitness, HasMean.Fitness, HasHistogram.Fitness, HasHistogram.Degree, HasHistogram.StatisticsStationary
The module for investigating the evolutionary dynamics in asymmetric 2×2 games. The origin of asymmetries can either be due to environmental differences where individuals occupy rich or poor sites or due to genetic differences, e.g. with weak and strong types. The key distinction between the two scenarios is that in the former case, the offspring only inherits the strategy but not the patch quality, whereas in the latter both the strategy and type are are transmitted to the offspring.
Author:
Christoph Hauert

  • Field Details

    • RICH

      public static final int RICH
      The identifier of rich sites: (int) (trait / 2).
      See Also:

    • POOR

      public static final int POOR
      The identifier of poor sites: (int) (trait / 2).
      See Also:

    • COOPERATE_RICH

      public static final int COOPERATE_RICH
      The trait (and index) value of rich cooperators.
      See Also:

    • COOPERATE_POOR

      public static final int COOPERATE_POOR
      The trait (and index) value of poor cooperators.
      See Also:

    • DEFECT_RICH

      public static final int DEFECT_RICH
      The trait (and index) value of rich defectors.
      See Also:

    • DEFECT_POOR

      public static final int DEFECT_POOR
      The trait (and index) value of poor defectors.
      See Also:

    • game

      double[][] game
      The 2×2 payoff matrix for interactions between cooperators and defectors.

    • environment

      double[] environment
      The array of environmental values for rich and poor sites.

    • feedback

      double[] feedback
      The array with environmental feedback rates.
      See Also:

    • environmentalAsymmetry

      boolean environmentalAsymmetry
      The flag indicating the type of environmental asymmetry. If true asymmetries are due to environmental differences (non-heritable) and if false asymmetries have a genetic origin (heritable).

    • init4x4

      private boolean init4x4
      The flag to indicate whether a generic 4×4 was provided to for the interactions among the four strategy types.

    • map

      ATBT.ATBTMap map
      The map for projecting the four dimensional dynamical system onto a 2D phase plane.

    • cloPayoffs4x4

      public final CLOption cloPayoffs4x4
      Command line option to set the 2×2 payoff matrix for interactions between cooperators and defectors or the (generic) 4×4 payoff matrix for arbitrary interactions between four strategic types.

    • cloEnvironment

      public final CLOption cloEnvironment
      Command line option to set the environmental values of the two different patch types.

    • cloAsymmetry

      public final CLOption cloAsymmetry
      Command line option to set the origin of asymmetries to differences in genotype or in the environment.

    • cloFeedback

      public final CLOption cloFeedback
      Command line option to set the feedback between strategic types and patch quality.

  • Constructor Details

    • ATBT

      public ATBT(EvoLudo engine)
      Create a new instance of the module for asymmetric 2×2 games.
      Parameters:
      engine - the manager of modules and pacemaker for running the model

  • Method Details

    • load

      public void load()
      Description copied from class: Module
      Load new module and perform basic initializations.
      Overrides:
      load in class TBT
      See Also:

    • unload

      public void unload()
      Description copied from class: Module
      Unload module and free all resources.
      Overrides:
      unload in class TBT
      See Also:

    • getKey

      public String getKey()
      Description copied from class: Module
      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.
      Overrides:
      getKey in class TBT
      Returns:
      the identifying key of this module

    • getAuthors

      public String getAuthors()
      Description copied from class: Module
      Returns a string with information about the authors of the module.
      Overrides:
      getAuthors in class TBT
      Returns:
      the names of the authors

    • getTitle

      public String getTitle()
      Description copied from class: Module
      Returns title of active module, e.g. 2x2 games in TBT returns "2x2 Games".
      Overrides:
      getTitle in class TBT
      Returns:
      the title of active module

    • getDependent

      public int getDependent()
      Description copied from class: Module
      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
      Specified by:
      getDependent in interface ODE.HasDE
      Overrides:
      getDependent in class TBT
      Returns:
      the index of the vacant type

    • pairScores

      public double pairScores(int me, int[] traitCount, double[] traitScore)
      Description copied from interface: IBS.HasIBS.DPairs
      Calculate and return total (accumulated) payoff/score for pairwise interactions of the focal individual with trait/strategy me against opponents with different traits/strategies. The respective numbers of each of the nTraits opponent traits/strategies are provided in the array tCount. The payoffs/scores for each of the nTraits opponent traits/strategies must be stored and returned in the array tScore.

      Important: must be overridden and implemented in subclasses that define game interactions between pairs of individuals (nGroup=2, pairwise=true), otherwise see IBS.HasIBS.DGroups.groupScores(int[], double[]).

      Specified by:
      pairScores in interface IBS.HasIBS.DPairs
      Overrides:
      pairScores in class TBT
      Parameters:
      me - the trait index of the focal individual
      traitCount - number of opponents with each trait/strategy
      traitScore - array for returning the scores of each opponent trait/strategy
      Returns:
      score of focal individual me accumulated over all interactions

    • avgScores

      public void avgScores(double[] density, int n, double[] avgscores)
      Description copied from interface: ODE.HasDE
      Calculate the average payoff/score for the frequency of traits/strategies specified in the array density for interactions in groups of size n. The average payoffs/scores for each of the nTraits traits/strategies must be stored and returned in the array avgscores.

      Note: needs to be thread safe for parallel processing of PDE's.

      IMPORTANT: one of

      should be implemented in modules that advertise the model types ODE, SDE or PDE.

      Alternatively, the method ODE.getDerivatives(double, double[], double[], double[]) may be overridden in a subclass of ODE, which may prevent calls to avgScores(...) altogether.

      Specified by:
      avgScores in interface ODE.HasDE
      Overrides:
      avgScores in class TBT
      Parameters:
      density - the frequency/density of each trait/strategy
      n - the size of interaction groups
      avgscores - the array for storing the average payoffs/scores for each strategic type

    • mixedScores

      public void mixedScores(int[] count, double[] traitScores)
      Description copied from interface: IBS.HasIBS.DPairs
      Calculate the average payoff/score in a finite population with the number of each trait/strategy provided in count for pairwise interactions. The payoffs/scores for each of the nTraits traits/strategies must be stored and returned in the array traitScores.

      Important: must be overridden and implemented in subclasses that define game interactions in well-mixed populations where individuals interact with everyone else. Computationally it is not feasible to cover this scenario with IBS.HasIBS.DPairs.pairScores(int, int[], double[]) or IBS.HasIBS.DGroups.groupScores(int[], double[]), respectively.

      Note: If explicit calculations of the well-mixed scores are not available, interactions with everyone in well-mixed populations should checked for and excluded with a warning in IBS.check() (see CXPopulation for an example).

      Specified by:
      mixedScores in interface IBS.HasIBS.DPairs
      Overrides:
      mixedScores in class TBT
      Parameters:
      count - number of individuals for each trait/strategy
      traitScores - array for returning the payoffs/scores of each trait/strategy

    • check

      public boolean check()
      Description copied from class: Module
      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.

      Overrides:
      check in class Module
      Returns:
      true to trigger reset
      See Also:

    • setPayoffs

      public void setPayoffs(double[][] payoffs)
      Set the payoff matrix to payoffs, which can be a 2×2 or 4×4 matrix. For 2×2 matrices, it specifies the payoffs for interactions between cooperators and defectors, while for 4×4 matrices any generic payoff matrix for interactions among four types of strategies is possible.
      Overrides:
      setPayoffs in class TBT
      Parameters:
      payoffs - the payoff matrix

    • setEnvironmentalAsymmetry

      public void setEnvironmentalAsymmetry(boolean asym)
      Set the flag whether asymmetries are due to environmental differences, i.e. patch qualities (as opposed to genetic differences).
      Parameters:
      asym - true if asymmetries are of environmental origin

    • getEnvironmentalAsymmetry

      public boolean getEnvironmentalAsymmetry()
      Check whether asymmetries are due to environmental differences, i.e. patch qualities (as opposed to genetic differences).
      Returns:
      true if asymmetries are of environmental origin

    • setFeedback

      public boolean setFeedback(double[] feedback)
      Set the feedback between strategic types and patch qualities:
      1. cooperators restoring poor sites
      2. defectors degrading rich sites
      3. cooperators degrading rich sites
      4. defectors restoring poor sites
      The array feedback can have one, two or four elements:
      1. all four rates/probabilities are the same
      2. rates/probabilities for cooperators restoring poor sites and defectors degrading rich sites. The other two, cooperators degrading rich sites and defectors restoring poor sites are set to zero.
      3. all four rates/probabilities are set.
      Parameters:
      feedback - the array with feedback rates/probabilities
      Returns:
      true if feedback successfully set

    • getFeedback

      public double[] getFeedback()
      Get the array with feedback rates/probabilities.
      Returns:
      the feedback array
      See Also:

    • setEnvironment

      public boolean setEnvironment(double[] environment)
      Set the (array of) environmental values or patch qualities for rich and poor sites.
      Parameters:
      environment - the array of patch values
      Returns:
      true if environmental values successfully set

    • getEnvironment

      public double[] getEnvironment()
      Get the environmental values or patch qualities for rich and poor sites.
      Returns:
      the array of patch values

    • getPhase2DMap

      public HasPhase2D.Data2Phase getPhase2DMap()
      Description copied from interface: HasPhase2D
      Get the map that transforms the data of the module to a 2D phase plane (projection).
      Specified by:
      getPhase2DMap in interface HasPhase2D
      Returns:
      the map

    • 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 TBT
      Parameters:
      parser - the reference to parser that manages command line options
      See Also:

    • adjustCLO

      public void adjustCLO(CLOParser parser)
      Description copied from interface: CLOProvider
      Providers of command line options may want to remove certain options that other providers provided by overriding this method. After all command line options are collected, all providers get a chance to adjust the collection. In particular, options should be removed that do not make sense in present context. Overriding methods usually call CLOParser.removeCLO(String[]) or variants thereof.
      Specified by:
      adjustCLO in interface CLOProvider
      Overrides:
      adjustCLO in class TBT
      Parameters:
      parser - the reference to parser that manages command line options
      See Also:

    • createIBSPop

      public ATBT.ATBTPop createIBSPop()
      Opportunity to supply custom individual based simulations.

      Note: Cannot return more specific type due to subclass

      invalid reference 
      CG#createIBSPop()
      Overrides:
      createIBSPop in class TBT
      Returns:
      the custom IBSPopulation or null to use default.

    • createODE

      public Model createODE()
      Description copied from interface: ODE.HasODE
      Provides opportunity for model to supply custom ODE implementation.

      Important: if the custom ODE implementation involves random numbers, the shared random number generator should be used for reproducibility

      Specified by:
      createODE in interface ODE.HasODE
      Returns:
      the custom ODE model or null to use use default
      See Also: