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.

The simulator is equipped with a VisualizationMixin implementing useful visualization tools.

—

Simulator

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

Bases: VisualizationMixin

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(*, plot_type='kpi', filename=None, figsize=None, fontsize=None, show=True, **kwargs)

Unified plotting interface supporting some predefined plot types.

Plot the results of the last simulation.

Parameters:

• plot_type (str) – Plot type. Defaults to ‘x(t)’.

• filename (str, optional) – If not None the figure is saved with that filename. Defaults to None.

• figsize (tuple[int, int], optional) – Matplotlib’s figsize. Defaults to (3, 3).

• fontsize (int, optional) – Matplotlib’s fontsize. Defaults to 10.

• show (bool, optional) – Whether to show the figure. Defaults to True.

• **kwargs – Additional keyword arguments to bypass to the selected plot_type. Warning: unrecognized arguments are silently ignored.

• self (Simulator)

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=False)

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 False.

Returns:

The simulation results as a SimpleNamespace object.

Return type:

SimpleNamespace

—

Visualization Mixin

class popgames.plotting.visualization_mixin.VisualizationMixin

Bases: object

Visualization mixin to add plotting functionality to the Simulator class.

This class is expected to be mixed into the Simulator class. It is defined in a separate module to keep simulator.py clean.

plot(*, plot_type='kpi', filename=None, figsize=None, fontsize=None, show=True, **kwargs)

Unified plotting interface supporting some predefined plot types.

Plot the results of the last simulation.

Parameters:

• plot_type (str) – Plot type. Defaults to ‘x(t)’.

• filename (str, optional) – If not None the figure is saved with that filename. Defaults to None.

• figsize (tuple[int, int], optional) – Matplotlib’s figsize. Defaults to (3, 3).

• fontsize (int, optional) – Matplotlib’s fontsize. Defaults to 10.

• show (bool, optional) – Whether to show the figure. Defaults to True.

• **kwargs – Additional keyword arguments to bypass to the selected plot_type. Warning: unrecognized arguments are silently ignored.

• self (Simulator)

Return type:

None

—

Supported Plots

popgames.plotting.plotters.make_ternary_plot_multi_population(simulator, scale=30, fontsize=8, figsize=(4, 3), plot_edm_trajectory=False, filename=None, show=True)

Plot the trajectory of a multiple population in multiple ternary plots.

This method requires every population to have n^k=3 strategies.

Parameters:

• simulator (Simulator) – Simulator instance holding the data for the plot.

• scale (int, optional) – Scaling factor for the heatmap. Defaults to 30.

• fontsize (int, optional) – Font size for the heatmap. Defaults to 8.

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

• plot_edm_trajectory (bool, optional) – Whether to plot edm trajectory. Defaults to False.

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

• show (bool, optional) – Whether to show the figure. Defaults to True.

Return type:

None

popgames.plotting.plotters.make_ternary_plot_single_population(simulator, potential_function=None, scale=30, fontsize=8, figsize=(4, 3), plot_edm_trajectory=False, filename=None, show=True)

Plot the trajectory of a single population in a ternary plot.

This method requires the population to have n=3 strategies.

Parameters:

• simulator (Simulator) – Simulator instance holding the data for the plot.

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

• scale (int, optional) – Scaling factor for the heatmap. Defaults to 30.

• fontsize (int, optional) – Font size for the heatmap. Defaults to 8.

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

• plot_edm_trajectory (bool, optional) – Whether to plot edm trajectory. Defaults to False.

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

• show (bool, optional) – Whether to show the figure. Defaults to True.

Return type:

None

popgames.plotting.plotters.plot_kpi_over_time(simulator, plot_deterministic_approximation=False, **kwargs)

Parameters:

• simulator (Simulator)

• plot_deterministic_approximation (bool)

• kwargs (dict[str, Any])

Return type:

None

popgames.plotting.plotters.plot_ternary_trajectories(simulator, plot_deterministic_approximation=False, scale=30, potential_function=None, **kwargs)

Make a ternary plot for the simulated scenario.

This method is only supported for single-population games with n=3, and for multi-population games where each population has n^k=3 strategies.

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.

• simulator (Simulator)

• plot_deterministic_approximation (bool)

• kwargs (dict[str, Any])

Return type:

None

popgames.plotting.plotters.plot_univariate_trajectories_joint(simulator, plot_deterministic_approximation=False, **kwargs)

This method generates 2(num_populations)+1 plots, one for each vector x, q, and p, against time, and for x and p the plots are generated per population.

Optionally: It also plots the trajectory of each element under the deterministic approximation of the evolutionary dynamics model.

Parameters:

• simulator (Simulator) – The simulator object holding the data to plot.

• plot_deterministic_approximation (bool, optional) – Whether to plot the related trajectories under the deterministic approximation. Defaults to False.

• **kwargs (dict[str, Any]) – Keyword arguments to specify plotting options.

Return type:

None

popgames.plotting.plotters.plot_univariate_trajectories_split(simulator, plot_deterministic_approximation=False, **kwargs)

This method generates several plots, one for each element of the vectors x, q, and p, against time.

Optionally: It also plots the trajectory of each element under the deterministic approximation of the evolutionary dynamics model.

Parameters:

• simulator (Simulator) – The simulator object holding the data to plot.

• plot_deterministic_approximation (bool, optional) – Whether to plot the related trajectories under the deterministic approximation. Defaults to False.

• **kwargs (dict[str, Any]) – Keyword arguments to specify plotting options.

Return type:

None