configuration.md

Configuration Guide

This guide explains how simulation settings are organised, how run.py loads them, and what each major section controls. All configs are written in YAML and merged with the defaults in experiments/default.yml unless you explicitly disable merging.

Loading configuration files

python run.py <path/to/experiment.yml> calls core.utils.build_merged_config(), which:

1. Loads experiments/default.yml.
2. Loads your override file (YAML or JSON).
3. Normalises aliases (e.g., scheduler → scheduler_params).
4. Fills in omitted seeds deterministically so subsystems stay reproducible while remaining decorrelated.

You can supply only the fields you want to override:

# experiments/my_experiment.yml
seed: 1729
simulation:
  iterations: 200
population:
  num_agents: 40

Top-level sections

seed

Sets the global RNG seed. When present, run.py seeds both Python's random and NumPy, and downstream builders derive additional seeds from it.

language

Controls the initial morphology, lexicon templates, and phonology.

• stems.count: Number of base stems.
• stems.template: Template key from core.lexicon.templates.TEMPLATES.
• stems.other_templates: Optional list of additional templates for diversity.
• affixes.count: Number of affix slots/positions.
• affixes.template: Template key for affix generation.
• affixes.explicit_list: Optional list of literal affixes; when combined with split_among_agents: true the list is partitioned across agents.
• dialect_different_stems: How many stems differ across dialects.
• dialects: Number of dialect variants to seed.
• phonology.rules: Ordered list of rule identifiers from core.phonology.rule_library used to build the initial cascade.

agent

Configures how individual agents behave.

• adoption_policy: Chooses how agents adopt heard forms. Set method to bernoulli, degree, cumulative, or semantic_router; nested params tune each policy.
• lexicon_update: Defines the induction/compression pipeline. Each steps entry names an induction or compression block with method-specific parameters. schedule controls how the steps cycle.
• contact_policy: Chooses how agents pick communication partners (broadcast, random, k_random).

See core/adoption.py, core/induction.py, and core/compression.py for available methods and parameters.

population

Creates the population and network topology.

• num_agents: Number of agents in the simulation.
• utterance_length: Tokens per interaction round.
• network.type: Graph generator (scale_free, log_normal, erdos_renyi, complete). Additional parameters (e.g., avg_degree) can be provided as needed.
• cache_params.enabled: When true, initial morphologies are cached under data/_cache_populations.
• cache_params.include_seed: Includes the seed in cache keys so different seeds cache separately.
• cache_params.dir: Where to store caches.

simulation

High-level runtime parameters.

• iterations: Number of ticks.
• scheduler.kind: sync, async, or randomized_async (see core/scheduler.py).
• events: Time-indexed events that modify the simulation (network splits, cascade events, etc.). Each key is a tick; the value is a list of event descriptors.

Cascade events

Cascade events let you inject new phonological rules mid-run.

simulation:
  events:
    10:
      - type: cascade
        params:
          cascade_rules: ["VoicingAssimilation"]
          agent_selection: random
          selection_params:
            fraction: 0.3
          cumulative: true
          seed: 123

• cascade_rules: Identifiers from core.phonology.rule_library.
• agent_selection: random, component, all, degree_high, or degree_low.
• selection_params: Extra arguments (e.g., fraction, component_id).
• cumulative: Whether to append to the existing cascade (true) or overwrite it (false).
• seed: Re-seeds agent sampling for reproducibility.

Other supported events live in core/simulation.py and core/network.py (e.g., network splits/merges).

Adoption-policy events (target components or agents)

Adoption-policy events let you switch the adoption method mid-run, and optionally target only a component (after a split) or an explicit list of agent IDs.

simulation:
  events:
    - tick: 100
      type: adoption_policy   # alias: set_adoption_policy
      params:
        policy:
          method: bernoulli
          p: 0.05
          novelty: 0.5
        agent_selection: all

    # Flat shorthand is also accepted.
    - tick: 200
      type: adoption_policy
      params:
        method: bernoulli
        p: 0.1
        novelty: 0.25
        agent_selection: agents
        selection_params:
          agent_ids: [3, 7, 11]

• policy: Adoption policy config (must include method; see core/adoption.py).
• agent_selection: all (default), random, component, random_within_component, degree_high, degree_low, or agents.
• selection_params: Extra arguments:
  • fraction for random / degree_high / degree_low / random_within_component
  • component_id for component / random_within_component
  • agent_ids for agents

Compression-policy events (target components or agents)

Compression-policy events let you switch the compression method mid-run, and optionally target only a component (after a split) or an explicit list of agent IDs.

simulation:
  events:
    - tick: 30
      type: compression_policy   # alias: set_compression_policy
      params:
        policy:
          method: snap_to_shape
          r: 0.2
          thresh: 0.7
        agent_selection: component
        selection_params:
          component_id: 0

    - tick: 60
      type: compression_policy
      params:
        policy:
          method: drastic
          thresh: 0.9
        agent_selection: agents
        selection_params:
          agent_ids: [3, 7, 11]
        compression_interval: 20

• policy: Compression policy config (must include method; see core/compression.py).
• agent_selection: all (default), random, component, random_within_component, degree_high, degree_low, or agents.
• selection_params: Extra arguments:
  • fraction for random / degree_high / degree_low / random_within_component
  • component_id for component / random_within_component
  • agent_ids for agents
• compression_interval / compression_start: Optional overrides for how often/when compression runs for the selected agents. When current_tick is supplied internally by the simulation, a numeric compression_start value is interpreted as an offset from “now”.

ilm

Controls iterated learning model behaviour (optional). Set ilm.enabled: true to activate.

• ticks_per_generation: Number of ticks before a handover.
• utterances_per_learner: Training utterances per learner.
• network: How to rebuild the network between generations (persistence: keep|rebuild, rebuild_type).
• mentorship: Mentor assignment parameters (mode, k, require_anchor).
• learners: Overrides for learner agents, including their own adoption and lexicon update policies.

output

Configures artefacts written under data/<run_name>/.

• data_dir: Folder name (relative to data/) or absolute path.
• overwrite_output_dir: When false, runs abort if the folder exists.
• log_frequency: Tick interval for logging.
• agent_stats: Enable per-agent outputs (detailed_stats, lexicons, signatures, images).
• pop_stats: Toggle timeseries, morphology grids, signature prevalence, and network frames. Use fixed_scales to pin colour scales.
• summary_stats: Final aggregate plots and GIFs. Nested gifs controls live vs end-of-run rendering.