Package org.evoludo.simulator.models

Class IBSDPopulation

Object

IBSPopulation

IBSDPopulation

Direct Known Subclasses:

CDL.IBSPop, IBSPop, NetGames.IBSPop, RSP.IBSPop, SIR.IBSPop, TBT.IBSPop

public class IBSDPopulation
extends IBSPopulation

The core class for individual based simulations with discrete traits. Manages the traits of the population, while delegating the management of the population and individual fitness as well as simulation steps to super.

Author:

Christoph Hauert

See Also:

• IBSPopulation

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	IBSDPopulation.link	A minimalstic helper class (or data structure) to represent a single directed link in the network structure.

Field Summary

Fields

Modifier and Type	Field	Description
protected double[]	accuTypeScores	The array with the total scores for each trait.
protected boolean[]	active	The array indicating which traits are active.
private IBSDPopulation.link[]	activeLinks	The array to keep track of all links along which a change in the population composition may occur.
protected IBS.HasIBS.DGroups	groupmodule	For group interaction modules module==groupmodule holds and null otherwise.
protected IBSD.Init	init	Type of initial configuration.
int[]	initCount	The array with the initial number of individuals of each trait.
protected Discrete	module	The discrete module associated with this model.
protected Mutation.Discrete	mutation	The mutation parameters.
protected IBSDPopulation	opponent	The interaction partner/opponent of this population opponent.getModule()==getModule().getOpponent().
protected boolean	optimizeMoran	The flag to indicate whether optimizations of Moran processes are requested.
protected IBS.HasIBS.DPairs	pairmodule	For pairwise interaction modules module==pairmodule holds and null otherwise.
private int[]	tmpCount	Temporary storage for the number of each trait in group interactions.
private int[]	tmpGroup	Temporary storage for indices of individuals in group interactions.
private double[]	tmpScore	Temporary storage for the scores of each trait prior to the group interactions.
private int[]	tmpTraits	Temporary storage for traits of individuals in group interactions.
private double[]	tmpTraitScore	Temporary storage for the scores of each trait in group interactions.
private int[]	traits	The array of individual traits.
int[]	traitsCount	The array with the total number of individuals of each trait.
protected int[]	traitsNext	The array for temporarily storing traits during updates.

Fields inherited from class IBSPopulation

adjustScores, competition, compGroup, consistencyCheckRequested, debugFocal, debugModel, debugModels, debugNModels, debugSame, distrMigrants, engine, fitness, groupScores, hasLookupTable, interaction, interactions, interGroup, isConsistent, isMultispecies, isNeutral, logger, map2fit, maxEffScoreIdx, maxFitness, maxScore, migrationType, minFitness, minScore, nMixedInter, nPopulation, nTraits, pAddwire, playerScoreAveraged, playerScoring, playerUpdate, pMigration, populationUpdate, pRewire, rng, scores, smallScores, staticmodule, sumFitness, syncFraction, tags, typeFitness, typeScores, VACANT

Constructor Summary

Constructors

