> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# EvolutionEngine Specification for EMEP

> Specification for the EvolutionEngine component in EMEP, covering the full evolutionary optimization loop for model merging and candidate generation.

The EvolutionEngine drives EMEP's search for high-performing merged models. It orchestrates the full evolutionary loop: population initialization, candidate validation, fitness evaluation, selection, mutation, crossover, and termination. This page specifies the complete flow, state transitions, and integration points with other EMEP components.

## Evolution Loop Flowchart

The engine follows a fixed generational loop. Each iteration produces, validates, and evaluates offspring before updating the population.

```mermaid theme={null}
flowchart TD
    START([START]) --> INIT[Initialize Search Space]
    INIT --> POP[Initialize Population]
    POP --> VALIDATE[Validate Candidates]
    VALIDATE --> EVAL[Evaluate Candidates]
    EVAL --> FITNESS[Calculate Fitness]
    FITNESS --> RANK[Rank Candidates]
    RANK --> SELECTION[Selection]
    SELECTION --> CHECK{Check Termination?}
    CHECK -->|Yes| TERM[Termination]
    CHECK -->|No| MUT[Mutation]
    MUT --> CROSS[Crossover]
    CROSS --> OFFSPRING[Generate Offspring]
    OFFSPRING --> VALIDATE_OFF[Validate Offspring]
    VALIDATE_OFF --> EVAL_OFF[Evaluate Offspring]
    EVAL_OFF --> DIV[Diversity / Constraint Check]
    DIV --> NEXT[Next Generation]
    NEXT --> VALIDATE
    TERM --> OUTPUT[Best Candidate / Pareto Front]
    OUTPUT --> END([END])
```

## Phase Descriptions

**Initialize Search Space**

The engine reads the ModelRegistry to discover available parent models. It builds a search space of possible merge configurations based on registered, validated, and compatible models. Only models in VALIDATED or REGISTERED state are eligible.

**Initialize Population**

The first generation is created using one or more initialization strategies: random, seeded from known good candidates, or Latin hypercube sampling. Population size is configurable. The Population component manages size and diversity targets.

**Validate Candidates**

Each candidate passes through the ModelCompatibilityAnalyzer. Candidates receive COMPATIBLE, CONDITIONALLY\_COMPATIBLE, or INCOMPATIBLE status. Only COMPATIBLE and CONDITIONALLY\_COMPATIBLE candidates proceed. INCOMPATIBLE candidates are discarded with a logged reason.

**Evaluate Candidates**

The EvaluationEngine runs each candidate through the benchmark suite. Metrics are collected from the Optimization Set only. The Hidden Test Set is never used during evolution. This isolation prevents overfitting the search process.

**Calculate Fitness**

The FitnessEngine computes scalar or vector fitness values. Fitness is computed solely from the Optimization Set. The Validation Set and Hidden Test Set are reserved for post-evolution reporting.

**Rank Candidates**

Candidates are ranked by fitness. For single-objective runs, this is a simple sort. For multi-objective runs, non-dominated sorting and crowding distance (NSGA-II, Deb et al. 2002) determine ranking.

**Selection**

The Selection component chooses parents for the next generation. Supported selectors include tournament, truncation, elitism, and roulette. Elitism preserves the top-performing candidates unconditionally.

**Check Termination**

Termination triggers when any of the following conditions are met:

* Maximum generations reached
* Fitness plateau (no improvement for N generations)
* Diversity collapse (population variance below threshold)
* Target fitness achieved
* User cancellation

**Mutation and Crossover**

The Mutation and Crossover components generate offspring genomes. Mutation applies alpha jitter, per-layer perturbation, strategy switches, or density adjustment. Crossover combines parent genomes through uniform, one-point, or arithmetic blend operators.

**Validate and Evaluate Offspring**

Offspring repeat the validation and evaluation pipeline. Invalid or failed candidates are logged and excluded from the population update.

**Diversity and Constraint Check**

The engine enforces diversity minimums and hard constraints. If diversity falls below threshold, the engine injects random immigrants or expands the search space.

**Next Generation**

The new population replaces the old. Elite candidates carry forward. The loop repeats.

**Termination and Output**

Upon termination, the engine returns the best candidate or the full Pareto front for multi-objective runs. Results are persisted to the ExperimentTracker and ArtifactStore.

## Integration Points

| Component                  | Role in Evolution                        |
| -------------------------- | ---------------------------------------- |
| ModelRegistry              | Supplies eligible parent models          |
| ModelCompatibilityAnalyzer | Validates candidate compatibility        |
| EvaluationEngine           | Runs benchmarks and collects metrics     |
| FitnessEngine              | Computes fitness from evaluation results |
| ExperimentTracker          | Logs every generation and candidate      |
| ArtifactStore              | Stores candidate model artifacts         |

## Research Basis

The EvolutionEngine design is grounded in Evolutionary Model Merge (Akiba et al. 2024), which demonstrated that evolutionary search can discover merge configurations outperforming manual tuning. NSGA-II (Deb et al. 2002) and NSGA-III (Deb & Jain 2014) provide the multi-objective optimization foundation. CMA-ES (Hansen 2001) is reserved as a future alternative search strategy.

## Configuration Parameters

| Parameter            | Default | Description                                        |
| -------------------- | ------- | -------------------------------------------------- |
| population\_size     | 32      | Number of candidates per generation                |
| max\_generations     | 100     | Hard termination limit                             |
| elitism\_count       | 4       | Top candidates preserved each generation           |
| mutation\_rate       | 0.1     | Probability of mutation per gene                   |
| crossover\_rate      | 0.8     | Probability of crossover per pair                  |
| diversity\_threshold | 0.05    | Minimum population variance                        |
| plateau\_generations | 10      | Generations without improvement before termination |

## Candidate Status Mapping

Candidates receive status from the EvaluationEngine:

* **PASS**: Meets all thresholds, proceeds to ranking
* **FAIL**: Below minimum thresholds, excluded from selection
* **REGRESSION**: Worse than baseline on critical metrics, flagged for review
* **INVALID**: Failed compatibility or integrity checks
* **INCOMPLETE**: Evaluation interrupted, candidate excluded

## Notes

<Info>
  The EvolutionEngine does not access the Hidden Test Set at any point. All fitness calculations, rankings, and termination decisions use the Optimization Set exclusively. The Validation Set and Hidden Test Set are reserved for post-evolution evaluation and final reporting.
</Info>

<Warning>
  Evolutionary search is computationally expensive. Each generation may require tens to hundreds of GPU-hours depending on population size, model scale, and benchmark complexity. Budget limits should be configured before starting a run.
</Warning>