EvolutionEngine: Full Specification and Master Flowchart

The EvolutionEngine is the central orchestrator of EMEP’s evolutionary search loop. It drives the primary pipeline from validated model candidates through evaluation, fitness assignment, selection, and reproduction to discover high-performing merged models. This page specifies the full algorithm, data structures, decision points, and termination conditions for both single-objective and multi-objective optimization modes.

This specification is for a system that has not yet been implemented. All algorithmic details, parameters, and performance characteristics are engineering assumptions unless otherwise tagged.

Master Algorithm Flowchart

The following flowchart describes the complete lifecycle of an evolutionary run from initialization through termination.

Multi-Objective Sub-Flow

When running in multi-objective mode, the fitness calculation and selection steps are replaced by the following sub-flow:

Purpose

The EvolutionEngine performs automated, directed search over the space of possible merged models. It uses evolutionary algorithms to explore combinations of parent models, merge strategies, and hyperparameters to produce candidates that outperform any individual parent on target benchmarks.

Problem Definition

Given a set of base models (M = {m_1, m_2, …, m_n}), a set of merge strategies (S = {s_1, s_2, …, s_k}), and a fitness function (F), find the merged model (m^) that maximizes (F(m^)) subject to constraints on model size, inference latency, and safety thresholds.

Inputs

Input	Type	Description
`base_models`	`List[ModelID]`	Registered models eligible as merge parents
`merge_strategies`	`List[MergeStrategy]`	Strategies available for candidate generation
`evaluation_profile`	`EvaluationProfile`	Benchmark suite and metrics for fitness calculation
`config`	`EvolutionConfig`	Hyperparameters controlling the search
`compute_budget`	`ComputeBudget`	Maximum GPU-hours or wall-clock time

Preconditions

All base_models must be in REGISTERED or EVALUATED lifecycle state.
At least two base models must be marked COMPATIBLE or CONDITIONALLY_COMPATIBLE.
The evaluation_profile must contain at least one benchmark split.
compute_budget must be greater than zero.

Parameters

Parameter	Type	Default	Description
`population_size`	`int`	`50`	Number of individuals maintained per generation
`max_generations`	`int`	`100`	Hard stop after N generations
`max_candidates`	`int`	`5000`	Hard stop after N total candidates evaluated
`no_improvement_n`	`int`	`20`	Stop if best fitness stagnates for N generations
`elitism_count`	`int`	`2`	Top N individuals copied unmodified to next generation
`mutation_rate`	`float`	`0.3`	Probability of applying mutation to an offspring
`crossover_rate`	`float`	`0.7`	Probability of applying crossover to selected parents
`tournament_size`	`int`	`3`	Number of individuals in tournament selection
`diversity_threshold`	`float`	`0.05`	Minimum pairwise genome distance to maintain diversity
`constraint_penalty`	`float`	`1e6`	Penalty applied to constraint-violating candidates

Tensor Shapes

Not applicable at the engine level. Tensor shapes are validated per-candidate by the MergeEngine and TensorEngine.

Mathematical Formulation

Single-Objective Fitness Maximization

\max_{g \in \mathcal{G}} F(g)

Where:

$\mathcal{G}$ is the genome search space
$F(g)$ is the scalar fitness of genome $g$
$F(g) = w_1 \cdot f_1(g) + w_2 \cdot f_2(g) + ... + w_n \cdot f_n(g) - P(g)$
$P(g)$ is the constraint penalty

Multi-Objective Formulation

\max_{g \in \mathcal{G}} \vec{F}(g) = (f_1(g), f_2(g), ..., f_m(g))

Subject to:

$c_i(g) \leq 0$ for all constraints $i$
$g$ produces a valid merged model

Step-by-Step Processing

Initialize Search Space

Enumerate all valid combinations of parent model IDs and merge strategies based on compatibility analysis. Filter out infeasible combinations (e.g., Franken-Merge requires architectural alignment).

Initialize Population

Generate population_size genomes using the configured initialization strategy: random, seeded from known good configurations, or warm-started from a previous experiment.

Validate Candidates

For each genome, invoke ModelCompatibilityAnalyzer to verify parent compatibility. Reject genomes with INCOMPATIBLE parents before merge.

Evaluate Candidates

Dispatch each valid candidate to the EvaluationEngine for benchmark execution. Collect per-metric scores.

Calculate Fitness

Aggregate per-metric scores into a fitness scalar (single-objective) or vector (multi-objective). Apply constraint penalties and regression penalties.

Rank Population

Sort by fitness descending (single-objective) or perform non-dominated sorting (multi-objective).

Check Termination

Evaluate termination criteria in order: max generations, max candidates, compute budget exhausted, no improvement for N generations.

Selection

Select parents for reproduction using tournament, truncation, or rank-based selection. In multi-objective mode, use NSGA-II selection with crowding distance.

Mutation

Apply mutation operators to selected genomes with probability mutation_rate. See Mutation for operator details.

Crossover

Apply crossover operators to pairs of selected genomes with probability crossover_rate. See Crossover for operator details.

Generate Offspring

Produce new genomes from mutated/crossed parents. Ensure population size is maintained.

Validate Offspring

Re-run compatibility and structural validation on new genomes. Reject invalid offspring.

Evaluate Offspring

