Configuration Tuning Guide

Configuration Tuning Guide

This guide covers parameter tuning for ByteBiota simulation stability and evolution dynamics.

Configuration Parsing {#config-parsing}

The configuration system parses environment variables from .env files. Important: Inline comments in configuration values cause parsing errors. Use clean values without comments:

# ❌ WRONG - causes parsing error
ENV_HARVEST_YIELD=100            # Increased from 90 (11% increase)

# ✅ CORRECT - clean value
ENV_HARVEST_YIELD=100

The system automatically strips comments using .split('#')[0].strip() for affected parameters.

Parameter Categories {#parameter-categories}

Energy Management

  • ENERGY_INITIAL: Starting energy for new organisms (default: 300)
  • ENERGY_MAX: Maximum energy cap (default: 500)
  • CPU_COST_PER_INSTRUCTION: Energy cost per CPU instruction (default: 0.0004)
  • MEMORY_RENT_PER_BYTE: Energy cost per byte of memory (default: 0.00008)
  • CHILD_ENERGY_REQUIREMENT: Energy needed for reproduction (default: 25)

Resource Harvesting

  • HARVEST_MULTIPLIER: Energy gained per resource unit (default: 5.0)
  • TASK_BONUS: Energy bonus for completing tasks (default: 150)
  • PRIORITY_BOOST_DURATION: Duration of priority boost after task completion (default: 20)

Environment

  • ENV_MAX_RESOURCE: Maximum resources in environment (default: 2500)
  • ENV_RESOURCE_REGEN_AMOUNT: Resources regenerated per cycle (default: 120)
  • ENV_RESOURCE_REGEN_INTERVAL: Cycles between regeneration (default: 45)
  • ENV_HARVEST_YIELD: Resources gained per harvest action (default: 100)

Mutation and Evolution

  • COPY_BIT_FLIP_RATE: Probability of bit flip during genome copying (default: 0.002)
  • INSERTION_DELETION_RATE: Probability of genome length changes (default: 0.0002)
  • BACKGROUND_FLIP_INTERVAL: Cycles between background mutations (default: 5000000)

Tuning Strategies {#tuning-strategies}

For Population Stability

  1. Enable Reproduction: Lower CHILD_ENERGY_REQUIREMENT and reduce energy costs
  2. Prevent Collapse: Increase MIN_POPULATION_FOR_REAP and adjust reaper thresholds
  3. Resource Balance: Ensure HARVEST_MULTIPLIER × ENV_HARVEST_YIELD provides sufficient energy

For Diversity Maintenance

  1. Mutation Rates: Balance COPY_BIT_FLIP_RATE and INSERTION_DELETION_RATE
  2. Selection Pressure: Adjust reaper parameters to prevent clonal takeover
  3. Seed Bank: Increase SEED_BANK_SIZE for genetic diversity preservation

For Performance

  1. Resource Limits: Set appropriate RESOURCE_PRESET for system capabilities
  2. Memory Management: Adjust MEMORY_REAP_THRESHOLD and MAX_OCCUPANCY_RATIO
  3. Scheduling: Tune SLICER_POWER and BASE_SLICE for execution efficiency

Common Issues {#common-issues}

Configuration Parsing Errors

  • Symptom: ValueError: invalid literal for int() with base 10
  • Cause: Type conversion mismatch (e.g., float value converted to int) or inline comments in environment variable values
  • Fix: Ensure correct data types in config parsing and remove comments from configuration values

Type Conversion Bugs

  • Symptom: Server crashes on startup with type conversion errors
  • Cause: Mismatch between expected data type in config structure and environment variable parsing
  • Example: CHILD_ENERGY_REQUIREMENT=0.5 (float) being converted with int() instead of float()
  • Fix: Update config structure and parsing code to use consistent data types

Worker Statistics Errors

  • Symptom: AttributeError: 'NoneType' object has no attribute 'state'
  • Cause: Environment not initialized when collecting statistics
  • Fix: Add null checks in statistics collection code

Population Collapse

  • Symptom: Population drops below 10 organisms
  • Causes: High energy costs, insufficient resources, aggressive reaping
  • Fixes: Lower energy costs, increase resource availability, adjust reaper thresholds

Infinite Growth

  • Symptom: Unbounded population growth
  • Causes: Too many resources, insufficient reaping, low energy costs
  • Fixes: Reduce resource regeneration, increase energy costs, lower reaper thresholds

Back to Home