Constructor	Description
IBSDPopulation(EvoLudo engine, Discrete module)	Creates a population of individuals with discrete traits 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).
void	adjustPairGameScoresAt(int me)	Adjusts scores of focal individual with index me and its neighbors after me changed trait.
void	adjustScoreAt(int index, double adjust)	Adjust score of individual with index index by adjust and update all applicable helper variables, e.g.
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).
boolean	checkConvergence()	Check if population has converged.
void	commitTraitAt(int me)	The change of a trait of the player at index is stored in a temporary variable and must be committed before proceeding.
void	commitTraits()	After a synchronous update step the new state must be copied back to become the current state.
void	countTraits(int[] counts, int[] myTraits, int offset, int len)	Count the number of each trait in the array traits starting at offset for len individuals.
protected void	debugMarkChange()	Override in subclass for example to mark those individuals in the GUI that were involved in the debug step.
protected boolean	doAdjustScores()	Check if scores can be adjusted rather than recalculated after an individual changed its trait.
void	encodeTraits(StringBuilder plist)	Encode the traits of all individuals in the IBS model in a plist inspired XML string.
private double	estimateVacantFrequency(int type)	Helper method to determine the frequency of vacant sites based on an estimate of the carrying capacity.
private void	fillStripe(int offset, int width, int trait)	Helper method to initialize lattice structures with homogeneous stripes of each trait.
double	getFitnessAt(int idx)	Gets the fitness of the individual with index idx.
void	getFitnessHistogramData(double[][] bins)	Generates a histogram of the fitness distribution in this population.
IBSD.Init	getInit()	Gets the type of the initial configuration and its arguments.
void	getInitialTraits(double[] inittraits)	Returns the initial trait(s) of this population in the array init.
void	getMeanFitness(double[] mean)	Returns the mean fitness of this population in the array mean.
void	getMeanTraits(double[] mean)	Returns the mean trait(s) of this population in the array mean.
double	getMonoScore(int type)	Gets the score of individuals in a population that is monomorphic in trait type.
int	getPopulationSize()	Gets current population size.
double	getScoreAt(int idx)	Gets the score of the individual with index idx.
String	getStatus()	Gets the status of the as a formatted string.
int	getTraitAt(int idx)	Gets the trait of the individual with index idx.
<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.
String	getTraitNameAt(int idx)	Gets the formatted name of the trait of the individual at site index.
String	getTraits()	Gets the traits of all individuals as indices.
int[]	getTraitsCount()	Gets the count of each trait.
boolean	haveSameTrait(int a, int b)	Check if individuals with index a and index b have the same traits.
void	init()	Initialize the model.
protected void	initFrequency()	Initial configuration with trait frequencies as specified in arguments.
protected void	initKaleidoscope()	Initial configuration that generates evolutionary kaleidoscopes for deterministic update rules.
protected void	initMono()	Monomorphic initial configuration with specified trait (and frequency in modules that allow empty sites).
void	initMono(int monoType)	Initialize monomorphic population with trait monoType.
void	initMono(int monoType, double monoFreq)	Initialize monomorphic population with trait monoType.
protected int	initMutant()	Monomorphic initial configuration with a single mutant placed in a location chosen uniformly at random (uniform initialization, cosmic rays).
protected void	initStripes()	Initial configuration with monomorphic stripes of each type to investigate invasion properties of one trait into another with at least one instance of all possible pairings.
protected int	initTemperature()	Monomorphic initial configuration with a single mutant placed in a random location chosen with probability proprtional to the number of incoming links (temperature initialization, errors in reproduction).
protected void	initUniform()	Initial configuration with uniform trait frequencies of all active traits.
void	isConsistent()	Convenience method during development to perform a number of consistency checks of the current state.
boolean	isMonomorphic()	Check if population is monomorphic.
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.
protected boolean	maybeMutateAt(int focal, boolean switched)	Consider mutating the trait of the focal individual with index focal.
protected void	maybeMutateMoran(int source, int dest)	Consider mutating the trait of the parent individual with index source.
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.
private boolean	mouseSetHit(int hit, int trait)	Process event from GUI: individual with index hit was hit by mouse (or tap) in order to set its trait to trait.
int	mutateAt(int focal)	Mutate the trait of the focal individual with index focal.
void	playGroupGameAt(IBSGroup group)	Play a group interaction with the individuals in group.
void	playPairGameAt(IBSGroup group)	Play a pairwise interaction with the individuals in group.
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.
void	prepareTraits()	Prior to a synchronous update step the current state must be duplicated in preparation for processing the next step.
void	reset()	Reset the model.
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	restoreTraits(Plist plist)	Restore the traits of all individuals encoded in the plist inspired map of key, value-pairs.
void	setInit(IBSD.Init init)	Sets the type of the initial configuration and any accompanying arguments.
boolean	setInitialTraits(double[] init)	Set the initial trait frequencies in the population.
boolean	setNextTraitAt(int idx, int trait)	Sets the next trait of the individual with index idx to trait.
void	setOpponentPop(IBSPopulation opponent)	Set the interaction partner/opponent of this population.
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	setTraitAt(int idx, int trait)	Sets the trait of the individual with index idx to trait.
protected void	stripGroupVacancies(IBSGroup group, int[] gTraits, int[] gIdxs)	Eliminate vacant sites from the assembled group.
protected int	stripVacancies(int[] groupidx, int groupsize, int[] gTraits, int[] gIdxs)	Process traits while excluding vacant sites.
private int	sum(int start, int end)	Helper method to determine the number of stripes required so that each trait shares at least one interface with every other trait: nStripes = nTraits + 2 * sum(2, nTraits - 2).
void	swapTraits(int a, int b)	Swap traits of individuals with index a and index b.
void	updateFromModelAt(int index, int modelPlayer)	Update individual with index me and adopt the trait of individual with index you.
protected void	updateMixedMeanScores()	Calculate scores in well-mixed populations as well as hierarchical structures with well-mixed units.
boolean	updatePlayerBestResponse(int me, int[] group, int size)	Best-response update.
protected int	updatePlayerEcologyAt(int me)	Perform a single ecological update of the individual with index me: Focal individual dies with probability proportional to the death rate.
void	updatePlayerMoranBirthDeath()	Perform a single, Moran (Birth-death) update for a random individual selected with a probability proportional to fitness.
void	updatePlayerMoranDeathBirth()	Perform a single Moran (death-Birth) update for a site selected uniformly at random.
protected void	updatePlayerMoranDeathBirth(boolean withSelf)	The optimized Moran process for death-Birth and imitation updatating.
void	updatePlayerMoranImitate()	Perform a single, Moran (imitate) update for a site selected uniformly at random.
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.
void	updateTraitCount()	Update the count of each trait.
void	yalpGroupGameAt(IBSGroup group)	Counterpart of IBSPopulation.playGroupGameAt(IBSGroup), IBSPopulation.playGameAt(int) and/or IBSPopulation.playGameSyncAt(int).

Methods inherited from class IBSPopulation