Dispatch valid offspring to the EvaluationEngine.

Diversity and Constraint Check

Compute pairwise genome distances. If diversity falls below diversity_threshold, inject random immigrants. Re-check constraints.

Next Generation

Combine elites, surviving parents, and valid offspring to form the next generation. Increment generation counter.

Decision Points

Decision	Condition	True Branch	False Branch
Config valid	All required fields present and in range	Proceed to init	Fail with error
Termination met	Any termination criterion satisfied	Output best candidate	Continue to selection
Diversity check	Min pairwise distance >= threshold	Accept offspring	Inject immigrants or penalize
Constraint satisfied	All constraints within bounds	Use raw fitness	Apply penalty or reject
Candidate valid	Merge produces loadable model	Evaluate	Mark INVALID

Branch Conditions

Single-objective branch: Uses weighted sum fitness, tournament selection, and elitism.
Multi-objective branch: Uses Pareto dominance, non-dominated sorting, NSGA-II selection, and returns a Pareto front.
Warm-start branch: If prior experiment lineage exists, seed initial population with top performers from related experiments.

Outputs

Output	Type	Description
`best_candidate`	`Candidate`	Highest fitness individual (single-objective)
`pareto_front`	`List[Candidate]`	Set of non-dominated solutions (multi-objective)
`population_history`	`List[Population]`	Per-generation population snapshots
`fitness_trajectory`	`List[float]`	Best fitness per generation
`experiment_id`	`ExperimentID`	Reference to the tracked experiment

Failure Conditions

Invalid configuration: Missing required fields or out-of-range parameters. Status: FAILED.
No compatible parents: All base model pairs are INCOMPATIBLE. Status: FAILED.
All candidates invalid: Merge or validation fails for every genome. Status: FAILED.
Compute budget exhausted: Wall-clock or GPU-hour limit reached before termination. Status: CANCELLED.
Evaluation failure: EvaluationEngine returns INCOMPLETE for all candidates. Status: FAILED.

Validation

Configuration schema validated against JSON Schema before run start.
All parent model IDs verified against ModelRegistry.
Merge strategy compatibility checked per genome.
Fitness values bounded to prevent NaN/Inf propagation.

Complexity

Phase	Complexity	Notes
Initialization	$O(P \cdot C)$	$P$ = population size, $C$ = compatibility checks
Evaluation	$O(P \cdot E)$	$E$ = evaluation cost per candidate (dominates)
Selection	$O(P \cdot \log P)$	Tournament or rank-based
Non-dominated sorting	$O(M \cdot P^2)$	$M$ = number of objectives
Per generation	$O(P \cdot (E + M \cdot P))$	Evaluation dominates in practice

Memory Requirements

Population storage: $O(P \cdot G)$ where $G$ is genome size (typically < 1 KB per genome).
Model checkpoint caching: $O(K \cdot S)$ where $K$ = cached candidates, $S$ = model size.
Fitness trajectory: $O(G_{max})$ where $G_{max}$ = max generations.

Numerical Stability

Fitness scores clipped to $[-10^6, 10^6]$ to prevent overflow.
Constraint penalties additive, not multiplicative, to avoid gradient collapse.
Crowding distance computation uses normalized objective ranges.

Precision Considerations

Fitness aggregation uses float64 to prevent precision loss across many objectives.
Alpha coefficients stored as float32 in genomes (sufficient for merge operations).
Generation counter: int64.

Reproducibility

Random seeds set for population initialization, mutation, and selection.
All hyperparameters logged to ExperimentTracker.
Genome lineage tracked via parent pointers for full provenance.

Unit Tests

Test	Description
`test_init_population_size`	Assert population size equals config
`test_termination_max_generations`	Stop exactly at max generations
`test_termination_no_improvement`	Stop after N stagnant generations
`test_elitism_preserved`	Top N individuals survive unmodified
`test_invalid_config_rejected`	Schema validation catches bad config
`test_multi_objective_returns_front`	Output is a valid Pareto front

Integration Tests

Test	Description
`test_end_to_end_single_objective`	Full run with mock EvaluationEngine
`test_end_to_end_multi_objective`	Full run with two objectives
`test_warm_start_from_lineage`	Seed from prior experiment
`test_compute_budget_enforced`	Stop before max generations if budget exhausted
`test_diversity_injection`	Low diversity triggers immigrant injection

Acceptance Criteria

Single-objective run produces a candidate with fitness greater than best parent baseline (Research hypothesis).
Multi-objective run produces a Pareto front with at least two non-dominated solutions.
Termination criteria are independently configurable and correctly enforced.
All experiment states transition correctly: CREATED → PREPARING → RUNNING → EVALUATING → COMPLETED.
Full lineage traceable from any output candidate to its original parents.

Known Limitations

Evaluation cost dominates runtime; no asynchronous or batched evaluation specified yet (Future goal).
No adaptive hyperparameter tuning during the run (Research hypothesis).
Diversity metric is Hamming distance on genome encoding; may not reflect phenotypic diversity (Engineering assumption).

Research References

Evolutionary Model Merge: Akiba et al. 2024
NSGA-II: Deb et al. 2002 (for multi-objective selection)
Model Soups: Wortsman et al. 2022 (for weighted merging baseline)