Package org.evoludo.simulator.modules

Class TBT

Object
Module
Discrete
TBT
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, HasPop2D, HasPop2D.Fitness, HasPop2D.Strategy, HasPop3D, HasPop3D.Fitness, HasPop3D.Strategy, CLOProvider
Direct Known Subclasses:
ATBT, DemesTBT, simTBT
public class TBT extends Discrete implements IBS.HasIBS.DPairs, ODE.HasODE, SDE.HasSDE, PDE.HasPDE, HasPop2D.Strategy, HasPop3D.Strategy, HasMean.Strategy, HasPop2D.Fitness, HasPop3D.Fitness, HasMean.Fitness, HasHistogram.Fitness, HasHistogram.Degree, HasHistogram.StatisticsProbability, HasHistogram.StatisticsTime, HasHistogram.StatisticsStationary
The module for investigating the evolutionary dynamics in the classical 2×2 games. The prisoner's dilemma and the snowdrift game are popular instances of 2×2 games. The ranking of the payoffs determines the characteristics of the game. Consider the payoff matrix \begin{align} \begin{matrix} & \begin{matrix} &\hspace{-3ex} C &\hspace{-1ex} D \end{matrix} \\ \begin{matrix} C\\ D \end{matrix} & \hspace{-1ex} \begin{pmatrix}R & S\\ T & P\end{pmatrix} \end{matrix} \end{align} where \(R\) refers to the payoff for mutual cooperation, \(S\) to the sucker's payoff to a cooperator facing a defector, \(T\) to the temptation to defect for a defector facing a cooperator and \(P\) to the punishment for mutual defection. The notation and terminology go back to Robert Axelrod who popularised the prisoner's dilemma in the early '80s. The prisoner's dilemma is characterized by the ranking \(T>R>P>S\), which means that a defector is always better off regardless of what the opponent plays, i.e. \(T>R\) and \(P>S\), yet the payoff for mutual cooperation exceeds that of mutual defection, i.e. \(R>P\). This results in a classical conflict of interest between the individual and the group, which is the essence of social dilemmas. As a consequence cooperation is doomed in the prisoner's dilemma in the absence of supporting mechanisms, such as structured populations with limited local interactions

Similarly, the snowdrift game is characterized by \(T>R>S>P\) and now the best strategy depends on the opponent. Against a cooperator it is still better to defect but against a defector it pays to cooperate. The snowdrift game is still a social dilemma because individuals are tempted to move away from mutual cooperation but the dilemma is relaxed because cooperation is not necessarily doomed in the absence of supporting mechanisms.

Author:
Christoph Hauert

  • Field Details

    • COOPERATE

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

    • DEFECT

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

    • payoffs

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

    • cloPayoffs

      public final CLOption cloPayoffs
      Command line option to set the 2×2 payoff matrix for interactions between cooperators and defectors.

  • Constructor Details

    • TBT

      public TBT(EvoLudo engine)
      Create a new instance of the module for 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 Discrete
      See Also:

    • unload

      public void unload()
      Description copied from class: Module
      Unload module and free all resources.
      Overrides:
      unload in class Discrete
      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 Module
      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 Module
      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".
      Specified by:
      getTitle in class Module
      Returns:
      the title of active module

    • getTraitName

      public String getTraitName(int idx)
      Description copied from class: Module
      Gets the name of the trait with index trait.
      Overrides:
      getTraitName in class Module
      Parameters:
      idx - the index of the trait
      Returns:
      the name of the trait

    • getMeanColors

      public Color[] getMeanColors()
      Description copied from class: Module
      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.
      Overrides:
      getMeanColors in class Module
      Returns:
      the array of mean value colors

    • 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 Module
      Returns:
      the index of the vacant type

    • getMinGameScore

      public double getMinGameScore()
      Description copied from class: Module
      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.
      Specified by:
      getMinGameScore in class Module
      Returns:
      the minimum payoff/score
      See Also:

    • getMaxGameScore

      public double getMaxGameScore()
      Description copied from class: Module
      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.
      Specified by:
      getMaxGameScore in class Module
      Returns:
      the maximum payoff/score
      See Also:

    • getMonoGameScore

      public double getMonoGameScore(int type)
      Description copied from class: Discrete
      Calculate and return the payoff/score of individuals in monomorphic populations with trait/strategy type.

      Note: Optional implementation. Returns Double#NaN if not defined or not implemented.

      Overrides:
      getMonoGameScore in class Discrete
      Parameters:
      type - trait/strategy
      Returns:
      payoff/score in monomorphic population with trait/strategy 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
      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
      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[] traitCount, double[] traitScore)
      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
      Parameters:
      traitCount - number of individuals for each trait/strategy
      traitScore - array for returning the payoffs/scores of each trait/strategy

    • setPayoffs

      public void setPayoffs(double[][] payoffs)
      Set the payoffs from the 2×2 matrix payoffs.
      Parameters:
      payoffs - the payoff matrix

    • getPayoffs

      public double[][] getPayoffs()
      Get the payoffs as a 2×2 matrix.
      Returns:
      the payoff matrix

    • setPayoff

      public void setPayoff(double payoff, int me, int you)
      Set the payoff for type me against type you to payoff.
      Parameters:
      payoff - the payoff to me
      me - the strategy index of the row player
      you - the strategy index of the column player

    • getPayoff

      public double getPayoff(int me, int you)
      Get the payoff for type me against type you.
      Parameters:
      me - the strategy index of the row player
      you - the strategy index of the column player
      Returns:
      the payoff to me

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

    • createIBSPop

      public IBSDPopulation createIBSPop()
      Description copied from class: Module
      Opportunity to supply custom individual based simulations.
      Overrides:
      createIBSPop in class Module
      Returns:
      the custom IBSPopulation or null to use default.