checkGeometry, createCompetitionGeometry, createInteractionGeometry, debugScores, debugUpdatePopulationAt, doBirthDeathMigration, doDeathBirthMigration, doDiffusionMigration, doMigration, doSyncMigration, encodeFitness, encodeGeometry, encodeInteractions, generateGeometry, getCompetitionGeometry, getCompGroup, getFitness, getFitnessData, getFitnessNameAt, getFitnessNameAt, getInteractionGeometry, getInteractionsAt, getInterGroup, getMaxScore, getMigrationProb, getMigrationType, getMinScore, getModule, getNMean, getPlayerScoreAveraged, getPlayerScoring, getPopulationUpdate, getScoreNameAt, getScores, getSpeciesUpdateRate, getSyncFraction, getTagAt, getTagData, getTagNameAt, getTags, getTotalFitness, migrateMoran, mouseHitNode, mutate, nextBinomial, parseGeometry, pickFitFocalIndividual, pickFitFocalIndividual, pickFitNeighborAt, pickFitNeighborAt, pickFocalIndividual, pickFocalIndividual, pickFocalSite, pickFocalSite, pickNeighborSiteAt, playGameAt, playGameSyncAt, processScore, random01, random01d, random0n, random0N, randomGaussian, removeScoreAt, removeScoreAt, restoreGeometry, restoreInteractions, setAddwire, setConsistencyCheck, setMaxEffScoreIdx, setMigrationProb, setMigrationType, setPlayerScoreAveraged, setPlayerScoring, setPopulationUpdate, setRewire, setSyncFraction, setTagAt, srandom, step, swapScoresAt, updateEffScoreRange, updateFitnessAt, updateMinMaxScores, updatePlayerAsync, updatePlayerAsyncAt, updatePlayerAt, updatePlayerAt, updatePlayerBest, updatePlayerBestHalf, updatePlayerEcology, updatePlayerMoranBirthDeathAt, updatePlayerMoranDeathBirthAt, updatePlayerMoranImitateAt, updatePlayerSwap, updateProportionalAbs, updateReplicatorHalf, updateReplicatorPlus, updateScoreAt, updateScoreAt, updateThermal

Methods inherited from class Object

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

Field Details

module

protected Discrete module

The discrete module associated with this model.

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

pairmodule

protected IBS.HasIBS.DPairs pairmodule

For pairwise interaction modules module==pairmodule holds and null otherwise. Convenience field to reduce the number of (unnecessary) casts.

See Also:

• IBS.HasIBS.DPairs

groupmodule

protected IBS.HasIBS.DGroups groupmodule

For group interaction modules module==groupmodule holds and null otherwise. Convenience field to reduce the number of (unnecessary) casts.

See Also:

• IBS.HasIBS.DGroups

opponent

protected IBSDPopulation opponent

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

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

optimizeMoran

protected boolean optimizeMoran

The flag to indicate whether optimizations of Moran processes are requested. true if optimizations for Moran process requested.

Note:

1. Optimizations are requested with the command line option --optimize (or -1), see IBSD.cloOptimize.
2. Optimizations destroy the time line of events. Do not use if e.g. fixation times are of interest (but fine for fixation probabilities).
3. Currently restricted to discrete traits and structured populations, where Moran type processes can be optimized by skipping events involving individuals of the same type (see maybeMutateMoran(int, int)).

mutation

protected Mutation.Discrete mutation

The mutation parameters.

traits

private int[] traits

The array of individual traits.

traitsNext

protected int[] traitsNext

The array for temporarily storing traits during updates.

active

protected boolean[] active

The array indicating which traits are active. Convenience field to reduce calls to module.

accuTypeScores

protected double[] accuTypeScores

The array with the total scores for each trait.

traitsCount

public int[] traitsCount

The array with the total number of individuals of each trait.

initCount

public int[] initCount

The array with the initial number of individuals of each trait.

activeLinks

private IBSDPopulation.link[] activeLinks

The array to keep track of all links along which a change in the population composition may occur. This is used for optimized Moran updating.

See Also:

• optimizeMoran

tmpTraits

private int[] tmpTraits

Temporary storage for traits of individuals in group interactions.

tmpGroup

private int[] tmpGroup

Temporary storage for indices of individuals in group interactions.

tmpCount

private int[] tmpCount

Temporary storage for the number of each trait in group interactions.

tmpTraitScore

private double[] tmpTraitScore

Temporary storage for the scores of each trait in group interactions.

tmpScore

private double[] tmpScore

Temporary storage for the scores of each trait prior to the group interactions.

init

protected IBSD.Init init

Type of initial configuration.

See Also:

• IBSD.Init.clo

Constructor Details

IBSDPopulation

public IBSDPopulation(EvoLudo engine,
 Discrete module)

Creates a population of individuals with discrete traits for IBS simulations.

Parameters:

engine - the pacemaker for running the model

module - the module that defines the game

Method Details

setOpponentPop

public void setOpponentPop(IBSPopulation opponent)

Description copied from class: IBSPopulation

Set the interaction partner/opponent of this population.

Overrides:

setOpponentPop in class IBSPopulation

Parameters:

opponent - the interaction partner/opponent

getPopulationSize

public int getPopulationSize()

Description copied from class: IBSPopulation

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.

Overrides:

getPopulationSize in class IBSPopulation

Returns:

current population size

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.

Allocates memory for optimized Moran process.

