Skip to content

architecture.md

Latest commit

 

History

History
41 lines (32 loc) · 3.48 KB

architecture.md

File metadata and controls

41 lines (32 loc) · 3.48 KB
Raw

Architecture Overview

This document describes the major modules inside core/, how they collaborate during a simulation, and where to look when extending behaviour.

High-level flow

  1. run.py loads and normalises configuration via core.utils.build_merged_config().
  2. Simulation(**cfg) constructs subsystems (population, scheduler, metrics collector, optional ILM manager).
  3. Each tick the scheduler decides which agents act; agents communicate according to the contact policy; heard tokens trigger adoption and lexicon updates.
  4. Metrics are collected and written to disk via core.metrics.DataCollector and core.viz helpers.
config → Simulation → Population → Agents ↔ Network → Metrics/DataCollector

Core modules

  • core/simulation.py: Orchestrates setup and the main loop. Handles scheduled events (network rewiring, cascade injections, ILM turnover) and delegates communication to the population.
  • core/population.py: Builds the agent roster, attaches network structure, and offers utilities for component-aware splits/merges. Also exposes hooks used by ILM to rebuild mentorship networks.
  • core/agent.py: Implements the agent state machine—producing utterances, hearing input, adopting forms, and advancing the morphology lifecycle.
  • core/adoption.py: Policy factories for deciding whether to adopt a heard form (bernoulli, degree, cumulative, semantic_router).
  • core/induction.py & core/compression.py: Lexicon update steps that fill missing paradigm cells (induction) and reduce morphological complexity (compression).
  • core/contact.py: Strategies for selecting interlocutors (broadcast, random, k_random).
  • core/forms/morphology.py: Represents morphological paradigms, computes signatures/patterns, and serialises lexicons for analysis.
  • core/phonology/: Rule implementations and cascade utilities that reshape forms before they are produced or adopted.
  • core/network.py: Graph builders (scale_free, log_normal, erdos_renyi, complete) plus utilities to split/merge components while preserving IDs for downstream analysis.
  • core/scheduler.py: Tick-level scheduling (sync, async, randomized_async) and event grouping.
  • core/metrics.py & core/viz.py: Collect numerical metrics, produce plots, and export GIFs/images summarising evolution.
  • core/cache.py & core/population_utils.py: Cache initial morphologies and lexicons so repeated runs with the same parameters can start quickly.
  • core/semantics.py: Optional semantic vector space used by semantic_router adoption.
  • core/ilm.py: Implements iterated learning—learner turnover, mentorship assignment, and network rebuilding between generations.
  • core/utils.py: Configuration helpers (merging defaults, normalising aliases, seed management).

Extending the system

  • New adoption or contact strategies: Add a factory function in the relevant module and expose it in POLICIES. Document parameters in your experiment config.
  • Custom events: Extend Simulation.perform_event (or helper modules) to react to new simulation.events entries.
  • Additional phonology rules: Implement in core/phonology/rule_library.py and reference by name in configs.
  • Metrics: Extend core/metrics.DataCollector or build post-processing notebooks/scripts that consume the data under data/<run_name>/.

Most subsystems accept dependency-injected classes or callables through the config. Inspect the dataclasses near the top of each module for supported parameters and defaults.