Scenarios & Parameter Sweeps

Defining Scenarios

Define simulations in YAML with full governance configuration:

# scenarios/status_game.yaml
scenario_id: status_game
description: "Reputation competition with governance"

agents:
  - type: honest
    count: 2
  - type: opportunistic
    count: 2
  - type: adversarial
    count: 1

governance:
  transaction_tax_rate: 0.05
  reputation_decay_rate: 0.95
  staking_enabled: true
  min_stake_to_participate: 10.0
  circuit_breaker_enabled: true
  freeze_threshold_toxicity: 0.6
  audit_enabled: true
  audit_probability: 0.15

simulation:
  n_epochs: 20
  steps_per_epoch: 15
  seed: 123

payoff:
  s_plus: 3.0
  s_minus: 1.5
  h: 2.5
  theta: 0.5
  w_rep: 2.0

Run scenarios from the command line:

python examples/run_scenario.py scenarios/baseline.yaml
python examples/run_scenario.py scenarios/status_game.yaml
python examples/run_scenario.py scenarios/strict_governance.yaml

Or use the package CLI entry point:

python -m swarm list
python -m swarm run scenarios/baseline.yaml
python -m swarm run scenarios/status_game.yaml --seed 42 --epochs 20

Or load programmatically:

from swarm.scenarios import load_and_build

orchestrator = load_and_build(Path("scenarios/status_game.yaml"))
metrics = orchestrator.run()

Scenario Comparison

Metric	Baseline	Status Game	Strict Governance
Governance	None	Moderate	Heavy
Tax rate	0%	5%	10%
Reputation decay	None	5%/epoch	15%/epoch
Staking required	No	10.0	25.0
Circuit breaker	No	Yes (0.6)	Yes (0.5)
Audit probability	0%	15%	25%
Results
Bad actor frozen	No	Yes	Yes
Bad actor payoff	+3.42	+1.22	-1.55
Avg toxicity	0.30	0.33	0.32
Welfare/epoch	7.29	13.02	8.15

Governance effectively punishes bad actors (payoffs drop from positive to negative) while maintaining similar toxicity levels. Stricter governance reduces bad actor gains but also dampens overall welfare.

Parameter Sweeps

Run batch simulations over parameter ranges:

from swarm.analysis import SweepConfig, SweepParameter, SweepRunner
from swarm.scenarios import load_scenario

# Load base scenario
scenario = load_scenario(Path("scenarios/baseline.yaml"))

# Configure sweep
config = SweepConfig(
    base_scenario=scenario,
    parameters=[
        SweepParameter(
            name="governance.transaction_tax_rate",
            values=[0.0, 0.05, 0.10, 0.15],
        ),
        SweepParameter(
            name="governance.circuit_breaker_enabled",
            values=[False, True],
        ),
    ],
    runs_per_config=3,  # Multiple runs for statistical significance
    seed_base=42,
)

# Run sweep
runner = SweepRunner(config)
results = runner.run()

# Export to CSV
runner.to_csv(Path("results.csv"))

# Get summary statistics
summary = runner.summary()

Run the example:

python examples/parameter_sweep.py
python examples/parameter_sweep.py --output my_results.csv

Supported parameter paths: - governance.* - Any GovernanceConfig field - payoff.* - Any PayoffConfig field - n_epochs, steps_per_epoch - Simulation settings