Scripts

Scripts

Back to Home

Command-line and monitoring utilities augment the core simulator with analysis, diagnostics, and live dashboards. Use this page to track each script’s responsibilities and expected inputs.

Kill processes {#killprocesses}

killprocesses.sh terminates all ByteBiota server/worker processes and frees ports 8080.

  • Invocation: ./killprocesses.sh
  • Behavior: Searches by common uvicorn and CLI patterns, kills matched PIDs, then validates nothing remains bound to 8080.
  • Worker Detection: Specifically targets zsh processes containing python -m bytebiota worker commands and direct Python processes running src.bytebiota.worker.worker.
  • Notes: On some systems it may prompt for sudo to terminate foreign processes.

Worker Health Test {#worker-health-test}

test_worker_health.sh runs a comprehensive 2-minute health test of the distributed ByteBiota system with work progress validation.

  • Invocation: ./test_worker_health.sh
  • Duration: 2 minutes with work progress checks at 60s and 120s
  • Work Progress Check: Fails if step_count doesn't increase between 60s and 120s measurements
  • Final Validation: Requires population > 10 organisms after 2 minutes
  • Metrics: Work done (step_count), population growth, server/worker connectivity
  • Output: Color-coded console output with detailed debugging information on failure
  • Dependencies: Requires jq, python, lsof for full functionality
  • Cleanup: Automatically cleans up processes using killprocesses.sh before and after test
  • Step Counting Fix: The test validates that the server properly accumulates step counts from worker results instead of just incrementing by 1
  • Progress Validation: The test now accepts systems that execute significant work (>1000 steps) even if there's no progress between checkpoints, handling cases where organisms die quickly but the distributed system is functioning correctly
  • Critical Bug Detection: The test correctly identifies when the distributed system is not working - specifically when organisms die too quickly and the worker fails to submit results, causing the simulation to stall
  • Worker Result Submission Fix: The test now uses TARGET_INTERVAL_SECONDS=1 to ensure aggressive result submission, and the assignment handler has been fixed to always return ExecutionResults even when all organisms die
  • Memory Allocation Investigation: The test revealed that organisms cannot reproduce due to memory allocation failures ("ALLOCATION FAILED: Organism X needs 64 bytes but allocation failed"), preventing population growth despite generous energy parameters
  • Configuration Analysis: Comparison with working single machine version (20M steps, 333 organisms) revealed that the test was using overly aggressive energy parameters; updated to use proven working configuration from single machine version
  • Organism ID Bug Fix: Fixed critical bug where StateAggregator._get_next_organism_id() was resetting to ID 1 when all organisms died, preventing new organisms from getting unique IDs; now uses server's global organism ID counter
  • Energy Economy Investigation: Added detailed energy flow instrumentation to worker executor to track energy gains/losses. Created comprehensive energy analysis script showing ancestor program loses 28.52 energy per reproduction cycle with original parameters
  • Energy Parameter Optimization: Adjusted energy parameters to make system more sustainable: reduced CPU cost (0.04→0.02), memory rent (0.0025→0.001), reproduction cost (25→15), increased harvest multiplier (1.2→2.0) and yield (10→15). New parameters show +58.20 energy gain per cycle
  • Reproduction Logic Issue: Despite energy improvements, organisms show "Reproduction attempts: 0" in all test runs, indicating fundamental issue with ancestor program execution or reproduction logic in distributed system

Experiment Diagnostics {#experiment-diagnostics}

scripts/experiment_diagnostics.py scans JSONL logs to produce population, energy, and diversity summaries plus heuristic recommendations. Update this section as new metrics or report formats are added.

Taxonomy Classifier {#taxonomy-classifier}

scripts/taxonomy_classifier.py classifies genomes stored in checkpoints with TaxonomyClassifier, printing lineage details and species summaries. Document output schema changes and new filtering options here.

Monitor {#monitor}

scripts/monitor.py hosts a lightweight HTTP dashboard that visualises live metrics and mutation trends from experiment logs. Record any endpoint changes, UI tweaks, or deployment notes in this section.

Genome Analyzer {#genome-analyzer}

scripts/genome_analyzer.py inspects checkpoint genomes, reporting opcode mixes, structural loops, and invalid instructions. Update this section when expanding opcode coverage or analysis features.