Discussions/extensions

groupScores unused in IBSDPopulation. Merge with traitScore?

Overrides:

reset in class IBSPopulation

See Also:

• optimizeMoran
• updatePlayerMoranBirthDeath()

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.

Optimized Moran process: a significant speed boost is achieved when restricting events along links that potentially result in an actual change of the population composition, i.e. by focussing on those links that connect individuals of different traits. This destroys the time scale.

Overrides:

updatePlayerMoranBirthDeath in class IBSPopulation

See Also:

• optimizeMoran

updatePlayerMoranImitate

public void updatePlayerMoranImitate()

Description copied from class: IBSPopulation

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

Overrides:

updatePlayerMoranImitate in class IBSPopulation

See Also:

• Ohtsuki, H., Hauert, C., Lieberman, E. & Nowak, M. (2006) A simple rule for the evolution of cooperation on graphs, Nature 441, 502-505

updatePlayerMoranDeathBirth

public void updatePlayerMoranDeathBirth()

Description copied from class: IBSPopulation

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.

Overrides:

updatePlayerMoranDeathBirth in class IBSPopulation

See Also:

• Ohtsuki, H., Hauert, C., Lieberman, E. & Nowak, M. (2006) A simple rule for the evolution of cooperation on graphs, Nature 441, 502-505

updatePlayerMoranDeathBirth

protected void updatePlayerMoranDeathBirth(boolean withSelf)

The optimized Moran process for death-Birth and imitation updatating. A significant speed boost is achieved when restricting events along links that potentially result in an actual change of the population composition, i.e. by focussing on those links that connect individuals of different traits. This destroys the time scale.

Parameters:

withSelf - the flag to indicate whether to include to focal individual

See Also:

• optimizeMoran
• IBSPopulation.updatePlayerMoranDeathBirth()
• IBSPopulation.updatePlayerMoranImitate()

updatePlayerEcologyAt

protected int updatePlayerEcologyAt(int me)

Perform a single ecological update of the individual with index me:

1. Focal individual dies with probability proportional to the death rate.
2. Otherwise, draw a random neighbour and, if unoccupied, place clonal offspring on neighboring site with probability proportional to fitness.

Overrides:

updatePlayerEcologyAt in class IBSPopulation

Parameters:

me - the index of the focal site

Returns:

the number of elapsed realtime units

updateFromModelAt

public void updateFromModelAt(int index,
 int modelPlayer)

Description copied from class: IBSPopulation

Update individual with index me and adopt the trait of individual with index you.

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

Overrides:

updateFromModelAt in class IBSPopulation

Parameters:

index - the index of the focal individual

modelPlayer - the index of the model individual to adopt trait from

See Also:

• updateFromModelAt(int, int)
• IBSMCPopulation.updateFromModelAt(int, int)

mutateAt

public int mutateAt(int focal)

Description copied from class: IBSPopulation

Mutate the trait of the focal individual with index focal. The mutated trait is committed and the scores updated.

Specified by:

mutateAt in class IBSPopulation

Parameters:

focal - the index of the focal individual

Returns:

the number of elapsed realtime units

maybeMutateAt

protected boolean maybeMutateAt(int focal,
 boolean switched)

Description copied from class: IBSPopulation

Consider mutating the trait of the focal individual with index focal. The trait of the focal individual is stored in the array traits unless the focal individual switched trait. In that case the current trait is stored in the array traitsNext.

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

Specified by:

maybeMutateAt in class IBSPopulation

Parameters:

focal - the index of the focal individual

switched - true if the focal individual switched trait

Returns:

true if the trait of the focal individual changed

maybeMutateMoran

protected void maybeMutateMoran(int source,
 int dest)

Description copied from class: IBSPopulation

Consider mutating the trait of the parent individual with index source. The mutated trait is committed and the scores updated.

Specified by:

maybeMutateMoran in class IBSPopulation

Parameters:

source - the index of the parent individual

dest - the index of the location for the offspring placement

debugMarkChange

protected void debugMarkChange()

Description copied from class: IBSPopulation

Override in subclass for example to mark those individuals in the GUI that were involved in the debug step.

Overrides:

debugMarkChange in class IBSPopulation

haveSameTrait

public boolean haveSameTrait(int a,
 int b)

Description copied from class: IBSPopulation

Check if individuals with index a and index b have the same traits.

Specified by:

haveSameTrait in class IBSPopulation

Parameters:

a - the index of first individual

b - the index of second individual

Returns:

true if the two individuals have the same traits

isSameTrait

public boolean isSameTrait(int a)

Description copied from class: IBSPopulation

Check if individual with index a has switched traits.

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

Specified by:

isSameTrait in class IBSPopulation

Parameters:

a - index of individual

Returns:

true if trait remained unchanged

See Also:

• IBSPopulation.commitTraitAt(int)

swapTraits

public void swapTraits(int a,
 int b)

Description copied from class: IBSPopulation

Swap traits of individuals with index a and index b.

Note: the traits still need to be committed.

Specified by:

swapTraits in class IBSPopulation

Parameters:

a - the index of first individual

b - the index of second individual

See Also:

