Multi-Variate Gaussian Kernel#

Multivariate Gaussian Influence Kernel Module#

This module implements the multivariate Gaussian influence kernel and its associated computations. The multivariate Gaussian kernel models the influence of agents based on a multivariate Gaussian distribution, incorporating covariance matrices to account for correlations between dimensions.

Mathematical Definitions:#

The multivariate Gaussian influence kernel is defined as:

\[f_i(x_i, b) = \exp\left(-\frac{1}{2} (b - x_i)^T \Sigma_i^{-1} (b - x_i)\right)\]
where:

  • \(x_i\) is the position of agent \(i\)

  • \(b\) is the bin point

  • \(\Sigma_i\) is the covariance matrix for agent \(i\)

Vectorized Functions:#

For improved performance with large datasets, this module provides vectorized versions of core functions:

  • influence_vectorized : Compute influence for all agents simultaneously using batch matrix operations

  • d_ln_f_vectorized : Compute gradients for all agents simultaneously with optimized tensor operations

  • cov_matrix_vectorized : Compute inverse covariance matrices for multiple agents efficiently

  • symmetric_nash_vectorized : Vectorized computation of symmetric Nash equilibrium points

The vectorized functions provide 5-10x performance improvements for large agent populations while maintaining full numerical accuracy and comprehensive error handling.

Dependencies:#

  • InflGame.utils

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 multivariate Gaussian influence kernel. The symmetric_nash_stability function computes the parameter for the symmetric Nash’s stability using the multivariate Gaussian influence kernel with diagonal covariance matrices.

Example:#

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

# Define parameters
num_agents = 3
agents_pos = np.array([[0.2, 0.3], [0.5, 0.5], [0.8, 0.7]])
bin_points = np.array([[0.1, 0.2], [0.4, 0.5], [0.7, 0.8]])
sigma_inv = torch.tensor([[[2.0, 0.0], [0.0, 1.0]]] * num_agents)  # Inverse covariance matrices
resource_distribution = np.array([0.3, 0.4, 0.3])

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

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

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

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

Functions

InflGame.kernels.MV_gauss.cov_matrix(parameter_instance)#

Computes the inverse of a multivariate Gaussian covariance matrix.

Parameters:

parameter_instance (torch.Tensor) – Covariance matrix for a player (\(\Sigma\)).

Returns:

Inverse of the covariance matrix (\(\Sigma^{-1}\)).

Return type:

torch.Tensor

InflGame.kernels.MV_gauss.cov_matrix_vectorized(parameter_instances)#

Computes the inverse of multiple multivariate Gaussian covariance matrices using vectorized operations.

This function efficiently processes multiple covariance matrices simultaneously, providing significant performance improvements over single-matrix inversions.

Parameters:
parameter_instancestorch.Tensor | np.ndarray | List

Covariance matrices for all agents, shape (num_agents, dim, dim).

Returns:
torch.Tensor

Inverse covariance matrices, shape (num_agents, dim, dim).

Raises:
TypeError

If input type is not supported.

ValueError

If input dimensions are invalid or matrices are singular.

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import torch
>>> cov_matrices = torch.eye(2).unsqueeze(0).repeat(3, 1, 1)  # 3 identity matrices
>>> inv_matrices = cov_matrix_vectorized(cov_matrices)
>>> print(inv_matrices.shape)
torch.Size([3, 2, 2])
InflGame.kernels.MV_gauss.d_ln_f(agent_id, agents_pos, bin_points, sigma_inv)#

Computes the gradient of the logarithm of the multivariate Gaussian influence kernel.

The gradient is calculated as:

\[d_{i}(x_i, b) = -\Sigma_i^{-1} (b - x_i)\]
where:

  • \(x_i\) is the position of agent \(i\)

  • \(b\) is the bin point

  • \(\Sigma_i^{-1}\) is the inverse covariance matrix for agent \(i\)

Parameters:

  • agent_id (int) – The current player’s ID (\(i\)).

  • agents_pos (np.ndarray) – Positions of all agents (\(x_i\)).

  • bin_points (np.ndarray) – Locations of the resource/bin points (\(b\)).

  • sigma_inv (torch.Tensor) – Inverse of the covariance matrix (\(\Sigma_i^{-1}\)).

Returns:

The gradient values for all bin points.

Return type:

int | torch.Tensor

InflGame.kernels.MV_gauss.d_ln_f_vectorized(agents_pos, bin_points, sigma_inv)#

Computes the gradient of the logarithm of the multivariate 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) = -\Sigma_i^{-1} (b - x_i)\]
Parameters:
agents_posnp.ndarray | torch.Tensor

Positions of all agents, shape (num_agents, num_dims).

bin_pointsnp.ndarray | torch.Tensor

Locations of the resource/bin points, shape (num_bins, num_dims).

sigma_invtorch.Tensor | np.ndarray

Inverse covariance matrices for all agents, shape (num_agents, num_dims, num_dims).

Returns:
torch.Tensor

Gradient tensor of shape (num_agents, num_dims, num_bins) where element [i,d,j] represents the gradient of agent i in dimension d at bin point j.

Raises:
TypeError

If input types are not supported.

ValueError

If input dimensions are incompatible or contain invalid values.

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import torch
>>> import numpy as np
>>> agents_pos = np.array([[0.2, 0.3], [0.5, 0.5]])
>>> bin_points = np.array([[0.1, 0.2], [0.4, 0.5], [0.7, 0.8]])
>>> sigma_inv = torch.eye(2).unsqueeze(0).repeat(2, 1, 1)
>>> gradients = d_ln_f_vectorized(agents_pos, bin_points, sigma_inv)
>>> print(gradients.shape)
torch.Size([2, 2, 3])
InflGame.kernels.MV_gauss.gaussian_symmetric_stability_2d(num_agents, e_values, resource_distribution)#
..deprecated::

