egttools.numerical.PairwiseComparisonNumerical¶

class PairwiseComparisonNumerical(self: egttools.numerical.numerical.PairwiseComparisonNumerical, pop_size: int, game: egttools.numerical.numerical.games.AbstractGame, cache_size: int)¶

Bases: pybind11_object

A class containing methods to study numerically the evolutionary dynamics using the Pairwise comparison rule.

This class defines methods to estimate numerically fixation probabilities, stationary distributions with or without mutation, and strategy distributions.

Parameters

population_size (int) – Size of the population.
game (egttools.games.AbstractGame) – A game object which must implement the abstract class egttools.games.AbstractGame. This game will contain the expected payoffs for each strategy in the game, or at least a method to compute it, and a method to calculate the fitness of each strategy for a given population state.
cache_size (int) – The maximum size of the cache.

Note

Numerical computations are not exact. Moreover, for now we still did not implement a method to automatically detect if the precision of the estimation of the stationary and strategy distributions are good enough and, thus, stop the simulation. You are advised to test different nb_generations and transitory periods for your specific problem (game).

If you want to have exact calculations, you can use egttools.analytical.PairwiseComparison. However, this is only advisable for systems with a smaller number of states (i.e., not too big population size or number of strategies). Otherwise, the calculations might require too much memory.

Methods

`estimate_fixation_probability`	Estimates the fixation probability of an invading strategy in a population o resident strategy.
`estimate_stationary_distribution`	Estimates the stationary distribution of the population of strategies given the game.
`estimate_stationary_distribution_sparse`	Estimates the stationary distribution of the population of strategies given the game.
`estimate_strategy_distribution`	Estimates the distribution of strategies in the population given the current game.
`evolve`	Runs the moran process for a given number of generations.
`run`	Runs the evolutionary process and returns a matrix with all the states the system went through.

Attributes

`cache_size`	Maximum memory which can be used to cache the fitness calculations.
`nb_states`	number of possible population states
`nb_strategies`	Number of strategies in the population.
`payoffs`	Payoff matrix containing the payoff of each strategy (row) for each game state (column)
`pop_size`	Size of the population.

__init__(self: egttools.numerical.numerical.PairwiseComparisonNumerical, pop_size: int, game: egttools.numerical.numerical.games.AbstractGame, cache_size: int) → None¶

A class containing methods to study numerically the evolutionary dynamics using the Pairwise comparison rule.

This class defines methods to estimate numerically fixation probabilities, stationary distributions with or without mutation, and strategy distributions.

Parameters

population_size (int) – Size of the population.
game (egttools.games.AbstractGame) – A game object which must implement the abstract class egttools.games.AbstractGame. This game will contain the expected payoffs for each strategy in the game, or at least a method to compute it, and a method to calculate the fitness of each strategy for a given population state.
cache_size (int) – The maximum size of the cache.

Note

Numerical computations are not exact. Moreover, for now we still did not implement a method to automatically detect if the precision of the estimation of the stationary and strategy distributions are good enough and, thus, stop the simulation. You are advised to test different nb_generations and transitory periods for your specific problem (game).

If you want to have exact calculations, you can use egttools.analytical.PairwiseComparison. However, this is only advisable for systems with a smaller number of states (i.e., not too big population size or number of strategies). Otherwise, the calculations might require too much memory.

__new__(**kwargs)¶

estimate_fixation_probability(self: egttools.numerical.numerical.PairwiseComparisonNumerical, index_invading_strategy: int, index_resident_strategy: int, nb_runs: int, nb_generations: int, beta: float) → float¶

Estimates the fixation probability of an invading strategy in a population o resident strategy.

This method estimates the fixation probability of one mutant of the invading strategy in a population where all other individuals adopt the resident strategy.

The :param nb_runs is very important, since simulations are stopped once a monomorphic state is reached (all individuals adopt the same strategy). The more runs you specify, the better the estimation. You should consider specifying at least a 1000 runs.

