quale evolve

The quale command line tool compiles, validates, runs, and inspects Quale experiments.

quale evolve is the primary command for running evolution experiments. It compiles your .quale files to bytecode, sets up the GenericDomain, and runs the full evolutionary loop until the generation limit or convergence - printing progress each generation and saving checkpoints along the way. This is the command you run when you are ready to let evolution do its work.

quale <command> [options]

Commands:
  evolve  <file-or-dir>  Run evolution experiment
  check   <file-or-dir>  Validate without running
  inspect <checkpoint>   Inspect evolved topology
  export  <file>         Extract/convert brain from checkpoint or brain file
  serve   [--port 8094]  Start API server for checkpoint data
  replay  <checkpoint>   Replay scenario with tick-by-tick brain activity
  export-demo <dir> --output <dir>  Export demo experiment for R2 upload

---

quale evolve

Compiles a .quale project to bytecode and runs the evolutionary loop.

All .quale files use the GenericDomain, which compiles perception, action, state machines, entity interactions, and fitness blocks into bytecode.

quale evolve <file-or-dir> [flags]

Arguments

Argument	Description
<file-or-dir>	Path to a single .quale file or a directory containing .quale files

Flags

Flag	Default	Description
--run <Name>	(sole evolve block)	Specify which evolve block to run when a project contains multiple evolve blocks. If the project has exactly one evolve block, this flag is optional.
--seed <N>	(from .quale file)	Override the random seed specified in the .quale file. When set to a non-zero value, this takes precedence over the seed in the evolve block.
--resume <path>	(none)	Resume evolution from a checkpoint file (.quale-ckpt). The checkpoint’s population, generation counter, best genome, and innovation state are restored.
--gpu	false	Use the C compute library for GPU-accelerated scenario evaluation. Requires the GPU library in gpu/ to be built first via CMake.
--cpu	true	Use CPU for scenario evaluation (default).

Behavior

1. Compiles the .quale project through the parser, validator, and bytecode compiler pipeline
2. Prints any warnings to stderr
3. If compilation errors are found, prints them to stderr and exits with code 1
4. Applies the --seed override if provided
5. Configures the GenericDomain with the compiled project (bytecode programs for perception, action, machines, entity handlers, and fitness)
6. Creates the EvolutionEngine with the compiled configuration
7. Initializes the GPU compute library if --gpu is set
8. Either resumes from a checkpoint, seeds from a previous run’s checkpoint (via seed_from in the evolve block), or initializes a fresh population
9. Prints a run banner showing population size, generations, seed, sensor/actuator counts, and eval mode (CPU or GPU)
10. Runs the evolutionary loop until convergence or the generation limit
11. Saves periodic checkpoints to checkpoints/<run_name>/
12. Saves a final checkpoint and the best brain (.quale-brain) on completion
13. Prints the best genome’s fitness and topology

Examples

-- Run a single-file experiment
quale evolve rail-driver.quale

-- Run a directory project
quale evolve my_experiment/

-- Run a specific evolve block in a multi-block project
quale evolve my_experiment/ --run SignalCompliance

-- Override the random seed
quale evolve rail-driver.quale --seed 123

-- Resume from a checkpoint
quale evolve rail-driver.quale --resume checkpoints/signalcompliance/checkpoint_gen100.quale-ckpt

-- Use GPU acceleration
quale evolve rail-driver.quale --gpu

-- Combine flags
quale evolve my_experiment/ --run Phase2 --seed 42 --gpu

---

Exit Codes

Code	Meaning
0	Success
1	Compilation error (syntax, validation), usage error, or checkpoint load failure in inspect
2	Runtime error (domain configuration failure, checkpoint load failure in evolve --resume, GPU init failure)

---

Input Formats

Format	Used By	Description
.quale file	evolve, check	Quale DSL source file
.quale directory	evolve, check	Directory of .quale files (merged automatically)
.quale-ckpt file	evolve --resume, inspect	Checkpoint with full population state

---

Environment

Quale does not read any environment variables. All configuration comes from the .quale files and CLI flags. When no seed is specified via --seed or the seed field in the evolve block, the runtime generates a random seed using rand.Uint64() (Go’s automatically-seeded global RNG).

Checkpoints are written to checkpoints/<run_name>/ relative to the current working directory. A best.quale-brain file is saved alongside the checkpoints when evolution completes.

The evolve command starts a pprof HTTP server on localhost:6060 for heap profiling and logs memory statistics to stderr every 10 seconds. A 20GB memory limit is enforced - Go will panic with a stack trace rather than consuming all available memory.