Evolve

The evolve block ties everything together - it is the “run” button that tells the engine which body, world, perception, action, and fitness definition to use, and how many generations to run. Every other construct 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 constructs:

body <Name> { ... }          -- Agent state layout and brain interface
world <Name> { ... }         -- Simulation environment with entities
perception <Name> { ... }    -- World/agent state to brain sensor values
action <Name> { ... }        -- Brain actuator outputs to world changes
dynamics <Name> { ... }      -- Per-tick state cascade rules
fitness <Name> { ... }       -- Gates, metrics, and optimization objectives
evolve <Name> { ... }        -- Evolution experiment configuration

Evolve Block

Configures the evolution experiment. References all named constructs. Machines are automatically included via their parent body or world blocks.

evolve HumanFactorsDemo {
    body: Operator
    world: OperatorRoute
    perception: OperatorSenses
    action: OperatorActions
    fitness: OperatorAssessment
    dynamics: OperatorPhysiology

    population: 200
    generations: 1000
    scenarios: 3
    ticks: 6000
    seed: 42
    agents: 1
}

evolve NetworkSecurityDemo {
    body: Sentinel
    world: TrafficStream
    perception: TrafficAnalysis
    action: SecurityResponse
    fitness: DetectionAssessment

    population: 200
    generations: 1000
    scenarios: 5
    ticks: 3000
    seed: 42
    agents: 1
}

evolve SurvivalDemo {
    body: Forager
    world: ForestFloor
    perception: ForagerSenses
    action: ForagerActions
    fitness: SurvivalAssessment
    dynamics: ForagerMetabolism

    population: 200
    generations: 500
    scenarios: 5
    ticks: 300
    seed: 42
    agents: 1
}

Complete Field Reference

Block references (link the experiment to its component definitions):

Field	Required	Description
`body`	Yes	Reference to a body definition (includes agent machines)
`world`	Yes	Reference to a world definition (includes world machines and entities)
`perception`	Yes	Reference to a perception definition
`action`	Yes	Reference to an action definition
`fitness`	Yes	Reference to a fitness definition
`dynamics`	No	Reference to a dynamics definition

Experiment parameters:

Field	Type	Default	Description
`population`	int	200	Genomes in the population
`generations`	int	5000	Maximum generations
`scenarios`	int	5	Random scenarios per evaluation
`ticks`	int	300	Steps per scenario
`seed`	int	random	Random seed (0 = `rand.Uint64()` from Go’s auto-seeded global RNG)
`agents`	int	1	Brain instances per scenario (1 or 2)
`seed_from`	string	none	Seed population from a previous checkpoint path

Optional sub-blocks:

Sub-block	Description
`mutation { ... }`	Mutation rate configuration
`speciation { ... }`	Speciation parameters
`convergence { ... }`	Convergence (early stop) criteria
`checkpoint { ... }`	Checkpoint save configuration

The dynamics field is optional. The Network Security demo omits it entirely since the IDS agent has no physiological state that changes over time independent of actions.

Cross-Reference Validation

The compiler validates that all blocks are consistent:

Perception sensor assignments match body sensor declarations
Action actuator reads match body actuator declarations
Perception and action spatial query calls match world query declarations
All agent.* references across all blocks match body state declarations
Fitness record references match record types emitted by entity interaction handlers
Machine scope visibility rules are enforced

Evolution Sub-Blocks

The evolve block supports optional sub-blocks for fine-tuning evolution parameters. These have sensible defaults and can be omitted.

evolve Tuned {
    body: Operator
    world: OperatorRoute
    perception: OperatorSenses
    action: OperatorActions
    fitness: OperatorAssessment
    dynamics: OperatorPhysiology

    population: 300
    generations: 2000
    scenarios: 5
    ticks: 6000
    seed: 42
    agents: 1

    mutation {
        weight_shift:      0.8
        bias_shift:        0.5
        add_connection:    0.15
        remove_connection: 0.05
        add_node:          0.03
        remove_node:       0.01
        rewire:            0.02
        change_activation: 0.02
    }

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

    convergence {
        plateau:   200 generations
        threshold: 0.001
    }

    checkpoint {
        every: 1 generations
        keep:  99999
    }
}

mutation Sub-Block

Controls the probability of each mutation type per offspring.

Field	Type	Default	Description
`weight_shift`	float	0.8	Probability of perturbing a connection weight
`bias_shift`	float	0.5	Probability of perturbing a node bias
`add_connection`	float	0.15	Probability of adding a new connection
`remove_connection`	float	0.05	Probability of removing an existing connection
`add_node`	float	0.03	Probability of splitting a connection with a new hidden node
`remove_node`	float	0.01	Probability of removing a hidden node
`rewire`	float	0.02	Probability of moving one end of a connection
`change_activation`	float	0.02	Probability of changing a node’s activation function

speciation Sub-Block

Controls how the population is divided into species for diversity preservation.

Field	Type	Default	Description
`threshold`	float	3.0	Compatibility distance threshold for same-species membership
`target_species`	int	15	Target number of species (threshold auto-adjusts toward this)
`stagnation`	int + unit	25 generations	Generations without improvement before a species is dissolved

convergence Sub-Block

Controls when evolution stops automatically.

Field	Type	Default	Description
`plateau`	int + unit	200 generations	Generations without global fitness improvement before stopping
`threshold`	float	0.001	Minimum improvement delta to count as progress

checkpoint Sub-Block

Controls how checkpoints are saved during evolution.

Field	Type	Default	Description
`every`	int + unit	1 generation	Save a checkpoint every N generations
`keep`	int	99999	Maximum number of checkpoints to retain on disk

seed_from

Seeds the initial population from a previous experiment’s checkpoint.

evolve Phase2 {
    seed_from: "checkpoints/phase1/best.quale-ckpt"
    ...
}

Comments

-- Line comment

--! Note
--!! Critical note

--[ Block comment
    can span multiple lines ]--

Syntax	Type	Behavior
`--`	Line comment	Discarded by the parser
`--!`	Note	Preserved in AST; shown by `quale check`
`--!!`	Critical	Preserved in AST; fails `quale check --strict`
`--[ ... ]--`	Block comment	Multi-line; discarded by the parser

Tick Loop

The simulation tick loop is defined by the blocks referenced in the evolve block:

Step	Source	Description
1	World machines	`scope: world` machines update world state
2	Perception	Transforms world + agent state into brain sensor values
3	Brain fires	Signal propagation through the connectome (engine, fixed)
4	Action	Interprets actuator outputs through physics, moves agent, triggers entity interactions
5	Agent machines	`scope: agent` machines handle state transitions
6	Dynamics	Per-tick state cascade (fatigue, stress, boredom)
7	Accumulators	Per-tick fitness metric running sums (engine, automatic)

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

-- 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/