Plots#

1D Visualization Module#

This module provides visualization tools for analyzing and understanding the dynamics of agents and resource distributions in 1D domains for influencer games. It includes utilities for plotting agent positions, gradients, influence distributions, and bifurcation dynamics in 1D domains.

The module is designed to work with the InflGame.adaptive package and supports creating visual representations of agent behaviors and resource distributions in 1D environments.

Dependencies:#

matplotlib
NumPy
PyTorch
InflGame.utils
InflGame.domains

Usage:#

The functions in this module can be used to visualize agent dynamics and resource distributions in 1D domains. For example, the pos_plot_1d function can be used to plot agent positions over time, while the dist_and_pos_plot_1d function can visualize both agent positions and influence distributions.

Example:#

from InflGame.domains.one_d.one_plots import pos_plot_1d, equilibrium_bifurcation_plot_1d
import torch
import numpy as np

# Plot agent positions over time
fig = pos_plot_1d(
    num_agents=3,
    pos_matrix=torch.randn(100, 3),
    domain_bounds=(0, 1),
    title_ads=['Example Plot']
)
fig.show()

Functions

InflGame.domains.one_d.one_plots.create_gradient_vector_field_plot_clipped(vis, grid_resolution=20, figsize=(24, 12), max_magnitude=None, normalize_arrows=True)#

Create gradient vector field plot with clipped magnitudes for 1D domain visualization.

Deprecated since version This: function is kept as legacy code and should not be used in new development.

Generates a 2D vector field plot showing gradient directions and magnitudes at grid points in the projected 2D plane. Includes magnitude clipping for better visualization of large gradients and optional normalization to show pure direction information.

Following Influencer Games patterns:

Use torch tensor operations for autograd compatibility
Preserve original state using .clone()
Handle 1d domain type properly
Return matplotlib figure for visualization

Parameters:

vis (Shell) – Visualization Shell instance containing the field and parameters.
grid_resolution (int) – Number of grid points per dimension (default: 20).
figsize (tuple) – Figure size as (width, height) in inches (default: (24, 12)).
max_magnitude (Optional[float]) – Maximum gradient magnitude for clipping; if None, auto-clips at 95th percentile.
normalize_arrows (bool) – If True, normalize all arrows to same length for direction visualization.

Returns:

Tuple of (matplotlib figure, dictionary with computed data including positions, gradients, statistics).

Return type:

Tuple[matplotlib.figure.Figure, Dict]

InflGame.domains.one_d.one_plots.dist_and_pos_plot_1d(num_agents, bin_points, resource_distribution, pos_matrix, len_grad_matrix, infl_dist, cm, NUM_COLORS, title_ads, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14})#

Plot agent influence distributions and positions over time in a 1D domain.

Creates a side-by-side visualization with:

Left panel: Influence distributions for each agent overlaid with resource distribution
Right panel: Agent positions changing over gradient ascent iterations

This provides comprehensive insight into both the spatial influence patterns and the temporal evolution of agent positions.

Parameters:

num_agents (int) – Number of agents in the simulation.
bin_points (np.ndarray) – Discretized points defining resource allocation regions.
resource_distribution (np.ndarray) – Resource values at each bin point.
pos_matrix (torch.Tensor) – Matrix of agent positions over time (shape: [time_steps, num_agents]).
len_grad_matrix (int) – Number of time steps for x-axis scaling.
infl_dist (List[torch.Tensor]) – Influence distribution arrays for each agent.
cm (mpl.colors.Colormap) – Matplotlib colormap for agent colors.
NUM_COLORS (int) – Total number of colors in the colormap (typically num_agents + 1).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.

Returns:

The generated matplotlib figure.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.equilibrium_bifurcation_envelope_plot_1d(num_agents, bin_points, resource_distribution, infl_type, reach_parameters, extreme_positions, reach_start, reach_end, refinements, plot_type, title_ads, short_title=False, norm=True, infl_cshift=False, cmaps={'crit': 'Greys', 'envelope': '#FF6B6B', 'heat': 'Blues', 'trajectory': '#851321'}, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, cbar_config={'center_labels': True, 'label_alignment': 'center', 'shrink': 0.8}, axis_return=False, show_pred=False, optional_vline=None, envelope_alpha=0.3)#

