Class IBSPopulation<M extends Module<?>, P extends IBSPopulation<?,?>>

Object
IBSPopulation<M,P>
Type Parameters:
M - the module type controlling the population dynamics
P - the concrete population type used as opponent reference
Direct Known Subclasses:
IBSDPopulation, IBSMCPopulation
public abstract class IBSPopulation<M extends Module<?>, P extends IBSPopulation<?,?>> extends Object
The core class for individual based simulations. Manages the population, including keeping track of the payoffs and fitness of individuals.

Note: traits cannot be handled here because they are represented by ints in discrete models but doubles in continuous models.

Author:
Christoph Hauert
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    adjustScores
    Optimization: Flag to indicate whether adjusting instead of recalculating scores is possible.
    protected AbstractGeometry
    competition
    The geometry of the competition graph.
    protected IBSGroup
    compGroup
    Reference to the competition/reference/model group.
    (package private) boolean
    consistencyCheckRequested
    The flag to indicate whether consistency checks on the state of the IBS model are requested.
    private double[]
    cProbs
    Conveninece variable to store cumulative probability distributions for replicator updating.
    protected int
    debugFocal
    Helper variable to store index of focal individual (birth) that got updated during debug step.
    protected int
    debugModel
    Helper variable to store index of target individual (death) that got updated during debug step.
    protected int[]
    debugModels
    Helper variable to store array of indices of individual that served as models during debug step.
    protected int
    debugNModels
    Helper variable to number of individual that served as models during debug step.
    protected boolean
    debugSame
    Helper flag to indicate an actual trait change during debug step.
    protected RNGDistribution.Geometric
    distrMigrants
    The distribution to determine the number of migrants.
    protected EvoLudo
    engine
    The pacemaker of all models.
    protected double[]
    fitness
    The array of individual fitness values.
    private static final int
    GILLESPIE_OPTIMIZATION_THRESHOLD
    Threshold population size for using the Gillespie optimization for picking individuals proportional to fitness.
    protected double[]
    groupScores
    Array to hold scores of individuals during payoff calculations.
    protected boolean
    hasLookupTable
    Optimization: Flag to indicate whether lookup tables can be used.
    private static final String
    INSTEAD_OF
    String for formatting log messages
    protected AbstractGeometry
    interaction
    The geometry of the interaction graph.
    protected int[]
    interactions
    The array of individual interaction counts.
    protected IBSGroup
    interGroup
    Reference to the interaction group.
    protected boolean
    isMultispecies
    Flag to indicate whether the model entertains multiple species, i.e.
    protected boolean
    isNeutral
    Flag to indicate whether dynamic is neutral, i.e.
    protected Logger
    logger
    Logger for keeping track of and reporting events and issues.
    protected Map2Fitness
    map2fit
    The map converting scores to fitness and vice versa.
    protected int
    maxEffScoreIdx
    Optimization: The index of the individual that currently holds the maximum score.
    protected double
    maxFitness
    The absolute maximum fitness in the population.
    protected double
    maxScore
    The absolute maximum score in the population.
    protected IBS.MigrationType
    migrationType
    The type of migration.
    protected double
    minFitness
    The absolute minimum fitness in the population.
    protected double
    minScore
    The absolute minimum score in the population.
    protected M
    module
    The module associated with this population.
    protected Mutation
    mutation
    The mutation parameters.
    (package private) int
    nIssues
    The number of concistency issues encountered in the state of the IBS model.
    protected int
    nMixedInter
    Optimization: Number of interactions in well-mixed populations for update rules that take advantage of IBSDPopulation.updateMixedScores().
    protected int
    nPopulation
    The size of the population.
    protected int
    nTraits
    The number of traits in module.
    protected P
    opponent
    The interaction partner/opponent of this population opponent.getModule()==getModule().getOpponent().
    protected boolean
    optimizeHomo
    true if optimizations for homogeneous populations requested.
    protected double[]
    pAddwire
    The array containing the probabilities for adding links to the interaction and competition graphs.
    protected boolean
    playerScoreAveraged
    Flag to indicate whether player scores are averaged (default) or accumulated.
    protected IBS.ScoringType
    playerScoring
    Flag to indicate whether scores are reset whenever a player adopts the trait of another (default) or only if an actual change of trait occurred.
    (package private) PlayerUpdate
    playerUpdate
    The update type of players.
    protected double
    pMigration
    The probability of migration.
    (package private) PopulationUpdate
    populationUpdate
    The population update.
    protected double[]
    pRewire
    The array containing the probabilities for rewiring links of the interaction and competition graphs.
    protected RNGDistribution
    rng
    The shared random number generator to ensure reproducibility of results.
    protected double[]
    scores
    The array of individual scores.
    protected double[]
    smallScores
    Array to hold scores of individuals during payoff calculations for small groups (not all neighbours).
    protected Features.Static
    staticmodule
    Convenience field for static modules to avoid casts.
    protected double
    sumFitness
    The total fitness of the population.
    (package private) double
    syncFraction
    The fraction of the population that gets updated in synchronous updates.
    protected double[]
    tags
    The array of individual tags counts.
    protected double[]
    typeFitness
    Optimization: the lookup table for fitness in well-mixed populations.
    protected double[]
    typeScores
    Optimization: the lookup table for scores in well-mixed populations.
    protected int
    vacantIdx
    The index of vacant sites or -1 if module does not support vacancies.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    IBSPopulation(EvoLudo engine, M module)
    Creates a population of individuals for IBS simulations.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    adjustGameScoresAt(int me)
    Adjust scores of focal player me and its neighbours (interaction partners).
    abstract void
    adjustPairGameScoresAt(int me)
    Adjusts scores of focal individual with index me and its neighbors after me changed trait.
    abstract void
    adjustScoreAt(int index, double adjust)
    Adjust score of individual with index index by adjust and update all applicable helper variables, e.g.
    abstract void
    adjustScoreAt(int index, double before, double after)
    Adjust score of individual with index index from before to after and update all applicable helper variables, e.g.
    boolean
    becomesVacantAt(int index)
    Check if site with index index will become vacant in this time step.
    boolean
    check()
    Check all model parameters for consistency and adjust if necessary (and feasible).
    private void
    checkAdjustScoresConsistency()
    Check consistency when not using lookup tables.
    (package private) void
    checkCompSampling()
    Validate competition sampling rules for well-mixed populations and adjust if required.
    (package private) void
    checkConsistentFitness()
    Check consistency of scores and fitness values for modules that implement Payoffs.
    boolean
    checkConvergence()
    Check if population has converged.
    private void
    checkFitnessSum(double sumFitnessStore)
    Check consistency of total fitness.
    (package private) boolean
    checkGeometry()
    Check the interaction and competition geometries for consistency and adjust if necessary (and feasible).
    (package private) boolean
    checkGeometryRewire()
    Rewire the interaction and competition geometries if requested.
    private void
    checkIndividualConsistency(int n)
    Check consistency of scores for a single individual.
    (package private) boolean
    checkInteractions(int nGroup)
    Validate interaction structures and adjust incompatible settings.
    (package private) boolean
    checkLookupTable(int nGroup, boolean ephemeralScores)
    Check whether lookup tables for scores and fitness can be used.
    private void
    checkLookupTableConsistency()
    Check consistency of scores when using lookup tables.
    (package private) void
    checkMigration()
    Check consistency of migration settings and adjust if necessary (and feasible).
    private void
    checkNoAdjustScoresConsistency()
    Check consistency when scores are not adjusted.
    (package private) boolean
    checkNoLookupTable(boolean ephemeralScores)
    Free memory used for lookup tables and allocate arrays for scores, fitness and interactions.
    (package private) boolean
    checkOptimizations()
    Check whether optimizations for homogeneous states can be used.
    (package private) boolean
    checkPayoffs(int nGroup)
    Check settings for modules implementing Payoffs.
    private void
    checkTraitScores(double[] typeScoresStore, double[] typeFitnessStore)
    Check consistency of scores for all traits.
    abstract void
    commitTraitAt(int index)
    The change of a trait of the player at index is stored in a temporary variable and must be committed before proceeding.
    abstract void
    commitTraits()
    After a synchronous update step the new state must be copied back to become the current state.
    protected void
    debugMarkChange()
    Override in subclass for example to mark those individuals in the GUI that were involved in the debug step.
    protected void
    debugScores(double hit)
    Log report if picking failed to shed better light on what might be the root cause for the failure.
    protected void
    debugUpdate(int me, int rGroupSize, double nProb, double norm, double choice)
    Log report if updating failed to shed better light on what might be the root cause for the failure.
    void
    debugUpdatePopulationAt(int focal)
    Update focal individual with index focal for debugging.
    protected abstract boolean
    doAdjustScores()
    Check if scores can be adjusted rather than recalculated after an individual changed its trait.
    void
    doBirthDeathMigration()
    Perform a birth-death migration, where a focal individual (selected proportional to fitness) produces a migrant offspring, which replaces another member of the population uniformly at random.
    void
    doDeathBirthMigration()
    Perform a death-birth migration, where a member of the population (selected uniformly at random) dies and the remaining individuals compete to repopulate the vacant site.
    void
    doDiffusionMigration()
    Perform diffusion migration, which is implemented as two players swap their locations while leaving their respective neighbourhood structure untouched.
    void
    doMigration()
    Perform asynchronous migration.
    int
    doSyncMigration()
    Perform synchronous migration.
    void
    encodeFitness(StringBuilder plist)
    Encode the fitness of all individuals in the IBS model in a plist inspired XML string.
    void
    encodeGeometry(StringBuilder plist)
    Encode the interaction and competition structures of the IBS model in a plist inspired XML string.
    void
    encodeInteractions(StringBuilder plist)
    Encode the interactions of all individuals in the IBS model in a plist inspired XML string.
    abstract void
    encodeTraits(StringBuilder plist)
    Encode the traits of all individuals in the IBS model in a plist inspired XML string.
    private String
    formatInfoAt(int focal, int model)
    Helper method to format information about updating the focal individual at index focal using the model individual with index model.
    AbstractGeometry
    getCompetitionGeometry()
    Gets the competition geometry.
    IBSGroup
    getCompGroup()
    Gets the competition/reference/model group.
    String
    getFitness(int digits)
    Gets the fitness of all individuals with precision digits.
    double
    getFitnessAt(int idx)
    Gets the fitness of the individual with index idx.
    <T> void
    getFitnessData(T[] colors, ColorMap.Gradient1D<T> colorMap)
    Returns the fitness of all individuals in this population coded as colors in the array colors using the map colorMap.
    void
    getFitnessHistogramData(double[][] bins)
    Generates a histogram of the fitness distribution in this population.
    String
    getFitnessNameAt(int idx)
    Gets the formatted and prettyfied fitness of the individual with index idx as a string.
    String
    getFitnessNameAt(int idx, boolean pretty)
    Gets the formatted fitness of the individual with index idx as a string.
    AbstractGeometry
    getInteractionGeometry()
    Gets the interaction geometry.
    int
    getInteractionsAt(int idx)
    Gets the number of interactions of the individual with index idx.
    IBSGroup
    getInterGroup()
    Gets the interaction group.
    double
    getMaxScore()
    Returns the maximum score min in this population, taking the population structure and payoff accounting into account.
    abstract double[]
    getMeanFitness(double[] mean)
    Returns the mean fitness of this population in the array mean.
    abstract double[]
    getMeanTraits(double[] mean)
    Returns the mean trait(s) of this population in the array mean.
    double
    getMigrationProb()
    Gets the migration probability.
    IBS.MigrationType
    getMigrationType()
    Gets the type of migrations.
    double
    getMinScore()
    Returns the minimum score min in this population, taking the population structure and payoff accounting into account.
    M
    getModule()
    Gets the module associated with this population.
    int
    getNMean()
    Return the number of mean values for this population (for traits or fitness).
    (package private) int
    getNMixedInteractions(int nGroup)
    Determine the number of interactions in well-mixed populations with lookup tables.
    boolean
    getPlayerScoreAveraged()
    Gets whether player scores are averaged (as opposed to accumulated).
    IBS.ScoringType
    getPlayerScoring()
    Gets the type for managing scores of individuals.
    int
    getPopulationSize()
    Gets current population size.
    PopulationUpdate
    getPopulationUpdate()
    Gets the population update.
    double
    getScoreAt(int idx)
    Gets the score of the individual with index idx.
    String
    getScoreNameAt(int idx)
    Gets the formatted score of the individual with index idx.
    String
    getScores(int digits)
    Gets the scores of all individuals with precision digits.
    double
    getSpeciesUpdateRate()
    Gets the update rate of this species.
    abstract String
    getStatus()
    Gets the status of the as a formatted string.
    double
    getSyncFraction()
    Get the fraction of the population that gets updated in synchronous updates.
    double
    getTagAt(int idx)
    Gets the tag of the individual with index idx.
    <T> void
    getTagData(T[] colors, ColorMap<T> colorMap)
    Returns the tags of all individuals in this population coded as colors in the array colors using the map colorMap.
    String
    getTagNameAt(int idx)
    Gets the formatted tag of the individual with index idx as string.
    double[]
    getTags(double[] mem)
    Copies the tags of all individuals in the population and returns them in the array mem.
    double
    getTotalFitness()
    Gets the total fitness of the population.
    abstract <T> void
    getTraitData(T[] colors, ColorMap<T> colorMap)
    Returns the traits of all individuals in this population coded as colors in the array colors using the map colorMap.
    abstract String
    getTraitNameAt(int index)
    Gets the formatted name of the trait of the individual at site index.
    abstract boolean
    haveSameTrait(int a, int b)
    Check if individuals with index a and index b have the same traits.
    void
    init()
    Initialize the model.
    void
    isConsistent()
    Convenience method during development to perform a number of consistency checks of the current state.
    boolean
    isMonomorphic()
    Check if population is monomorphic.
    abstract boolean
    isSameTrait(int a)
    Check if individual with index a has switched traits.
    boolean
    isVacantAt(int index)
    Check if site with index index is occupied by an individual or vacant.
    (package private) void
    logAccountingIssue(double actual, double expected)
    Log an accounting issue.
    (package private) void
    logAccountingIssue(String descr, double actual, double expected, String issue)
    Log an accounting issue.
    (package private) void
    logFitnessIssue(int idx, double actual, double expected)
    Log a fitness issue.
    (package private) void
    logMapIssue(int idx, double actual, double expected)
    Log a mapping issue.
    (package private) void
    logScoringIssue(int idx, double actual, double expected)
    Log a scoring issue.
    (package private) void
    logScoringIssue(int idx, double actual, String issue)
    Log a scoring issue.
    protected abstract boolean
    maybeMutateAt(int focal, boolean switched)
    Consider mutating the trait of the focal individual with index focal.
    protected abstract void
    maybeMutateMoran(int source, int dest)
    Consider mutating the trait of the parent individual with index source.
    protected void
    migrateMoran(int source, int dest)
    Perform a single Moran update for the reproducing node with index source and the node that gets replaced with index dest.
    boolean
    mouseHitNode(int hit)
    Called from GUI if node/individual with index idx received a mouse click or tap.
    boolean
    mouseHitNode(int hit, boolean alt)
    Called from GUI if node/individual with index idx received a mouse click or tap and indicates whether the alt-key had been pressed.
    int
    mutate()
    Perform a mutation event.
    abstract int
    mutateAt(int focal)
    Mutate the trait of the focal individual with index focal.
    int
    nextBinomial(double p, int n)
    Draw a binomially distributed random integer.
    private int
    optimizeHomo()
    Optimize homogeneous population states by skipping to the next mutation event.
    private int
    pickFailed()
    Handle failed pick.
    private int
    pickFailed(double remainder)
    Handle failed pick and report details about failure.
    int
    pickFitFocalIndividual()
    Draws the index of a member of the population with a probability proportional to fitness.
    int
    pickFitFocalIndividual(int excl)
    Draws the index of a member of the population with a probability proportional to fitness but excluding the individual with the index excl.
    private int
    pickFitFocalNoVacant()
    Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.
    private int
    pickFitFocalNoVacant(int excl)
    Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.
    private int
    pickFitFocalNoVacantGillespieOptimized(int excl)
    Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.
    private int
    pickFitFocalSkipVacant()
    Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.
    private int
    pickFitFocalSkipVacant(int excl)
    Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.
    private int
    pickFitFocalSkipVacantGillespieOptimized(int excl)
    Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.
    protected int
    pickFitNeighborAt(int me)
    Pick a neighbour of the focal individual me with probability proportional to their fitness.
    protected int
    pickFitNeighborAt(int me, boolean withSelf)
    Pick a neighbour of the focal individual me with probability proportional to their fitness.
    private int
    pickFitNeighborNoVacantAt(int me, boolean withSelf)
    Pick a neighbour of the focal individual me with probability proportional to their fitness assuming no vacant sites.
    private int
    pickFitNeighborSkipVacantAt(int me, boolean withSelf)
    Pick a neighbour of the focal individual me with probability proportional to their fitness assuming vacant sites.
    private int
    pickFocalHead(int pick)
    Pick a focal individual uniformly at random starting from head.
    private int
    pickFocalHead(int pick, int excl)
    Pick a focal individual uniformly at random starting from head, excluding individual excl.
    int
    pickFocalIndividual()
    Draws the index of a individual of the population uniformly at random.
    int
    pickFocalIndividual(int excl)
    Draws the index of a individual of the population uniformly at random but excluding the individual with index excl.
    int
    pickFocalSite()
    Draws the index of a site in the population uniformly at random, irrespective of whether it is occupied or not.
    int
    pickFocalSite(int excl)
    Draws the index of a site in the population uniformly at random, irrespective of whether it is occupied or not.
    private int
    pickFocalSkipVacant()
    Pick a focal individual uniformly at random but skipping vacant sites.
    private int
    pickFocalSkipVacant(int excl)
    Pick a focal individual uniformly at random but excluding the individual with index excl.
    private int
    pickFocalTail(int pick)
    Pick a focal individual uniformly at random starting from tail.
    private int
    pickFocalTail(int pick, int excl)
    Pick a focal individual uniformly at random starting from tail, excluding individual excl.
    int
    pickNeighborSiteAt(int me)
    Picks a neighbouring site of the focal individual me uniformly at random.
    private int
    pickNeutralNeighbourAt(int me, boolean withSelf)
    Helper method to do picking under neutral conditions (no or negligible fitness differences).
    void
    playGameAt(int me)
    Update the score of individual me.
    void
    playGameSyncAt(int me)
    Update the score of individual me.
    abstract void
    playGroupGameAt(IBSGroup group)
    Play a group interaction with the individuals in group.
    abstract void
    playPairGameAt(IBSGroup group)
    Play a pairwise interaction with the individuals in group.
    abstract 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.
    abstract void
    prepareTraits()
    Prior to a synchronous update step the current state must be duplicated in preparation for processing the next step.
    protected double
    processScore(double score, int count)
    Process the accumulated score in this population, taking the updating into account.
    double
    random01()
    Draw a uniformly distributed random double from the semi-closed interval [0, 1) with 32bit resolution.
    int
    random0n(int n)
    Draw a uniformly distributed random integer number from the semi-closed interval [0, n).
    double
    randomGaussian(double mean, double sdev)
    Draw a Gaussian (normal) distributed random double.
    void
    removeScoreAt(int index, double nilscore)
    Removes the score nilscore based on a single interaction from the individual with index index.
    void
    removeScoreAt(int index, double nilscore, int incr)
    Removes the score nilscore based on incr interactions from the individual with index index.
    void
    reset()
    Reset the model.
    (package private) void
    resetEphemeral(int nGroup)
    Precalculate the number of interactions for ephemeral payoffs and store in the interactions array.
    (package private) void
    resetMoran()
    Ensure that Moran type population updates have non-negative fitness values.
    void
    resetScoreAt(int index)
    Reset score of individual at index index.
    void
    resetScores()
    Reset scores and fitness of all individuals to zero.
    void
    resetTraits()
    Reset all traits in preparation of the next update step.
    boolean
    restoreFitness(Plist plist)
    Restore the fitness of all individuals encoded in the plist inspired map of key, value-pairs.
    boolean
    restoreGeometry(Plist plist)
    Restore the interaction and competition structures encoded in the plist inspired map of key, value-pairs.
    boolean
    restoreInteractions(Plist plist)
    Restore the interactions of all individuals encoded in the plist inspired map of key, value-pairs.
    abstract boolean
    restoreTraits(Plist plist)
    Restore the traits of all individuals encoded in the plist inspired map of key, value-pairs.
    private double
    second(int excl)
    Find the second highest score.
    void
    setAddwire(double[] addwire)
    Set the probabilities for adding links to the interaction and competition graphs.
    void
    setConsistencyCheck(boolean check)
    Enable consistency checks of the state of the IBS model.
    (package private) void
    setGeometryNames()
    Set the names of the interaction and competition geometries based on the module name and whether the geometries are the same or different.
    protected void
    setMaxEffScoreIdx()
    Find the index of the individual with the highest score.
    void
    setMigrationProb(double aValue)
    Sets the migration probability to aValue.
    void
    setMigrationType(IBS.MigrationType type)
    Sets the type of migrations to type.
    void
    setOpponentPop(IBSPopulation<?,?> opponent)
    Set the interaction partner/opponent of this population.
    void
    setPlayerScoreAveraged(boolean aver)
    Sets whether scores of individuals are averaged over multiple interactions or accumulated.
    void
    setPlayerScoring(IBS.ScoringType type)
    Sets the type for managing scores of individuals.
    void
    setPopulationUpdate(PopulationUpdate populationUpdate)
    Sets the population update.
    void
    setRewire(double[] rewire)
    Set the probabilities for rewiring links of the interaction and competition graphs.
    void
    setScoreAt(int index, double newscore, int inter)
    Sets the score of individual with index index to newscore as the result of inter interactions.
    void
    setSyncFraction(double sync)
    Set the fraction of the population that gets updated in synchronous updates.
    boolean
    setTagAt(int idx, double tag)
    Sets the tag of the individual with index idx.
    int
    step()
    Perform a single IBS step, i.e.
    void
    swapScoresAt(int idxa, int idxb)
    Swap the scores (and fitness) of individuals with indices idxa and idxb.
    abstract void
    swapTraits(int a, int b)
    Swap traits of individuals with index a and index b.
    private double
    totFitnessNoVacant(int me)
    Compute total fitness of neighbours of individual me assuming no vacant sites.
    private double
    totFitnessSkipVacant(int me)
    Compute total fitness of neighbours of individual me assuming vacant sites.
    protected boolean
    updateEffScoreRange(int index, double before, double after)
    Keep track of highest score through a reference to the corresponding individual.
    private boolean
    updateFailed(int me, int rGroupSize, double nProb, double norm, double choice)
    Handle failed adoption decision and log diagnostic details before aborting.
    void
    updateFitnessAt(int idx)
    Update the fitness of the individual with index idx by mapping its current score.
    void
    updateFromModelAt(int me, int you)
    Update individual with index me and adopt the trait of individual with index you.
    void
    updateMinMaxScores()
    Retrieve and store extremal scores and fitnesses to reduce calls to Module.
    private int
    updateOnce()
    Update all individuals in the population once asynchronously.
    protected void
    updatePlayerAsync()
    Perform a single, asynchronous update of the trait of a randomly selected individual.
    void
    updatePlayerAsyncAt(int me)
    Update the trait of the focal individual with index me.
    boolean
    updatePlayerAt(int me)
    Perform a single update of the individual with index me.
    boolean
    updatePlayerAt(int me, int[] refGroup, int rGroupSize)
    Perform a single update of the individual with index me using the rGroupSize models in the array refGroup.
    protected boolean
    updatePlayerBest(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of the best performing reference individual among the rGroupSize models in the array refGroup.
    protected boolean
    updatePlayerBestHalf(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of the best performing reference individual among the the rGroupSize models in the array refGroup.
    boolean
    updatePlayerBestResponse(int me, int[] group, int size)
    Best-response update.
    int
    updatePlayerEcology()
    Perform a single ecological update of an individual selected uniformly at random.
    protected int
    updatePlayerEcologyAt(int index)
    Perform a single ecological update of the site with index index.
    void
    updatePlayerMoranBirthDeath()
    Perform a single, Moran (Birth-death) update for a random individual selected with a probability proportional to fitness.
    protected void
    updatePlayerMoranBirthDeathAt(int parent)
    Perform a Moran (Birth-death) update for the focal individual with index parent to produce a clonal offspring and replace one of the parent's neighbours selected uniformly at random.
    void
    updatePlayerMoranDeathBirth()
    Perform a single Moran (death-Birth) update for a site selected uniformly at random.
    protected void
    updatePlayerMoranDeathBirthAt(int vacant)
    Perform a single Moran (death-Birth) update for the focal site with index vacant.
    void
    updatePlayerMoranImitate()
    Perform a single, Moran (imitate) update for a site selected uniformly at random.
    protected void
    updatePlayerMoranImitateAt(int imitator)
    Update the focal individual with index imitator by comparing its own payoff and those of its neighbors.
    void
    updatePlayerSwap(int a, int b)
    Swap players in locations a and b.
    protected boolean
    updateProportionalAbs(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of one reference individual (including itself) among the the rGroupSize models in the array refGroup with a probability proportional to their scores.
    private boolean
    updateReplicator(int me, int[] refGroup, int rGroupSize, boolean betterOnly)
    Helper method for replicator type updates.
    protected boolean
    updateReplicatorHalf(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup.
    private boolean
    updateReplicatorNeutral(int me, int[] refGroup, int rGroupSize, boolean betterOnly)
    Replicator type update in the neutral case.
    private double
    updateReplicatorNoise(int[] refGroup, int rGroupSize, double myFitness, boolean betterOnly)
    Replicator type update with noise.
    private double
    updateReplicatorNoNoise(int[] refGroup, int rGroupSize, double myFitness, boolean betterOnly)
    Replicator type update without noise.
    protected boolean
    updateReplicatorPlus(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup.
    protected void
    updateScoreAt(int me, boolean switched)
    Update the scores of the focal individual with index me.
    void
    updateScoreAt(int index, double newscore)
    Update the score of the individual with index index by adding newscore from single interaction.
    void
    updateScoreAt(int index, double newscore, int incr)
    Update the score of the individual with index index by adding (incr &gt; 0 or removing, incr &lt; 0) newscore as the result of incr interactions.
    void
    updateScores()
    Update the scores of all individuals in the population.
    private int
    updateSyncAll()
    Update all individuals in the population synchronously.
    private int
    updateSyncFraction()
    Update a fraction of individuals in the population synchronously.
    protected boolean
    updateThermal(int me, int[] refGroup, int rGroupSize)
    Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup.
    private double
    updateThermalNoise(int me, int[] refGroup, int rGroupSize)
    Thermal update with noise.
    private double
    updateThermalNoNoise(int me, int[] refGroup, int rGroupSize)
    Thermal update without noise.
    abstract void
    yalpGroupGameAt(IBSGroup group)
    Counterpart of playGroupGameAt(IBSGroup), playGameAt(int) and/or playGameSyncAt(int).

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • engine

      protected EvoLudo engine
      The pacemaker of all models. Interface with the outside world.

    • module

      protected M extends Module<?> module
      The module associated with this population.

    • staticmodule

      protected Features.Static staticmodule
      Convenience field for static modules to avoid casts.

    • opponent

      protected P extends IBSPopulation<?,?> opponent
      The interaction partner/opponent of this population opponent.getModule()==getModule().getOpponent(). In intra-species interactions opponent==this. Convenience field.

    • logger

      protected Logger logger
      Logger for keeping track of and reporting events and issues.

    • rng

      protected RNGDistribution rng
      The shared random number generator to ensure reproducibility of results.
      See Also:

    • isMultispecies

      protected boolean isMultispecies
      Flag to indicate whether the model entertains multiple species, i.e. nSpecies&gt;1. Convenience field. Reduces calls to Module.

    • populationUpdate

      PopulationUpdate populationUpdate
      The population update.

    • playerUpdate

      PlayerUpdate playerUpdate
      The update type of players. Convenience field.
      See Also:

    • vacantIdx

      protected int vacantIdx
      The index of vacant sites or -1 if module does not support vacancies. Convenience field.
      See Also:

    • nTraits

      protected int nTraits
      The number of traits in module. Convenience field.
      See Also:

    • interaction

      protected AbstractGeometry interaction
      The geometry of the interaction graph.

    • interGroup

      protected IBSGroup interGroup
      Reference to the interaction group.

    • competition

      protected AbstractGeometry competition
      The geometry of the competition graph.

    • compGroup

      protected IBSGroup compGroup
      Reference to the competition/reference/model group.

    • playerScoreAveraged

      protected boolean playerScoreAveraged
      Flag to indicate whether player scores are averaged (default) or accumulated.
      See Also:

    • playerScoring

      protected IBS.ScoringType playerScoring
      Flag to indicate whether scores are reset whenever a player adopts the trait of another (default) or only if an actual change of trait occurred.
      See Also:

    • migrationType

      protected IBS.MigrationType migrationType
      The type of migration.

    • pMigration

      protected double pMigration
      The probability of migration.

    • distrMigrants

      protected RNGDistribution.Geometric distrMigrants
      The distribution to determine the number of migrants.

    • cProbs

      private double[] cProbs
      Conveninece variable to store cumulative probability distributions for replicator updating.
      See Also:

    • fitness

      protected double[] fitness
      The array of individual fitness values.
      See Also:

    • minFitness

      protected double minFitness
      The absolute minimum fitness in the population. Convenience field used for fitness based picking of focal individuals or for the GUI for scaling graphs.

    • maxFitness

      protected double maxFitness
      The absolute maximum fitness in the population. Convenience field used for fitness based picking of focal individuals or for the GUI for scaling graphs.

    • sumFitness

      protected double sumFitness
      The total fitness of the population. Convenience field used for fitness based picking of focal individuals or for the GUI for scaling graphs.

    • scores

      protected double[] scores
      The array of individual scores.
      See Also:

    • minScore

      protected double minScore
      The absolute minimum score in the population. Even though largely replaced by minFitness in simulations it remains a useful and often more intuitive quantity than fitness when visualizing results in the GUI. Convenience field.

    • maxScore

      protected double maxScore
      The absolute maximum score in the population. Even though largely replaced by maxFitness in simulations it remains a useful and often more intuitive quantity than fitness when visualizing results in the GUI. Convenience field.

    • groupScores

      protected double[] groupScores
      Array to hold scores of individuals during payoff calculations.

    • smallScores

      protected double[] smallScores
      Array to hold scores of individuals during payoff calculations for small groups (not all neighbours).

    • interactions

      protected int[] interactions
      The array of individual interaction counts.

    • tags

      protected double[] tags
      The array of individual tags counts. This can be used to trace ancestry.

    • nMixedInter

      protected int nMixedInter
      Optimization: Number of interactions in well-mixed populations for update rules that take advantage of IBSDPopulation.updateMixedScores(). nMixedInter is calculated ahead of time in check().

    • typeScores

      protected double[] typeScores
      Optimization: the lookup table for scores in well-mixed populations.

    • typeFitness

      protected double[] typeFitness
      Optimization: the lookup table for fitness in well-mixed populations.

    • nPopulation

      protected int nPopulation
      The size of the population. Convenience field to reduce calls to module.

    • map2fit

      protected Map2Fitness map2fit
      The map converting scores to fitness and vice versa. Convenience field to reduce calls to module.

    • adjustScores

      protected boolean adjustScores
      Optimization: Flag to indicate whether adjusting instead of recalculating scores is possible.

      Notes:

      1. Adjusting scores is only feasible if all individuals have a fixed number of interactions. For example, if all individuals always interact with all their neighbours, see IBSGroup.SamplingType.ALL. The only exception are well-mixed populations, GeometryType.WELLMIXED. With continuous traits all possible encounters would need to be considered, which is computationally not feasible. In contrast, for discrete traits separate calculations to determine the scores of each trait type are possible.
      2. With random interactions the scores of individuals are based on variable sets of interaction partners and their numbers of interactions may vary.
      See Also:

    • hasLookupTable

      protected boolean hasLookupTable
      Optimization: Flag to indicate whether lookup tables can be used.

    • isNeutral

      protected boolean isNeutral
      Flag to indicate whether dynamic is neutral, i.e. no selection acting on the different traits. The dynamic is considered neutral if maxScore-minScore<1e-8.

    • maxEffScoreIdx

      protected int maxEffScoreIdx
      Optimization: The index of the individual that currently holds the maximum score. This allows more efficient fitness based picking.
      See Also:

    • GILLESPIE_OPTIMIZATION_THRESHOLD

      private static final int GILLESPIE_OPTIMIZATION_THRESHOLD
      Threshold population size for using the Gillespie optimization for picking individuals proportional to fitness.
      See Also:

    • mutation

      protected Mutation mutation
      The mutation parameters.

    • optimizeHomo

      protected boolean optimizeHomo
      true if optimizations for homogeneous populations requested.

      Note:

      • optimizations can be requested with the command line option --optimize, see IBSD.cloOptimize.
      • currently restricted to discrete traits where homogeneous population states can be skipped by deterministically introducing new mutant after an geometrically (exponentially) distributed waiting time (see IBSD).
      • requires small mutation rates.
      • does not work for variable population sizes.

    • debugFocal

      protected int debugFocal
      Helper variable to store index of focal individual (birth) that got updated during debug step.

    • debugSame

      protected boolean debugSame
      Helper flag to indicate an actual trait change during debug step.

    • debugModel

      protected int debugModel
      Helper variable to store index of target individual (death) that got updated during debug step.

    • debugModels

      protected int[] debugModels
      Helper variable to store array of indices of individual that served as models during debug step.

    • debugNModels

      protected int debugNModels
      Helper variable to number of individual that served as models during debug step.

    • pRewire

      protected double[] pRewire
      The array containing the probabilities for rewiring links of the interaction and competition graphs.
      See Also:

    • pAddwire

      protected double[] pAddwire
      The array containing the probabilities for adding links to the interaction and competition graphs.
      See Also:

    • nIssues

      int nIssues
      The number of concistency issues encountered in the state of the IBS model.
      See Also:

    • consistencyCheckRequested

      boolean consistencyCheckRequested
      The flag to indicate whether consistency checks on the state of the IBS model are requested.
      See Also:

    • INSTEAD_OF

      private static final String INSTEAD_OF
      String for formatting log messages
      See Also:

    • syncFraction

      double syncFraction
      The fraction of the population that gets updated in synchronous updates.

  • Constructor Details

    • IBSPopulation

      protected IBSPopulation(EvoLudo engine, M module)
      Creates a population of individuals for IBS simulations.
      Parameters:
      engine - the pacemaker for running the model
      module - the module that defines the game

  • Method Details

    • getModule

      public M getModule()
      Gets the module associated with this population.
      Returns:
      the module associated with this population

    • setOpponentPop

      public void setOpponentPop(IBSPopulation<?,?> opponent)
      Set the interaction partner/opponent of this population.
      Parameters:
      opponent - the interaction partner/opponent

    • getStatus

      public abstract String getStatus()
      Gets the status of the as a formatted string. This is typically used in the GUI to summarize the progress of the model.
      Returns:
      the status of the population

    • prepareTraits

      public abstract void prepareTraits()
      Prior to a synchronous update step the current state must be duplicated in preparation for processing the next step.
      See Also:

    • commitTraits

      public abstract void commitTraits()
      After a synchronous update step the new state must be copied back to become the current state.
      See Also:

    • commitTraitAt

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

    • haveSameTrait

      public abstract boolean haveSameTrait(int a, int b)
      Check if individuals with index a and index b have the same traits.
      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 abstract boolean isSameTrait(int a)
      Check if individual with index a has switched traits.

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

      Parameters:
      a - index of individual
      Returns:
      true if trait remained unchanged
      See Also:

    • swapTraits

      public abstract void swapTraits(int a, int b)
      Swap traits of individuals with index a and index b.

      Note: the traits still need to be committed.

      Parameters:
      a - the index of first individual
      b - the index of second individual
      See Also:

    • playPairGameAt

      public abstract void playPairGameAt(IBSGroup group)
      Play a pairwise interaction with the individuals in group.
      Parameters:
      group - the group of individuals interacting in pairs

    • playGroupGameAt

      public abstract void playGroupGameAt(IBSGroup group)
      Play a group interaction with the individuals in group.
      Parameters:
      group - the group of interacting individuals

    • adjustPairGameScoresAt

      public abstract void adjustPairGameScoresAt(int me)
      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.

      Parameters:
      me - the index of the focal individual

    • yalpGroupGameAt

      public abstract void yalpGroupGameAt(IBSGroup group)
      Counterpart of playGroupGameAt(IBSGroup), playGameAt(int) and/or playGameSyncAt(int). Removes the payoffs of group interactions.
      Parameters:
      group - the interaction group

    • adjustScoreAt

      public abstract void adjustScoreAt(int index, double before, double after)
      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.

      Parameters:
      index - the index of the individual
      before - the score before adjustments
      after - the score after adjustments

    • adjustScoreAt

      public abstract void adjustScoreAt(int index, double adjust)
      Adjust score of individual with index index by adjust and update all applicable helper variables, e.g. sumFitness.
      Parameters:
      index - the index of the individual
      adjust - the score adjustment

    • updatePlayerBestResponse

      public boolean updatePlayerBestResponse(int me, int[] group, int size)
      Best-response update.

      Important:

      1. The array group is untouchable because it may refer to the population structure. Any change would also permanently change the structure.
      2. The best-response update must be implemented in subclasses that override this method. By default throws an error.
      3. Instead of overriding the method, subclasses may remove PlayerUpdate.Type.BEST_RESPONSE from PlayerUpdate#clo.
      Parameters:
      me - the index of individual to update
      group - the array with indices of reference group
      size - the size of the reference group
      Returns:
      true if trait changed (signaling score needs to be reset)

    • preferredPlayerBest

      public abstract 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'?

      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

    • isVacantAt

      public boolean isVacantAt(int index)
      Check if site with index index is occupied by an individual or vacant.

      Note: Assumes that trait are committed.

      Parameters:
      index - the index of the individual/site to check
      Returns:
      true if site index is vacant

    • becomesVacantAt

      public boolean becomesVacantAt(int index)
      Check if site with index index will become vacant in this time step.

      Note: Assumes that trait are not committed.

      Parameters:
      index - the index of the individual/site to check
      Returns:
      true if site index will become vacant

    • isMonomorphic

      public boolean isMonomorphic()
      Check if population is monomorphic.

      Note: In models that admit vacant sites this does not imply a homogeneous (or absorbing) state of the population. Without vacant sites monomorphic states are absorbing, at least in the absence of mutations.

      Returns:
      true if population is monomorphic
      See Also:

    • checkConvergence

      public boolean checkConvergence()
      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.

      Returns:
      true if converged.

    • getTraitNameAt

      public abstract String getTraitNameAt(int index)
      Gets the formatted name of the trait of the individual at site index.
      Parameters:
      index - the index of the
      Returns:
      the string describing the trait

    • getInteractionGeometry

      public AbstractGeometry getInteractionGeometry()
      Gets the interaction geometry.
      Returns:
      the interaction geometry

    • getInterGroup

      public IBSGroup getInterGroup()
      Gets the interaction group.
      Returns:
      the interaction group

    • getCompetitionGeometry

      public AbstractGeometry getCompetitionGeometry()
      Gets the competition geometry.
      Returns:
      the competition geometry

    • getCompGroup

      public IBSGroup getCompGroup()
      Gets the competition/reference/model group.
      Returns:
      the competition/reference/model group

    • getPopulationUpdate

      public PopulationUpdate getPopulationUpdate()
      Gets the population update.
      Returns:
      the population update

    • setPopulationUpdate

      public void setPopulationUpdate(PopulationUpdate populationUpdate)
      Sets the population update.
      Parameters:
      populationUpdate - the population update

    • getTotalFitness

      public double getTotalFitness()
      Gets the total fitness of the population.
      Returns:
      the total fitness

    • doSyncMigration

      public int doSyncMigration()
      Perform synchronous migration.
      Returns:
      the number of migrants

    • doMigration

      public void doMigration()
      Perform asynchronous migration.

    • doDiffusionMigration

      public void doDiffusionMigration()
      Perform diffusion migration, which is implemented as two players swap their locations while leaving their respective neighbourhood structure untouched.

    • updatePlayerSwap

      public void updatePlayerSwap(int a, int b)
      Swap players in locations a and b.
      Parameters:
      a - the index of the first individual
      b - the index of the second individual

    • doBirthDeathMigration

      public void doBirthDeathMigration()
      Perform a birth-death migration, where a focal individual (selected proportional to fitness) produces a migrant offspring, which replaces another member of the population uniformly at random.

      Note: This is almost identical to Moran (birth-death) updating in well-mixed populations (only victim and migrant always different)

    • doDeathBirthMigration

      public void doDeathBirthMigration()
      Perform a death-birth migration, where a member of the population (selected uniformly at random) dies and the remaining individuals compete to repopulate the vacant site. One competitor succeeds with a probability proportional proportional to fitness.

      Note: This is almost identical to Moran (birth-death) updating in well-mixed populations

    • pickFocalSite

      public int pickFocalSite()
      Draws the index of a site in the population uniformly at random, irrespective of whether it is occupied or not.
      Returns:
      the index of the picked site

    • pickFocalSite

      public int pickFocalSite(int excl)
      Draws the index of a site in the population uniformly at random, irrespective of whether it is occupied or not.
      Parameters:
      excl - the index of the excluded site
      Returns:
      the index of the picked site

    • pickFocalIndividual

      public int pickFocalIndividual()
      Draws the index of a individual of the population uniformly at random. Vacant sites are skipped. In the absence of vacant sites this is equivalent to pickFocalSite().

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Returns:
      the index of the picked individual

    • pickFocalSkipVacant

      private int pickFocalSkipVacant()
      Pick a focal individual uniformly at random but skipping vacant sites.
      Returns:
      the index of the picked individual

    • pickFocalSkipVacant

      private int pickFocalSkipVacant(int excl)
      Pick a focal individual uniformly at random but excluding the individual with index excl.
      Parameters:
      excl - the index of the excluded individual
      Returns:
      the index of the picked individual

    • pickFocalHead

      private int pickFocalHead(int pick)
      Pick a focal individual uniformly at random starting from head.
      Parameters:
      pick - the pick index
      Returns:
      the index of the picked individual

    • pickFocalHead

      private int pickFocalHead(int pick, int excl)
      Pick a focal individual uniformly at random starting from head, excluding individual excl.
      Parameters:
      pick - the pick index
      excl - the index of the excluded individual
      Returns:
      the index of the picked individual

    • pickFocalTail

      private int pickFocalTail(int pick)
      Pick a focal individual uniformly at random starting from tail.
      Parameters:
      pick - the pick index
      Returns:
      the index of the picked individual

    • pickFocalTail

      private int pickFocalTail(int pick, int excl)
      Pick a focal individual uniformly at random starting from tail, excluding individual excl.
      Parameters:
      pick - the pick index
      excl - the index of the excluded individual
      Returns:
      the index of the picked individual

    • pickFailed

      private int pickFailed()
      Handle failed pick.
      Returns:
      never returns control

    • pickFailed

      private int pickFailed(double remainder)
      Handle failed pick and report details about failure.
      Parameters:
      remainder - remaining probability mass that failed to select an individual
      Returns:
      never returns control

    • pickFocalIndividual

      public int pickFocalIndividual(int excl)
      Draws the index of a individual of the population uniformly at random but excluding the individual with index excl. Vacant sites are skipped.

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the excluded individual
      Returns:
      the index of the picked individual

    • pickFitFocalIndividual

      public int pickFitFocalIndividual()
      Draws the index of a member of the population with a probability proportional to fitness.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Discussions/extensions:

      1. Should picking include vacant sites, or not, or selectable?
      2. Currently vacant sites are excluded for fitness based picking but not for random picking.
      3. Perform more systematic analysis regarding the threshold population size (currently nPopulation &geq; 100) for the two Gillespie methods sometimes 4*nPopulation trials are needed, which seems too much...
      Returns:
      the index of the picked member

    • pickFitFocalNoVacant

      private int pickFitFocalNoVacant()
      Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Returns:
      the index of the picked member

    • pickFitFocalSkipVacant

      private int pickFitFocalSkipVacant()
      Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Returns:
      the index of the picked member

    • pickFitFocalIndividual

      public int pickFitFocalIndividual(int excl)
      Draws the index of a member of the population with a probability proportional to fitness but excluding the individual with the index excl.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the index of the picked member

    • pickFitFocalNoVacant

      private int pickFitFocalNoVacant(int excl)
      Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the index of the picked member

    • pickFitFocalNoVacantGillespieOptimized

      private int pickFitFocalNoVacantGillespieOptimized(int excl)
      Draws the index of a member of the population with a probability proportional to fitness but assuming no vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the index of the picked member

    • pickFitFocalSkipVacant

      private int pickFitFocalSkipVacant(int excl)
      Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the index of the picked member

    • pickFitFocalSkipVacantGillespieOptimized

      private int pickFitFocalSkipVacantGillespieOptimized(int excl)
      Draws the index of a member of the population with a probability proportional to fitness but assuming vacant sites.

      Note: scores must be ≥0

      Important: This method is highly time sensitive. Any optimization effort is worth making.

      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the index of the picked member

    • second

      private double second(int excl)
      Find the second highest score.
      Parameters:
      excl - the index of the member that should be excluded from picking
      Returns:
      the second highest score

    • debugScores

      protected void debugScores(double hit)
      Log report if picking failed to shed better light on what might be the root cause for the failure.
      Parameters:
      hit - the 'left-over fitness' from picking

    • pickFitNeighborAt

      protected int pickFitNeighborAt(int me)
      Pick a neighbour of the focal individual me with probability proportional to their fitness.
      Parameters:
      me - the index of the focal individual
      Returns:
      the index of a neighbour

    • pickFitNeighborAt

      protected int pickFitNeighborAt(int me, boolean withSelf)
      Pick a neighbour of the focal individual me with probability proportional to their fitness. If the flag withSelf==true then the focal individual is included in the picking.
      Parameters:
      me - the index of the focal individual
      withSelf - the flag whether to include self
      Returns:
      the index of a neighbour

    • pickFitNeighborNoVacantAt

      private int pickFitNeighborNoVacantAt(int me, boolean withSelf)
      Pick a neighbour of the focal individual me with probability proportional to their fitness assuming no vacant sites. If the flag withSelf==true then the focal individual is included in the picking.
      Parameters:
      me - the index of the focal individual
      withSelf - the flag whether to include self
      Returns:
      the index of a neighbour

    • totFitnessNoVacant

      private double totFitnessNoVacant(int me)
      Compute total fitness of neighbours of individual me assuming no vacant sites.
      Parameters:
      me - the index of the focal individual
      Returns:
      the total fitness of neighbours

    • pickFitNeighborSkipVacantAt

      private int pickFitNeighborSkipVacantAt(int me, boolean withSelf)
      Pick a neighbour of the focal individual me with probability proportional to their fitness assuming vacant sites. If the flag withSelf==true then the focal individual is included in the picking.
      Parameters:
      me - the index of the focal individual
      withSelf - the flag whether to include self
      Returns:
      the index of a neighbour

    • totFitnessSkipVacant

      private double totFitnessSkipVacant(int me)
      Compute total fitness of neighbours of individual me assuming vacant sites.
      Parameters:
      me - the index of the focal individual
      Returns:
      the total fitness of neighbours

    • pickNeutralNeighbourAt

      private int pickNeutralNeighbourAt(int me, boolean withSelf)
      Helper method to do picking under neutral conditions (no or negligible fitness differences). In well-mixed populations the picking includes the focal individual if withSelf==true. Otherwise picking never includes me.
      Parameters:
      me - the index of the focal individual
      withSelf - the flag whether to include self
      Returns:
      the index of a neighbour

    • pickNeighborSiteAt

      public int pickNeighborSiteAt(int me)
      Picks a neighbouring site of the focal individual me uniformly at random. This is where the focal individual places its offspring in the Moran process under Birth-death updating. The original Moran process refers to well-mixed (or mean-field) populations where the offspring can replace its parent (albeit with a small probability of \(o(1/N)\), where \(N\) is the population size). In contrast in the spatial Moran process the offspring replaces a neighbour of the parent.

      Notes:

      1. The parent is never picked.
      2. Vacant sites are picked with the same probability as occupied ones.
      Parameters:
      me - the index of the focal individual
      Returns:
      the index of a neighbour
      See Also:

    • updateFromModelAt

      public void updateFromModelAt(int me, int you)
      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.

      Parameters:
      me - the index of the focal individual
      you - the index of the model individual to adopt trait from
      See Also:

    • playGameSyncAt

      public void playGameSyncAt(int me)
      Update the score of individual me.

      After initialization and for synchronized population updating this method is invoked (rather than playGameAt(int)). The synchronous flag simply indicates that all players are going to be updated. For directed graphs this implies that incoming and outgoing links do not need to be treated separately because every outgoing link corresponds to an incoming link of another node.

      Parameters:
      me - the index of the focal individual

    • playGameAt

      public void playGameAt(int me)
      Update the score of individual me. This method is called if adjusting scores is not an option. If site me is vacant do nothing.
      Parameters:
      me - the index of the focal individual
      See Also:

    • adjustGameScoresAt

      public void adjustGameScoresAt(int me)
      Adjust scores of focal player me and its neighbours (interaction partners).

      Requirements/notes:

      1. This optimized method is only applicable if IBSGroup.SamplingType.ALL is true and not GeometryType.WELLMIXED, i.e. if the interaction group includes all neighbors but not all other members of the population.
      2. For pairwise interactions more efficient approaches are possible but those require direct access to the trait and are hence delegated to subclasses.
      Parameters:
      me - the index of the focal individual
      See Also:

    • updateScoreAt

      public void updateScoreAt(int index, double newscore)
      Update the score of the individual with index index by adding newscore from single interaction.
      Parameters:
      index - the index of the individual
      newscore - the new score of the individual

    • updateScoreAt

      public void updateScoreAt(int index, double newscore, int incr)
      Update the score of the individual with index index by adding (incr &gt; 0 or removing, incr &lt; 0) newscore as the result of incr interactions.

      Important:

      1. Traits are already committed when adding scores (incr>0).
      2. Traits are not committed when removing scores (incr<0).
      3. This routine is never called for the focal site (i.e. the one that may have changed trait and hence where it matters whether traits are committed).
      4. resetScoreAt(int) deals with the focal site.
      Parameters:
      index - the index of the individual
      newscore - score/payoff to add (incr>0) or subtract (incr<0)
      incr - number of interactions

    • updateFitnessAt

      public void updateFitnessAt(int idx)
      Update the fitness of the individual with index idx by mapping its current score. Keeps track of sumFitness.

      Note: If sumFitness decreases dramatically rounding errors become an issue. More specifically, if sumFitness is reduced to half or less, recalculate from scratch.

      Parameters:
      idx - the index of the individual

    • setScoreAt

      public void setScoreAt(int index, double newscore, int inter)
      Sets the score of individual with index index to newscore as the result of inter interactions. Also derives the corresponding fitness and adjusts sumFitness.

      Note: Assumes that resetScores() was called earlier (or at least resetScoreAt(int) for those sites that setScoreAt(int) is used for updating their score).

      Parameters:
      index - the index of the individual
      newscore - new score to set
      inter - number of interactions

    • removeScoreAt

      public void removeScoreAt(int index, double nilscore)
      Removes the score nilscore based on a single interaction from the individual with index index.
      Parameters:
      index - the index of the individual
      nilscore - the score to remove
      See Also:

    • removeScoreAt

      public void removeScoreAt(int index, double nilscore, int incr)
      Removes the score nilscore based on incr interactions from the individual with index index.
      Parameters:
      index - the index of the individual
      nilscore - the score to remove
      incr - the number of interactions to remove
      See Also:

    • resetScoreAt

      public void resetScoreAt(int index)
      Reset score of individual at index index.

      Important: traits must not yet have been committed.

      Discussions/extensions:

      Revise the entire trait updating procedure: it's inefficient to first reset scores then update traits then update score...
      Parameters:
      index - the index of the individual

    • swapScoresAt

      public void swapScoresAt(int idxa, int idxb)
      Swap the scores (and fitness) of individuals with indices idxa and idxb.
      Parameters:
      idxa - the index of the first individual
      idxb - the index of the second individual

    • resetScores

      public void resetScores()
      Reset scores and fitness of all individuals to zero.

    • updateScores

      public void updateScores()
      Update the scores of all individuals in the population.

    • getScoreAt

      public double getScoreAt(int idx)
      Gets the score of the individual with index idx.
      Parameters:
      idx - the index of the individual
      Returns:
      the score of the individual

    • getFitnessAt

      public double getFitnessAt(int idx)
      Gets the fitness of the individual with index idx.
      Parameters:
      idx - the index of the individual
      Returns:
      the fitness of the individual

    • updateEffScoreRange

      protected boolean updateEffScoreRange(int index, double before, double after)
      Keep track of highest score through a reference to the corresponding individual.

      Discussions/extensions:

      1. Keeping track of the lowest performing individual is very costly because the poor performers are much more likely to get updated. In contrast, the maximum performer is least likely to get replaced. For example, in cSD with a well-mixed population of 10'000 spends >80% of CPU time hunting down the least performing individual! Besides, the minimum score is never used. The maximum score is only used for global, fitness based selection such as the Birth-death process. (room for optimization?)
      2. For synchronous updates this method is not only wasteful but problematic because sites that are later updated experience different conditions.
      3. For constant fitness (maxEffScoreIdx &lt; 0) tracking the maximum is not needed.
      4. if (isVacantAt(index)) {...} is only executed if after == before, i.e. the code is almost dead... suspicious or ingenious?!
      Parameters:
      index - the index of the individual
      before - the score before the update
      after - the score after the update
      Returns:
      true if effective range of payoffs has changed (or, more precisely, if the reference individual has changed); false otherwise.

    • setMaxEffScoreIdx

      protected void setMaxEffScoreIdx()
      Find the index of the individual with the highest score.

    • step

      public int step()
      Perform a single IBS step, i.e. update one individual for asynchronous updates or once the entire population for synchronous updates.

      Discussions/extensions

      1. Review migration. Exclusively used in Demes2x2. Should probably be treated as an independent event, in particular independent of population or player updates
      2. Implement Wright-Fisher update.
      3. How to scale realtime with multiple populations? How to define a generation if population sizes can vary?
      4. updatePlayerEcology() returns time increment in realtime units. Everyone else does fine without...
      Returns:
      the number of elapsed realtime units

    • optimizeHomo

      private int optimizeHomo()
      Optimize homogeneous population states by skipping to the next mutation event.
      Returns:
      the number of elapsed realtime units

    • updateSyncAll

      private int updateSyncAll()
      Update all individuals in the population synchronously.
      Returns:
      the number of elapsed realtime units

    • updateSyncFraction

      private int updateSyncFraction()
      Update a fraction of individuals in the population synchronously.
      Returns:
      the number of elapsed realtime units

    • updateOnce

      private int updateOnce()
      Update all individuals in the population once asynchronously.
      Returns:
      the number of elapsed realtime units

    • getSpeciesUpdateRate

      public double getSpeciesUpdateRate()
      Gets the update rate of this species. Only used in multi-species modules. Determines the relative rate at which this species is picked as compared to others.
      Returns:
      the species update rate
      See Also:

    • mutate

      public int mutate()
      Perform a mutation event. The focal individual is picked uniformly at random.
      Returns:
      the number of elapsed realtime units

    • mutateAt

      public abstract int mutateAt(int focal)
      Mutate the trait of the focal individual with index focal. The mutated trait is committed and the scores updated.
      Parameters:
      focal - the index of the focal individual
      Returns:
      the number of elapsed realtime units

    • maybeMutateAt

      protected abstract boolean maybeMutateAt(int focal, boolean switched)
      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.

      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 abstract void maybeMutateMoran(int source, int dest)
      Consider mutating the trait of the parent individual with index source. The mutated trait is committed and the scores updated.
      Parameters:
      source - the index of the parent individual
      dest - the index of the location for the offspring placement

    • debugUpdatePopulationAt

      public void debugUpdatePopulationAt(int focal)
      Update focal individual with index focal for debugging.

      Notes:

      • Must remain in sync with population updates in IBS and step().
      • For debugging only; time not advanced.
      Parameters:
      focal - the index of the individual to update

    • debugMarkChange

      protected void debugMarkChange()
      Override in subclass for example to mark those individuals in the GUI that were involved in the debug step.

    • formatInfoAt

      private String formatInfoAt(int focal, int model)
      Helper method to format information about updating the focal individual at index focal using the model individual with index model.
      Parameters:
      focal - the index of the focal individual
      model - the index of the model individual
      Returns:
      the formatted information

    • updatePlayerAsync

      protected void updatePlayerAsync()
      Perform a single, asynchronous update of the trait of a randomly selected individual.

    • updatePlayerAsyncAt

      public void updatePlayerAsyncAt(int me)
      Update the trait of the focal individual with index me.
      Parameters:
      me - the index of the focal individual

    • updateScoreAt

      protected void updateScoreAt(int me, boolean switched)
      Update the scores of the focal individual with index me.
      Parameters:
      me - the index of the focal individual
      switched - true if the focal switched trait

    • updatePlayerMoranBirthDeath

      public void updatePlayerMoranBirthDeath()
      Perform a single, Moran (Birth-death) update for a random individual selected with a probability proportional to fitness. This is the original Moran process where the offspring can replace the parent in well-mixed populations. For structured populations this corresponds to the spatial Moran process with Bd updating in Ohtsuki et al. Nature 2005.
      See Also:

    • updatePlayerMoranBirthDeathAt

      protected void updatePlayerMoranBirthDeathAt(int parent)
      Perform a Moran (Birth-death) update for the focal individual with index parent to produce a clonal offspring and replace one of the parent's neighbours selected uniformly at random. This is the original Moran process where the offspring can replace the parent in well-mixed populations.
      Parameters:
      parent - the index of the parent

    • updatePlayerMoranDeathBirth

      public void updatePlayerMoranDeathBirth()
      Perform a single Moran (death-Birth) update for a site selected uniformly at random. This corresponds to the spatial Moran process with dB updating in Ohtsuki et al. Nature 2005.
      See Also:

    • updatePlayerMoranDeathBirthAt

      protected void updatePlayerMoranDeathBirthAt(int vacant)
      Perform a single Moran (death-Birth) update for the focal site with index vacant. One of its (incoming) neighbours succeeds, with a probability proportional to its fitness, in producing a clonal offspring and placing it at site vacant.
      Parameters:
      vacant - the index of the vacant site

    • updatePlayerMoranImitate

      public void updatePlayerMoranImitate()
      Perform a single, Moran (imitate) update for a site selected uniformly at random. This corresponds to imitate in Ohtsuki et al. Nature 2005.
      See Also:

    • updatePlayerMoranImitateAt

      protected void updatePlayerMoranImitateAt(int imitator)
      Update the focal individual with index imitator by comparing its own payoff and those of its neighbors. The focal individual imitates the trait of a neighbour (or keeps its own) with a probability proportional to the corresponding individual's fitness (including its own).
      Parameters:
      imitator - the index of the individual that reassesses its trait

    • migrateMoran

      protected void migrateMoran(int source, int dest)
      Perform a single Moran update for the reproducing node with index source and the node that gets replaced with index dest. The three Moran variants (death-Birth, Birth-death and imitate) differ only in their selection of the individuals source and dest and then call this method, migrateMoran(int, int).

      Note: Moran optimizations for discrete trait require access to this method.

      Parameters:
      source - the index of the parent node
      dest - the index of the node where the offspring is placed
      See Also:

    • updatePlayerEcology

      public int updatePlayerEcology()
      Perform a single ecological update of an individual selected uniformly at random.
      Returns:
      the number of elapsed realtime units

    • updatePlayerEcologyAt

      protected int updatePlayerEcologyAt(int index)
      Perform a single ecological update of the site with index index.

      Important: No default implementation is possible. Modules with ecological updates need to subclass IBSPopulation and provide their own implementations.

      Parameters:
      index - the index of the focal site
      Returns:
      the number of elapsed realtime units

    • updatePlayerAt

      public boolean updatePlayerAt(int me)
      Perform a single update of the individual with index me. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring
      Parameters:
      me - the index of the focal individual
      Returns:
      true if trait of reference adopted
      See Also:

    • updatePlayerAt

      public boolean updatePlayerAt(int me, int[] refGroup, int rGroupSize)
      Perform a single update of the individual with index me using the rGroupSize models in the array refGroup. Returns true if the individual changed its trait to signal that the focal individual's score will need to be reset.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updatePlayerBest

      protected boolean updatePlayerBest(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of the best performing reference individual among the rGroupSize models in the array refGroup. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.

      Notes:

      1. If the scores of two reference individuals tie but exceed the focal individual's score, expert advice is needed.
      2. If the focal individual's score is highest but ties with one or more reference individuals the focal individual keeps its trait.
      3. For the best update it does not matter whether scores are averaged or accumulated.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updatePlayerBestHalf

      protected boolean updatePlayerBestHalf(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of the best performing reference individual among the the rGroupSize models in the array refGroup. If the scores of two (or more) references or the score of the focal individual and one (or more) reference(s) tie, then a coin toss decides which trait to keep/adopt. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.

      Notes:

      For the best update it does not matter whether scores are averaged or accumulated.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updateProportionalAbs

      protected boolean updateProportionalAbs(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of one reference individual (including itself) among the the rGroupSize models in the array refGroup with a probability proportional to their scores. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updateReplicatorPlus

      protected boolean updateReplicatorPlus(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup. The focal individual \(i\) imitates the trait of a better performing reference individual \(j\) with a probability proportional to the difference in fitness: \[p_{i\to j} = \frac{(f_i-f_j)_+}\alpha,\] where \(\alpha\) denotes a normalization factor to ensure \(p_{i\to j}\in[0,1]\). Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updateReplicatorHalf

      protected boolean updateReplicatorHalf(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup. The focal individual \(i\) imitates the trait of a reference individual \(j\) with a probability proportional to the difference in fitness: \[p_{i\to j} = \frac{f_i-f_j}\alpha\] where \(\alpha\) denotes a normalization factor to ensure \(p_{i\to j}\in[0,1]\). This corresponds to the microscopic updating which recovers the standard replicator equation in the continuum limit. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updateReplicator

      private boolean updateReplicator(int me, int[] refGroup, int rGroupSize, boolean betterOnly)
      Helper method for replicator type updates. Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      betterOnly - the flag to indicate whether only better performing reference individuals are considered
      Returns:
      true if trait of reference adopted
      See Also:

    • updateReplicatorNeutral

      private boolean updateReplicatorNeutral(int me, int[] refGroup, int rGroupSize, boolean betterOnly)
      Replicator type update in the neutral case.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      betterOnly - the flag to indicate whether only better performing reference individuals are considered
      Returns:
      true if trait of reference adopted

    • updateReplicatorNoNoise

      private double updateReplicatorNoNoise(int[] refGroup, int rGroupSize, double myFitness, boolean betterOnly)
      Replicator type update without noise.
      Parameters:
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      myFitness - the fitness of the focal individual
      betterOnly - the flag to indicate whether only better performing reference individuals are considered
      Returns:
      the probability of no adoption

    • updateReplicatorNoise

      private double updateReplicatorNoise(int[] refGroup, int rGroupSize, double myFitness, boolean betterOnly)
      Replicator type update with noise.
      Parameters:
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      myFitness - the fitness of the focal individual
      betterOnly - the flag to indicate whether only better performing reference individuals are considered
      Returns:
      the probability of no adoption

    • updateThermal

      protected boolean updateThermal(int me, int[] refGroup, int rGroupSize)
      Updates the focal individual with index me by adopting the trait of one reference individual among the the rGroupSize models in the array refGroup. The focal individual \(i\) imitates the trait of a reference individual \(j\) with a probability proportional to the difference in fitness: \[p_{i\to j} = \frac1{1+\exp(-(f_i-f_j)/T)}\] where \(T\) denotes the temperature (or noise) in adopting a trait. In the limit \(T\to\infty\) imitation reduces to a coin toss, \(p_{i\to j}=1/2\). In contrast, for \(T\to 0\) it converges to the step-function, with \(\Theta(x)=1\) for positive \(x\), \(\Theta(x)=0\) for \(x\) negative and \(\Theta(0)=1/2\). Returns true if the individual adopted the trait of the reference individual. Does not imply that the trait changed in discrete modules. Whether the individuals score is reset depends on playerScoring.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      true if trait of reference adopted
      See Also:

    • updateThermalNoNoise

      private double updateThermalNoNoise(int me, int[] refGroup, int rGroupSize)
      Thermal update without noise.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      the probability of no adoption

    • updateThermalNoise

      private double updateThermalNoise(int me, int[] refGroup, int rGroupSize)
      Thermal update with noise.
      Parameters:
      me - the index of the focal individual
      refGroup - the group of reference individuals
      rGroupSize - the number of reference individuals
      Returns:
      the probability of no adoption

    • updateFailed

      private boolean updateFailed(int me, int rGroupSize, double nProb, double norm, double choice)
      Handle failed adoption decision and log diagnostic details before aborting.
      Parameters:
      me - the focal individual index
      rGroupSize - number of reference individuals considered
      nProb - residual probability of no adoption
      norm - normalization constant for cumulative probabilities
      choice - sampled random number that failed to match a candidate
      Returns:
      never returns control

    • debugUpdate

      protected void debugUpdate(int me, int rGroupSize, double nProb, double norm, double choice)
      Log report if updating failed to shed better light on what might be the root cause for the failure.
      Parameters:
      me - the index of the focal individual
      rGroupSize - number of reference individuals considered
      nProb - residual probability of no adoption
      norm - normalization constant for cumulative probabilities
      choice - sampled random value that failed to match a candidate

    • getMinScore

      public double getMinScore()
      Returns the minimum score min in this population, taking the population structure and payoff accounting into account.
      Returns:
      the processed minimum score

    • getMaxScore

      public double getMaxScore()
      Returns the maximum score min in this population, taking the population structure and payoff accounting into account.
      Returns:
      the processed maximum score

    • processScore

      protected double processScore(double score, int count)
      Process the accumulated score in this population, taking the updating into account. In heterogeneous networks count must refer to the highest degree for maximum scores and the lowest degree for minimum scores.
      Parameters:
      score - the minimum or maximum score
      count - the number of interactions for the score
      Returns:
      the processed extremal score

    • updateMinMaxScores

      public void updateMinMaxScores()
      Retrieve and store extremal scores and fitnesses to reduce calls to Module.

    • check

      public boolean check()
      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.
      Returns:
      true if reset is required
      See Also:

    • checkGeometry

      boolean checkGeometry()
      Check the interaction and competition geometries for consistency and adjust if necessary (and feasible).
      Returns:
      true if reset is required

    • checkGeometryRewire

      boolean checkGeometryRewire()
      Rewire the interaction and competition geometries if requested.
      Returns:
      true if rewiring changed

    • setGeometryNames

      void setGeometryNames()
      Set the names of the interaction and competition geometries based on the module name and whether the geometries are the same or different.

    • checkMigration

      void checkMigration()
      Check consistency of migration settings and adjust if necessary (and feasible).

    • checkInteractions

      boolean checkInteractions(int nGroup)
      Validate interaction structures and adjust incompatible settings.
      Parameters:
      nGroup - interaction group size
      Returns:
      true if changes require a reset

    • checkPayoffs

      boolean checkPayoffs(int nGroup)
      Check settings for modules implementing Payoffs.
      Parameters:
      nGroup - the interaction group size
      Returns:
      true if reset is required

    • checkLookupTable

      boolean checkLookupTable(int nGroup, boolean ephemeralScores)
      Check whether lookup tables for scores and fitness can be used. Free memory if possible and request a reset if the use of lookup tables has changed.
      Parameters:
      nGroup - the interaction group size
      ephemeralScores - the flag for ephemeral scores
      Returns:
      true if reset is required

    • checkNoLookupTable

      boolean checkNoLookupTable(boolean ephemeralScores)
      Free memory used for lookup tables and allocate arrays for scores, fitness and interactions. Returns true if reset is required.
      Parameters:
      ephemeralScores - the flag for ephemeral scores
      Returns:
      true if reset is required

    • getNMixedInteractions

      int getNMixedInteractions(int nGroup)
      Determine the number of interactions in well-mixed populations with lookup tables.
      Parameters:
      nGroup - the interaction group size
      Returns:
      the number of interactions

    • checkCompSampling

      void checkCompSampling()
      Validate competition sampling rules for well-mixed populations and adjust if required.

    • checkOptimizations

      boolean checkOptimizations()
      Check whether optimizations for homogeneous states can be used. Disable if necessary (and log warnings).
      Returns:
      true if reset is required

    • setRewire

      public void setRewire(double[] rewire)
      Set the probabilities for rewiring links of the interaction and competition graphs.
      Parameters:
      rewire - the array double[] {<interaction>, <competition>}

    • setAddwire

      public void setAddwire(double[] addwire)
      Set the probabilities for adding links to the interaction and competition graphs.
      Parameters:
      addwire - the array double[] {<interaction>, <competition>}

    • doAdjustScores

      protected abstract boolean doAdjustScores()
      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).
      AbstractGeometry.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).
      Returns:
      true if adjusting scores is feasible
      See Also:

    • reset

      public void reset()
      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.
      See Also:

    • resetMoran

      void resetMoran()
      Ensure that Moran type population updates have non-negative fitness values. Adjust the payoff-to-fitness mapping if necessary.

    • resetEphemeral

      void resetEphemeral(int nGroup)
      Precalculate the number of interactions for ephemeral payoffs and store in the interactions array.
      Parameters:
      nGroup - the group size

    • init

      public void init()
      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

      See Also:

    • setConsistencyCheck

      public void setConsistencyCheck(boolean check)
      Enable consistency checks of the state of the IBS model. Never use in production.
      Parameters:
      check - true to request consistency checks

    • isConsistent

      public void isConsistent()
      Convenience method during development to perform a number of consistency checks of the current state. Once an inconsistency is found there is no need to keep looking and no further checks are performed.

      Execution time is of little concern here. Never use in the final simulation code.

    • checkConsistentFitness

      void checkConsistentFitness()
      Check consistency of scores and fitness values for modules that implement Payoffs.

    • checkIndividualConsistency

      private void checkIndividualConsistency(int n)
      Check consistency of scores for a single individual.
      Parameters:
      n - the index of the individual

    • checkLookupTableConsistency

      private void checkLookupTableConsistency()
      Check consistency of scores when using lookup tables.

    • checkTraitScores

      private void checkTraitScores(double[] typeScoresStore, double[] typeFitnessStore)
      Check consistency of scores for all traits.
      Parameters:
      typeScoresStore - the stored type scores
      typeFitnessStore - the stored type fitness

    • checkFitnessSum

      private void checkFitnessSum(double sumFitnessStore)
      Check consistency of total fitness.
      Parameters:
      sumFitnessStore - the stored fitness sum

    • checkAdjustScoresConsistency

      private void checkAdjustScoresConsistency()
      Check consistency when not using lookup tables.

    • checkNoAdjustScoresConsistency

      private void checkNoAdjustScoresConsistency()
      Check consistency when scores are not adjusted.

    • logScoringIssue

      void logScoringIssue(int idx, double actual, String issue)
      Log a scoring issue.
      Parameters:
      idx - the index of the individual
      actual - the actual score
      issue - the issue description

    • logScoringIssue

      void logScoringIssue(int idx, double actual, double expected)
      Log a scoring issue.
      Parameters:
      idx - the index of the individual
      actual - the actual score
      expected - the expected score

    • logMapIssue

      void logMapIssue(int idx, double actual, double expected)
      Log a mapping issue.
      Parameters:
      idx - the index of the individual
      actual - the actual score
      expected - the expected score

    • logFitnessIssue

      void logFitnessIssue(int idx, double actual, double expected)
      Log a fitness issue.
      Parameters:
      idx - the index of the individual
      actual - the actual fitness
      expected - the expected fitness

    • logAccountingIssue

      void logAccountingIssue(double actual, double expected)
      Log an accounting issue.
      Parameters:
      actual - the actual value
      expected - the expected value

    • logAccountingIssue

      void logAccountingIssue(String descr, double actual, double expected, String issue)
      Log an accounting issue.
      Parameters:
      descr - the description of the value
      actual - the actual value
      expected - the expected value
      issue - the issue description

    • resetTraits

      public void resetTraits()
      Reset all traits in preparation of the next update step. Simply an opportunity for customizations in subclasses.

    • getNMean

      public int getNMean()
      Return the number of mean values for this population (for traits or fitness).

      Note: The number of mean traits in a model may differ from the number of traits in the corresponding module. This is the case for example for GeometryType.SQUARE_NEUMANN_2ND with two disjoint interaction or competition graphs.

      Returns:
      the number of mean values
      See Also:

    • getMeanTraits

      public abstract double[] 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.
      Parameters:
      mean - the array for returning the trait values
      Returns:
      the array mean containing the mean trait values
      See Also:

    • getTraitData

      public abstract <T> void getTraitData(T[] colors, ColorMap<T> colorMap)
      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).
      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

    • getMeanFitness

      public abstract double[] 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 init() or reset().
      Parameters:
      mean - the array for storing the mean fitness values
      Returns:
      the array mean containing the mean fitness values
      See Also:

    • getFitnessData

      public <T> void getFitnessData(T[] colors, ColorMap.Gradient1D<T> colorMap)
      Returns the fitness 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).
      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

    • getFitnessHistogramData

      public void getFitnessHistogramData(double[][] bins)
      Generates a histogram of the fitness distribution in this population. The result is returned in the array bins.

      Notes:

      1. bins is a 2D array because discrete models generate histograms for each trait separately.
      2. By default generate a histogram of the scores in bins[0].
      3. Consider moving to IBSDPopulation and IBSCPopulation with arguments bins[][] and bins[], respectively.
      Parameters:
      bins - the 2D array to store the histogram(s)

    • getScores

      public String getScores(int digits)
      Gets the scores of all individuals with precision digits. Scores of vacant sites are reported as 0d/0d.
      Parameters:
      digits - the number of digits for the scores
      Returns:
      the formatted scores

    • getScoreNameAt

      public String getScoreNameAt(int idx)
      Gets the formatted score of the individual with index idx.
      Parameters:
      idx - the index of the individual
      Returns:
      the formatted score

    • getFitness

      public String getFitness(int digits)
      Gets the fitness of all individuals with precision digits. Fitness of vacant sites are reported as 0d/0d.
      Parameters:
      digits - the number of digits for the scores
      Returns:
      the formatted fitness

    • getFitnessNameAt

      public String getFitnessNameAt(int idx, boolean pretty)
      Gets the formatted fitness of the individual with index idx as a string. If the flag pretty is set the formatting is prettyfied by replacing the exponent E in scientific notation to a power of 10.
      Parameters:
      idx - the index of the individual
      pretty - flag to prettify formatting
      Returns:
      the formatted fitness

    • getFitnessNameAt

      public String getFitnessNameAt(int idx)
      Gets the formatted and prettyfied fitness of the individual with index idx as a string.
      Parameters:
      idx - the index of the individual
      Returns:
      the formatted fitness

    • getInteractionsAt

      public int getInteractionsAt(int idx)
      Gets the number of interactions of the individual with index idx. Returns -1 if site idx is vacant or fitness is static, i.e. not based on interactions.
      Parameters:
      idx - the index of the individual
      Returns:
      the number of interactions

    • getTags

      public double[] getTags(double[] mem)
      Copies the tags of all individuals in the population and returns them in the array mem.
      Parameters:
      mem - the array to copy the tags into
      Returns:
      the array of tags

    • getTagData

      public <T> void getTagData(T[] colors, ColorMap<T> colorMap)
      Returns the tags 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).
      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 tags into colors

    • getTagAt

      public double getTagAt(int idx)
      Gets the tag of the individual with index idx.
      Parameters:
      idx - the index of the individual
      Returns:
      the tag number

    • getTagNameAt

      public String getTagNameAt(int idx)
      Gets the formatted tag of the individual with index idx as string.
      Parameters:
      idx - the index of the individual
      Returns:
      the tag as a string

    • setTagAt

      public boolean setTagAt(int idx, double tag)
      Sets the tag of the individual with index idx.
      Parameters:
      idx - the index of the individual
      tag - the new tag of the individual
      Returns:
      true if the tag changed

    • getPopulationSize

      public int getPopulationSize()
      Gets current population size. For most models with fixed population sizes this simply returns nPopulation. Ecological models with variable population sizes must override this method to return the actual population size.
      Returns:
      current population size

    • setSyncFraction

      public void setSyncFraction(double sync)
      Set the fraction of the population that gets updated in synchronous updates.
      Parameters:
      sync - the fraction that gets updated

    • getSyncFraction

      public double getSyncFraction()
      Get the fraction of the population that gets updated in synchronous updates.
      Returns:
      the fraction that gets updated

    • setMigrationType

      public void setMigrationType(IBS.MigrationType type)
      Sets the type of migrations to type.
      Parameters:
      type - the new type of migrations

    • getMigrationType

      public IBS.MigrationType getMigrationType()
      Gets the type of migrations.
      Returns:
      the type of migrations

    • setMigrationProb

      public void setMigrationProb(double aValue)
      Sets the migration probability to aValue.
      Parameters:
      aValue - the new migration probability

    • getMigrationProb

      public double getMigrationProb()
      Gets the migration probability.
      Returns:
      the migration probability

    • setPlayerScoring

      public void setPlayerScoring(IBS.ScoringType type)
      Sets the type for managing scores of individuals.
      Parameters:
      type - the type for managing scores
      See Also:

    • getPlayerScoring

      public IBS.ScoringType getPlayerScoring()
      Gets the type for managing scores of individuals.
      Returns:
      true if scores are always reset
      See Also:

    • setPlayerScoreAveraged

      public void setPlayerScoreAveraged(boolean aver)
      Sets whether scores of individuals are averaged over multiple interactions or accumulated.
      Parameters:
      aver - the flag to indicate whether scores are averaged

    • getPlayerScoreAveraged

      public boolean getPlayerScoreAveraged()
      Gets whether player scores are averaged (as opposed to accumulated).
      Returns:
      true if player scores are averaged.

    • mouseHitNode

      public boolean mouseHitNode(int hit)
      Called from GUI if node/individual with index idx received a mouse click or tap.
      Parameters:
      hit - the index of the node
      Returns:
      false if no actions taken

    • mouseHitNode

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

    • encodeFitness

      public void encodeFitness(StringBuilder plist)
      Encode the fitness of all individuals in the IBS model in a plist inspired XML string.
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreFitness

      public boolean restoreFitness(Plist plist)
      Restore the fitness of all individuals encoded in the plist inspired map of key, value-pairs.
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also:

    • encodeInteractions

      public void encodeInteractions(StringBuilder plist)
      Encode the interactions of all individuals in the IBS model in a plist inspired XML string.
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreInteractions

      public boolean restoreInteractions(Plist plist)
      Restore the interactions of all individuals encoded in the plist inspired map of key, value-pairs.
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also:

    • encodeTraits

      public abstract void encodeTraits(StringBuilder plist)
      Encode the traits of all individuals in the IBS model in a plist inspired XML string.
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreTraits

      public abstract boolean restoreTraits(Plist plist)
      Restore the traits of all individuals encoded in the plist inspired map of key, value-pairs.
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also:

    • encodeGeometry

      public void encodeGeometry(StringBuilder plist)
      Encode the interaction and competition structures of the IBS model in a plist inspired XML string.
      Parameters:
      plist - the StringBuilder to write the encoded state to
      See Also:

    • restoreGeometry

      public boolean restoreGeometry(Plist plist)
      Restore the interaction and competition structures encoded in the plist inspired map of key, value-pairs.
      Parameters:
      plist - the map of key, value-pairs
      Returns:
      true if successful
      See Also:

    • random0n

      public int random0n(int n)
      Draw a uniformly distributed random integer number from the semi-closed interval [0, n).
      Parameters:
      n - the upper limit of interval (exclusive)
      Returns:
      the random integer number in [0, n).

    • random01

      public double random01()
      Draw a uniformly distributed random double from the semi-closed interval [0, 1) with 32bit resolution. This is the default.
      Returns:
      the random number in [0, 1).

    • randomGaussian

      public double randomGaussian(double mean, double sdev)
      Draw a Gaussian (normal) distributed random double.
      Parameters:
      mean - the mean of the Gaussian distribution
      sdev - the standard deviation of the Gaussian distribution
      Returns:
      the Gaussian random number

    • nextBinomial

      public int nextBinomial(double p, int n)
      Draw a binomially distributed random integer.
      Parameters:
      p - the probability of success
      n - the number of trials
      Returns:
      the number of successes