Seed bank

Back to Home

Seed bank {#seed-bank}

The seed bank preserves representative genomes so the simulation can reseed lost lineages and analyse long-term diversity. Entries now store full taxonomy (kingdom, genus, species) alongside raw genomes so downstream tooling can reason about specific discoveries.

Capture policy {#capture-policy}

Every captured genome is classified immediately and stored with its taxonomy metadata in seed_bank_taxa. The simulator safeguards against duplicate hashes and only evicts an existing entry when it can do so without violating minimum reserves for the affected kingdom and species.

Species reserve {#species-reserve}

Each kingdom keeps a safety buffer of two slots by default, and the simulator enforces the same floor per species (configurable via Config.evolution.seed_bank_species_reserve, default 2). Eviction candidates must leave at least the reserve count in place for both the kingdom and the species lineage; if no such candidate exists the capture attempt is rejected instead of discarding rare genomes.

Seed usage {#seed-usage}

Seeds from the seed bank are used to reintroduce diversity when the population needs replenishment. The simulator has two main triggers for spawning new organisms from the seed bank:

Repopulation spawning {#repopulation-spawning}

When the population drops below the repopulation threshold (default: 100 organisms), the simulator begins spawning new organisms to restore population levels. Seeds are used with 90% probability when available, falling back to default ancestor genomes otherwise.

  • Trigger: Population < REPOPULATION_START_THRESHOLD (default: 100)
  • Batch size: Up to REPOPULATION_BATCH organisms per step (default: 10)
  • Stop condition: Population reaches REPOPULATION_STOP_THRESHOLD (default: 200)
  • Seed preference: 90% chance to use seed bank, 10% chance to use default ancestor

Stagnation spawning {#stagnation-spawning}

When no births occur for an extended period (stagnation), the simulator injects new organisms to restart evolutionary activity. This prevents complete population collapse during evolutionary dead ends.

  • Trigger: No births for STAGNATION_SPAWN_INTERVAL steps (default: 30,000)
  • Batch size: STAGNATION_SPAWN_COUNT organisms (default: 2)
  • Seed preference: 90% chance to use seed bank, 10% chance to use default ancestor

Diversity bias {#diversity-bias}

When selecting seeds from the bank, the simulator uses a diversity bias strategy:
- Weighted selection: Prefers genomes from the middle/end of the bank (less recently used)
- Mutation on spawn: 10% chance of random mutation during genome copying to maintain diversity
- Usage tracking: Used genomes are moved to the end of the bank and logged for observability

Seed capture {#seed-capture}

Genomes are captured to the seed bank during successful reproduction events:
- Trigger: After successful DIVIDE operation (line 162 in os_calls.py)
- Classification: Immediate taxonomy classification and metadata storage
- Reserve protection: Eviction respects minimum species and kingdom reserves

Checkpoint audit {#checkpoint-audit}

Checkpoint creation reclassifies all stored genomes and tracks the historical maximum count per species. If a species that once met the reserve now falls below it, the checkpoint logger emits a seed_bank_reserve_alert so runs can be investigated before diversity is lost again.