Plot equilibrium bifurcation envelope showing extreme agent positions in a 1D domain.

Creates an envelope plot showing the maximum and minimum positions achieved by agents across different reach parameters, providing insight into the spread and stability of equilibria. The envelope reveals the range of positions agents explore as the influence parameter varies.

Parameters:

num_agents (int) – Number of agents in the simulation.
bin_points (np.ndarray) – Discretized points defining resource allocation regions.
resource_distribution (np.ndarray) – Resource values at each bin point.
infl_type (str) – Type of influence kernel (‘gaussian’, ‘beta’, ‘multi_gaussian’, etc.).
reach_parameters (List[float]) – Array of reach parameter values to test.
extreme_positions (Dict[str, torch.Tensor]) – Dictionary with ‘max’ and ‘min’ keys containing extreme position tensors.
reach_start (float) – Starting value of reach parameter range.
reach_end (float) – Ending value of reach parameter range.
refinements (int) – Number of refinements for critical value estimation.
plot_type (str) – Type of plot (‘line’, ‘envelope’, or ‘heat’).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
short_title (bool) – Use abbreviated title format.
norm (bool) – Normalize heatmap values.
infl_cshift (bool) – Whether influence uses center shift.
cmaps (dict) – Color map configuration dictionary with keys ‘heat’, ‘trajectory’, ‘crit’, ‘envelope’.
font (dict) – Font configuration dictionary.
cbar_config (dict) – Colorbar configuration dictionary.
axis_return (bool) – If True, return axes object; if False, return figure object.
show_pred (bool) – Show predicted critical values (only for Gaussian kernels).
optional_vline (Optional[List[float]]) – Optional vertical lines to add to plot.
envelope_alpha (float) – Transparency level for envelope fill (0-1).

Returns:

The generated matplotlib figure or axes object.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.equilibrium_bifurcation_envelope_plot_1d_COMPLETE(num_agents, bin_points, resource_distribution, infl_type, reach_parameters, matrix_list, reach_start, reach_end, refinements, plot_type, title_ads, short_title=False, norm=True, infl_cshift=False, cmaps={'crit': 'Greys', 'envelope': '#FF6B6B', 'heat': 'Blues', 'trajectory': '#851321'}, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, cbar_config={'center_labels': True, 'label_alignment': 'center', 'shrink': 0.8}, axis_return=False, show_pred=False, optional_vline=None, envelope_alpha=0.3)#

Plot complete equilibrium bifurcation envelope with multiple trajectory data in a 1D domain.

Advanced version that combines envelope data with multiple position matrices to create a comprehensive visualization showing both the envelope of extreme positions and detailed trajectory evolution. Includes density heatmap generation from multiple equilibrium searches.

Parameters:

num_agents (int) – Number of agents in the simulation.
bin_points (np.ndarray) – Discretized points defining resource allocation regions.
resource_distribution (np.ndarray) – Resource values at each bin point.
infl_type (str) – Type of influence kernel (‘gaussian’, ‘beta’, ‘multi_gaussian’, etc.).
reach_parameters (List[float]) – Array of reach parameter values to test.
matrix_list (Dict[str, torch.Tensor]) – Dictionary containing multiple position matrices and envelope data.
reach_start (float) – Starting value of reach parameter range.
reach_end (float) – Ending value of reach parameter range.
refinements (int) – Number of refinements for critical value estimation.
plot_type (str) – Type of plot (‘line’, ‘envelope’, or ‘heat’).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
short_title (bool) – Use abbreviated title format.
norm (bool) – Normalize heatmap values.
infl_cshift (bool) – Whether influence uses center shift.
cmaps (dict) – Color map configuration dictionary with keys ‘heat’, ‘trajectory’, ‘crit’, ‘envelope’.
font (dict) – Font configuration dictionary.
cbar_config (dict) – Colorbar configuration dictionary.
axis_return (bool) – If True, return axes object; if False, return figure object.
show_pred (bool) – Show predicted critical values (only for Gaussian kernels).
optional_vline (Optional[List[float]]) – Optional vertical lines to add to plot.
envelope_alpha (float) – Transparency level for envelope fill (0-1).

