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, sets up the domain, 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
  replay                 Replay simulation (not yet implemented)

---

quale evolve

Compiles a .quale project and runs the evolutionary loop.

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.
--domain <name>	survival	Domain layer to use for the experiment. Available domains are listed in the help text.

Behavior

1. Compiles the .quale project through the parser, validator, and 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. Looks up the domain from the registry and calls Domain.Configure()
6. Creates the EvolutionEngine with the compiled configuration
7. Either resumes from a checkpoint or initializes a fresh population
8. Prints a run banner showing population size, generations, seed, and sensor/actuator counts
9. Runs the evolutionary loop until convergence or the generation limit
10. Saves periodic checkpoints to checkpoints/<run_name>/
11. Saves a final checkpoint on completion
12. Prints the best genome’s fitness and topology

Examples

# Run a single-file experiment with default domain (survival)
quale evolve experiment.quale

# Run a directory project
quale evolve my_experiment/

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

# Override the random seed
quale evolve experiment.quale --seed 123

# Resume from a checkpoint
quale evolve experiment.quale --resume checkpoints/phase1/checkpoint_gen100.quale-ckpt

# Use a specific domain
quale evolve experiment.quale --domain mydomain

# Combine flags
quale evolve my_experiment/ --run Phase2 --seed 42 --domain survival

---

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)

---

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), not the system clock directly.

Checkpoints are written to checkpoints/<run_name>/ relative to the current working directory.