Class 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
- Author:
- Christoph Hauert
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
The extension for IBS simulations specific to voluntary (non-linear) public goods games.Nested classes/interfaces inherited from interface Features
Features.Groups, Features.Pairs, Features.Static
Nested classes/interfaces inherited from interface HasHistogram
HasHistogram.Degree, HasHistogram.Fitness, HasHistogram.StatisticsProbability, HasHistogram.StatisticsStationary, HasHistogram.StatisticsTime, HasHistogram.Strategy
Nested classes/interfaces inherited from interface HasMean
HasMean.Fitness, HasMean.Strategy
Nested classes/interfaces inherited from interface HasPop2D
HasPop2D.Fitness, HasPop2D.Strategy
Nested classes/interfaces inherited from interface HasPop3D
HasPop3D.Fitness, HasPop3D.Strategy
Nested classes/interfaces inherited from interface IBS.HasIBS
IBS.HasIBS.CGroups, IBS.HasIBS.CPairs, IBS.HasIBS.DGroups, IBS.HasIBS.DPairs, IBS.HasIBS.MCGroups, IBS.HasIBS.MCPairs
-
Field Summary
FieldsModifier and TypeFieldDescriptionfinal CLOption
Command line option to set the cost of cooperation, i.e.final CLOption
Command line option to set the multiplication factor for public good interactions.final CLOption
Command line option to set the payoff to cooperators that failed to find any interaction partners.final CLOption
Command line option to set the payoff to defectors that failed to find any interaction partners.final CLOption
Command line option to set the payoff to loners that refuse to participate in the public goods interaction.final CLOption
Command line option to set whether contributors get a share of the benefits generated by their own contributions.final CLOption
Command line option to set whether a single contributor suffices to generate the public good.static final int
The trait (and index) value of cooperators.protected double
The cost of cooperation or the individual contribution to the public good.static final int
The trait (and index) value of defectors.protected boolean
The flag to indicate whether the public good gets created even with a single participant.protected boolean
The flag to indicate whether the public good is linear, i.e.static final int
The trait (and index) value of loners.private double[]
Helper variable containing the interpolated interest rates for0, 1, ..., N
cooperators among the up toN
interacting individuals.protected boolean
The flag to indicate whether cooperators benefit from their own contributions to the common pool.protected double
The payoff to lone cooperators.protected double
The payoff to lone defectors.protected double
The payoff to loners.protected double
The multiplication factor of the (non-linear) public good with a single cooperator.protected double
The multiplication factor of the (non-linear) public good with all cooperators.Fields inherited from class Discrete
cloMonoStop, monoStop, mutation, species
Fields inherited from class Module
active, cloDeathRate, cloGeometry, cloNGroup, cloNPopulation, cloPhase2DAxis, cloSpeciesUpdateRate, cloTraitColors, cloTraitDisable, cloTraitNames, competition, deathRate, defaultColor, engine, ibs, ID, interaction, logger, map2fitness, markers, model, nActive, name, nGroup, nPopulation, nTraits, opponent, playerUpdate, speciesUpdateRate, structure, traitColor, traitName, trajectoryColor, VACANT
Fields inherited from interface HasS3
CORNER_LEFT, CORNER_RIGHT, CORNER_TOP, EDGE_BOTTOM, EDGE_LEFT, EDGE_RIGHT
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Providers of command line options may want to remove certain options that other providers provided by overriding this method.void
avgScores
(double[] density, int n, double[] avgscores) Calculate the average payoff/score for the frequency of traits/strategies specified in the arraydensity
for interactions in groups of sizen
.boolean
check()
Check all parameters.void
collectCLO
(CLOParser parser) All providers of command line options must implement this method to collect their options.Opportunity to supply custom individual based simulations.Returns a string with information about the authors of the module.double
Get the cost of cooperation.int
Get the index of dependent type or-1
if Module does not have an dependent type.double
Get the interest rate in linear public goods games, or, for a single contributor in non-linear public goods games, i.e.double
Calculates and returns the maximum payoff/score of an individual.double
Calculates and returns the minimum payoff/score of an individual.double
getMonoGameScore
(int type) Calculate and return the payoff/score of individuals in monomorphic populations with trait/strategytype
.boolean
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.double
Get the payoff to lone cooperators.double
Get the payoff to lone defectors.double
Set the payoff of loners.boolean
getSolo()
Get whether a single contributor is enough to generate the public good.getTitle()
Returns title of active module, e.g.void
groupScores
(int[] traitCount, double[] traitScore) Calculate the payoff/score for interactions in groups consisting of traits/strategies with respective numbers given in the arraytCount
.private void
Helper method to initialize the array with nonlinear interest rates for group size1,2,3,...,N
, whereN
is the maximum interaction group size based on the interest rate for groups with a single cooperatorr1
and groups of all cooperatorsrN
.protected double
interest
(int nc) Helper method to return the interest rate/multiplication factor of the public good withnc
contributors.void
load()
Load new module and perform basic initializations.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 incount
for interaction groups of sizen
.double
pairScores
(int me, int[] traitCount, double[] traitScore) Calculate and return total (accumulated) payoff/score for pairwise interactions of the focal individual with trait/strategyme
against opponents with different traits/strategies.void
setCostCoop
(double aValue) Set the cost of cooperation.void
setInterest
(double r) Set interest (multiplication factor) in linear public goods interaction.void
setInterest
(double r1, double rN) Set non-linear interest (multiplication factor) in public goods interaction with interestr1
with a single contributor andrN
if allN
participants contribute.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.void
setPayLoneCoop
(double aValue) Set the payoff to lone cooperators.void
setPayLoneDefect
(double aValue) Set the payoff to lone defectors.void
setPayLoner
(double aValue) Set the payoff of loners.void
setSolo
(boolean aValue) Set whether public goods is produced already with a single contributor and no other participants.void
unload()
Unload module and free all resources.Methods inherited from class Discrete
add, getMaxMonoGameScore, getMinMonoGameScore, getMonoStop, getMutation, setMonoStop
Methods inherited from class Module
createGeometry, getActiveTraits, getCompetitionGeometry, getDeathRate, getGeometry, getIBSPopulation, getID, getInteractionGeometry, getKey, getMapToFitness, getMarkers, getMeanColors, getModelTypes, getNActive, getName, getNGroup, getNPopulation, getNRoles, getNSpecies, getNTraits, getOpponent, getPlayerUpdate, getSpecies, getSpecies, getSpeciesUpdateRate, getTraitColor, getTraitColors, getTraitName, getTraitNames, getTrajectoryColor, getVacant, init, isNeutral, processColorMap, reset, run, setActiveTraits, setDeathRate, setGeometries, setIBSPopulation, setModel, setName, setNGroup, setNPopulation, setNTraits, setOpponent, setSpeciesUpdateRate, setTraitColors, setTraitNames, setTrajectoryColor
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface Features.Groups
getNGroup, isPairwise
Methods inherited from interface HasHistogram
getCustomLevels, getNTraits, getTraitColors
Methods inherited from interface IBS.HasIBS
createIBS
Methods inherited from interface IBS.HasIBS.DGroups
mixedScores
Methods inherited from interface MilestoneListener
modelDidInit, modelDidReset, modelLoaded, modelRelaxed, modelRunning, modelSettings, modelStopped, modelUnloaded, moduleLoaded, moduleRestored, moduleUnloaded
Methods inherited from interface ODE.HasODE
createODE
Methods inherited from interface PDE.HasPDE
createPDE
Methods inherited from interface SDE.HasSDE
createSDE
-
Field Details
-
COOPERATE
public static final int COOPERATEThe trait (and index) value of cooperators.- See Also:
-
DEFECT
public static final int DEFECTThe trait (and index) value of defectors.- See Also:
-
LONER
public static final int LONERThe trait (and index) value of loners.- See Also:
-
r1
protected double r1The multiplication factor of the (non-linear) public good with a single cooperator. -
rN
protected double rNThe multiplication factor of the (non-linear) public good with all cooperators. -
isLinearPGG
protected boolean isLinearPGGThe flag to indicate whether the public good is linear, i.e.r1 == rN
. -
costCoop
protected double costCoopThe cost of cooperation or the individual contribution to the public good. -
payLoner
protected double payLonerThe payoff to loners. -
payLoneCoop
protected double payLoneCoopThe payoff to lone cooperators. -
payLoneDefect
protected double payLoneDefectThe payoff to lone defectors. -
othersOnly
protected boolean othersOnlyThe flag to indicate whether cooperators benefit from their own contributions to the common pool. -
doSolo
protected boolean doSoloThe flag to indicate whether the public good gets created even with a single participant. -
ninterest
private double[] ninterestHelper variable containing the interpolated interest rates for0, 1, ..., N
cooperators among the up toN
interacting individuals. -
cloInterest
Command line option to set the multiplication factor for public good interactions. -
cloCost
Command line option to set the cost of cooperation, i.e. contributions to the public good. -
cloLoner
Command line option to set the payoff to loners that refuse to participate in the public goods interaction. -
cloLoneCooperator
Command line option to set the payoff to cooperators that failed to find any interaction partners. -
cloLoneDefector
Command line option to set the payoff to defectors that failed to find any interaction partners. -
cloOthers
Command line option to set whether contributors get a share of the benefits generated by their own contributions. -
cloSolo
Command line option to set whether a single contributor suffices to generate the public good.
-
-
Constructor Details
-
CDL
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. -
unload
public void unload()Description copied from class:Module
Unload module and free all resources. -
getAuthors
Description copied from class:Module
Returns a string with information about the authors of the module.- Overrides:
getAuthors
in classModule
- Returns:
- the names of the authors
-
getTitle
Description copied from class:Module
Returns title of active module, e.g. 2x2 games inTBT
returns "2x2 Games". -
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 interfaceODE.HasDE
- Overrides:
getDependent
in classModule
- 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 classModule
- 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 classModule
- 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/strategytype
.Note: Optional implementation. Returns
Double#NaN
if not defined or not implemented.- Overrides:
getMonoGameScore
in classDiscrete
- 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 withnc
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/strategyme
against opponents with different traits/strategies. The respective numbers of each of thenTraits
opponent traits/strategies are provided in the arraytCount
. The payoffs/scores for each of thenTraits
opponent traits/strategies must be stored and returned in the arraytScore
.Important: must be overridden and implemented in subclasses that define game interactions between pairs of individuals (
nGroup=2
,pairwise=true
), otherwise seeIBS.HasIBS.DGroups.groupScores(int[], double[])
.- Specified by:
pairScores
in interfaceIBS.HasIBS.DPairs
- Parameters:
me
- the trait index of the focal individualtraitCount
- number of opponents with each trait/strategytraitScore
- 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 arraytCount
. The interaction group size is given by the sum overtCount[i]
fori=0,1,...,nTraits
. The payoffs/scores for each of thenTraits
traits/strategies must be stored and returned in the arraytScore
.Important: must be overridden and implemented in subclasses that define game interactions among groups of individuals (for groups with sizes
nGroup>2
, otherwise seeIBS.HasIBS.DPairs.pairScores(int, int[], double[])
).- Specified by:
groupScores
in interfaceIBS.HasIBS.DGroups
- Parameters:
traitCount
- group composition given by the number of individuals with each trait/strategytraitScore
- 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 incount
for interaction groups of sizen
. The payoffs/scores for each of thenTraits
traits/strategies must be stored and returned in the arraytraitScores
.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
IBS.check()
(seeIBSMCPopulation
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 withIBS.HasIBS.DPairs.pairScores(int, int[], double[])
orIBS.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 interfaceIBS.HasIBS.DGroups
- Parameters:
count
- number of individuals for each trait/strategyn
- interaction group sizetraitScores
- 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 arraydensity
for interactions in groups of sizen
. The average payoffs/scores for each of thenTraits
traits/strategies must be stored and returned in the arrayavgscores
.Note: needs to be thread safe for parallel processing of PDE's.
IMPORTANT: one of
should be implemented in modules that advertise the model typesODE, SDE
orPDE
.Alternatively, the method
ODE.getDerivatives(double, double[], double[], double[])
may be overridden in a subclass ofODE
, which may prevent calls toavgScores(...)
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} \]
-
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 returntrue
.Note: All parameter changes that don't require a reset can be made on the fly, in particular also while a model is running.
-
initInterest
private void initInterest()Helper method to initialize the array with nonlinear interest rates for group size1,2,3,...,N
, whereN
is the maximum interaction group size based on the interest rate for groups with a single cooperatorr1
and groups of all cooperatorsrN
. 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 interestr1
with a single contributor andrN
if allN
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 contributorrN
- 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. ifisLinearPGG == 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 isfalse
.- 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
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, theparser
issues a warning and ignores the option. Thus, in general, implementing subclasses should first register their options and callsuper.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 interfaceCLOProvider
- Overrides:
collectCLO
in classDiscrete
- Parameters:
parser
- the reference to parser that manages command line options- See Also:
-
adjustCLO
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 callCLOParser.removeCLO(String[])
or variants thereof.- Specified by:
adjustCLO
in interfaceCLOProvider
- Parameters:
parser
- the reference to parser that manages command line options- See Also:
-
createIBSPop
Description copied from class:Module
Opportunity to supply custom individual based simulations.- Overrides:
createIBSPop
in classModule
- Returns:
- the custom IBSPopulation or
null
to use default.
-