Gaussian kernel#

Gaussian Influence Kernel Module#

This module implements the Gaussian influence kernel and its associated computations. The Gaussian kernel models the influence of agents based on a Gaussian distribution centered at their positions.

Mathematical Definitions:#

The Gaussian influence kernel is defined as:

\[f_i(x_i, b) = \exp\left(-\frac{(b - x_i)^2}{2\sigma_i^2}\right)\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(\sigma_i\) is the parameter for agent \(i\)

Usage:#

The influence function computes the influence of an agent at specific bin points,: while the d_ln_f function calculates the gradient of the logarithm of the Gaussian influence kernel.

The symmetric_nash_stability function computes the parameter needed for the symmetric Nash to be stable.

New vectorized functions are available for improved performance: - influence_vectorized : Compute influence for all agents simultaneously - d_ln_f_vectorized : Compute gradients for all agents simultaneously - symmetric_nash_stability_vectorized : Vectorized stability computation

Example:#

import numpy as np
import torch
from InflGame.kernels.gauss import influence, d_ln_f, symmetric_nash_stability
from InflGame.kernels.gauss import influence_vectorized, d_ln_f_vectorized

# Define parameters
num_agents = 3
parameter_instance = [0.5, 0.5, 0.5]
agents_pos = np.array([0.2, 0.5, 0.8])
bin_points = np.linspace(0, 1, 100)
resource_distribution = np.random.rand(100)

# Single agent computation (backward compatible)
influence_values = influence(agent_id=0, parameter_instance=parameter_instance, 
                            agents_pos=agents_pos, bin_points=bin_points)
print("Influence values:", influence_values)

# Vectorized computation (all agents at once)
all_influences = influence_vectorized(parameter_instance=parameter_instance, 
                                     agents_pos=agents_pos, bin_points=bin_points)
print("All influences shape:", all_influences.shape)  # (num_agents, num_bins)

# Single agent gradient
gradient = d_ln_f(agent_id=0, parameter_instance=parameter_instance, 
                 agents_pos=agents_pos, bin_points=bin_points)
print("Gradient values:", gradient)

# Vectorized gradients (all agents at once)
all_gradients = d_ln_f_vectorized(parameter_instance=parameter_instance,
                                 agents_pos=agents_pos, bin_points=bin_points)
print("All gradients shape:", all_gradients.shape)  # (num_agents, num_bins)

Functions

InflGame.kernels.gauss.d_ln_f(agent_id, parameter_instance, agents_pos, bin_points)#

Computes the gradient of the logarithm of the Gaussian influence kernel for a single agent.

This function provides backward compatibility while internally using optimized vectorized operations.

The gradient is calculated as:

\[d_{i}(x_i,b) = -\frac{(b - x_i)}{\sigma_i^2}\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(\sigma_i\) is the parameter for agent \(i\)

Parameters:

agent_idint: The current player/agent’s ID (\(i\)).
parameter_instancelist | np.ndarray | torch.Tensor: Parameter(s) (\(\sigma_i\)) for the Gaussian distribution.
agents_posnp.ndarray | torch.Tensor: Current positions of all agents (\(x_i\)).
bin_pointsnp.ndarray | torch.Tensor: Locations of the resource/bin points (\(b_k\)).

Returns:

torch.Tensor: Gradient values \(d_{(i,k)}\) for all \(k\) values.

Notes

For improved performance when computing gradients for multiple agents, consider using d_ln_f_vectorized instead.

InflGame.kernels.gauss.d_ln_f_vectorized(parameter_instance, agents_pos, bin_points)#

Compute the gradient of the logarithm of the Gaussian influence kernel for all agents.

This vectorized function calculates gradients for all agents simultaneously, providing significant performance improvements over single-agent computations.

The gradient is calculated as:

\[d_{i}(x_i,b) = -\frac{(b - x_i)}{\sigma_i^2}\]

Parameters:

parameter_instancelist | np.ndarray | torch.Tensor: Parameters (\(\sigma_i\)) for all agents, shape (num_agents,).
agents_posnp.ndarray | torch.Tensor: Current positions of all agents (\(x_i\)), shape (num_agents,).
bin_pointsnp.ndarray | torch.Tensor: Locations of the resource/bin points (\(b_k\)), shape (num_bins,).

Returns:

torch.Tensor: Gradient matrix of shape (num_agents, num_bins) where element [i,j] represents the gradient of agent i at bin point j.

Examples

>>> import numpy as np
>>> agents_pos = np.array([0.2, 0.5, 0.8])
>>> parameters = np.array([0.1, 0.15, 0.1])
>>> bins = np.linspace(0, 1, 50)
>>> gradients = d_ln_f_vectorized(parameters, agents_pos, bins)
>>> print(gradients.shape)
torch.Size([3, 50])

InflGame.kernels.gauss.influence(agent_id, parameter_instance, agents_pos, bin_points)#

Calculates the influence of a single agent using the Gaussian influence kernel.

This function provides backward compatibility while internally using optimized vectorized operations when beneficial.

The influence is computed as:

\[f_i(x_i,b) = \exp\left(-\frac{(b-x_i)^2}{2\sigma_i^2}\right)\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(\sigma_i\) is the parameter for agent \(i\)

Parameters:

agent_idint: The current player/agent’s ID.
parameter_instancelist | np.ndarray | torch.Tensor: Parameter(s) unique to the agent’s influence distribution (\(\sigma_i\)).
agents_posnp.ndarray | torch.Tensor: Current positions of all agents (\(x_i\)).
bin_pointsnp.ndarray | torch.Tensor: Locations of the resource/bin points (\(b\)).

Returns:

torch.Tensor: The agent’s influence calculated using the Gaussian method.

Notes

For improved performance when computing influence for multiple agents, consider using influence_vectorized instead.

InflGame.kernels.gauss.influence_vectorized(parameter_instance, agents_pos, bin_points)#

Compute the Gaussian influence for all agents simultaneously using vectorized operations.

This function calculates the influence matrix where each row represents an agent’s influence across all bin points, providing significant performance improvements over single-agent computations.

The influence is computed as:

\[f_i(x_i,b) = \exp\left(-\frac{(b-x_i)^2}{2\sigma_i^2}\right)\]

Parameters:

parameter_instancelist | np.ndarray | torch.Tensor: Parameters (\(\sigma_i\)) for all agents, shape (num_agents,).
agents_posnp.ndarray | torch.Tensor: Current positions of all agents (\(x_i\)), shape (num_agents,).
bin_pointsnp.ndarray | torch.Tensor: Locations of the resource/bin points (\(b\)), shape (num_bins,).

Returns:

torch.Tensor: Influence matrix of shape (num_agents, num_bins) where element [i,j] represents the influence of agent i at bin point j.

Examples

>>> import numpy as np
>>> agents_pos = np.array([0.2, 0.5, 0.8])
>>> parameters = np.array([0.1, 0.15, 0.1])
>>> bins = np.linspace(0, 1, 50)
>>> influences = influence_vectorized(parameters, agents_pos, bins)
>>> print(influences.shape)
torch.Size([3, 50])

InflGame.kernels.gauss.symmetric_nash_stability(num_agents, d_values, resource_distribution)#

Calculates the symmetric stability parameter (\(\sigma^*\)) for symmetric Gaussian influence kernels.

This function provides backward compatibility while using optimized internal computations.

The symmetric stability parameter is given by:

\[\sigma^* = \sqrt{\frac{(N-2)}{(N-1)} \cdot \frac{\sum_{b\in \mathbb{B}} (b-x)^2 \cdot B(b)}{\sum_{b\in \mathbb{B}} B(b)}}\]

where:

\(N\) is the number of agents
\(b\in \mathbb{B}\) is the set of bin points
\(B(b)\) is the resource distribution at bin point \(b\)

Parameters:

num_agentsint: Number of agents (\(N\)).
d_valuestorch.Tensor: Gradient values (\(d_{(i,k)}\)) at equilibrium.
resource_distributionlist | np.ndarray: Distribution of resources (\(r_k\)).

Returns:

torch.Tensor: Symmetric stability parameter (\(\sigma^*\)).

InflGame.kernels.gauss.symmetric_nash_stability_vectorized(num_agents, d_values, resource_distribution)#

Calculate the symmetric stability parameter using vectorized operations.

This function provides improved performance for symmetric Nash equilibrium stability calculations through vectorized tensor operations.

The symmetric stability parameter is given by:

\[\sigma^* = \sqrt{\frac{(N-2)}{(N-1)} \cdot \frac{\sum_{b\in \mathbb{B}} (b-x)^2 \cdot B(b)}{\sum_{b\in \mathbb{B}} B(b)}}\]

Parameters:

num_agentsint: Number of agents (\(N\)).
d_valuestorch.Tensor: Gradient values (\(d_{(i,k)}\)) at equilibrium, shape (num_agents, num_bins) or (num_bins,).
resource_distributionlist | np.ndarray | torch.Tensor: Distribution of resources (\(r_k\)), shape (num_bins,).

Returns:

torch.Tensor: Symmetric stability parameter (\(\sigma^*\)).

Examples

>>> import torch
>>> num_agents = 5
>>> d_vals = torch.randn(100)  # Gradient values
>>> resources = torch.rand(100)  # Resource distribution
>>> sigma_star = symmetric_nash_stability_vectorized(num_agents, d_vals, resources)
>>> print(f"Sigma*: {sigma_star.item():.4f}")

Gaussian kernel#

Gaussian Influence Kernel Module#

Mathematical Definitions:#

Usage:#

Example:#

This Page