Evolve

The evolve block is what ties everything together - it is the “run” button that tells the engine which body, world, items, and fitness definition to use, and how many generations to run. Every other construct (body, items, world, dynamics, fitness) is just a definition until an evolve block references it. You can have multiple evolve blocks in a project to run different experiments with different configurations, selecting between them via the --run flag.

File Structure

A Quale project is either a single file or a directory of .quale files.

quale evolve experiment.quale        # single file
quale evolve my_experiment/            # directory (all .quale files merged)
quale check  experiment.quale        # validate without running
quale inspect checkpoint.quale-ckpt  # inspect evolved topology

Top-Level Constructs

Every .quale file contains one or more of these six constructs:

body <Name> { ... }       // What the agent can sense and do
item <Name> { ... }       // Things in the world the agent encounters
world <Name> { ... }      // The environment configuration
dynamics <Name> { ... }   // State cascade rules
fitness <Name> { ... }    // What "success" means
evolve <Name> { ... }     // The evolution experiment configuration

---

Evolve Block

Configures the evolution experiment. References body, items, world, fitness, and optionally dynamics by name.

evolve ForagingExperiment {
    // Required references
    body:        Agent
    items:       [SafeFood, DangerousFood, Water]
    world:       ForestFloor
    fitness:     ForagerGoals
    dynamics:    Metabolism  // optional - state cascade rules

    // Evolution parameters
    population:  300
    generations: 2000
    scenarios:   5            // random scenarios per genome evaluation
    ticks:       300          // steps per scenario
    seed:        42           // random seed (0 = system clock)
    agents:      1            // brain instances per scenario (1 or 2)

    // Optional: seed from previous experiment
    // seed_from: Phase1                          // by evolve block name
    // seed_from: "checkpoints/phase1.quale-ckpt" // by file path

    // Optional blocks (omitted = sensible defaults)
    mutation {
        weight_shift:      0.8
        bias_shift:        0.1
        add_connection:    0.05
        remove_connection: 0.03
        add_node:          0.03
        remove_node:       0.01
        rewire:            0.02
        change_activation: 0.01
    }

    speciation {
        threshold:      3.0
        target_species: 15
        stagnation:     15 generations
    }

    convergence {
        plateau:   200 generations
        threshold: 0.5
    }

    checkpoint {
        every: 100 generations
        keep:  3
    }
}

Required Fields

Field	Description
body	Reference to a body definition
items	List of item definitions [Name1, Name2, ...]
world	Reference to a world definition
fitness	Reference to a fitness definition

Optional Fields

Field	Default	Description
dynamics	none	Reference to a dynamics definition
population	200	Genomes in the population
generations	5000	Maximum generations
scenarios	5	Random scenarios per evaluation
ticks	300	Steps per scenario
seed	random	Random seed (0 = rand.Uint64() from Go’s auto-seeded global RNG)
agents	1	Brain instances per scenario (1 or 2)
seed_from	none	Parsed and compiled but not yet wired to the CLI runtime. Use --resume for checkpoint loading.

---

Comments

// Line comment

/* Block comment
   can span multiple lines */

Block comments do not nest.

---

CLI Commands

# Run evolution
quale evolve experiment.quale
quale evolve experiment.quale --seed 123    # override seed
quale evolve experiment.quale --run Phase2  # specific evolve block
quale evolve experiment.quale --resume checkpoints/checkpoint_gen100.quale-ckpt
quale evolve experiment.quale --domain mydomain     # use a specific domain layer

# Validate without running
quale check experiment.quale

# Inspect checkpoint
quale inspect checkpoint.quale-ckpt

# Directory projects (all .quale files merged)
quale evolve my_experiment/
quale check my_experiment/

---

Quick Examples

Minimal Experiment

body Simple {
    sensor energy: internal(0..1)
    actuator act:  trigger(threshold: 0.5)
}

item Resource {
    category: resource
    properties { value: 1.0 }
    on_consume { energy: +0.5 }
}

world Tiny {
    size: 5 x 5
    walls: border
    item_respawn: 20 ticks
    spawn resource: 3
}

fitness Goal {
    maximize survival: 10.0
    maximize energy:    5.0
}

evolve Test {
    body: Simple
    items: [Resource]
    world: Tiny
    fitness: Goal
    population: 50
    generations: 100
    ticks: 100
}

Multi-Agent Social Experiment

body Social {
    sensor health:       internal(0..1)
    sensor peer_nearby:  directional(range: 15, directions: 4)
    sensor peer_health:  social(health)
    actuator move:       directional(threshold: 0.5, directions: 4)
}

// ... items, world, fitness ...

evolve SocialTest {
    // ...
    agents: 2     // two brain instances per scenario
}