Simulator

This module defines the Simulator class, which provides numerical tools to simulate the interplay between population games, payoff mechanisms, and revision processes.

The simulator tracks the evolution of strategic distributions and payoffs over time. It supports both finite-agent simulations and numerical integration of deterministic dynamics models.

—

Simulator

class popgames.simulator.Simulator(population_game, payoff_mechanism, revision_processes, num_agents)

Bases: object

Simulates the interplay between the three core objects: i) A population game, ii) A payoff mechanism, and iii) a list of revision processes (one per population).

Initialize the simulator object.

Parameters:

• population_game (PopulationGame) – The population game object.

• payoff_mechanism (PayoffMechanism) – The payoff mechanism object.

• revision_processes (Union[RevisionProcessABC, list[RevisionProcessABC]]) – A single revision process for the single-population case, or a list of revision processes for the multi-population case, where each element corresponds to a specific population.

• num_agents (Union[int, list[int]]) – The number of agents as an integer for the single-population case, or a list of integers specifying the number of agents in each population for the multi-population case.

integrate_edm_pdm(t_span, x0, q0=None, t_eval=None, method='Radau', output_trajectory=True)

Numerically integrate the underlying EDM-PDM system.

This method relies on scipy.integrate.solve_ivp.

Parameters:

• t_span (tuple) – The time span of the integration.

• x0 (np.ndarray) – The initial strategic distribution of the society.

• q0 (np.ndarray) – The initial state of the PDM. Defaults to None.

• t_eval (list) – The times at which to evaluate the integration. Defaults to None.

• method (str) – The integration method. Defaults to ‘Radau’.

• output_trajectory (bool) – Whether to output the trajectory or just the final state-output pair. Defaults to True.

Returns:

The integration results as a SimpleNamespace object.

Return type:

SimpleNamespace

plot_distance_to_gne()

Plot the Euclidean distance to a generalized Nash equilibrium (GNE) of the underlying game.

Return type:

None

plot_pdm_trajectory(fontsize=8, figsize=(4, 2), filename=None, plot_edm_related_trajectory=False)

Plot the PDM trajectory over time.

Parameters:

• fontsize (int) – Fontsize. Defaults to 8.

• figsize (tuple[int, int]) – Figure size. Defaults to (4,2)

• filename (str, optional) – Filename to save the figure. Defaults to None.

• plot_edm_related_trajectory (bool) – Whether to plot edm trajectory or not. Defaults to False.

Return type:

None

reset(x0=None, q0=None)

Resets the simulator.

Parameters:

• x0 (np.ndarray, Optional) – The initial state for the strategic distribution of the society. Defaults to None.

• q0 (np.ndarray, Optional) – The initial state for the payoff mechanism’s PDM. Defaults to None.

Return type:

None

run(T_sim, verbose=True)

Run the simulation.

Parameters:

• T_sim (int) – The total time to simulate (in units specified by the agents’ alarm clocks).

• verbose (bool) – Whether to print simulation information. Defaults to True.

Returns:

The simulation results as a SimpleNamespace object.

Return type:

SimpleNamespace

ternary_plot(scale=30, fontsize=8, figsize=(4, 3), filename=None, plot_edm_trajectory=False, potential_function=None)

Make a ternary plot for the simulated scenario.

This method is only supported for single-population games with n=3.

Parameters:

• scale (int) – Scaling factor for the ternary plot. Defaults to 30.

• fontsize (int) – Fontsize for the plot. Defaults to 8.

• figsize (tuple[int, int]) – Figure size. Defaults to (4, 3).

• filename (str, optional) – Filename to save the figure. Defaults to None.

• plot_edm_trajectory (bool) – Whether to plot edm trajectory or not. Defaults to False.

• potential_function (Callable[[np.ndarray], np.ndarray]) – Potential function to plot as a heatmap. Defaults to None.

Return type:

None