Dirichlet Kernel

Dirichlet Influence Kernel Module

This module implements the Dirichlet influence kernel and its associated computations. The Dirichlet kernel models the influence of agents based on a multivariate probability distribution centered on their position and defined over a simplex.

Mathematical Definitions:

The Dirichlet influence kernel is defined as:

\[f_i(\alpha, b) = \frac{1}{\beta(\alpha)} \prod_{l=1}^{L} b_{l}^{\alpha_{l} - 1}\]

where:

• \(\alpha\) is the vector of parameters for the Dirichlet distribution, defined by the param function.

• \(b\) is the bin point.

• \(\beta(\alpha)\) is the beta function.

Dependencies: ————-yy - InflGame.utils

Usage:

The param function generates the alpha parameters for the Dirichlet kernel from agents positions, while the influence function computes the influence of agents at specific bin points. The d_ln_f function calculates the gradient of the logarithm of the Dirichlet PDF with respect to agent positions.

New vectorized functions are available for improved performance: - param_vectorized : Generate alpha parameters for all agents simultaneously - influence_vectorized : Compute influence for all agents simultaneously - d_ln_f_vectorized : Compute gradients for all agents simultaneously

Example:

import numpy as np
import torch
from InflGame.kernels.diric import param, influence, d_ln_f
from InflGame.kernels.diric import param_vectorized, influence_vectorized, d_ln_f_vectorized

# Define parameters
num_agents = 3
parameter_instance = [2.0, 3.0, 4.0]
agents_pos = np.array([[0.2, 0.3, 0.5], [0.4, 0.4, 0.2], [0.6, 0.2, 0.2]])
fixed_pa = 2
bin_points = np.array([[0.1, 0.2, 0.7], [0.3, 0.3, 0.4]])

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

# Vectorized computation (all agents at once)
alpha_matrix_vec = param_vectorized(num_agents, parameter_instance, agents_pos, fixed_pa)
all_influences = influence_vectorized(bin_points=bin_points, alpha_matrix=alpha_matrix_vec)
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, 
                 alpha_matrix=alpha_matrix, fixed_pa=fixed_pa)
print("Gradient values:", gradient)

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

Functions

InflGame.kernels.diric.d_ln_f(agent_id, agents_pos, bin_points, alpha_matrix, fixed_pa)

Computes the gradient of the logarithm of the Dirichlet PDF with respect to agent positions for a single agent.

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

The gradient is calculated as follows:

• For \(l \neq \varphi\):

  \[d_{(i,l)} = \frac{\alpha_{i,\varphi}}{x_{i,\varphi}} \left(\ln(b_{l}) - \psi(\alpha_{i,l}) + \psi\left(\sum_{l=1}^{L} \alpha_{i,l}\right)\right)\]

• For \(l = \varphi\):

  \[\begin{split}d_{(i,\varphi)} = - \sum_{\substack{j=1 \\ j \neq \varphi}}^{L} \frac{x_{i,j}}{x_{i,\varphi}} \cdot d_{(i,j)}\end{split}\]

where:

• \(L\) is the number of dimensions.

• \(b_{l}\) is the bin point in dimension \(l\).

• \(x_{i,l}\) is the position of agent \(i\) in dimension \(l\).

• \(\varphi\) is the fixed parameter index.

• \(\alpha_{i,l}\) is the parameter for agent \(i\) in dimension \(l\).

• \(\psi\) is the digamma function.

Parameters:

agent_idint

The ID of the agent (\(i\)).

agents_posnp.ndarray | torch.Tensor

Current positions of all agents (\(x_{i,l}\)).

bin_pointsnp.ndarray | torch.Tensor

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

alpha_matrixtorch.Tensor

Alpha parameters for the Dirichlet influence (\(\alpha\)).

fixed_paint

Index of the fixed coordinate direction (\(\varphi\)).

Returns:

torch.Tensor

Gradient values (\(d_{(i,l)}\)) for all \(l\) values. Shape: (num_dims, num_bins)

Raises:

ValueError

If input parameters are invalid or incompatible.

RuntimeError

If computation fails due to numerical issues.

TypeError

If input types are not supported.

IndexError

If agent_id or fixed_pa is out of bounds.

Notes

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

InflGame.kernels.diric.d_ln_f_vectorized(agents_pos, bin_points, alpha_matrix, fixed_pa)

Compute the gradient of the logarithm of the Dirichlet 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 described in the single-agent function.

Parameters:

agents_posnp.ndarray | torch.Tensor

Current positions of all agents (\(x_{i,l}\)), shape (num_agents, num_dims).

bin_pointsnp.ndarray | torch.Tensor

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

alpha_matrixtorch.Tensor

Alpha parameters for the Dirichlet influence (\(\alpha\)), shape (num_agents, num_dims).

fixed_paint

Index of the fixed coordinate direction (\(\varphi\)).

Returns:

torch.Tensor

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

Raises:

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import numpy as np
>>> agents_pos = np.array([[0.2, 0.3, 0.5], [0.4, 0.4, 0.2]])
>>> bin_points = np.array([[0.1, 0.2, 0.7], [0.3, 0.3, 0.4]])
>>> alpha_matrix = torch.tensor([[2.0, 3.0, 4.0], [1.5, 2.5, 3.5]])
>>> gradients = d_ln_f_vectorized(agents_pos, bin_points, alpha_matrix, fixed_pa=2)
>>> print(gradients.shape)
torch.Size([2, 3, 2])

InflGame.kernels.diric.influence(agent_id, bin_points, alpha_matrix)

Computes the influence of a single agent using the Dirichlet kernel.

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

The influence is calculated as the Dirichlet PDF evaluated at the bin points:

\[f_i(\alpha, b) = \frac{1}{\beta(\alpha)} \prod_{l=1}^{L} b_{l}^{\alpha_{l} - 1}\]

where:

• \(L\) is the number of dimensions.

• \(b\) is the bin point.

• \(\alpha\) is the vector of parameters for the Dirichlet distribution calculated by the param function.

• \(\beta(\alpha)\) is the beta function.

Parameters:

agent_idint

The ID of the agent (\(i\)).

bin_pointsnp.ndarray | torch.Tensor

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

alpha_matrixtorch.Tensor

Alpha parameters for the Dirichlet influence (\(\alpha\)).

Returns:

torch.Tensor

Influence values for the agent at each bin point.

Raises:

ValueError

If input parameters are invalid or incompatible.

RuntimeError

If computation fails due to numerical issues.

TypeError

If input types are not supported.

IndexError

If agent_id is out of bounds.

Notes

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

InflGame.kernels.diric.influence_vectorized(bin_points, alpha_matrix)

Compute the Dirichlet 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 calculated as:

\[f_i(\alpha, b) = \frac{1}{\beta(\alpha)} \prod_{l=1}^{L} b_{l}^{\alpha_{l} - 1}\]

Parameters:

bin_pointsnp.ndarray | torch.Tensor

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

alpha_matrixtorch.Tensor

Alpha parameters for the Dirichlet influence (\(\alpha\)), shape (num_agents, 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:

RuntimeError

If computation fails due to numerical issues.

Examples

>>> import numpy as np
>>> bin_points = np.array([[0.1, 0.2, 0.7], [0.3, 0.3, 0.4]])
>>> alpha_matrix = torch.tensor([[2.0, 3.0, 4.0], [1.5, 2.5, 3.5]])
>>> influences = influence_vectorized(bin_points, alpha_matrix)
>>> print(influences.shape)
torch.Size([2, 2])

InflGame.kernels.diric.param(num_agents, parameter_instance, agents_pos, fixed_pa)

Generates a matrix of alpha parameters for all agents based on their positions and a fixed parameter.

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

The alpha matrix is defined as:

\[\begin{split}A = \begin{bmatrix} \alpha_{1,1} & \alpha_{1,2} & \cdots & \alpha_{1,L} \\ \alpha_{2,1} & \alpha_{2,2} & \cdots & \alpha_{2,L} \\ \vdots & \vdots & \ddots & \vdots \\ \alpha_{N,1} & \alpha_{N,2} & \cdots & \alpha_{N,L} \end{bmatrix}\end{split}\]

The alpha parameters are calculated as follows:

• If \(l \neq \varphi\):

  \[\alpha_{i,l} = \frac{\alpha_{i}}{x_{i,\varphi}} \cdot x_{i,l}\]

• If \(l = \varphi\):

  \[\alpha_{i,l} = \alpha_{i}\]

Where:

• \(N\) is the number of agents

• \(L\) is the number of dimensions

• \(x_{i,l}\) is the position of agent \(i\) in dimension \(l\)

• \(\varphi\) is the fixed parameter index

• \(\alpha_{i}\) is the parameter for agent \(i\) and is a fixed parameter.

Parameters:

num_agentsint

Number of agents (\(N\)).

parameter_instancelist | np.ndarray | torch.Tensor

Fixed alpha values for each agent (\(\alpha_i\)).

agents_poslist | np.ndarray | torch.Tensor

Positions of agents in the space (\(x_{i,l}\)).

fixed_paint

Index of the fixed coordinate direction (\(\varphi\)).

Returns:

torch.Tensor

Alpha matrix (\(A\)), where each row corresponds to the alpha parameters of an agent.

Raises:

ValueError

If input parameters are invalid or incompatible.

RuntimeError

If computation fails due to numerical issues.

TypeError

If input types are not supported.

IndexError

If fixed_pa is out of bounds.

Notes

For improved performance with large agent populations, consider using param_vectorized directly.

InflGame.kernels.diric.param_vectorized(num_agents, parameter_instance, agents_pos, fixed_pa)

Generate alpha parameters matrix for all agents using vectorized operations.

This function provides significant performance improvements over single-agent parameter generation through vectorized tensor operations.

The alpha matrix is defined as:

\[\begin{split}A = \begin{bmatrix} \alpha_{1,1} & \alpha_{1,2} & \cdots & \alpha_{1,L} \\ \alpha_{2,1} & \alpha_{2,2} & \cdots & \alpha_{2,L} \\ \vdots & \vdots & \ddots & \vdots \\ \alpha_{N,1} & \alpha_{N,2} & \cdots & \alpha_{N,L} \end{bmatrix}\end{split}\]

Parameters:

num_agentsint

Number of agents (\(N\)).

parameter_instancelist | np.ndarray | torch.Tensor

Fixed alpha values for each agent (\(\alpha_i\)), shape (num_agents,).

agents_poslist | np.ndarray | torch.Tensor

Positions of agents in the space (\(x_{i,l}\)), shape (num_agents, num_dims).

fixed_paint

Index of the fixed coordinate direction (\(\varphi\)).

Returns:

torch.Tensor

Alpha matrix (\(A\)) of shape (num_agents, num_dims), where each row corresponds to the alpha parameters of an agent.

Raises

RuntimeError

If computation fails due to numerical issues.

TypeError

If input types are not supported.

Examples

>>> import numpy as np
>>> agents_pos = np.array([[0.2, 0.3, 0.5], [0.4, 0.4, 0.2]])
>>> parameters = [2.0, 3.0]
>>> alpha_matrix = param_vectorized(2, parameters, agents_pos, fixed_pa=2)
>>> print(alpha_matrix.shape)
torch.Size([2, 3])