Parameters

index_invading_strategy (int) – Index of the invading strategy.
index_resident_strategy (int) – Index of the resident strategy.
nb_runs (int) – Number of independent runs. This parameter is very important, since simulations are stopped once a monomorphic state is reached (all individuals adopt the same strategy). The more runs you specify, the better the estimation. You should consider specifying at least a 1000 runs.
nb_generations (int) – Maximum number of generations for a single run.
beta (float) – Intensity of selection.

Returns

A matrix containing all the states the system when through, including also the initial state. The shape of the matrix is (nb_generations - transient, nb_strategies).

Return type

numpy.ndarray

estimate_stationary_distribution(self: egttools.numerical.numerical.PairwiseComparisonNumerical, nb_runs: int, nb_generations: int, transitory: int, beta: float, mu: float) → numpy.ndarray[numpy.float64[m, 1]]¶

Estimates the stationary distribution of the population of strategies given the game.

This method directly estimates how frequent each strategy is in the population, without calculating the stationary distribution as an intermediary step. You should use this method when the number of states of the system is bigger than MAX_LONG_INT, since it would not be possible to index the states in this case, and estimate_stationary_distribution and estimate_stationary_distribution_sparse would run into an overflow error.

Parameters

nb_runs (int) – Number of independent simulations to perform. The final result will be an average over all the runs.
nb_generations (int) – Total number of generations.
transitory (int) – Transitory period. These generations will be excluded from the final average. Thus, only the last nb_generations - transitory generations will be taken into account. This is important, since in order to obtain a correct average at the steady state, we need to skip the transitory period.
beta (float) – Intensity of selection. This parameter determines how important the difference in payoff between players is for the probability of imitation. If beta is small, the system will mostly undergo random drift between strategies. If beta is high, a slight difference in payoff will make a strategy disapear.
mu (float) – Probability of mutation. This parameter defines how likely it is for a mutation event to occur at a given generation

Returns

The average frequency of each strategy in the population stored in a sparse array.

Return type

scipy.sparse.csr_matrix

estimate_stationary_distribution_sparse(self: egttools.numerical.numerical.PairwiseComparisonNumerical, nb_runs: int, nb_generations: int, transitory: int, beta: float, mu: float) → scipy.sparse.csr_matrix[numpy.float64]¶

Estimates the stationary distribution of the population of strategies given the game.

This method directly estimates how frequent each strategy is in the population, without calculating the stationary distribution as an intermediary step. You should use this method when the number of states of the system is bigger than MAX_LONG_INT, since it would not be possible to index the states in this case, and estimate_stationary_distribution and estimate_stationary_distribution_sparse would run into an overflow error.

Parameters

nb_runs (int) – Number of independent simulations to perform. The final result will be an average over all the runs.
nb_generations (int) – Total number of generations.
transitory (int) – Transitory period. These generations will be excluded from the final average. Thus, only the last nb_generations - transitory generations will be taken into account. This is important, since in order to obtain a correct average at the steady state, we need to skip the transitory period.
beta (float) – Intensity of selection. This parameter determines how important the difference in payoff between players is for the probability of imitation. If beta is small, the system will mostly undergo random drift between strategies. If beta is high, a slight difference in payoff will make a strategy disapear.
mu (float) – Probability of mutation. This parameter defines how likely it is for a mutation event to occur at a given generation

Returns

scipy.sparse.csr_matrix
The average frequency of each strategy in the population stored in a sparse array.

estimate_strategy_distribution(self: egttools.numerical.numerical.PairwiseComparisonNumerical, nb_runs: int, nb_generations: int, transitory: int, beta: float, mu: float) → numpy.ndarray[numpy.float64[m, 1]]¶

Estimates the distribution of strategies in the population given the current game.

