Jacobian#

Functions

`compute_jacobian_optimized`(adaptive_env, ...)	Convenience function to compute the Jacobian matrix from an AdaptiveEnv object.
`dd_lnf_matrix`(agent_id, parameter_instance, ...)	Calculate the second derivative of the log-influence function.
`jacobian_diag`(resource_distribution, ...[, ...])	Compute diagonal Jacobian matrix elements using JIT-optimized vectorized operations.
`jacobian_matrix`(num_agents, parameters, ...)	Compute the full Jacobian matrix for multi-agent adaptive dynamics using optimized vectorized operations.
`jacobian_off_diag`(resource_distribution, ...)	Compute off-diagonal Jacobian matrix elements using JIT-optimized vectorized operations.
`shift_matrix_jacobian`(num_agents, ...)	Compute the shift matrix Jacobian using JIT-optimized vectorized operations.
`shift_matrix_jacobian_ii`(num_agents, ...)	Compute second-order shift matrix Jacobian using JIT-optimized vectorized operations.
`shift_matrix_jacobian_ij`(num_agents, ...)	Compute mixed partial derivative shift matrix Jacobian using JIT-optimized vectorized operations.

InflGame.adaptive.jacobian.compute_jacobian_optimized(adaptive_env, position, infl_fshift=False, device='cpu')#

Convenience function to compute the Jacobian matrix from an AdaptiveEnv object.

This high-level wrapper extracts all necessary data from an adaptive environment instance and computes the Jacobian matrix. It handles device placement and automatically computes required intermediate matrices (influence, probability, derivatives).

Usage Example:

from InflGame.adaptive.grad_func_env import AdaptiveEnv
from InflGame.adaptive.jacobian import compute_jacobian_optimized

# Create and set up environment
env = AdaptiveEnv(...)
env.gradient_ascent()

# Compute Jacobian at final positions
jacobian = compute_jacobian_optimized(env, env.agents_pos)

# Check stability
eigenvalues = torch.linalg.eigvals(jacobian)
is_stable = torch.all(eigenvalues.real < 0)

Parameters:

adaptive_envAdaptiveEnv: The adaptive environment containing agent configuration and dynamics.
positiontorch.Tensor: Agent positions at which to evaluate the Jacobian.
infl_fshiftbool: Whether to include influence function shift corrections.
devicestr: Device for tensor computations (‘cpu’ or ‘cuda’).

Returns:

torch.Tensor: Jacobian matrix of shape (N, N) on the specified device.

Note

This function automatically computes influence_matrix, prob_matrix, and d_lnf_matrix from the environment. For repeated Jacobian evaluations at the same position, consider caching these intermediate matrices.

InflGame.adaptive.jacobian.dd_lnf_matrix(agent_id, parameter_instance, infl_type, x=None)#

Calculate the second derivative of the log-influence function.

Computes \(\frac{\partial^2}{\partial x_i^2} \ln(f_i(x_i, b_k))\) where \(f_i\) is the influence kernel for agent \(i\). This second derivative is needed for computing diagonal elements of the Jacobian matrix.

Supported Influence Types:

‘gaussian’: Returns \(-1/\sigma_i^2\) where \(\sigma_i\) is the reach parameter
‘beta’: Uses polygamma function to compute beta distribution second derivatives

Parameters:

agent_idint: Index of the agent (0 to N-1).
parameter_instanceUnion[List[float], np.ndarray, torch.Tensor]: Parameters for the influence function (e.g., reach/sigma values).
infl_typestr: Type of influence kernel (‘gaussian’, ‘beta’, etc.).
xUnion[float, torch.Tensor], optional: Agent positions (required for beta kernel, optional otherwise).

Returns:

torch.Tensor: Second derivative value as a scalar tensor.

Raises:

ValueError: If influence type is not recognized.

Note

For beta kernels, the computation uses scipy’s polygamma function which requires scalar inputs, so tensor values are converted to float.

InflGame.adaptive.jacobian.jacobian_diag(resource_distribution, infl_fshift, dd_i, di, pi, shift_i=0, shift_ii=0)#

Compute diagonal Jacobian matrix elements using JIT-optimized vectorized operations.

Calculates \(J_{ii}\), representing the second derivative of agent \(i\)’s utility with respect to its own position. This determines local stability and convergence rate for the agent.

Parameters:

resource_distributionUnion[List[float], np.ndarray, torch.Tensor]: Resource values at each bin point.
infl_fshiftbool: Whether to include influence function shift corrections.
dd_iUnion[float, torch.Tensor]: Second derivative of log-influence \(\partial^2 \ln(f_i)/\partial x_i^2\) for agent i.
ditorch.Tensor: First derivative of log-influence \(\partial \ln(f_i)/\partial x_i\) for agent i.
pitorch.Tensor: Probability distribution for agent i across bins.
shift_iUnion[float, torch.Tensor]: Shift function correction for agent i (used if infl_fshift=True).
shift_iiUnion[float, torch.Tensor]: Second-order shift function correction for agent i (used if infl_fshift=True).

Returns:

torch.Tensor: Scalar Jacobian element \(J_{ii}\).

Note

All tensor inputs are automatically converted to float32 for consistency.

InflGame.adaptive.jacobian.jacobian_matrix(num_agents, parameters, agents_pos, bin_points, resource_distribution, infl_type, infl_fshift, Q, infl_matrix, prob_matrix, d_lnf_matrix, x=None)#

Compute the full Jacobian matrix for multi-agent adaptive dynamics using optimized vectorized operations.

The Jacobian matrix \(J\) is an \(N \times N\) matrix where element \(J_{ij}\) represents the partial derivative of agent \(i\)’s utility gradient with respect to agent \(j\)’s position.

Mathematical Formulation:

For agent \(i\) with utility:

\[u_i(x) = \sum_{k=1}^{K} G_{i,k}(x, b_k) B(b_k)\]

The Jacobian elements are:

\[J_{ij} = \frac{\partial^2 u_i}{\partial x_i \partial x_j}\]

Stability Analysis:

The eigenvalues of \(J\) determine equilibrium stability: - All eigenvalues with negative real parts → stable equilibrium - Any eigenvalue with positive real part → unstable equilibrium - Zero real parts → marginal stability (further analysis needed)

Parameters:

num_agentsint: Number of agents in the system.
parametersUnion[List[float], np.ndarray, torch.Tensor]: Influence function parameters (e.g., reach/sigma values for each agent).
agents_posUnion[List[float], np.ndarray, torch.Tensor]: Current positions of all agents.
bin_pointsUnion[List[float], np.ndarray, torch.Tensor]: Discretized domain points for resource distribution.
resource_distributionUnion[List[float], np.ndarray, torch.Tensor]: Resource values at each bin point.
infl_typestr: Type of influence kernel (‘gaussian’, ‘beta’, ‘multi_gaussian’, etc.).
infl_fshiftbool: Whether to include influence function shift corrections.
Qfloat: Scaling factor for shift functions (relevant if infl_fshift=True).
infl_matrixtorch.Tensor: Pre-computed influence matrix of shape (N, K).
prob_matrixtorch.Tensor: Pre-computed probability matrix of shape (N, K).
d_lnf_matrixtorch.Tensor: Pre-computed first derivatives of log-influence, shape (N, K).
xUnion[float, torch.Tensor], optional: Agent positions (used for beta kernel second derivatives, optional).

Returns:

torch.Tensor: Jacobian matrix of shape (N, N).

Note

This is the primary function for Jacobian computation. It pre-computes shift matrices and second derivatives before assembling the full Jacobian using vectorized operations.