Skip to main content

Parameter System

2.5 Parameter System​

The parameter system provides Python descriptors (Input, Variable, Constant) that attach discoverable metadata to agent and model attributes. This enables automatic UI generation, config loading with validation, parameter sweeps, and gradient-based optimisation.

Input​

A user-configurable parameter loaded from config.json. Supports min/max range validation, type checking on assignment, and grouping for UI panels.

class Input:
    def __init__(
        self,
        default: Any,
        *,
        min: Optional[float] = None,      # Minimum allowed value
        max: Optional[float] = None,      # Maximum allowed value
        description: str = "",             # Human-readable description
        units: str = "",                   # Units of measurement (e.g., "USD", "bps")
        group: str = "",                   # Logical group for UI panels
        type_hint: Optional[Type] = None,  # Explicit type (inferred from default if omitted)
        differentiable: bool = False,      # Candidate for gradient-based optimisation
    ) -> None

The differentiable flag is forward-looking: it marks parameters that the planned JAX backend will treat as differentiable variables for gradient-based calibration.

Variable​

An observable model state value. Variables are writable by model code and readable by external tools (dashboards, output recorders, experiment runners).

class Variable:
    def __init__(self, description: str = "", units: str = "",
                 type_hint: Type = Any) -> None

Constant​

A fixed value set once and never changed. Assignment after initialisation raises AttributeError.

class Constant:
    def __init__(self, value: Any, description: str = "",
                 type_hint: Optional[Type] = None) -> None

Usage Example​

from simudyne.engine.sdk import Agent
from simudyne.engine.params import Input, Variable, Constant

class Bank(Agent):
    __state_schema__ = {"cash": float}

    # Inputs: configurable via config.json, sweepable via ExperimentRunner
    interest_rate = Input(default=0.05, min=0.0, max=1.0,
                          description="Annual interest rate", units="fraction",
                          group="Finance")
    leverage_limit = Input(default=10.0, min=1.0, max=50.0,
                           description="Maximum leverage ratio",
                           differentiable=True)

    # Variables: observable model state
    total_assets = Variable(description="Total asset value", units="USD")

    # Constants: fixed after creation
    bank_type = Constant(value="commercial", description="Bank classification")

The introspection API (get_inputs(), get_params(), get_constants()) enables tools to discover all parameters on a model or agent class without instantiating it, which is used by the experiment runner, calibrator, and REST API for automatic parameter discovery.

Last updated on