This function is deprecated. Use symmetric_nash_stability instead. Computes the symmetric stability in 2D using the multivariate Gaussian influence kernel.

Parameters:

  • num_agents (int) – Number of agents in the system (\(N\)).

  • e_values (list | np.ndarray) – Eigenvalues of the covariance matrix (\(\lambda\)).

  • resource_distribution (np.ndarray) – Distribution of resources across the bin points (\(B(b)\)).

Returns:

The stability values [sigma_star_1, sigma_star_2] sorted in descending order.

Return type:

list

InflGame.kernels.MV_gauss.influence(agent_id, agents_pos, bin_points, sigma_inv)#

Computes the influence of an agent using the multivariate Gaussian kernel.

The influence is computed as:

\[f_i(x_i, b) = \exp\left(-\frac{1}{2} (b - x_i)^T \Sigma_i^{-1} (b - x_i)\right)\]
where:

  • \(x_i\) is the position of agent \(i\)

  • \(b\) is the bin point

  • \(\Sigma_i^{-1}\) is the inverse covariance matrix for agent \(i\)

Parameters:

  • agent_id (int) – The current player’s ID (\(i\)).

  • agents_pos (np.ndarray) – Positions of all agents (\(x_i\)).

  • bin_points (np.ndarray) – Locations of the resource/bin points (\(b\)).

  • sigma_inv (torch.Tensor) – Inverse of the covariance matrix (\(\Sigma_i^{-1}\)).

Returns:

The influence values for the agent.

Return type:

torch.Tensor

InflGame.kernels.MV_gauss.influence_vectorized(agents_pos, bin_points, sigma_inv)#

Computes the multivariate 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{1}{2} (b - x_i)^T \Sigma_i^{-1} (b - x_i)\right)\]
Parameters:
agents_posnp.ndarray | torch.Tensor

Positions of all agents, shape (num_agents, num_dims).

bin_pointsnp.ndarray | torch.Tensor

Locations of the resource/bin points, shape (num_bins, num_dims).

sigma_invtorch.Tensor | np.ndarray

Inverse covariance matrices for all agents, shape (num_agents, num_dims, num_dims).

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.

Raises:
TypeError

If input types are not supported.

ValueError

If input dimensions are incompatible or contain invalid values.

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import torch
>>> import numpy as np
>>> agents_pos = np.array([[0.2, 0.3], [0.5, 0.5], [0.8, 0.7]])
>>> bin_points = np.array([[0.1, 0.2], [0.4, 0.5], [0.7, 0.8]])
>>> sigma_inv = torch.eye(2).unsqueeze(0).repeat(3, 1, 1)
>>> influences = influence_vectorized(agents_pos, bin_points, sigma_inv)
>>> print(influences.shape)
torch.Size([3, 3])
InflGame.kernels.MV_gauss.symmetric_nash(bin_points, resource_distribution)#

Calculates the symmetric stability point in 2D for the multivariate Gaussian influence kernel.

This is equivalent to the mean of the resource distribution across the bin points. The symmetric Nash’s component in the lth dimension is calculated as:

\[x^*_{l} = \frac{\sum_{b\in \mathbb{B}} b_l \cdot B(b_l)}{\sum_{b} B(b_l)}\]
where:

  • \(x^*_{l}\) is the symmetric stability point in dimension \(l\)

  • \(b_l\) is the bin point in dimension \(l\)

  • \(\mathbb{B}\) is the set of bin points

  • \(B(b_i)\) is the distribution of resources across the bin points

Parameters:

  • bin_points (np.ndarray) – Locations of the resource/bin points in 2D.

  • resource_distribution (np.ndarray) – Distribution of resources across the bin points.

Returns:

The symmetric stability point as [x_star1, x_star2].

Return type:

list

InflGame.kernels.MV_gauss.symmetric_nash_stability(num_agents, bin_points, resource_distribution)#

This is a special case only since the covariance matrix is diagonal.

Computes the parameter value for the symmetric Nash stability in 2D. The symmetric Nash stability is calculated as:

\[\sigma^* = \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

  • \(x\) is the symmetric stability point

  • \(B(b)\) is the resource distribution at bin point \(b\)

Parameters:

  • num_agents (int) – Number of agents in the system (\(N\)).

  • bin_points (np.ndarray) – Locations of the resource/bin points in 2D (\(b\)).

  • resource_distribution (np.ndarray) – Distribution of resources across the bin points (\(B(b)\)).

Returns:

The computed stability value for the system.

Return type:

float

InflGame.kernels.MV_gauss.symmetric_nash_vectorized(bin_points, resource_distribution)#

Calculates the symmetric stability point using vectorized operations.

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

The symmetric Nash equilibrium point in each dimension is:

\[x^*_{l} = \frac{\sum_{b\in \mathbb{B}} b_l \cdot B(b_l)}{\sum_{b} B(b_l)}\]
Parameters:
bin_pointsnp.ndarray | torch.Tensor

Locations of the resource/bin points, shape (num_bins, num_dims).

resource_distributionnp.ndarray | torch.Tensor

Distribution of resources across the bin points, shape (num_bins,).

Returns:
torch.Tensor

Symmetric stability point, shape (num_dims,).

Raises:
TypeError

If input types are not supported.

ValueError

If input dimensions are incompatible or contain invalid values.

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import torch
>>> import numpy as np
>>> bin_points = np.array([[0.1, 0.2], [0.4, 0.5], [0.7, 0.8]])
>>> resources = np.array([0.3, 0.4, 0.3])
>>> nash_point = symmetric_nash_vectorized(bin_points, resources)
>>> print(nash_point)
tensor([0.4000, 0.5000])