SPECTER Labs
Technical Docs contracts

Research Modes

Defines the paper-grounded entrypoints in lenia-swarm.

Implementation detail belongs in PaperGroundedLanes.

Registry

Mode Paper anchor Public entrypoint Paper configs Current scope
Flow tasks Flow-Lenia 2022 evolve configs/papers/flowlenia-2022/ task-conditioned optimization
RD validation Reaction-Diffusion Lenia 2023 reaction-diffusion-2023 configs/papers/reaction-diffusion-lenia-2023/ mathematical validation/emulation
Sensorimotor Hamon et al. 2024 sensorimotor-2024 configs/papers/sensorimotor-lenia-2024/ goal-conditioned diversity search
QD LeniaBreeder 2024 qd-2024 configs/papers/leniabreeder-2024/ MAP-Elites and AURORA repertoire search
Ecology Flow-Lenia ecology 2025 ecology-2025 configs/papers/flowlenia-ecology-2025/ intrinsic-evolution ecology runs
Curiosity AI scientist 2025 curiosity-2025 configs/papers/ai-scientist-2025/ curiosity-driven universe exploration
Atlas Lenia parameter space 2026 atlas-2026 configs/papers/lenia-atlas-2026/ classical Lenia atlas runs

Retired user-facing names:

  • leniabreeder-2024
  • flowlenia-ecology-2025
  • ai-scientist-2025

Those names may still appear in config directories and older artifacts because they remain provenance labels.

Shared Rules

  • Paper-specific logic must live above the shared simulator.
  • No research mode may silently change the core Flow-Lenia equations.
  • The invariant guard is LeniaCoreTests.swift, especially testPopulationKernelsMatchSingleKernelPath.
  • Durable run outputs should go to SPECTER_ARTIFACT_ROOT when set; otherwise the mode writes to the explicit --output path.
  • Contract changes to run outputs must remain deterministic and rerunnable from captured configs.

Mode Surfaces

Flow tasks

Entrypoint:

  • LeniaCLI evolve --config <task.json> --es <optimizer.json> --output <dir>

Primary outputs:

  • summary.json
  • history.jsonl
  • task-specific run artifacts captured by evolve

Notes:

  • This mode is for explicit objectives such as directed motion, angular motion, obstacle navigation, and chemotaxis.
  • It is not a repertoire builder and it is not a compendium writer.

RD validation

Entrypoint:

  • LeniaCLI reaction-diffusion-2023 --config-dir <dir> --output <dir>

Primary outputs:

  • summary.json
  • validation/emulation reports written by the mode

Notes:

  • This mode is a validator.
  • It is not a discovery lane and it does not write compendium rows.

Sensorimotor

Entrypoint:

  • LeniaCLI sensorimotor-2024 --config-dir <dir> --output <dir>

Primary outputs:

  • summary.json
  • history.jsonl
  • archive/evaluation artifacts written by the mode

Notes:

  • This mode implements the 2024 agency-discovery protocol.
  • It is archive-based, not compendium-indexed.

QD

Entrypoints:

  • LeniaCLI qd-2024 --config-dir <dir> --algorithm me --output <dir>
  • LeniaCLI qd-2024 --config-dir <dir> --algorithm aurora --output <dir>
  • LeniaCLI qd-2024 --distributed --algorithm me ...

Primary outputs:

  • summary.json
  • history.jsonl
  • metrics.csv
  • best.json
  • repertoire/centroids.json
  • repertoire/occupied.json

Additional outputs:

  • aurora-diagnostics.jsonl for AURORA
  • distributed.json for distributed MAP-Elites

Notes:

  • qd-2024 writes repertoire artifacts, not run-library exports.
  • qd-2024 is not auto-indexed into compendium.sqlite.
  • There is currently no built-in bridge from qd-2024 outputs to:
    • compendium indexing
    • taxonomy assignment
    • ecology export
    • morphometrics thresholding
  • Distributed support currently exists for --algorithm me only.

Ecology

Entrypoint:

  • LeniaCLI ecology-2025 --config-dir <dir> --output <dir>

Primary outputs:

  • summary.json
  • ecology metrics/artifacts written by the mode

Notes:

  • This mode studies long-run ecosystem dynamics.
  • It is separate from the compendium/indexer pipeline.

Curiosity

Entrypoint:

  • LeniaCLI curiosity-2025 --config-dir <dir> --output <dir>

Primary outputs:

  • summary.json
  • archive/coverage artifacts written by the mode

Notes:

  • This mode is system-level exploration, not per-creature indexing.

Atlas

Entrypoint:

  • LeniaCLI atlas-2026 --config-dir <dir> --output <dir>

Primary outputs:

  • summary.json
  • data/phases/*.json
  • data/kernels/**/mu_*/sigma_*.json

Notes:

  • This mode maps classical parameter space.
  • It does not auto-populate the compendium.

Compendium Boundary

The compendium remains the indexed database produced by LeniaCLI index.

Relevant docs:

Current writer-of-record surfaces:

  • LeniaCLI index
  • LeniaCLI local when auto-indexing is enabled

Research modes do not become compendium-visible unless they emit an artifact layout that the indexer understands and are then indexed explicitly.

Current status by mode:

Mode Auto-indexes into compendium Emits indexer-ready library/export bundles
Flow tasks No No
RD validation No No
Sensorimotor No No
QD No No
Ecology No No
Curiosity No No
Atlas No No

Apple Silicon Note

These modes are intended to run on the MLX/Metal path on Apple Silicon.

Current performance facts that affect the contract:

  • batched evaluation is the default expectation for the heavy modes,
  • qd-2024 has local and distributed MAP-Elites paths,
  • reintegrationBatched remains the main custom-kernel candidate if another major speed step is needed.

Papers