> ## 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.

# Population Management in EMEP Evolution

> Specification for population initialization, diversity preservation, and archival elite pool management in the EMEP EvolutionEngine.

Population management controls how candidates are created, maintained, and evolved across generations in EMEP. It defines initialization strategies, size constraints, diversity enforcement, and the archival elite pool. This page specifies the Population component and its integration with the EvolutionEngine.

## Population Lifecycle

```mermaid theme={null}
flowchart TD
    START([START]) --> INIT[Initialization Strategy]
    INIT --> SIZE[Set Population Size]
    SIZE --> GEN[Generate Candidates]
    GEN --> VALIDATE[Validate Candidates]
    VALIDATE --> EVAL[Evaluate Candidates]
    EVAL --> DIV[Diversity Check]
    DIV --> ARCHIVE[Update Elite Archive]
    ARCHIVE --> SELECT[Selection for Breeding]
    SELECT --> MUT[Mutation / Crossover]
    MUT --> OFFSPRING[Generate Offspring]
    OFFSPRING --> REPLACE[Replace Population]
    REPLACE --> DIV
    DIV --> TERM{Termination?}
    TERM -->|No| SELECT
    TERM -->|Yes| END([END])
```

## Initialization Strategies

**Random Initialization**

Generates genomes with uniformly random values within valid bounds. Parent models are selected randomly from the eligible pool. Alpha coefficients are sampled from a Dirichlet distribution to ensure they sum to 1.0. Merge methods are selected uniformly from supported strategies.

**Seeded from Known Good**

Bootstraps the population from previously successful candidates. The Population component queries the ExperimentTracker for candidates with PASS or PROMOTED status. Their genomes are cloned with small perturbations to explore the local neighborhood. This accelerates convergence when prior knowledge exists.

**Latin Hypercube Sampling**

Divides each genome parameter range into N equal intervals, where N is the population size. Samples are placed such that each interval contains exactly one point per dimension. This guarantees better coverage of the search space than pure random sampling, especially in low-to-moderate dimensional spaces.

## Population Size

The default population size is 32. Size is configurable per experiment. Larger populations improve diversity and reduce premature convergence. Smaller populations reduce computational cost per generation.

| Population Size | Use Case                              | Trade-off                             |
| --------------- | ------------------------------------- | ------------------------------------- |
| 16              | Fast prototyping, small model scales  | Higher variance, risk of local optima |
| 32              | Standard runs, balanced exploration   | Default, good for most experiments    |
| 64              | Large models, complex search spaces   | Higher cost, better coverage          |
| 128+            | Research exploration, multi-objective | Very high cost, thorough search       |

## Diversity Preservation

Diversity is measured as the average pairwise Hamming distance between genome encodings. The Population component tracks diversity per generation. If diversity drops below the configured threshold, the engine applies one or more rescue strategies:

* Inject random immigrants: add N new random candidates
* Expand search space: include additional parent models
* Increase mutation rate temporarily
* Restart from Latin hypercube sampling

## Archival Elite Pool

The elite archive stores the top-performing candidates across all generations, regardless of whether they were selected for breeding. The archive is immutable and append-only.

**Elite Selection Criteria**

* Top K candidates by fitness per generation
* Any candidate that achieves a new best fitness
* Any candidate that discovers a new Pareto-optimal point

**Archive Size**

The archive size is unbounded by default. For long-running experiments, a configurable cap triggers removal of the oldest entries when exceeded. Removed entries remain in the ExperimentTracker but are no longer loaded into memory.

## Replacement Strategy

After offspring generation, the new population replaces the old. Replacement options include:

* **Generational**: entire population replaced by offspring
* **Steady-state**: worst candidates replaced one at a time
* **Elitist**: top E candidates preserved, remainder replaced

EMEP defaults to elitist replacement with E equal to the elitism count.

## Integration with EvolutionEngine

The Population component exposes a single interface to the EvolutionEngine:

```text theme={null}
Population.initialize(strategy, size, parents)
Population.evaluate()
Population.select_breeding_pool(count)
Population.replace(offspring)
Population.get_diversity()
Population.get_elite_archive()
```

All state changes are logged to the ExperimentTracker with generation number and timestamp.

<Info>
  The elite archive is distinct from the active population. Elite candidates are not automatically included in breeding unless they are re-selected by the Selection component. This prevents premature convergence on a single high-performing lineage.
</Info>