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

# Crossover Operators for Merge Genome Combination

> Specification for crossover operators in EMEP, including uniform, one-point on layer index, and arithmetic blend with constraint enforcement.

Crossover operators combine two parent genomes to produce offspring in the EMEP evolutionary loop. Each operator defines how genetic material is exchanged while preserving structural validity. This page specifies the three supported crossover strategies and their constraints.

## Crossover Flowchart

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[Input Parent A + Parent B]
    INPUT --> COMPAT{Compatible?}
    COMPAT -->|No| FAIL[Return Failure]
    COMPAT -->|Yes| SELECT[Select Operator]
    SELECT --> UNI[Uniform Crossover]
    SELECT --> ONE[One-Point Layer Crossover]
    SELECT --> ARITH[Arithmetic Blend]
    UNI --> VALIDATE[Validate Offspring]
    ONE --> VALIDATE
    ARITH --> VALIDATE
    VALIDATE -->|Valid| OUTPUT[Return Offspring]
    VALIDATE -->|Invalid| RETRY{Retry?}
    RETRY -->|Yes| SELECT
    RETRY -->|No| FAIL
    FAIL --> END([END])
    OUTPUT --> END
```

## Compatibility Check

Before crossover, the two parent genomes must share:

* The same base architecture family
* Compatible tensor shapes for all overlapping layers
* At least one common merge method if strategy switching is disabled

The ModelCompatibilityAnalyzer performs this check. Incompatible pairs produce no offspring.

## Uniform Crossover

Each gene in the offspring genome is selected independently from either parent with equal probability. Genes are:

* `merge_method`: categorical, copied from one parent
* `alpha`: vector, copied as a whole or blended
* `per_layer_alpha`: map, keys merged, values selected per key
* `density`: scalar, copied from one parent
* `task_vectors`: list, merged by parent index
* `layer_routing`: map, keys merged, values selected per key
* `structural_parameters`: copied as a whole from one parent
* `quantization`: copied from one parent

Uniform crossover preserves diversity but may produce inconsistent combinations. Offspring are validated before acceptance.

## One-Point Layer Crossover

A single layer index is chosen as the crossover point. All layer-specific parameters below the point come from Parent A; all at or above come from Parent B. This is meaningful for `per_layer_alpha` and `layer_routing`.

For global parameters (alpha, merge\_method, density), the offspring receives the full set from Parent A. This operator is most effective when parents have different layer-wise blending strategies.

Crossover point selection is uniform across all layer indices. The point is recorded in the offspring metadata for lineage tracking.

## Arithmetic Blend

Scalar and vector fields are blended arithmetically rather than copied:

```text theme={null}
alpha_offspring = beta * alpha_A + (1 - beta) * alpha_B
density_offspring = beta * density_A + (1 - beta) * density_B
```

Beta is sampled uniformly from \[0, 1]. After blending:

* Alpha is re-normalized to sum to 1.0
* Density is clipped to \[0.2, 1.0]

Categorical fields (merge\_method, quantization) are copied from the parent with higher fitness. If fitness is equal, selection is random.

## Constraint Enforcement

All offspring must satisfy the same validation rules as mutated genomes:

1. Alpha sums to 1.0
2. Density in valid range
3. Layer routing without gaps or overlaps
4. Parent models exist and are compatible
5. Structural parameters match architecture family

Invalid offspring trigger a retry with a different crossover point or beta value. After 3 retries, the crossover fails and the pair produces no offspring.

## Operator Selection Probabilities

| Operator         | Default Probability | Best For                              |
| ---------------- | ------------------- | ------------------------------------- |
| Uniform          | 0.4                 | High diversity, complex search spaces |
| One-Point Layer  | 0.3                 | Layer-wise specialization             |
| Arithmetic Blend | 0.3                 | Smooth fitness landscapes             |

Probabilities are configurable per experiment. The EvolutionEngine may adjust probabilities adaptively based on offspring success rates.

<Info>
  Crossover produces two offspring per pair by default: one with the primary blend and one with the inverse (1 - beta). Both are validated and evaluated independently.
</Info>