Jones’ Kernel#

Jones Influence Kernel Module#

This module implements the Jones influence kernel and its associated computations. The Jones kernel models the influence of agents based on a power-law relationship between their positions and resource/bin points.

Mathematical Definitions:#

The Jones influence kernel is defined as:

\[f_i(x_i, b) = \frac{1}{|x_i - b|^{P_i}}\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(P_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 Jones influence kernel.

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

Example:#

import numpy as np
import torch
from InflGame.kernels.jones import influence, d_ln_f
from InflGame.kernels.jones import 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.5, 0.8])
bin_points = np.linspace(0, 1, 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.jones.d_ln_f(agent_id, parameter_instance, agents_pos, bin_points)#

Computes the gradient of the logarithm of the Jones 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) = P_i \cdot \frac{\text{sgn}(x_i - b)}{|x_i - b|} = \frac{P_i}{x_i - b}\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(P_i\) is the parameter for agent \(i\)
\(\text{sgn}\) is the sign function

Parameters:

agent_idint: The current player/agent’s ID (\(i\)).
parameter_instancelist | np.ndarray | torch.Tensor: Parameter(s) (\(P_i\)) for the Jones 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.

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 gradients for multiple agents, consider using d_ln_f_vectorized instead.

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

Compute the gradient of the logarithm of the Jones 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) = P_i \cdot \frac{\text{sgn}(x_i - b)}{|x_i - b|} = \frac{P_i}{x_i - b}\]

Parameters:

parameter_instancelist | np.ndarray | torch.Tensor: Parameters (\(P_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.

Raises:

ValueError: If input parameters are invalid or incompatible.
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.5, 0.8])
>>> parameters = np.array([2.0, 3.0, 4.0])
>>> bins = np.linspace(0, 1, 50)
>>> gradients = d_ln_f_vectorized(parameters, agents_pos, bins)
>>> print(gradients.shape)
torch.Size([3, 50])

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

Calculates the influence of a single agent using the Jones 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) = \frac{1}{|x_i - b|^{P_i}}\]

where:

\(x_i\) is the position of agent \(i\)
\(b\) is the bin point
\(P_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) unique to the agent’s influence distribution (\(P_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 Jones method.

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.jones.influence_vectorized(parameter_instance, agents_pos, bin_points)#

Compute the Jones 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) = \frac{1}{|x_i - b|^{P_i}}\]

Parameters:

parameter_instancelist | np.ndarray | torch.Tensor: Parameters (\(P_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.

Raises:

ValueError: If input parameters are invalid or incompatible.
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.5, 0.8])
>>> parameters = np.array([2.0, 3.0, 4.0])
>>> bins = np.linspace(0, 1, 50)
>>> influences = influence_vectorized(parameters, agents_pos, bins)
>>> print(influences.shape)
torch.Size([3, 50])

Jones’ Kernel#

Jones Influence Kernel Module#

Mathematical Definitions:#

Usage:#

Example:#

This Page