egttools.games.AbstractGame

class AbstractGame(self: egttools.numerical.numerical_.games.AbstractGame)

Bases: pybind11_object

Base class for all game-theoretic models in EGTtools.

This abstract class defines the required interface for any game to be used in evolutionary dynamics models. All concrete games must inherit from this class and implement its methods.

Methods

calculate_fitness	Computes the fitness of a given strategy in a population.
calculate_payoffs	Calculates and stores all payoffs internally for all possible group compositions.
nb_strategies	Returns the number of strategies available in the game.
payoff	Returns the expected payoff of a specific strategy in a group.
payoffs	Returns the current payoff matrix of the game.
play	Computes the payoff of each strategy for a given group composition.
save_payoffs	Saves the current payoff matrix to a file.
type	Returns the type of the game as a string.

__init__(self: egttools.numerical.numerical_.games.AbstractGame) → None

__new__(**kwargs)

__str__(self: egttools.numerical.numerical_.games.AbstractGame) → str

Returns a string representation of the game object.

Returns:

A string describing the game instance.

Return type:

str

calculate_fitness(self: egttools.numerical.numerical_.games.AbstractGame, strategy_index: int, pop_size: int, strategies: numpy.ndarray[numpy.uint64[m, 1]]) → float

Computes the fitness of a given strategy in a population.

Parameters:

• strategy_index (int) – The index of the strategy whose fitness is being computed.

• pop_size (int) – Total population size.

• strategies (NDArray[np.int64]) – Vector representing the number of individuals using each strategy.

Returns:

The computed fitness of the specified strategy.

Return type:

float

calculate_payoffs(self: egttools.numerical.numerical_.games.AbstractGame) → numpy.ndarray[numpy.float64[m, n]]

Calculates and stores all payoffs internally for all possible group compositions.

This method must be called before computing fitness values or using the game in simulations.

nb_strategies(self: egttools.numerical.numerical_.games.AbstractGame) → int

Returns the number of strategies available in the game.

Returns:

The total number of strategies.

Return type:

int

payoff(self: egttools.numerical.numerical_.games.AbstractGame, strategy: int, group_composition: list[int]) → float

Returns the expected payoff of a specific strategy in a group.

Parameters:

• strategy (int) – Index of the focal strategy.

• group_composition (NDArray[np.int64]) – Vector specifying the number of individuals using each strategy.

Returns:

Expected payoff of the strategy in the given group context.

Return type:

float

payoffs(self: egttools.numerical.numerical_.games.AbstractGame) → numpy.ndarray[numpy.float64[m, n]]

Returns the current payoff matrix of the game.

Returns:

The stored payoff matrix used in the game.

Return type:

NDArray[np.float64]

play(self: egttools.numerical.numerical_.games.AbstractGame, group_composition: list[int], game_payoffs: list[float]) → None

Computes the payoff of each strategy for a given group composition.

This method modifies game_payoffs in-place to store the payoff of each strategy, given a group composed of the specified number of individuals per strategy.

This avoids memory reallocation by reusing the existing array, which can significantly speed up simulations.

Parameters:

• group_composition (NDArray[np.int64]) – A vector of shape (n_strategies,) indicating the number of individuals playing each strategy in the group.

• game_payoffs (NDArray[np.float64]) – A pre-allocated vector of shape (n_strategies,) which will be updated with the payoffs of each strategy in the group. Modified in-place.

Returns:

This function modifies game_payoffs directly.

Return type:

None

Examples

>>> group = np.array([1, 2, 0])
>>> out = np.zeros_like(group, dtype=np.float64)
>>> game.play(group, out)
>>> print(out)  # Contains payoffs for each strategy in the group

save_payoffs(self: egttools.numerical.numerical_.games.AbstractGame, file_name: str) → None

Saves the current payoff matrix to a file.

Parameters:

file_name (str) – Name of the file to which the matrix should be saved.

type(self: egttools.numerical.numerical_.games.AbstractGame) → str

Returns the type of the game as a string.

Returns:

A label identifying the game type (e.g., “NormalFormGame”).

Return type:

str

__annotations__ = {}