Prisoner’s Dilemma

This example models a population of agents repeatedly choosing between two strategies: cooperate or defect, as in the classic Prisoner’s Dilemma game.

It demonstrates how revision dynamics can drive the population toward defection, even when mutual cooperation would be socially optimal.

import numpy as np
import matplotlib.pyplot as plt
from popgames import (
    SinglePopulationGame,
    PayoffMechanism,
    PoissonRevisionProcess,
    Simulator,
)
from popgames.revision_protocol import Softmax

T, R, P, S = 3.0, 2.0, 1.0, 0.0 # Prisoner's dilemma parameters
                                # s.t. T > R > P > S
                                # https://en.wikipedia.org/wiki/Prisoner%27s_dilemma
                                # (floats, so that the example also runs with the numba backend)
def fitness_function(x):
    return np.dot(
        np.array([[R, S], [T, P]]),
        x
    )

population_game = SinglePopulationGame(
    num_strategies=2,
    fitness_function=fitness_function,
)

payoff_mechanism = PayoffMechanism(
    h_map=fitness_function,
    n=2,
)

revision_process = PoissonRevisionProcess(
    Poisson_clock_rate=1,
    revision_protocol=Softmax(0.1),
)

sim = Simulator(
    population_game=population_game,
    payoff_mechanism=payoff_mechanism,
    revision_processes=revision_process,
    num_agents=1000
)

x0 = np.array([0.5, 0.5]).reshape(2, 1)
sim.reset(x0=x0)
out = sim.run(T_sim=30)

plt.figure(figsize=(3, 3))
plt.plot(out.t, out.x[0, :], label='Cooperators')
plt.plot(out.t, out.x[1, :], label='Defectors')
plt.xlabel('Time')
plt.ylabel('Portion of agents choosing each strategy')
plt.legend()
plt.grid()
plt.tight_layout()
plt.show()

Running with the Numba backend

The same simulation can run with the optional Numba backend (requires pip install "popgames[numba]"). Only the simulator changes:

sim = Simulator(
    population_game=population_game,
    payoff_mechanism=payoff_mechanism,
    revision_processes=revision_process,
    num_agents=1000,
    backend="numba",
)

The fitness function is compiled automatically with numba.njit. This is why the payoff parameters are declared as floats (T, R, P, S = 3.0, 2.0, 1.0, 0.0): with integers, np.array([[R, S], [T, P]]) would be an integer matrix, and Numba does not support matrix products between integer and floating-point arrays. With the numpy backend, both versions work. If the fitness function cannot be compiled, the simulator logs a warning and falls back to the numpy backend.

With 1000 agents over 30 time units (about 30 000 revision events), this simulation is too small for the Numba backend to pay off: compiling the fitness function takes longer than the whole simulation with the numpy backend. The Numba backend is worth it for large populations or long horizons, e.g., num_agents=100_000.