Skip to content

running_experiments.md

Latest commit

 

History

History
67 lines (43 loc) · 2.6 KB

running_experiments.md

File metadata and controls

67 lines (43 loc) · 2.6 KB

Running Experiments

This walkthrough covers the typical workflow for launching a simulation, customising configuration files, and inspecting results.

1. Prepare your environment

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

For local development you can reuse the same virtual environment for repeated runs.

2. Select or create a config

Existing configs live under experiments/:

  • default.yml: Baseline settings used by most examples.
  • default_sfit.yml, default_sfit_afit.yml: Variants with alternative adoption/compression targets.
  • semantics_router.yml: Demonstrates semantic routing.
  • cascade_events.yml: Showcases mid-run phonological cascade injections.
  • ilm.yml: Enables the iterated learning model.

To create your own config, copy the default and modify only the sections you need:

cp experiments/default.yml experiments/my_run.yml

Then edit experiments/my_run.yml. Use the Configuration Guide as a reference for available fields.

3. Launch the simulation

Run run.py from the repository root:

python run.py experiments/my_run.yml

Key flags you may want to tweak in the config:

  • seed: For reproducibility across runs.
  • output.data_dir: Change the output folder name (default is the config stem).
  • output.overwrite_output_dir: Set to false to prevent accidental overwrites.

You can also run with no argument to use experiments/default.yml implicitly.

4. Inspect outputs

Results are written under data/<run_name>/ with the following structure:

  • agent_stats/: Per-agent lexicons, signatures, morphology images, and optional detailed logs.
  • pop_stats/: Timeseries TSVs, network frames, morphology grids.
  • summary_stats/: Aggregate plots and optional GIFs.

The run_name defaults to the output.data_dir value. Adjusting that field lets you organise multiple runs side by side.

5. Iterate quickly

  • Cache startup state: Caching is off by default. Set population.cache_params.enabled: true only when you want to reuse initial morphologies and the language settings are unchanged.
  • Reduce output volume: Disable expensive artefacts (agent_stats.images, pop_stats.network_frames) while experimenting.
  • Deterministic variations: Change individual seeds within submodules (e.g., scheduler, network) to explore variability without altering the overall scenario.

6. Analyse or post-process

The project exports ready-made images and GIFs, but you can also load the TSVs in pop_stats/ into notebooks or other tooling. See core/metrics.py for the exact columns written.