• IBSPopulation.commitTraitAt(int)

updateScoreAt

public void updateScoreAt(int index,
 double newscore,
 int incr)

Description copied from class: IBSPopulation

Update the score of the individual with index index by adding (incr > 0 or removing, incr < 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. IBSPopulation.resetScoreAt(int) deals with the focal site.

Overrides:

updateScoreAt in class IBSPopulation

Parameters:

index - the index of the individual

newscore - score/payoff to add (incr>0) or subtract (incr<0)

incr - number of interactions

setScoreAt

public void setScoreAt(int index,
 double newscore,
 int inter)

Description copied from class: IBSPopulation

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 IBSPopulation.resetScores() was called earlier (or at least IBSPopulation.resetScoreAt(int) for those sites that setScoreAt(int) is used for updating their score).

Overrides:

setScoreAt in class IBSPopulation

Parameters:

index - the index of the individual

newscore - new score to set

inter - number of interactions

getScoreAt

public double getScoreAt(int idx)

Description copied from class: IBSPopulation

Gets the score of the individual with index idx.

Overrides:

getScoreAt in class IBSPopulation

Parameters:

idx - the index of the individual

Returns:

the score of the individual

getFitnessAt

public double getFitnessAt(int idx)

Description copied from class: IBSPopulation

Gets the fitness of the individual with index idx.

Overrides:

getFitnessAt in class IBSPopulation

Parameters:

idx - the index of the individual

Returns:

the fitness of the individual

getTraitAt

public int getTraitAt(int idx)

Gets the trait of the individual with index idx. The trait is an index in [0,nTraits).

Parameters:

idx - the index of the individual

Returns:

the trait of the individual

See Also:

• Module.nTraits

setTraitAt

public void setTraitAt(int idx,
 int trait)

Sets the trait of the individual with index idx to trait. The trait is an index in [0,nTraits).

Parameters:

idx - the index of the individual

trait - the new trait

See Also:

• Module.nTraits

setNextTraitAt

public boolean setNextTraitAt(int idx,
 int trait)

Sets the next trait of the individual with index idx to trait. The trait is an index in [0,nTraits).

Parameters:

idx - the index of the individual

trait - the new trait

Returns:

true if the trait changed

See Also:

• commitTraitAt(int)

resetScoreAt

public void resetScoreAt(int index)

Description copied from class: IBSPopulation

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...

Overrides:

resetScoreAt in class IBSPopulation

Parameters:

index - the index of the individual

resetScores

public void resetScores()

Description copied from class: IBSPopulation

Reset scores and fitness of all individuals to zero.

Overrides:

resetScores in class IBSPopulation

updateScores

public void updateScores()

Update the scores of all individuals in the population.

Note: Overridden to set scores in well-mixed populations more efficiently.

Overrides:

updateScores in class IBSPopulation

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.

Note: Takes composition of entire population into account for Geometry.Type#MEANFIELD but only the reference neighborhood in structured populations.

Overrides:

updatePlayerBestResponse in class IBSPopulation

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 boolean preferredPlayerBest(int me,
 int best,
 int sample)

For deterministic updating with multiple traits (more than two), it must be specified which trait is the preferred one.

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

Here we introduce the convention of a cyclic preference where traits with lower indices are always preferred. For example, with N traits, trait 0 is preferred over 1 preferred over 2... preferred over N-1 preferred over N preferred over 0, etc. This convention is arbitrary but makes sense for systems with cyclic dominance of traits and such systems are most likely to produce evolutionary kaleidoscopes and only for those is this deterministic updating of crucial importance. For anything else, these are irrelevant quibbles.

Specified by:

preferredPlayerBest in class IBSPopulation

Parameters:

me - the index of the focal individual

best - the index of the best performing individual

sample - the index of the sample type

Returns:

true if sample is preferred over best

stripGroupVacancies

protected void stripGroupVacancies(IBSGroup group,
 int[] gTraits,
 int[] gIdxs)

Eliminate vacant sites from the assembled group.

Important: group.group is untouchable! It may be a reference to Geometry.out[group.focal] and hence any changes would actually alter the geometry!

Parameters:

group - the group which potentially includes references to vacant sites

gTraits - the array of traits in the group

gIdxs - the array of indices of the individuals in the group

stripVacancies

protected int stripVacancies(int[] groupidx,
 int groupsize,
 int[] gTraits,
 int[] gIdxs)

Process traits while excluding vacant sites.

Parameters:

groupidx - the array of indices of the individuals in the group

groupsize - the size of the group

gTraits - the array to store/return the traits

gIdxs - the array to store/return the pruned indexes

Returns:

the size of the interaction group after pruning

playPairGameAt

public void playPairGameAt(IBSGroup group)

Description copied from class: IBSPopulation

Play a pairwise interaction with the individuals in group.

Specified by:

playPairGameAt in class IBSPopulation

Parameters:

group - the group of individuals interacting in pairs

adjustScoreAt

public void adjustScoreAt(int index,
 double before,
 double after)

Description copied from class: IBSPopulation

Adjust score of individual with index index from before to after and update all applicable helper variables, e.g. sumFitness.

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

Specified by:

adjustScoreAt in class IBSPopulation

Parameters:

index - the index of the individual

before - the score before adjustments

after - the score after adjustments

adjustScoreAt

public void adjustScoreAt(int index,
 double adjust)

Description copied from class: IBSPopulation

Adjust score of individual with index index by adjust and update all applicable helper variables, e.g. sumFitness.

Specified by:

adjustScoreAt in class IBSPopulation

Parameters:

index - the index of the individual

adjust - the score adjustment

adjustPairGameScoresAt

public void adjustPairGameScoresAt(int me)

Description copied from class: IBSPopulation

Adjusts scores of focal individual with index me and its neighbors after me changed trait. Only works if adjustScores==true.

Important: new trait must not yet have been committed.

Specified by:

adjustPairGameScoresAt in class IBSPopulation

Parameters:

me - the index of the focal individual

playGroupGameAt

public void playGroupGameAt(IBSGroup group)

Description copied from class: IBSPopulation

Play a group interaction with the individuals in group.

Specified by:

playGroupGameAt in class IBSPopulation

Parameters:

group - the group of interacting individuals

yalpGroupGameAt

public void yalpGroupGameAt(IBSGroup group)

Description copied from class: IBSPopulation

Counterpart of IBSPopulation.playGroupGameAt(IBSGroup), IBSPopulation.playGameAt(int) and/or IBSPopulation.playGameSyncAt(int). Removes the payoffs of group interactions.

Specified by:

yalpGroupGameAt in class IBSPopulation

Parameters:

group - the interaction group

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 Geometry.Type.MEANFIELD, 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.

Overridden to allow for adjusting scores in well-mixed populations.

Overrides:

adjustGameScoresAt in class IBSPopulation

Parameters:

me - the index of the focal individual

See Also:

• IBSPopulation.adjustPairGameScoresAt(int)

updateMixedMeanScores

protected void updateMixedMeanScores()

Calculate scores in well-mixed populations as well as hierarchical structures with well-mixed units.

countTraits

public void countTraits(int[] counts,
 int[] myTraits,
 int offset,
 int len)

Count the number of each trait in the array traits starting at offset for len individuals. The result is stored in counts.

Note: offset is convenient for hierarchical structures and prevents copying parts of the traits array.

Parameters:

counts - the array to return the number of individuals with each trait

myTraits - the array with the traits of the individuals

offset - the offset into the array traits to start counting

len - the number of individuals to count

resetTraits

public void resetTraits()

Reset all traits in preparation of the next update step. Simply an opportunity for customizations in subclasses.

Reset the colors of recently changed trait.

Overrides:

resetTraits in class IBSPopulation

prepareTraits

public void prepareTraits()

Description copied from class: IBSPopulation

Prior to a synchronous update step the current state must be duplicated in preparation for processing the next step.

Specified by:

prepareTraits in class IBSPopulation

See Also:

• IBSPopulation.commitTraits()

commitTraits

public void commitTraits()

After a synchronous update step the new state must be copied back to become the current state.

For discrete modules, update the trait count of each type and check if population reached a homogeneous state.

Specified by:

commitTraits in class IBSPopulation

See Also:

• IBSPopulation.prepareTraits()

updateTraitCount

public void updateTraitCount()

Update the count of each trait.

See Also:

• traitsCount

getTraitsCount

public int[] getTraitsCount()

Gets the count of each trait.

Returns:

the array with the numbers of each trait

isConsistent

public void isConsistent()

Description copied from class: IBSPopulation

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.

Overrides:

isConsistent in class IBSPopulation

isMonomorphic

public boolean isMonomorphic()

Description copied from class: IBSPopulation

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.

Overrides:

isMonomorphic in class IBSPopulation

Returns:

true if population is monomorphic

See Also:

• Discrete.cloMonoStop

checkConvergence

public boolean checkConvergence()

Description copied from class: IBSPopulation

Check if population has converged. By default true if population is monomorphic and no (zero) mutations. However, different implementations may have different criteria for convergence.

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

Specified by:

checkConvergence in class IBSPopulation

Returns:

true if converged.

isVacantAt

public boolean isVacantAt(int index)

Description copied from class: IBSPopulation

Check if site with index index is occupied by an individual or vacant.

Note: Assumes that trait are committed.

Overrides:

isVacantAt in class IBSPopulation

Parameters:

index - the index of the individual/site to check

Returns:

true if site index is vacant

becomesVacantAt

public boolean becomesVacantAt(int index)

Description copied from class: IBSPopulation

Check if site with index index will become vacant in this time step.

Note: Assumes that trait are not committed.

Overrides:

becomesVacantAt in class IBSPopulation

Parameters:

index - the index of the individual/site to check

Returns:

true if site index will become vacant

commitTraitAt

public void commitTraitAt(int me)

Description copied from class: IBSPopulation

The change of a trait of the player at index is stored in a temporary variable and must be committed before proceeding.

Specified by:

commitTraitAt in class IBSPopulation

Parameters:

me - the index of the player that needs to have its new trait committed

getMonoScore

public double getMonoScore(int type)

Gets the score of individuals in a population that is monomorphic in trait type.

Parameters:

type - the trait type

Returns:

the monomorphic score

getFitnessHistogramData

public void getFitnessHistogramData(double[][] bins)

Description copied from class: IBSPopulation

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.

Overrides:

getFitnessHistogramData in class IBSPopulation

Parameters:

bins - the 2D array to store the histogram(s)

setInitialTraits

public boolean setInitialTraits(double[] init)

Set the initial trait frequencies in the population. Switches the initialization type to IBSD.Init.Type.FREQUENCY.

Parameters:

init - the initial traits

Returns:

true if the initialization was successful

getInitialTraits

public void getInitialTraits(double[] inittraits)

Returns the initial trait(s) of this population in the array init. Used by GUI to visualize the initial state of this IBS model.

Parameters:

inittraits - the array for returning the initial trait values

See Also:

• Discrete.getInitialTraits(int, double[])

getMeanTraits

public void getMeanTraits(double[] mean)

Description copied from class: IBSPopulation

Returns the mean trait(s) of this population in the array mean. Used by GUI to visualize the current state of this IBS model.

Specified by:

getMeanTraits in class IBSPopulation

Parameters:

mean - the array for returning the trait values

See Also:

• Model.getMeanTraits(int, double[])

getTraitData

public <T> void getTraitData(T[] colors,
 ColorMap<T> colorMap)

Description copied from class: IBSPopulation

Returns the traits of all individuals in this population coded as colors in the array colors using the map colorMap. Used by GUI to visualize the current state of this IBS model. Colors are coded in different data types <T> depending on the runtime environment (GWT or JRE) as well as the graph (e.g. PopGraph2D or PopGraph3D).

Specified by:

getTraitData in class IBSPopulation

Type Parameters:

T - the type of color data (String or MeshLambertMaterial for GWT and Color for JRE).

Parameters:

colors - the array where the colors of all nodes are stored

colorMap - the map that converts traits into colors

getMeanFitness

public void getMeanFitness(double[] mean)

Description copied from class: IBSPopulation

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

Specified by:

getMeanFitness in class IBSPopulation

Parameters:

mean - the array for storing the mean fitness values

See Also:

• Model.getMeanFitness(int, double[])

getTraits

public String getTraits()

Gets the traits of all individuals as indices. Those with indices in [0, nTraits) denote individuals that have not changed traits since the previous report, while those in [nTraits, 2*nTraits) have.

Returns:

the traits

getTraitNameAt

public String getTraitNameAt(int idx)

Description copied from class: IBSPopulation

Gets the formatted name of the trait of the individual at site index.

Specified by:

getTraitNameAt in class IBSPopulation

Parameters:

idx - the index of the

Returns:

the string describing the trait

getStatus

public String getStatus()

Description copied from class: IBSPopulation

Gets the status of the as a formatted string. This is typically used in the GUI to summarize the progress of the model.

Specified by:

getStatus in class IBSPopulation

Returns:

the status of the population

check

public boolean check()

Description copied from class: IBSPopulation

Check all model parameters for consistency and adjust if necessary (and feasible). Returns true if adjustments require a reset. Free memory if possible and request a reset if new memory needs to be allocated.

Overrides:

check in class IBSPopulation

Returns:

true if reset is required

See Also:

• Model.check()
• Model.reset()
• IBSPopulation.reset()

doAdjustScores

protected boolean doAdjustScores()

Description copied from class: IBSPopulation

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

Requirements:

Group.SAMPLING_ALL

individuals need to be interacting with all their neighbours (not just a randomly selected subset).

Geometry.MEANFIELD

interactions with everyone are not feasible (impossible to model efficiently), in general, for unstructured populations (subclasses can do better, e.g. for discrete trait it is possible, see doAdjustScores()).

playerScoreReset

if scores are reset whenever an individual adopts the trait of another (regardless of whether an actual trait change occurred) then the expected number of interactions of each individual remains constant over time (even though the interaction count may differ for individuals on heterogeneous structures).

Specified by:

doAdjustScores in class IBSPopulation

Returns:

true if adjusting scores is feasible

See Also:

• IBS.ScoringType
• IBSDPopulation

init

public void init()

Description copied from class: IBSPopulation

Initialize the model. All parameters must be consistent. Subclasses must override this method to generate the initial trait configuration and call super.

Note: Initialization leaves the interaction and competition structures untouched

Overrides:

init in class IBSPopulation

See Also:

• IBSPopulation.check()
• Model.init()

initUniform

protected void initUniform()

Initial configuration with uniform trait frequencies of all active traits.

See Also:

• IBSD.Init.Type.UNIFORM

initFrequency

protected void initFrequency()

Initial configuration with trait frequencies as specified in arguments.

See Also:

• IBSD.Init.Type.FREQUENCY

initMono

protected void initMono()

Monomorphic initial configuration with specified trait (and frequency in modules that allow empty sites).

See Also:

• IBSD.Init.Type.MONO

estimateVacantFrequency

private double estimateVacantFrequency(int type)

Helper method to determine the frequency of vacant sites based on an estimate of the carrying capacity. In well-mixed populations this is \(1-d/r\), where \(d\) is the death rate and \(r\) the fitness of the resident type. Similarly, on regular graphs the carrying capacity is \(1-(k-1)d/(r(k-1)-d)\), where \(k\) is the degree of the graph. Finally, on generic structures, the estimate of the carrying capacity is based on the average out-degree of all nodes.

Note: residents in structured populations additionally have a characteristic distribution, which is not accounted for in this estimate.

Parameters:

type - the resident type

Returns:

the estimated frequency of vacant sites

initMono

public void initMono(int monoType)

Initialize monomorphic population with trait monoType.

Parameters:

monoType - the monomorphic trait

initMono

public void initMono(int monoType,
 double monoFreq)

Initialize monomorphic population with trait monoType. If the module admits vacant sites the frequency of individuals with the monomorphic trait is set to monoFreq.

Parameters:

monoType - the monomorphic trait

monoFreq - the frequency of the monomorphic trait

initMutant

protected int initMutant()

Monomorphic initial configuration with a single mutant placed in a location chosen uniformly at random (uniform initialization, cosmic rays).

Returns:

the location of the mutant

See Also:

• IBSD.Init.Type.MUTANT

initTemperature

protected int initTemperature()

Monomorphic initial configuration with a single mutant placed in a random location chosen with probability proprtional to the number of incoming links (temperature initialization, errors in reproduction).

Returns:

the location of the mutant

See Also:

• IBSD.Init.Type.TEMPERATURE

initKaleidoscope

protected void initKaleidoscope()

Initial configuration that generates evolutionary kaleidoscopes for deterministic update rules. Whether this is possible and and what kind of initial configurations are required depends on the module. Hence this method must be overriden in subclasses that admit kaleidoscopes.

Note: requires the explicit adding of the key IBSD.Init.Type.KALEIDOSCOPE for IBS models. For example, add

 if (model instanceof IBSD) {
        CLOption clo = ((IBSDPopulation) getIBSPopulation()).getInit().clo;
        clo.addKey(Init.Type.KALEIDOSCOPE);
 }
 

to org.evoludo.simulator.modules.Module#adjustCLO(org.evoludo.util.CLOParser).

See Also:

• IBSD.Init.Type.KALEIDOSCOPE

initStripes

protected void initStripes()

Initial configuration with monomorphic stripes of each type to investigate invasion properties of one trait into another with at least one instance of all possible pairings.

See Also:

• IBSD.Init.Type.STRIPES

fillStripe

private void fillStripe(int offset,
 int width,
 int trait)

Helper method to initialize lattice structures with homogeneous stripes of each trait.

Parameters:

offset - the offset to the start of the stripe

width - the width of the stripe

trait - the trait of the stripe

See Also:

• initStripes()

sum

private int sum(int start,
 int end)

Helper method to determine the number of stripes required so that each trait shares at least one interface with every other trait: nStripes = nTraits + 2 * sum(2, nTraits - 2). Procedure tested for 2, 3, 4, 5 traits.

Parameters:

start - the starting trait

end - the end trait

Returns:

the number of traits

setInit

public void setInit(IBSD.Init init)

Sets the type of the initial configuration and any accompanying arguments. If either type or args are null the respective current setting is preserved.

Parameters:

init - the type and arguments of the initial configuration

getInit

public IBSD.Init getInit()

Gets the type of the initial configuration and its arguments.

Returns:

the type and arguments of the initial configuration

mouseHitNode

public boolean mouseHitNode(int hit,
 boolean alt)

Description copied from class: IBSPopulation

Called from GUI if node/individual with index idx received a mouse click or tap and indicates whether the alt-key had been pressed.

Overrides:

mouseHitNode in class IBSPopulation

Parameters:

hit - the index of the node

alt - true if the alt-key was pressed

Returns:

false if no actions taken

mouseSetHit

private boolean mouseSetHit(int hit,
 int trait)

Process event from GUI: individual with index hit was hit by mouse (or tap) in order to set its trait to trait.

Parameters:

hit - the index of the individual that was hit by mouse or tap

trait - the new trait of the individual

Returns:

false if no actions taken (should not happen)

restoreFitness

public boolean restoreFitness(Plist plist)

Restore the fitness of all individuals encoded in the plist inspired map of key, value-pairs.

Important: traits must already be restored!

Overrides:

restoreFitness in class IBSPopulation

Parameters:

plist - the map of key, value-pairs

Returns:

true if successful

See Also:

• Model.restoreState(Plist)

encodeTraits

public void encodeTraits(StringBuilder plist)

Description copied from class: IBSPopulation

Encode the traits of all individuals in the IBS model in a plist inspired XML string.

Specified by:

encodeTraits in class IBSPopulation

Parameters:

plist - the StringBuilder to write the encoded state to

See Also:

• Model.encodeState(StringBuilder)

restoreTraits

public boolean restoreTraits(Plist plist)

Description copied from class: IBSPopulation

Restore the traits of all individuals encoded in the plist inspired map of key, value-pairs.

Specified by:

restoreTraits in class IBSPopulation

Parameters:

plist - the map of key, value-pairs

Returns:

true if successful

See Also:

• Model.restoreState(Plist)