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/strategies. Manages the strategies 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/strategy, 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/strategy. Convenience variable.

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

      See Also:

    • traitMax

      protected double[] traitMax
      The array with the maximal values for each trait/strategy. Convenience variable.

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

      See Also:

    • strategies

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

    • strategiesScratch

      protected double[] strategiesScratch
      The array for temporarily storing strategies during updates.

    • groupStrat

      protected double[] groupStrat
      Temporary storage for strategies/traits of individuals in group interactions.

    • smallStrat

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

    • myTrait

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

    • oldTrait

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

    • oldScores

      protected double[] oldScores
      Temporary storage for the scores of each strategy/type prior to the 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.

    • inittrait

      private double[] inittrait
      The array for storing the mean and standard deviation of the initial state. 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 strategy of individual with index you.

      Note: method must be subclassed to deal with different data types of strategies 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 strategy from
      See Also:

    • haveSameStrategy

      public boolean haveSameStrategy(int a, int b)
      Description copied from class: IBSPopulation
      Check if individuals with index a and index b have the same strategies.
      Specified by:
      haveSameStrategy 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 strategies

    • isSameStrategy

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

      Note: this test is only meaningful before strategy gets committed.

      Specified by:
      isSameStrategy in class IBSPopulation
      Parameters:
      a - index of individual
      Returns:
      true if strategy remained the same
      See Also:

    • swapStrategies

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

      Note: the strategies still need to be committed.

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

    • mutateAt

      public double mutateAt(int focal)
      Description copied from class: IBSPopulation
      Mutate the strategy of the focal individual with index focal. The mutated strategy is committed and the scores updated.
      Specified by:
      mutateAt in class IBSPopulation
      Parameters:
      focal - the index of the focal individual
      Returns:
      the elapsed time in 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 strategy of the focal individual is stored in the array strategies unless the focal individual switched strategy. In that case the current strategy is stored in the array strategyScratch.

      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 strategy
      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 strategy 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/strategies of the focal individual with index focal if mutate == true. In all cases commit strategies 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 strategy has changed

    • preferredPlayerBest

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

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

      Here we introduce the convention the trait/strategy 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

    • deltaStrategies

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

    • gatherPlayers

      private void gatherPlayers(IBSGroup group)
      Gather the traits/strategies 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 strategy. 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/strategies.

      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 strategies it is possible, see IBSDPopulation.doAdjustScores()).
      playerScoreReset
      if scores are reset whenever an individual adopts the strategy of another (regardless of whether an actual strategy 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 strategy.

      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 strategy. Only works if adjustScores==true.

      Important: new strategy 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

    • prepareStrategies

      public void prepareStrategies()
      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:
      prepareStrategies in class IBSPopulation
      See Also:

    • commitStrategies

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

    • commitStrategyAt

      public void commitStrategyAt(int me)
      Description copied from class: IBSPopulation
      The change of a strategy of the player at index is stored in a temporary variable and must be committed before proceeding.
      Specified by:
      commitStrategyAt in class IBSPopulation
      Parameters:
      me - the index of the player that needs to have its new strategy 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

    • getInitialTraits

      public void getInitialTraits(double[] traits)
      Returns the initial trait(s) of this population in the array init. Used by GUI to visualize the initial state of this IBS model.

      Note: For continuous modules the IBS model returns the concatenated mean and stdev of each trait in traits.

      Specified by:
      getInitialTraits in class IBSPopulation
      Parameters:
      traits - the array for returning the initial trait values
      See Also:

    • 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/strategies 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/strategies 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 strategy 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 strategies 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

    • encodeStrategies

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

    • restoreStrategies

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