This method directly estimates how frequent each strategy is in the population, without calculating the stationary distribution as an intermediary step. You should use this method when the number of states of the system is bigger than MAX_LONG_INT, since it would not be possible to index the states in this case, and estimate_stationary_distribution and estimate_stationary_distribution_sparse would run into an overflow error.

Parameters

nb_runs (int) – Number of independent simulations to perform. The final result will be an average over all the runs.
nb_generations (int) – Total number of generations.
transitory (int) – Transitory period. These generations will be excluded from the final average. Thus, only the last nb_generations - transitory generations will be taken into account. This is important, since in order to obtain a correct average at the steady state, we need to skip the transitory period.
beta (float) – Intensity of selection. This parameter determines how important the difference in payoff between players is for the probability of imitation. If beta is small, the system will mostly undergo random drift between strategies. If beta is high, a slight difference in payoff will make a strategy disapear.
mu (float) – Probability of mutation. This parameter defines how likely it is for a mutation event to occur at a given generation

Returns

The average frequency of each strategy in the population.

Return type

numpy.ndarray[numpy.float64[m, 1]]

evolve(self: egttools.numerical.numerical.PairwiseComparisonNumerical, nb_generations: int, beta: float, mu: float, init_state: numpy.ndarray[numpy.uint64[m, 1]]) → numpy.ndarray[numpy.uint64[m, 1]]¶

Runs the moran process for a given number of generations.

Parameters

nb_generations (int) – Maximum number of generations.
beta (float) – Intensity of selection.
mu (float) – Mutation rate.
init_state (numpy.ndarray) – Initial state of the population. This must be a vector of integers of shape (nb_strategies,), containing the counts of each strategy in the population. It serves as the initial state from which the evolutionary process will start.

Returns

A vector of integers containing the final state reached during the evolutionary process.

Return type

numpy.ndarray

run()¶

Runs the evolutionary process and returns a matrix with all the states the system went through.

Parameters

nb_generations (int) – Maximum number of generations.
beta (float) – Intensity of selection.
init_state (numpy.ndarray) – Initial state of the population. This must be a vector of integers of shape (nb_strategies,), containing the counts of each strategy in the population. It serves as the initial state from which the evolutionary process will start.

Returns

A matrix containing all the states the system when through, including also the initial state. The shape of the matrix is (nb_generations + 1, nb_strategies).

Return type

numpy.ndarray

Runs the evolutionary process and returns a matrix with all the states the system went through.

Mutation events will happen with rate :param mu, and the transient states will not be returned.

Parameters

nb_generations (int) – Maximum number of generations.
transient (int) – Transient period. Amount of generations that should not be skipped in the return vector.
beta (float) – Intensity of selection.
mu (float) – Mutation rate.
init_state (numpy.ndarray) – Initial state of the population. This must be a vector of integers of shape (nb_strategies,), containing the counts of each strategy in the population. It serves as the initial state from which the evolutionary process will start.

Returns

A matrix containing all the states the system when through, including also the initial state. The shape of the matrix is (nb_generations - transient, nb_strategies).

Return type

numpy.ndarray

Runs the evolutionary process and returns a matrix with all the states the system went through.

Mutation events will happen with rate :param mu.

Parameters

nb_generations (int) – Maximum number of generations.
beta (float) – Intensity of selection.
mu (float) – Mutation rate.
init_state (numpy.ndarray) – Initial state of the population. This must be a vector of integers of shape (nb_strategies,), containing the counts of each strategy in the population. It serves as the initial state from which the evolutionary process will start.

Returns

A matrix containing all the states the system when through, including also the initial state. The shape of the matrix is (nb_generations - transient, nb_strategies).

Return type

numpy.ndarray

property cache_size¶: Maximum memory which can be used to cache the fitness calculations.

property nb_states¶: number of possible population states

property nb_strategies¶: Number of strategies in the population.

property payoffs¶: Payoff matrix containing the payoff of each strategy (row) for each game state (column)

property pop_size¶: Size of the population.