egttools.analytical.PairwiseComparison

class PairwiseComparison

Bases: pybind11_object

Analytical pairwise comparison model.

This class computes fixation probabilities, gradients of selection, and transition matrices for finite populations using the pairwise comparison rule. Results are exact, and rely on symbolic or deterministic calculation of fitness and payoffs.

Parameters:

  • population_size (int) – Size of the population.

  • game (egttools.games.AbstractGame) – Game object that implements AbstractGame. Provides payoffs and fitness calculations.

See also

egttools.numerical.PairwiseComparisonNumerical, egttools.analytical.StochDynamics

Examples

>>> from egttools.games import Matrix2PlayerGameHolder
>>> from egttools import PairwiseComparison
>>> game = Matrix2PlayerGameHolder(3, np.random.rand(3, 3))
>>> model = PairwiseComparison(100, game)

Analytical pairwise comparison model with configurable cache.

Extends the base constructor with a specified cache size, which accelerates repeated payoff/fitness evaluations in large simulations.

Parameters:

  • population_size (int) – Size of the population.

  • game (egttools.games.AbstractGame) – Game object that implements AbstractGame. Provides payoffs and fitness calculations.

  • cache_size (int) – Maximum number of evaluations to cache.

See also

egttools.numerical.PairwiseComparisonNumerical, egttools.analytical.StochDynamics

Note

Avoid using this model for large state spaces due to memory and performance limitations.

Methods

calculate_fixation_probability

Computes the fixation probability of one mutant in a monomorphic population.

calculate_gradient_of_selection

Computes the deterministic gradient of selection at a specific state.

calculate_transition_and_fixation_matrix_sml

Returns transition and fixation matrices assuming small mutation limit (SML).

calculate_transition_matrix

Computes the full transition matrix under mutation.

game

nb_states

nb_strategies

population_size

pre_calculate_edge_fitnesses

Precompute fitnesses at the edges of the simplex.

update_population_size

__init__()

Analytical pairwise comparison model.

This class computes fixation probabilities, gradients of selection, and transition matrices for finite populations using the pairwise comparison rule. Results are exact, and rely on symbolic or deterministic calculation of fitness and payoffs.

Parameters:

  • population_size (int) – Size of the population.

  • game (egttools.games.AbstractGame) – Game object that implements AbstractGame. Provides payoffs and fitness calculations.

See also

egttools.numerical.PairwiseComparisonNumerical, egttools.analytical.StochDynamics

Examples

>>> from egttools.games import Matrix2PlayerGameHolder
>>> from egttools import PairwiseComparison
>>> game = Matrix2PlayerGameHolder(3, np.random.rand(3, 3))
>>> model = PairwiseComparison(100, game)

Analytical pairwise comparison model with configurable cache.

Extends the base constructor with a specified cache size, which accelerates repeated payoff/fitness evaluations in large simulations.

Parameters:

  • population_size (int) – Size of the population.

  • game (egttools.games.AbstractGame) – Game object that implements AbstractGame. Provides payoffs and fitness calculations.

  • cache_size (int) – Maximum number of evaluations to cache.

See also

egttools.numerical.PairwiseComparisonNumerical, egttools.analytical.StochDynamics

Note

Avoid using this model for large state spaces due to memory and performance limitations.

__new__(**kwargs)
calculate_fixation_probability()

Computes the fixation probability of one mutant in a monomorphic population.

Parameters:

  • invading_strategy_index (int) – Index of the mutant strategy.

  • resident_strategy_index (int) – Index of the resident strategy.

  • beta (float) – Intensity of selection.

Returns:

Fixation probability of the mutant strategy.

Return type:

float

Example

>>> model.calculate_fixation_probability(1, 0, 0.1)
calculate_gradient_of_selection()

Computes the deterministic gradient of selection at a specific state.

Parameters:

  • beta (float) – Intensity of selection.

  • state (NDArray[np.int64]) – Population state as a count vector of shape (nb_strategies,).

Returns:

Gradient vector of shape (nb_strategies,).

Return type:

NDArray[np.float64]

Example

>>> model.calculate_gradient_of_selection(beta=0.5, state=np.array([50, 25, 25]))
calculate_transition_and_fixation_matrix_sml()

Returns transition and fixation matrices assuming small mutation limit (SML).

By assuming the limit of small mutations (SML), we can reduce the number of states of the dynamical system to those which are monomorphic, i.e., the whole population adopts the same strategy.

Thus, the dimensions of the transition matrix in the SML is (nb_strategies, nb_strategies), and the transitions are given by the normalized fixation probabilities. This means that a transition where i neq j, T[i, j] = fixation(i, j) / (nb_strategies - 1) and T[i, i] = 1 - sum{T[i, j]}.

This method will also return the matrix of fixation probabilities, where fixation_probabilities[i, j] gives the probability that one mutant j fixates in a population of i.

Parameters:

beta (float) – Selection strength.

Returns:

Tuple with transition matrix and fixation probabilities matrix.

Return type:

Tuple[NDArray[np.float64], NDArray[np.float64]]

calculate_transition_matrix()

Computes the full transition matrix under mutation.

Parameters:

  • beta (float) – Intensity of selection.

  • mu (float) – Mutation probability.

Returns:

Sparse matrix of shape (nb_states, nb_states) representing transition probabilities.

Return type:

scipy.sparse.csr_matrix

game()
nb_states()
nb_strategies()
population_size()
pre_calculate_edge_fitnesses()

Precompute fitnesses at the edges of the simplex.

This optimization step helps accelerate calculations when simulating dynamics repeatedly over boundary conditions.

update_population_size()
__annotations__ = {}