Class Mutualism

Object
Module<Discrete>
Discrete
Mutualism
All Implemented Interfaces:
Runnable, LifecycleListener, Model.HasDE, Model.HasDE.DPairs, Model.HasDE.EM, Model.HasDE.ODE, Model.HasDE.RK5, Model.HasIBS, Model.HasIBS.DPairs, RunListener, Features, Features.Pairs, Features.Payoffs, HasHistogram, HasHistogram.Degree, HasHistogram.Fitness, HasHistogram.StatisticsStationary, HasMean, HasMean.Fitness, HasMean.Traits, HasPhase2D, HasPop2D, HasPop2D.Fitness, HasPop2D.Traits, HasPop3D, HasPop3D.Fitness, HasPop3D.Traits, CLOProvider
public class Mutualism extends Discrete implements Features.Payoffs, Model.HasIBS.DPairs, Model.HasDE.DPairs, Model.HasDE.EM, Model.HasDE.RK5, HasPop2D.Traits, HasPop3D.Traits, HasMean.Traits, HasPhase2D, HasPop2D.Fitness, HasPop3D.Fitness, HasMean.Fitness, HasHistogram.Fitness, HasHistogram.Degree, HasHistogram.StatisticsStationary
The module to investigate 2×2 games in interactions between species, while competition remains within species. For example, with two well-mixed populations of size N and M all individuals of the first species interact with all M members of the second species. Converely, the members of the second species interact with N members of the first species.

Structured populations are represented by two separate but aligned geometries such that interactions happen between geometries while competition happens within each geometry. For example, lattice structured populations are represented by two layers, one for each species with interactions between them and competition within. Thus, on a regular lattice with k neighbours an individual with index i interacts with k+1 individuals, namely it's k neighbours plus the one at the same location i on the other layer.

Notes:

  1. The population sizes of each species needs to be the same. Except for well-mixed populations.
  2. The competition and interaction structures can be different within and/or between species.
