Package org.evoludo.simulator.modules

Class CDL

Object
Module
Discrete
CDL
All Implemented Interfaces:
Runnable, IBS.HasIBS, IBS.HasIBS.DGroups, IBS.HasIBS.DPairs, MilestoneListener, ODE.HasDE, ODE.HasODE, PDE.HasPDE, SDE.HasSDE, Features, Features.Groups, Features.Pairs, HasHistogram, HasHistogram.Degree, HasHistogram.Fitness, HasHistogram.StatisticsStationary, HasMean, HasMean.Fitness, HasMean.Strategy, HasPop2D, HasPop2D.Fitness, HasPop2D.Strategy, HasPop3D, HasPop3D.Fitness, HasPop3D.Strategy, HasS3, CLOProvider
Direct Known Subclasses:
CDLP, simCDL
public class CDL extends Discrete implements IBS.HasIBS.DGroups, ODE.HasODE, SDE.HasSDE, PDE.HasPDE, HasPop2D.Strategy, HasPop3D.Strategy, HasPop2D.Fitness, HasPop3D.Fitness, HasMean.Strategy, HasMean.Fitness, HasS3, HasHistogram.Fitness, HasHistogram.Degree, HasHistogram.StatisticsStationary
Cooperation in voluntary (non-linear) public goods interactions.
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:

    • LONER

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

    • r1

      protected double r1
      The multiplication factor of the (non-linear) public good with a single cooperator.

    • rN

      protected double rN
      The multiplication factor of the (non-linear) public good with all cooperators.

    • isLinearPGG

      protected boolean isLinearPGG
      The flag to indicate whether the public good is linear, i.e. r1 == rN.

    • costCoop

      protected double costCoop
      The cost of cooperation or the individual contribution to the public good.

    • payLoner

      protected double payLoner
      The payoff to loners.

    • payLoneCoop

      protected double payLoneCoop
      The payoff to lone cooperators.

    • payLoneDefect

      protected double payLoneDefect
      The payoff to lone defectors.

    • othersOnly

      protected boolean othersOnly
      The flag to indicate whether cooperators benefit from their own contributions to the common pool.

    • doSolo

      protected boolean doSolo
      The flag to indicate whether the public good gets created even with a single participant.

    • ninterest

      private double[] ninterest
      Helper variable containing the interpolated interest rates for 0, 1, ..., N cooperators among the up to N interacting individuals.

    • cloInterest

      public final CLOption cloInterest
      Command line option to set the multiplication factor for public good interactions.

    • cloCost

      public final CLOption cloCost
      Command line option to set the cost of cooperation, i.e. contributions to the public good.

    • cloLoner

      public final CLOption cloLoner
      Command line option to set the payoff to loners that refuse to participate in the public goods interaction.

    • cloLoneCooperator

      public final CLOption cloLoneCooperator
      Command line option to set the payoff to cooperators that failed to find any interaction partners.

    • cloLoneDefector

      public final CLOption cloLoneDefector
      Command line option to set the payoff to defectors that failed to find any interaction partners.

    • cloOthers

      public final CLOption cloOthers
      Command line option to set whether contributors get a share of the benefits generated by their own contributions.

    • cloSolo

      public final CLOption cloSolo
      Command line option to set whether a single contributor suffices to generate the public good.

  • Constructor Details

    • CDL

      public CDL(EvoLudo engine)
      Create a new instance of the module for voluntary public goods 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:

    • 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

    • 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

    • interest

      protected double interest(int nc)
      Helper method to return the interest rate/multiplication factor of the public good with nc contributors.
      Parameters:
      nc - the number of contributors
      Returns:
      the interest rate for nc contributors

    • 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

    • groupScores

      public void groupScores(int[] traitCount, double[] traitScore)
      Description copied from interface: IBS.HasIBS.DGroups
      Calculate the payoff/score for interactions in groups consisting of traits/strategies with respective numbers given in the array tCount. The interaction group size is given by the sum over tCount[i] for i=0,1,...,nTraits. The payoffs/scores for each of the nTraits traits/strategies must be stored and returned in the array tScore.

      Important: must be overridden and implemented in subclasses that define game interactions among groups of individuals (for groups with sizes nGroup>2, otherwise see IBS.HasIBS.DPairs.pairScores(int, int[], double[])).

      Specified by:
      groupScores in interface IBS.HasIBS.DGroups
      Parameters:
      traitCount - group composition given by the number of individuals with each trait/strategy
      traitScore - array for returning the payoffs/scores of each trait/strategy

    • mixedScores

      public void mixedScores(int[] count, int n, double[] traitScores)
      Calculate the average payoff/score in a finite population with the number of each trait/strategy provided in count for interaction groups of size n. The payoffs/scores for each of the nTraits traits/strategies must be stored and returned in the array traitScores.

      Notes:

      For payoff calculations:
      • each strategy sees one less of its own type in its environment
      • the size of the environment is nPopulation-1
      • the fact that the payoff of each strategy does not depend on its own type simplifies things
      If explicit calculations of the well-mixed scores are not available, interactions with everyone in well-mixed populations should be checked for and excluded with a warning in IBS.check() (see IBSMCPopulation for an example).

      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.
      standard non-linear PGG:
      \[ \begin{align} f_L =& c \sigma \\ f_D =& \frac{X}{M-1}\frac{N}{M-N} (B + S) + H_2(X+Y-1, 0, M-X-Y, N-1) \sigma c \\ f_C =& \frac{(r_1-1)N}{M-N} \left(1-H_2(X+Y-1, 0, M-X-Y, N-1)\right) c +\\ & \frac{N}{M-N}\left(\frac{X-2}{M-1} S - \frac{Y}{M-1} B\right) + H_2(X+Y-1, 0, M-X-Y, N-1) \sigma c \end{align} \] with \[ \begin{align} B =& \frac{M-1}{X+Y} \frac{M-N}{M}\left(r_1 - \frac{2 S}{N-1}\right) \times \left(\frac{N}{M-N} - \frac{\big(1-H_2(X+Y-1, 0, M-X-Y, N)\big)M}{N(X+Y-1)}\right) c \\ S =& \frac{(r_\text{all}-r_1)(X-1)}{(X+Y-2)} c \end{align} \] using \[ H_2(X, x, Y, y) = \frac{\binom{X}{x}\binom{Y}{y}}{\binom{X+Y}{x+y}} \]
      other's only non-linear PGG:
      \[ \begin{align} f_L =& c \sigma \\ f_D =& \frac{X}{M-1} \frac{N}{M-N} (B + S) + H_2(X+Y-1, 0, M-X-Y, N-1) \sigma c \\ f_C =& \frac{X-2}{M-1} \frac{N}{M-N} (B + S) +\frac{r_1 (N-1)}{(M-N)(X+Y)}c- \frac{N}{M-N}\left(\frac{r_1 (M-X-Y-N+1)}{N(X+Y)(X+Y-1)}+1\right)\times \\ & \left(1-H_2(X+Y-1, 0, M-X-Y, N-1)\right)c+ H_2(X+Y-1, 0, M-X-Y, N-1) \sigma c \end{align} \] with \[ \begin{align} B =& \frac{M-1}{X+Y} \frac{M-N}{M} \left(r_1 - \frac{2 S}{N-1}\right) \times \left(\frac{N}{M-N} - \frac{\big(1-H_2(X+Y-1, 0, M-X-Y, N)\big)M}{N(X+Y-1)}\right)c \\ S =& \frac{(r_\text{all}-r_1)(X-1)}{X+Y-2}\frac{N-1}{N-2}c. \end{align} \]
      Specified by:
      mixedScores in interface IBS.HasIBS.DGroups
      Parameters:
      count - number of individuals for each trait/strategy
      n - interaction group size
      traitScores - array for returning the payoffs/scores of each trait/strategy

    • avgScores

      public void avgScores(double[] density, int n, double[] avgscores)
      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.

      standard non-linear PGG:
      \[ \begin{align} f_L =& c \sigma \\ f_D =& x (B + S) c + \sigma c z^{N-1} \\ f_C =& (r_1-1)\left(1-z^{N-1}\right)c-y B c + x S c + \sigma c z^{N-1} \end{align} \] with \[ \begin{align} B =& \frac1{1-z} \left(r_1 - \frac{2 S}{N-1}\right) \left(1-\frac{1-z^N}{N (1-z)}\right) \\ S =& x \frac{r_\text{all}-r_1}{1-z} \end{align} \]
      other's only non-linear PGG:
      \[ \begin{align} f_L =& c \sigma \\ f_D =& x (B + S) c + \sigma c z^{N-1} \\ f_C =& x (B + S) c - \left(1-z^{N-1}\right)c + \sigma c z^{N-1} \end{align} \] with \[ \begin{align} B =& \frac1{1-z} \left(r_1 - \frac{2 S}{N-1}\right) \left(1 - \frac{1-z^N}{N (1-z)}\right) \\ S =& x \frac{r_\text{all}-r_1}{1-z}\frac{N-1}{N-2} \end{align} \]
      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

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

    • initInterest

      private void initInterest()
      Helper method to initialize the array with nonlinear interest rates for group size 1,2,3,...,N, where N is the maximum interaction group size based on the interest rate for groups with a single cooperator r1 and groups of all cooperators rN. Also takes into account whether a contributor gets a share of the benefit generated by their own contribution.

    • setCostCoop

      public void setCostCoop(double aValue)
      Set the cost of cooperation.
      Parameters:
      aValue - the cost of cooperation

    • getCostCoop

      public double getCostCoop()
      Get the cost of cooperation.
      Returns:
      the cost of cooperation

    • setInterest

      public void setInterest(double r)
      Set interest (multiplication factor) in linear public goods interaction.
      Parameters:
      r - the multiplication factor in linear public goods interactions

    • setInterest

      public void setInterest(double r1, double rN)
      Set non-linear interest (multiplication factor) in public goods interaction with interest r1 with a single contributor and rN if all N participants contribute. The interest rate for \(n\) contributors is given by \[ r(n) = r1 + n * (rN - r1) / M \] where \(M\) denotes the maximum number of contributors (\(N\) for standard public good games and one less for other's only public good games).
      Parameters:
      r1 - the multiplication factor for a single contributor
      rN - the multiplication factor with only contributors

    • getInterest

      public double getInterest()
      Get the interest rate in linear public goods games, or, for a single contributor in non-linear public goods games, i.e. if isLinearPGG == false.
      Returns:
      the interest rate

    • setSolo

      public void setSolo(boolean aValue)
      Set whether public goods is produced already with a single contributor and no other participants. Default is false.
      Parameters:
      aValue - true if single contributor is sufficient.

    • getSolo

      public boolean getSolo()
      Get whether a single contributor is enough to generate the public good.
      Returns:
      true if single contributor is sufficient to produce public good.

    • setOthersOnly

      public void setOthersOnly(boolean aValue)
      Set the flag whether the return of the public good is split among all members of the group or only all other's, i.e. excluding the contributor itself. In the other's only case contributors do not reap any share of the benefits created by their own contributions.
      Parameters:
      aValue - true if other's only

    • getOthersOnly

      public boolean getOthersOnly()
      Get the flag whether the return of the public good is split among all members of the group or only all other's, i.e. excluding the contributor itself.
      Returns:
      true other's only

    • setPayLoner

      public void setPayLoner(double aValue)
      Set the payoff of loners.
      Parameters:
      aValue - the new payoff of loners

    • getPayLoner

      public double getPayLoner()
      Set the payoff of loners.
      Returns:
      the payoff of loners

    • setPayLoneCoop

      public void setPayLoneCoop(double aValue)
      Set the payoff to lone cooperators. Defaults to loner payoff.
      Parameters:
      aValue - the payoff to lone cooperators.

    • getPayLoneCoop

      public double getPayLoneCoop()
      Get the payoff to lone cooperators.
      Returns:
      the payoff to lone cooperators.

    • setPayLoneDefect

      public void setPayLoneDefect(double aValue)
      Set the payoff to lone defectors. Defaults to loner payoff.
      Parameters:
      aValue - the payoff to lone defectors.

    • getPayLoneDefect

      public double getPayLoneDefect()
      Get the payoff to lone defectors.
      Returns:
      the payoff to lone defectors.

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