Validation

Validation Module

This module provides comprehensive validation functions for adaptive influence game configurations. It ensures that all parameters for the adaptive environment are properly typed, within valid ranges, and mutually compatible before simulation begins.

The module is designed to work with the InflGame.adaptive package and provides robust error checking with detailed error messages to help users quickly identify and fix configuration issues.

Dependencies:

• torch

• numpy

• matplotlib.tri

• InflGame.utils.general

Usage:

The validate_adaptive_config function is the main entry point for validating all configuration parameters before creating an AdaptiveEnv instance. It performs type checking, range validation, and compatibility checks between related parameters.

Example:

from InflGame.utils.validation import validate_adaptive_config
import torch
import numpy as np

# Define configuration
config = validate_adaptive_config(
    num_agents=3,
    agents_pos=np.array([0.2, 0.5, 0.8]),
    parameters=torch.tensor([1.0, 1.0, 1.0]),
    resource_distribution=torch.tensor([10.0, 20.0, 30.0]),
    bin_points=np.array([0.1, 0.4, 0.7]),
    infl_configs={'infl_type': 'gaussian'},
    learning_rate_type='cosine_annealing',
    learning_rate=[0.0001, 0.01, 15],
    time_steps=100,
    domain_type='1d',
    domain_bounds=[0, 1],
    tolerance=1e-5
)

# Use validated config to create environment
# env = AdaptiveEnv(**config)

Functions

InflGame.utils.validation.validate_adaptive_config(num_agents, agents_pos, parameters, resource_distribution, bin_points, infl_configs={'infl_type': 'gaussian'}, learning_rate_type='cosine', learning_rate=[0.0001, 0.01, 15], time_steps=100, fp=0, infl_cshift=False, cshift=0, infl_fshift=False, Q=0, domain_type='1d', domain_bounds=[0, 1], tolerance=1e-05, tolerated_agents=None)

Validate the configuration of an adaptive influence model.

Performs comprehensive validation of all parameters required to initialize an adaptive environment for influencer games. This includes type checking, range validation, and compatibility checks between related parameters. The function converts inputs to appropriate types and returns a validated configuration dictionary.

Parameters:

num_agentsint

Number of agents in the system. Must be a positive integer.

agents_posUnion[List[float], np.ndarray]

Initial positions of the agents. Length must equal num_agents. For 1D domains: 1D array of positions. For 2D domains: \((N, 2)\) array of (x, y) coordinates. For simplex domains: \((N, k)\) array of barycentric coordinates that sum to 1.

parameterstorch.Tensor

Parameters for influence kernels of each agent. Length must equal num_agents. Must contain finite values. For Gaussian kernels, typically positive values. For beta kernels, concentration parameter \(\phi > 0\).

resource_distributiontorch.Tensor

Resource distribution in the environment. Must match length of bin_points. Should contain non-negative finite values.

bin_pointsUnion[List[float], np.ndarray]

Points in the domain where resources are distributed. Must be non-empty. For 1D: points on the line segment. For 2D/simplex: coordinate pairs.

infl_configsDict[str, Union[str, callable]], optional

Influence kernel configuration dictionary, by default {'infl_type': 'gaussian'}.

• 'infl_type' (str): Type of influence kernel. Valid options:

  • 'gaussian': Gaussian influence kernel

  • 'multi_gaussian': Multivariate Gaussian kernel

  • 'dirichlet': Dirichlet kernel for simplex domains

  • 'beta': Beta distribution kernel

  • 'Jones_M': Jones mean kernel

  • 'custom': User-defined custom kernel

• 'custom_influence' (callable): Required when infl_type='custom'. Custom influence function.

learning_rate_typestr, optional

Type of learning rate schedule, by default ‘cosine’. Valid options:

• 'cosine_annealing': Cosine annealing schedule

• 'fixed': Constant learning rate

• 'trust_region': Trust region adaptive schedule

• 'gradient_magnitude': Magnitude-based adaptive schedule

learning_rateList[float], optional

Learning rate parameters, by default [.0001, .01, 15]. For schedules: [min_lr, max_lr, decay_steps]. For fixed: single value [lr].

time_stepsint, optional

Maximum number of gradient ascent iterations, by default 100. Must be a positive integer.

fpOptional[int], optional

Fixed parameter index for Dirichlet kernel, by default 0. Required when infl_type='dirichlet'. Must be non-negative integer between 0 and simplex dimension - 1.

infl_cshiftbool, optional

Whether to apply constant shift to influence function, by default False.

cshiftint, optional

Value of constant shift, by default 0. Required when infl_cshift=True. Must be a list, array, or tensor.

infl_fshiftbool, optional

Whether to apply functional shift to influence, by default False. Not yet implemented for multi-dimensional agents.

Qint, optional

Scaling factor for functional shift, by default 0. Required when infl_fshift=True. Should be non-negative.

domain_typestr, optional

Type of domain, by default ‘1d’. Valid options:

• '1d': One-dimensional line segment

• '2d': Two-dimensional rectangular domain

• 'simplex': Probability simplex

domain_boundsUnion[List[float], torch.Tensor], optional

Bounds of the domain, by default [0, 1].

• For '1d': [min, max]

• For '2d': [[xmin, xmax], [ymin, ymax]]

• For 'simplex': (r2, corners, triangle, trimesh) tuple with:

  • r2: 2D reference point

  • corners: \((3, 2)\) array of triangle vertices

  • triangle: matplotlib Triangulation object

  • trimesh: matplotlib Triangulation mesh object

tolerancefloat, optional

Convergence tolerance for position changes, by default \(10^{-5}\). Must be a positive number.

tolerated_agentsOptional[int], optional

Number of agents that must meet tolerance before stopping, by default None. If None, defaults to num_agents. Must be between 1 and num_agents.

Returns:

dict

Dictionary of validated and converted parameters with all inputs converted to appropriate types (tensors, validated ranges, etc.). Keys match parameter names.

Raises:

ValueError

If any configuration parameter is invalid or out of range.

TypeError

If input types are incorrect.

NotImplementedError

If unsupported functionality is requested (e.g., functional shift for multi-dimensional agents).

Warns:

UserWarning

For potentially problematic but not invalid configurations:

• Negative parameters for Gaussian kernels

• Negative learning rates

• Non-negative resources

• Negative Q parameter with functional shift

Examples

>>> import torch
>>> import numpy as np
>>> 
>>> # Validate a simple 1D configuration
>>> config = validate_adaptive_config(
...     num_agents=2,
...     agents_pos=[0.3, 0.7],
...     parameters=torch.tensor([0.1, 0.15]),
...     resource_distribution=torch.tensor([1.0, 2.0, 1.5]),
...     bin_points=[0.0, 0.5, 1.0],
...     domain_type='1d',
...     domain_bounds=[0, 1]
... )
>>> config['num_agents']
2