Package org.evoludo.simulator.models

Class IBSMCPopulation

Object
IBSPopulation
IBSMCPopulation
Direct Known Subclasses:
IBSCPopulation
public class IBSMCPopulation extends IBSPopulation
The core class for individual based simulations with multiple continuous traits. Manages the traits of the population, while delegating the management of the population and individual fitness as well as simulation steps to super. Note that some further optimizations and simplifications are possible in the special case of a single continuous trait, which is handled in the subclass IBSCPopulation.
Author:
Christoph Hauert
See Also:

  • Field Details

    • module

      protected Continuous module
      The continuous module associated with this model.

      Note: This deliberately hides IBSPopulation.module. The two variables point to the same object but this setup avoids unnecessary casts because only Continuous modules generate IBSCPopulation(s).

    • pairmodule

      protected IBS.HasIBS.MCPairs pairmodule
      For pairwise interaction modules module==pairmodule holds and null otherwise. Convenience field to reduce the number of (unnecessary) casts.
      See Also:

    • groupmodule

      protected IBS.HasIBS.MCGroups groupmodule
      For group interaction modules module==groupmodule holds and null otherwise. Convenience field to reduce the number of (unnecessary) casts.
      See Also:

    • opponent

      IBSMCPopulation opponent
      The interaction partner/opponent of this population opponent.getModule()==getModule().getOpponent(). In intra-species interactions opponent==this. Convenience field.

      Note: This deliberately hides IBSPopulation.opponent. The two variables point to the same object but this setup avoids unnecessary casts because only Discrete modules generate IBSDPopulation(s).

    • mutation

      protected Mutation.Continuous mutation
      The mutation parameters.

    • traitMin

      protected double[] traitMin
      The array with the minimal values for each trait. Convenience variable to reduce calls to module.

      Note: Internally traits are always scaled to [0, 1].

      See Also:

    • traitMax

      protected double[] traitMax
      The array with the maximal values for each trait. Convenience variable to reduce calls to module.

      Note: Internally traits are always scaled to [0, 1].

      See Also:

    • traits

      public double[] traits
      The array of individual traits. The traits of individual i are stored at traits[i * nTraits] through traits[(i + 1) * nTraits - 1]

    • traitsNext

      protected double[] traitsNext
      The array for temporarily storing traits during updates.

    • tmpGroup

      protected double[] tmpGroup
      Temporary storage for traits of individuals in group interactions.

    • smallTrait

      protected double[] smallTrait
      Temporary storage for traits of individuals in small sub-group interactions.

    • myTrait

      protected double[] myTrait
      Temporary storage for the traits of the focal individual.

    • oldTrait

      protected double[] oldTrait
      Temporary storage for the traits of the focal individual before the update. Used for adjusting scores.

    • oldScores

      protected double[] oldScores
      Temporary storage for the scores of each participant prior to group interactions.

    • meantrait

      private double[] meantrait
      The array for calculating and storing the mean traits and their standard deviation. Must be of length > 2 * nTraits.

    • init

      protected IBSC.Init init
      Type of initial configuration.
      See Also:

  • Constructor Details

    • IBSMCPopulation

      public IBSMCPopulation(EvoLudo engine, Continuous module)
      Creates a population of individuals with multiple continuous traits for IBS simulations.
      Parameters:
      engine - the pacemaker for running the model
      module - the module that defines the game

  • Method Details

    • setOpponentPop

      public void setOpponentPop(IBSPopulation opponent)
      Description copied from class: IBSPopulation
      Set the interaction partner/opponent of this population.
      Overrides:
      setOpponentPop in class IBSPopulation
      Parameters:
      opponent - the interaction partner/opponent

    • checkConvergence

      public boolean checkConvergence()
      Description copied from class: IBSPopulation
      Check if population has converged. By default true if population is monomorphic and no (zero) mutations. However, different implementations may have different criteria for convergence.

      Note: This tends to be less restrictive than reaching an absorbing state. Typically convergence is used as a criterion to abort simulations.

      Specified by:
      checkConvergence in class IBSPopulation
      Returns:
      true if converged.

    • getTraitMin

      public double[] getTraitMin()
      Get the minima for all traits.
      Returns:
      the array with the trait minima

    • getTraitMax

      public double[] getTraitMax()
      Get the maxima for all traits.
      Returns:
      the array with the trait maxima

    • updateFromModelAt

      public void updateFromModelAt(int index, int modelPlayer)
      Description copied from class: IBSPopulation
      Update individual with index me and adopt the trait of individual with index you.

      Note: method must be subclassed to deal with different data types of traits but should also include a call to super.

      Overrides:
      updateFromModelAt in class IBSPopulation
      Parameters:
      index - the index of the focal individual
      modelPlayer - the index of the model individual to adopt trait from
      See Also:

    • haveSameTrait

      public boolean haveSameTrait(int a, int b)
      Description copied from class: IBSPopulation
      Check if individuals with index a and index b have the same traits.
      Specified by:
      haveSameTrait in class IBSPopulation
      Parameters:
      a - the index of first individual
      b - the index of second individual
      Returns:
      true if the two individuals have the same traits

    • isSameTrait

      public boolean isSameTrait(int a)
      Description copied from class: IBSPopulation
      Check if individual with index a has switched traits.

      Note: this test is only meaningful before trait are committed.

      Specified by:
      isSameTrait in class IBSPopulation
      Parameters:
      a - index of individual
      Returns:
      true if trait remained unchanged
      See Also:

    • swapTraits

      public void swapTraits(int a, int b)
      Description copied from class: IBSPopulation
      Swap traits of individuals with index a and index b.

      Note: the traits still need to be committed.

      Specified by:
      swapTraits in class IBSPopulation
      Parameters:
      a - the index of first individual
      b - the index of second individual
      See Also:

    • mutateAt

      public int mutateAt(int focal)
      Description copied from class: IBSPopulation
      Mutate the trait of the focal individual with index focal. The mutated trait is committed and the scores updated.
      Specified by:
      mutateAt in class IBSPopulation
      Parameters:
      focal - the index of the focal individual
      Returns:
      the number of elapsed realtime units

    • maybeMutateAt

      protected boolean maybeMutateAt(int focal, boolean switched)
      Description copied from class: IBSPopulation
      Consider mutating the trait of the focal individual with index focal. The trait of the focal individual is stored in the array traits unless the focal individual switched trait. In that case the current trait is stored in the array traitsNext.

      Important: The trait is not committed regardless of whether a mutation occurred.

      Specified by:
      maybeMutateAt in class IBSPopulation
      Parameters:
      focal - the index of the focal individual
      switched - true if the focal individual switched trait
      Returns:
      true if the trait of the focal individual changed

    • maybeMutateMoran

      protected void maybeMutateMoran(int source, int dest)
      Description copied from class: IBSPopulation
      Consider mutating the trait of the parent individual with index source. The mutated trait is committed and the scores updated.
      Specified by:
      maybeMutateMoran in class IBSPopulation
      Parameters:
      source - the index of the parent individual
      dest - the index of the location for the offspring placement

    • mutateAt

      private boolean mutateAt(int focal, boolean switched)
      Mutate all traits of the focal individual with index focal if mutate == true. In all cases commit traits and update scores.
      Parameters:
      focal - the index of the focal individual that gets updated
      switched - true if focal already switched trait
      Returns:
      true if the trait has changed

    • preferredPlayerBest

      public boolean preferredPlayerBest(int me, int best, int sample)
      For deterministic updating with multiple traits (more than two), it must be specified which trait is the preferred one.

      Summary: does 'me' prefer 'sample' over 'best'?

      Here we introduce the convention the trait closer to me is preferred.

      Specified by:
      preferredPlayerBest in class IBSPopulation
      Parameters:
      me - the index of the focal individual
      best - the index of the best performing individual
      sample - the index of the sample type
      Returns:
      true if sample is preferred over best

    • deltaTraits

      private double deltaTraits(int a, int b)
      Measure the (Cartesian) distance between traits at a and b
      Parameters:
      a - the index where the traits of the first individual start
      b - the index where the traits of the second individual start
      Returns:
      the distance between a and b

    • gatherPlayers

      private void gatherPlayers(IBSGroup group)
      Gather the traits of all individuals in the interaction group group.
      Parameters:
      group - the interaction group

    • doAdjustScores

      protected boolean doAdjustScores()
      Description copied from class: IBSPopulation
      Check if scores can be adjusted rather than recalculated after an individual changed its trait. This requires that individuals interact with all their neighbours and that the structure of the population is not well-mixed. Some implementations may be able to extend adjustments to other structures. For example, adjusting scores is feasible in well-mixed populations for discrete traits.

      Requirements:

      Group.SAMPLING_ALL
      individuals need to be interacting with all their neighbours (not just a randomly selected subset).
      Geometry.MEANFIELD
      interactions with everyone are not feasible (impossible to model efficiently), in general, for unstructured populations (subclasses can do better, e.g. for discrete trait it is possible, see IBSDPopulation.doAdjustScores()).
      playerScoreReset
      if scores are reset whenever an individual adopts the trait of another (regardless of whether an actual trait change occurred) then the expected number of interactions of each individual remains constant over time (even though the interaction count may differ for individuals on heterogeneous structures).
      Specified by:
      doAdjustScores in class IBSPopulation
      Returns:
      true if adjusting scores is feasible
      See Also:

    • adjustScoreAt

      public void adjustScoreAt(int index, double before, double after)
      Description copied from class: IBSPopulation
      Adjust score of individual with index index from before to after and update all applicable helper variables, e.g. sumFitness.

      Important: Use only to adjust scores of individuals that did not change trait.

      Specified by:
      adjustScoreAt in class IBSPopulation
      Parameters:
      index - the index of the individual
      before - the score before adjustments
      after - the score after adjustments

    • adjustScoreAt

      public void adjustScoreAt(int index, double adjust)
      Description copied from class: IBSPopulation
      Adjust score of individual with index index by adjust and update all applicable helper variables, e.g. sumFitness.
      Specified by:
      adjustScoreAt in class IBSPopulation
      Parameters:
      index - the index of the individual
      adjust - the score adjustment

    • playPairGameAt

      public void playPairGameAt(IBSGroup group)
      Description copied from class: IBSPopulation
      Play a pairwise interaction with the individuals in group.
      Specified by:
      playPairGameAt in class IBSPopulation
      Parameters:
      group - the group of individuals interacting in pairs

    • adjustPairGameScoresAt

      public void adjustPairGameScoresAt(int me)
      Description copied from class: IBSPopulation
      Adjusts scores of focal individual with index me and its neighbors after me changed trait. Only works if adjustScores==true.

      Important: new trait must not yet have been committed.

      Specified by:
      adjustPairGameScoresAt in class IBSPopulation
      Parameters:
      me - the index of the focal individual

    • playGroupGameAt

      public void playGroupGameAt(IBSGroup group)
      Description copied from class: IBSPopulation
      Play a group interaction with the individuals in group.
      Specified by:
      playGroupGameAt in class IBSPopulation
      Parameters:
      group - the group of interacting individuals

    • yalpGroupGameAt

      public void yalpGroupGameAt(IBSGroup group)
      Description copied from class: IBSPopulation
      Counterpart of IBSPopulation.playGroupGameAt(IBSGroup), IBSPopulation.playGameAt(int) and/or IBSPopulation.playGameSyncAt(int). Removes the payoffs of group interactions.
      Specified by:
      yalpGroupGameAt in class IBSPopulation
      Parameters:
      group - the interaction group

    • prepareTraits

      public void prepareTraits()
      Description copied from class: IBSPopulation
      Prior to a synchronous update step the current state must be duplicated in preparation for processing the next step.
      Specified by:
      prepareTraits in class IBSPopulation
      See Also:

    • commitTraits

      public void commitTraits()
      Description copied from class: IBSPopulation
      After a synchronous update step the new state must be copied back to become the current state.
      Specified by:
      commitTraits in class IBSPopulation
      See Also:

    • commitTraitAt

      public void commitTraitAt(int me)
      Description copied from class: IBSPopulation
      The change of a trait of the player at index is stored in a temporary variable and must be committed before proceeding.
      Specified by:
      commitTraitAt in class IBSPopulation
      Parameters:
      me - the index of the player that needs to have its new trait committed

    • getTraitData

      public <T> void getTraitData(T[] colors, ColorMap<T> colorMap)
      Description copied from class: IBSPopulation
      Returns the traits of all individuals in this population coded as colors in the array colors using the map colorMap. Used by GUI to visualize the current state of this IBS model. Colors are coded in different data types <T> depending on the runtime environment (GWT or JRE) as well as the graph (e.g. PopGraph2D or PopGraph3D).
      Specified by:
      getTraitData in class IBSPopulation
      Type Parameters:
      T - the type of color data (String or MeshLambertMaterial for GWT and Color for JRE).
      Parameters:
      colors - the array where the colors of all nodes are stored
      colorMap - the map that converts traits into colors

    • getTraitHistogramData

      public void getTraitHistogramData(double[][] bins)
      Creates a histogram for each trait separately (if there are multiple) and returns the result in the array bins where the first index denotes the trait and the second refers to the bin.
      Parameters:
      bins - the array to store the histogram(s)

    • getTraitHistogramData

      public void getTraitHistogramData(double[] bins, int trait)
      Creates a histogram for the trait with index trait and returns the result in the array bins.
      Parameters:
      bins - the array to store the histogram(s)
      trait - the index of the trait

    • get2DTraitHistogramData

      public void get2DTraitHistogramData(double[] bins, int trait1, int trait2)
      Creates 2D histogram for traits trait1 and trait2. The result is returned in the linear array bins and arranged in a way that is compatible with square lattice geometries for visualization by Distribution and PopGraph2D (GWT only).
      Parameters:
      bins - the linear array to store the 2D histogram
      trait1 - the index of the first trait
      trait2 - the index of the second trait
      See Also:

    • getTraits

      public String getTraits(int digits)
      Gets all traits of all individuals. The traits are returned as a formatted string with an accuracy of digits decimals. With multiple traits they are listed sequentially for each individual.
      Parameters:
      digits - the number of decimals of the formatted string
      Returns:
      the formatted traits

    • getTraitNameAt

      public String getTraitNameAt(int index)
      Description copied from class: IBSPopulation
      Gets the formatted name of the trait of the individual at site index.
      Specified by:
      getTraitNameAt in class IBSPopulation
      Parameters:
      index - the index of the
      Returns:
      the string describing the trait

    • getMeanTraits

      public void getMeanTraits(double[] mean)
      Returns the mean trait(s) of this population in the array mean. Used by GUI to visualize the current state of this IBS model.

      For continuous traits the first nTraits entries represent the mean of each trait and the second nTraits entries denote the standard deviation.

      Specified by:
      getMeanTraits in class IBSPopulation
      Parameters:
      mean - the array for returning the trait values
      See Also:

    • getMeanFitness

      public void getMeanFitness(double[] mean)
      Returns the mean fitness of this population in the array mean. Used by GUI to visualize the current state of this IBS model. Returns true if data point belongs to the same time series and false if a new series was started through IBSPopulation.init() or IBSPopulation.reset().

      For continuous traits the first nTraits entries represent the mean fitness of each trait and the second nTraits entries denote their standard deviation.

      Specified by:
      getMeanFitness in class IBSPopulation
      Parameters:
      mean - the array for storing the mean fitness values
      See Also:

    • getStatus

      public String getStatus()
      Description copied from class: IBSPopulation
      Gets the status of the as a formatted string. This is typically used in the GUI to summarize the progress of the model.
      Specified by:
      getStatus in class IBSPopulation
      Returns:
      the status of the population

    • check

      public boolean check()
      Description copied from class: IBSPopulation
      Check all model parameters for consistency and adjust if necessary (and feasible). Returns true if adjustments require a reset. Free memory if possible and request a reset if new memory needs to be allocated.
      Overrides:
      check in class IBSPopulation
      Returns:
      true if reset is required
      See Also:

    • setInit

      public void setInit(IBSC.Init init)
      Sets the type of the initial configuration and any accompanying arguments. If either type or args are null the respective current setting is preserved.
      Parameters:
      init - the type and arguments of the initial configuration

    • getInit

      public IBSC.Init getInit()
      Gets the type of the initial configuration and its arguments.
      Returns:
      the type and arguments of the initial configuration

    • init

      public void init()
      Description copied from class: IBSPopulation
      Initialize the model. All parameters must be consistent. Subclasses must override this method to generate the initial trait configuration and call super.

      Note: Initialization leaves the interaction and competition structures untouched

      Overrides:
      init in class IBSPopulation
      See Also:

    • reset

      public void reset()
      Description copied from class: IBSPopulation
      Reset the model. All parameters must be consistent at this point. Allocate memory and initialize the interaction and competition structures. If structures include random elements, e.g. random regular graphs, a new structure is generated. Generate initial configuration. Subclasses must override this method to allocate memory for the trait and call super.
      Overrides:
      reset in class IBSPopulation
      See Also:

    • mouseHitNode

      public boolean mouseHitNode(int hit, boolean alt)
      Description copied from class: IBSPopulation
      Called from GUI if node/individual with index idx received a mouse click or tap and indicates whether the alt-key had been pressed.
      Overrides:
      mouseHitNode in class IBSPopulation
      Parameters:
      hit - the index of the node
      alt - true if the alt-key was pressed
      Returns:
      false if no actions taken

    • encodeTraits

      public void encodeTraits(StringBuilder plist)
      Description copied from class: IBSPopulation
      Encode the traits of all individuals in the IBS model in a plist inspired XML string.
      Specified by:
      encodeTraits in class IBSPopulation
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreTraits

      public boolean restoreTraits(Plist plist)
      Description copied from class: IBSPopulation
      Restore the traits of all individuals encoded in the plist inspired map of key, value-pairs.
      Specified by:
      restoreTraits in class IBSPopulation
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also: