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.

Examples

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_instancetorch.Tensor

Covariance matrix for a player (\(\Sigma\)).

Returns:

torch.Tensor

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

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_idint

The current player’s ID (\(i\)).

agents_posnp.ndarray

Positions of all agents (\(x_i\)).

bin_pointsnp.ndarray

Locations of the resource/bin points (\(b\)).

sigma_invtorch.Tensor

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

Returns:

torch.Tensor

The gradient values for all bin points.

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 since version 0.1: This function is deprecated. Use symmetric_nash_stability instead. Computes the symmetric stability in 2D using the multivariate Gaussian influence kernel.

Parameters:

num_agentsint

Number of agents in the system (\(N\)).

e_valueslist | np.ndarray

Eigenvalues of the covariance matrix (\(\lambda\)).

resource_distributionnp.ndarray

Distribution of resources across the bin points (\(B(b)\)).

Returns:

list

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

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_idint

The current player’s ID (\(i\)).

agents_posnp.ndarray

Positions of all agents (\(x_i\)).

bin_pointsnp.ndarray

Locations of the resource/bin points (\(b\)).

sigma_invtorch.Tensor

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

Returns:

torch.Tensor

The influence values for the agent.

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_pointsnp.ndarray

Locations of the resource/bin points in 2D.

resource_distributionnp.ndarray

Distribution of resources across the bin points.

Returns:

list

The symmetric stability point as [x_star1, x_star2].

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_agentsint

Number of agents in the system (\(N\)).

bin_pointsnp.ndarray

Locations of the resource/bin points in 2D (\(b\)).

resource_distributionnp.ndarray

Distribution of resources across the bin points (\(B(b)\)).

Returns:

float

The computed stability value for the system.

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])