egttools.games.abstract_games.AbstractNPlayerGameExpectedPayoff

class AbstractNPlayerGameExpectedPayoff(self: egttools.numerical.numerical_.games.AbstractNPlayerGame, nb_strategies: int, group_size: int)

Bases: AbstractNPlayerGame

This abstract Game class can be used in most scenarios where the fitness of a strategy is calculated as its expected payoff given the population state.

It assumes that the game is N player, since the fitness of a strategy given a population state is calculated as the expected payoff of that strategy over all possible group combinations in the given state.

Notes

It might be a good idea to overwrite the methods __str__, type, and save_payoffs to adapt to your given game implementation

It assumes that you have at least the following attributes:

1. And an attribute self.nb_strategies_ which contains the number of strategies that you are going to analyze for the given game. 2. self.payoffs() returns a numpy.ndarray and contain the payoff matrix of the game. This array is of shape (self.nb_strategies(), self.nb_group_configurations()), where self.nb_group_configurations() is the number of possible combinations of strategies in the group. Thus, each row should give the (expected) payoff of the row strategy when playing in a group with the column configuration. The payoff method provides an easy way to access the payoffs for any group composition, by taking as arguments the index of the row strategy and a List with the count of each possible strategy in the group.

You must still implement the methods play which should define how the game assigns payoffs to each strategy for a given game context. In particular, calculate_payoffs should fill the array self.payoffs_ with the correct values as explained above. We recommend that you run this method in the __init__ (initialization of the object) since, these values must be set before passing the game object to the numerical simulator (e.g., egttools.numerical.PairwiseComparisonNumerical).

Abstract N-Player Game.

This abstract base class represents a symmetric N-player game in which each strategy’s fitness is computed as the expected payoff over all group compositions in a population.

Notes

Subclasses must implement the play and calculate_payoffs methods. The following attributes are expected: - self.nb_strategies_ (int): number of strategies. - self.payoffs_ (numpy.ndarray): of shape (nb_strategies, nb_group_configurations).

Parameters:

• nb_strategies (int) – Total number of strategies in the game.

• group_size (int) – Size of the interacting group.

Methods

calculate_fitness	Computes the fitness of a given strategy in a population state.
calculate_payoffs	This method calculates the payoffs for each strategy in each possible group configuration.
group_size	Returns the size of the group.
nb_group_configurations	Returns the number of distinct group configurations.
nb_strategies	Returns the number of strategies in the game.
payoff	Returns the payoff of a strategy in a given group context.
payoffs	Returns the payoff matrix.
play	This method fills the game_payoffs container with the payoff of each strategy given the group_composition.
save_payoffs	Saves the payoff matrix to a text file.
type	Returns the string identifier for the game.
update_payoff	Updates an entry in the payoff matrix.

__init__(self: egttools.numerical.numerical_.games.AbstractNPlayerGame, nb_strategies: int, group_size: int) → None

Abstract N-Player Game.

This abstract base class represents a symmetric N-player game in which each strategy’s fitness is computed as the expected payoff over all group compositions in a population.

Notes

Subclasses must implement the play and calculate_payoffs methods. The following attributes are expected: - self.nb_strategies_ (int): number of strategies. - self.payoffs_ (numpy.ndarray): of shape (nb_strategies, nb_group_configurations).

Parameters:

• nb_strategies (int) – Total number of strategies in the game.

• group_size (int) – Size of the interacting group.

__new__(**kwargs)

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

Returns a string representation of the game.

Return type:

str

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

Computes the fitness of a given strategy in a population state.

Parameters:

• strategy_index (int) – The strategy of the focal player.

• pop_size (int) – Total population size (excluding the focal player).

• strategies (numpy.ndarray[uint64]) – The population state as a strategy count vector.

Returns:

Fitness of the focal strategy in the given state.

Return type:

float

calculate_payoffs()

This method calculates the payoffs for each strategy in each possible group configuration. Thus, it must fill the self.payoffs_ numpy.ndarray with these payoffs values. This array must be of shape (self.nb_strategies_, nb_group_configurations), where nb_group_configurations is the number of possible combinations of strategies in the group. Thus, each row should give the (expected) payoff of the row strategy when playing in a group with the column configuration.

Returns:

The payoff matrix of the game.

Return type:

numpy.ndarray

group_size(self: egttools.numerical.numerical_.games.AbstractNPlayerGame) → int

Returns the size of the group.

Return type:

int

nb_group_configurations(self: egttools.numerical.numerical_.games.AbstractNPlayerGame) → int

Returns the number of distinct group configurations.

Return type:

int

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

Returns the number of strategies in the game.

Return type:

int

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

Returns the payoff of a strategy in a given group context.

Parameters:

• strategy (int) – The strategy index.

• group_composition (list[int] or numpy.ndarray[int]) – The group configuration.

Returns:

The corresponding payoff.

Return type:

float

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

Returns the payoff matrix.

Returns:

The matrix of shape (nb_strategies, nb_group_configurations).

Return type:

numpy.ndarray

abstract play(group_composition, game_payoffs)

This method fills the game_payoffs container with the payoff of each strategy given the group_composition.

Strategies not present in the group will receive 0 payoff by default.

Parameters:

• group_composition (Union[List[int], numpy.ndarray]) – A List or a numpy.ndarray containing the counts of each strategy in the group (e.g., for a game with 3 possible strategies and group size 4, the following List is possible [3, 0, 1]).

• game_payoffs (numpy.ndarray) – A container for the payoffs that will be calculated. This avoids needing to create a new array at each call and should speed up computation.

Return type:

None

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

Saves the payoff matrix to a text file.

Parameters:

file_name (str) – Destination file path.

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

Returns the string identifier for the game.

Return type:

str

update_payoff(self: egttools.numerical.numerical_.games.AbstractNPlayerGame, strategy_index: int, group_configuration_index: int, value: float) → None

Updates an entry in the payoff matrix.

Parameters:

• strategy_index (int) – Index of the strategy (row).

• group_configuration_index (int) – Index of the group composition (column).

• value (float | numpy.float64) – The new payoff value.

__annotations__ = {}