Author:
Christoph Hauert
See Also:

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

    • alpha

      double alpha
      The payoff for mutual cooperation.

    • beta

      double beta
      The payoff to a cooperator when facing a defector.

    • gamma

      double gamma
      The payoff to a defector when facing a cooperator.

    • delta

      double delta
      The payoff for mutual defection.

    • partner

      Mutualism partner
      The reference to the partner species with partner.partner == this.

    • map

      Mutualism.MutualismMap map
      The map for translating the model data into 2D phase plane representation.

    • cloPayHost

      public final CLOption cloPayHost
      Command line option to set the payoffs for the host species (when interacting with the mutualist species).

    • cloPayMutualist

      public final CLOption cloPayMutualist
      Command line option to set the payoffs for the mutualist species (when interacting with the host species).

  • Constructor Details

    • Mutualism

      public Mutualism(EvoLudo engine)
      Create a new instance of the module for inter-species 2×2 games.

      Important:

      This instantiates only the skeleton and only of one species. The other species is created only when loading this module.
      Parameters:
      engine - the manager of modules and pacemaker for running the model

    • Mutualism

      public Mutualism(Mutualism partner)
      Create a new instance of the second, partner species for inter-species 2×2 games.
      Parameters:
      partner - the reference to the partner species

  • Method Details

    • load

      public void load()
      Load new module and perform basic initializations.

      Notes:

      • Because the Host and Mutualist species are identical (potentially apart from interaction parameters) almost everything can be allocated and set in the load() method.
      • Otherwise, species specific settings can be moved to the constructor. In case the species differ more and e.g. use different variables additional species can be defined as inner classes that extend the outer class (here Mutualism), see EcoMutualism for an example.
      Overrides:
      load in class Discrete
      See Also:

    • unload

      public void unload()
      Unload module and free all resources.

      Important:

      This method is only called for the first created instance (see Mutualism(EvoLudo)) but not it's partner (see Mutualism(Mutualism)). In order to properly unload both species partner.unload() needs to be called. However, to avoid infinite loops, use, e.g. 
      if (partner != null) {
        partner.partner = null;
        partner.unload();
        partner = null;
}
      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<Discrete>
      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<Discrete>
      Returns:
      the names of the authors

    • getTitle

      public String getTitle()
      Description copied from interface: Features
      Returns title of active module, e.g. 2x2 games in TBT returns "2x2 Games".
      Specified by:
      getTitle in interface Features
      Returns:
      the title of active module

    • getDependent

      public int getDependent()
      Description copied from interface: Model.HasDE
      For replicator dynamics the frequencies of all traits must sum up to one. Hence, for nTraits traits there are only nTraits-1 degrees of freedom. The index returned by getDependent() marks the one rate of change that is derived from all the others.

      Notes:

      • Dependent traits are used by models where the frequencies of all types must sum up to one.
      • Density modules do not have dependent traits and getDependent() should return -1.
      • Currently differential equations implementations are only provided for Discrete modules.
      Specified by:
      getDependent in interface Model.HasDE
      Returns:
      the index of the dependent trait (or -1 if there is none)

    • getMinPayoff

      public double getMinPayoff()
      Description copied from interface: Features.Payoffs
      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:
      getMinPayoff in interface Features.Payoffs
      Returns:
      the minimum payoff/score
      See Also:

    • getMaxPayoff

      public double getMaxPayoff()
      Description copied from interface: Features.Payoffs
      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:
      getMaxPayoff in interface Features.Payoffs
      Returns:
      the maximum payoff/score
      See Also:

    • getMonoPayoff

      public double getMonoPayoff(int mono)
      Calculate and return the payoff/score of individuals in monomorphic populations with trait type.

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

      Note: mono score is ill defined as the homogeneous states of the population and its opponent is required!

      Overrides:
      getMonoPayoff in class Discrete
      Parameters:
      mono - the index of the trait
      Returns:
      payoff/score in monomorphic population with trait type

    • avgScores

      public void avgScores(double[] density, double[] avgscores)
      Description copied from interface: Model.HasDE.DPairs
      Calculate the average payoff for the frequency of traits specified in the array state for pairwise interactions. The average payoffs for each of the nTraits traits must be stored and returned in the array scores.
      Specified by:
      avgScores in interface Model.HasDE.DPairs
      Parameters:
      density - the frequency/density of each trait
      avgscores - the array for storing the average payoffs/scores of each trait

    • mixedScores

      public void mixedScores(int[] traitCount, double[] traitScore)
      Calculate the average payoff/score in a finite population with the number of each trait provided in count for pairwise interactions. The payoffs/scores for each of the nTraits traits 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 Model.HasIBS.DPairs.pairScores(int, int[], double[]) or Model.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 Model.check() (see CXPopulation for an example).

      Note: count refers to opponent (here a different species)

      Specified by:
      mixedScores in interface Model.HasIBS.DPairs
      Parameters:
      traitCount - number of individuals for each trait
      traitScore - array for returning the payoffs/scores of each trait

    • pairScores

      public double pairScores(int me, int[] traitCount, double[] traitScore)
      Description copied from interface: Model.HasIBS.DPairs
      Calculate and return total (accumulated) payoff/score for pairwise interactions of the focal individual with trait me against opponents with different traits. The respective numbers of each of the nTraits opponent traits are provided in the array tCount. The payoffs/scores for each of the nTraits opponent traits 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 Model.HasIBS.DGroups.groupScores(int[], double[]).

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

    • setPayoffs

      public void setPayoffs(double[][] payoffs)
      Set the payoffs from the 2×2 matrix payoffs for the species represented by this module (identified by Module.id).
      Parameters:
      payoffs - the payoff matrix

    • getPayoffs

      public double[][] getPayoffs()
      Get the payoffs in the form of a 2×2 matrix for the species represented by this module (identified by Module.id).
      Returns:
      the payoff matrix

    • setPayoff

      public void setPayoff(double payoff, int me, int you)
      Set the payoff when trait me interacts with you (in the other species).
      Parameters:
      payoff - the payoff to me
      me - the trait index of the row player
      you - the trait index of the column player (refers to other species)

    • getPayoff

      public double getPayoff(int me, int you)
      Get the payoff when trait me interacts with you (in the other species).
      Parameters:
      me - the trait index of the row player
      you - the trait index of the column player (refers to other species)
      Returns:
      the payoff to me

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