Returns:

The generated matplotlib figure or axes object.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.equilibrium_bifurcation_plot_1d(num_agents, bin_points, resource_distribution, infl_type, reach_parameters, final_pos_matrix, reach_start, reach_end, refinements, plot_type, title_ads, short_title=False, norm=True, infl_cshift=False, cmaps={'crit': 'Greys', 'heat': 'Blues', 'trajectory': '#851321'}, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, cbar_config={'center_labels': True, 'label_alignment': 'center', 'shrink': 0.8}, axis_return=False, show_pred=False, optional_vline=None)#

Plot equilibrium bifurcation diagram for agents in a 1D domain.

Visualizes how equilibrium positions change as a function of the reach parameter (e.g., variance \(\sigma\) for Gaussian influence kernels). As \(\sigma\) decreases, agents bifurcate from symmetric positions to asymmetric equilibria.

Each agent has a vector of final positions \(X_i = [x_1, x_2, \dots, x_A]\) where \(A\) is the number of test parameters and \(x_i\) is the equilibrium position at parameter value \(i\).

Parameters:

num_agents (int) – Number of agents in the simulation.
bin_points (np.ndarray) – Discretized points defining resource allocation regions.
resource_distribution (np.ndarray) – Resource values at each bin point.
infl_type (str) – Type of influence kernel (‘gaussian’, ‘beta’, ‘multi_gaussian’, etc.).
reach_parameters (List[float]) – Array of reach parameter values to test.
final_pos_matrix (np.ndarray) – Matrix of final equilibrium positions (shape: [num_params, num_agents]).
reach_start (float) – Starting value of reach parameter range.
reach_end (float) – Ending value of reach parameter range.
refinements (int) – Number of refinements for critical value estimation.
plot_type (str) – Type of plot (‘line’ or ‘heat’).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
short_title (bool) – Use abbreviated title format.
norm (bool) – Normalize heatmap values.
infl_cshift (bool) – Whether influence uses center shift.
cmaps (dict) – Color map configuration dictionary with keys ‘heat’, ‘trajectory’, ‘crit’.
font (dict) – Font configuration dictionary.
cbar_config (dict) – Colorbar configuration dictionary.
axis_return (bool) – If True, return axes object; if False, return figure object.
show_pred (bool) – Show predicted critical values (only for Gaussian kernels).
optional_vline (Optional[List[float]]) – Optional vertical lines to add to plot.

Returns:

The generated matplotlib figure or axes object.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.final_position_histogram_1d(num_agents, domain_bounds, current_alpha, reach_parameter, final_pos_vector, title_ads, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14})#

Plot histogram of agent final positions at equilibrium in a 1D domain.

Creates a histogram showing the distribution of agent equilibrium positions for a specific reach parameter and resource configuration. Useful for analyzing clustering patterns and position distributions at equilibrium.

Parameters:

num_agents (int) – Number of agents in the simulation.
domain_bounds (Tuple[float, float]) – Minimum and maximum bounds of the 1D domain.
current_alpha (float) – Current resource parameter value (e.g., mode separation \(\\alpha\)).
reach_parameter (float) – Influence reach parameter value (e.g., \(\\sigma\)).
final_pos_vector (np.ndarray) – Vector of final equilibrium positions for all agents.
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.

Returns:

The generated matplotlib figure.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.gradient_plot_1d(num_agents, grad_matrix, title_ads=[], font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14})#

Plot agent gradients over time in a 1D domain.

Creates a line plot showing how the gradient values for each agent change over gradient ascent iterations. Each agent’s gradient trajectory is plotted as a separate line.

Parameters:

num_agents (int) – Number of agents in the simulation.
grad_matrix (torch.Tensor) – Matrix of agent gradients over time (shape: [time_steps, num_agents]).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.

Returns:

The generated matplotlib figure.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.pos_plot_1d(num_agents, pos_matrix, domain_bounds, title_ads=[], font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, axis_return=False)#

Plot agent positions over time in a 1D domain.

Creates a line plot showing how agent positions change over gradient ascent iterations. Each agent’s trajectory is plotted as a separate line with a distinct color.

Parameters:

num_agents (int) – Number of agents in the simulation.
pos_matrix (torch.Tensor) – Matrix of agent positions over time (shape: [time_steps, num_agents]).
domain_bounds (Tuple[float, float]) – Minimum and maximum bounds of the 1D domain.
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.
axis_return (Optional[bool]) – If True, return axes object; if False, return figure object.

Returns:

The generated matplotlib figure or axes object.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.prob_plot_1d(num_agents, agents_pos, bin_points, domain_bounds, prob, voting_configs, title_ads, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14})#

Plot probability distribution of agent influence in a 1D domain.

Visualizes the probability that each agent influences each bin/resource point via their relative influence. The probability is computed as:

\[G_{i,k}(\mathbf{x},b_k) = \frac{f_i(x_i, b_k)}{\sum_{j=1}^N f_j(x_j, b_k)}\]

where \(f_i(x_i, b_k)\) is the influence of agent \(i\) at bin point \(b_k\).

Parameters:

num_agents (int) – Number of agents in the simulation.
agents_pos (List[float]) – Current positions of all agents.
bin_points (np.ndarray) – Discretized points defining resource allocation regions.
domain_bounds (List[float]) – Minimum and maximum bounds of the 1D domain.
prob (List[np.ndarray]) – Probability distributions for each agent (one array per agent).
voting_configs (Dict[str, bool]) – Configuration dictionary with keys ‘fixed_party’ and ‘abstain’ for voting behavior.
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.

Returns:

The generated matplotlib figure.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.three_agent_dynamics(pos_matrix, x_star, title_ads, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, axis_return=False)#

Visualize three-agent dynamics in 3D trajectory space.

Creates a 3D plot where each axis represents one agent’s position over time, demonstrating the instability and complex dynamics of three-player influencer games in 1D domains. Only applicable for exactly 3 agents with 1D strategy spaces.

Parameters:

pos_matrix (np.ndarray) – Matrix of agent positions over time (shape: [time_steps, 3]).
x_star (float) – Equilibrium or reference position (e.g., symmetric Nash equilibrium).
title_ads (List[str]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.
axis_return (Optional[bool]) – If True, return axes object; if False, return figure object.

Returns:

The generated matplotlib figure or axes object.

Return type:

matplotlib.figure.Figure

InflGame.domains.one_d.one_plots.vector_plot_1d(ids, gradient, title_ads, font={'cbar_size': 12, 'default_size': 12, 'font_family': 'sans-serif', 'legend_size': 12, 'title_size': 14}, **kwargs)#

Plot vector field of gradients for two agents in a 1D domain.

Creates a streamplot showing the gradient vector field for a two-agent system, where each axis represents one agent’s position. The vectors indicate the direction and magnitude of gradient ascent at each point in the position space.

Parameters:

ids (List[int]) – Agent IDs to include in the vector field (must be exactly 2 agents).
gradient (torch.Tensor) – Gradient matrix for the vector field (shape: [grid_points, 2]).
title_ads (Optional[List[str]]) – Additional strings to append to the plot title.
font (dict) – Font configuration dictionary with keys: ‘default_size’, ‘cbar_size’, ‘title_size’, ‘legend_size’, ‘font_family’.
**kwargs –
Additional keyword arguments passed to matplotlib streamplot function.

Returns:

The generated matplotlib figure.

Return type:

matplotlib.figure.Figure

Plots#

1D Visualization Module#

Dependencies:#

Usage:#

Example:#

This Page