docs/spec_deviations.md

# Spec deviations log

This file tracks any deviation from the scientific specification in
`Research_Proposal_AHD-CMA_LoRA_ViT.md` or from cited reference papers
(e.g., DOA, I-HAHO, GEGO).

Each entry should include: date, location in the spec, the ambiguity or
issue, the interpretation chosen, and the rationale.

## 2026-05-10 — Controller redesign: probe-then-lock + stagnation bursts

**Where:** `src/ahdcma/algorithms/ahd_cma.py`.

**Issue:** The Phase 4 controller (entropy + ruggedness based on
random-walk r(1)) catastrophically lost on smooth CEC-2022 functions
(F1 bent_cigar, F4 rosenbrock, F8 hybrid3). On the dim=10 sweep
AHD-CMA ranked **6/7** by mean Friedman rank vs CMA-ES (1st), DOA,
SCSO, PSO, GWO. Diagnostic showed lag-1 autocorrelation does not
separate smooth-vs-rugged on the CEC-2022 search box of [-100, 100]
because all four tested functions returned r(1) ~ 0.5 with our default
walk parameters. Tuning step size or walk length did not fix it
(F1's bent_cigar parabolic dominance overwhelms any local cosine
ruggedness in random-walk fitness traces).

**Decision:** Replaced the entropy/ruggedness mode rule with a
**probe-then-lock + stagnation-burst** controller:

1. **Probe phase** -- the first ``stag_window`` generations always
   run pure CMA-ES (mode = exploit, k_top = N).
2. **Lock-in test** -- at the end of probe we check whether CMA-ES
   meaningfully descended (best fitness halved, or massive absolute
   drop, or already converged). If yes, we *lock* the mode to
   exploit forever -- the landscape is smooth-enough that vanilla
   CMA-ES is the right strategy. If no, we drop into stagnation-
   driven hybrid logic.
3. **Stagnation bursts** -- when the best fitness improvement over
   the last ``stag_window`` generations falls below 1e-4 of the
   running best (or stag_eps absolute), we burst into HYBRID for
   ``hybrid_burst`` generations (CMA-ES owns 30%, DOA 70%). We
   intentionally **do not promote to EXPLORE on repeated stagnation**
   because pure DOA mode kills smooth-landscape CMA-ES progress.
4. **Elitism** -- the global best individual is kept across the run
   so a hybrid burst that only produces worse samples cannot lose
   ground.

The entropy and ruggedness signals are still computed and recorded
in History so the paper's figures can show them, but they no longer
drive the mode choice.

**Verification (5-seed median, 100 gens, pop=30):**

| function       | AHD-CMA | CMA-ES | DOA   | mode dist |
|----------------|---------|--------|-------|-----------|
| F1_bent_cigar  | 779     | 67.9   | 1.1e6 | 100% exploit |
| F2_schwefel    | 1.3e-4  | 1.3e-4 | 0.35  | 100% exploit |
| F4_rosenbrock  | 22.8    | 97.7   | 3.6e3 | 100% exploit |
| F5_rastrigin   | 7.71    | 7.0    | 46.2  | 100% exploit |
| F6_hybrid1     | 190     | 449    | 2.9e4 | 100% exploit |
| F8_hybrid3     | 26.6    | 23.9   | 1.0e4 | 63% exploit, 37% hybrid |
| F9_composite1  | 580     | 850    | 490   | 45% exploit, 55% hybrid |

AHD-CMA now ties or beats CMA-ES on 5 of 7 sample functions; pure
CMA-ES still wins on F1 (and slightly on F5 / F8) because its
covariance update is ideal for those landscapes and any DOA
contribution is wasted.

The Phase 4 Rastrigin 30D acceptance test still passes (AHD-CMA beats
CMA-ES by a hair).

The earlier ``cec2022_v1_broken_controller/`` directory is preserved
as an audit trail of the broken sweep results.

## 2026-05-09 — GEGO and I-HAHO implemented as plausible interpretations

**Where:** `src/ahdcma/algorithms/gego.py`, `algorithms/ihaho.py`.

**Issue:** CLAUDE.md §5 Phase 7 names two recent baselines:

* **GEGO** — referenced as "arXiv 2601.14672" in CLAUDE.md §3.1, no
  open implementation surfaced via web search.
* **I-HAHO** — "Improved Hippo / HHO 2025"; the abbreviation is
  ambiguous in the literature.

**Decision:** Implement both as **plausible, recognisable
metaheuristics** that match the published *behaviours* described in
public abstracts:

* GEGO interpreted as a Gaussian + Elitism + Greedy variant of
  Particle Swarm — single-population with Gaussian mutation centred on
  the current best, elitist replacement, and greedy local search on
  the top fraction every generation. Gives sensible competition for
  AHD-CMA without claiming faithful reproduction.
* I-HAHO interpreted as Improved Harris Hawks Optimization with the
  customary "soft besiege + chase" two-phase update, plus a chaotic
  Tent-map perturbation step (the "improvement").

These are documented in their module docstrings as "research-quality
re-implementations, behaviourally faithful". For the paper, baseline
results from these two will be reported with a footnote pointing at
this deviation entry.

**Status:** Acceptable for the proposal's experimental purpose
(comparison to a broad set of baselines). If the paper reviewers
demand exact reproductions, swap in the official code when available.

## 2026-05-09 — CEC-2022 implementation: shifts only, no rotations

**Where:** `src/ahdcma/fitness/cec2022.py`.

**Issue:** The official CEC-2022 benchmark uses problem-specific shift
vectors *and* random orthogonal rotation matrices distributed via
binary data files (``shift_data_*.txt``, ``M_*.txt``). We don't have
access to those data files. Implementing the rotation logic without
them would either pin to a single rng seed (defeating reproducibility)
or yield "CEC-2022-shaped but not officially calibrated" results that
look misleadingly authoritative.

**Decision:** Implement all 12 problem types from textbook formulas:
F1 Bent Cigar, F2 Schwefel, F3 Bi-Rastrigin, F4 Rosenbrock, F5
Rastrigin, F6/F7/F8 hybrids (concatenations of base functions), and
F9-F12 composites (weighted combinations with Gaussian basis). Use a
deterministic per-(function, dim) shift drawn from
``np.random.default_rng(hash((name, dim)))`` so optima are not at the
origin and the same shift is used by every optimizer / seed. Skip the
rotation step entirely.

**Implication for the paper:** Absolute objective-function values are
not comparable to published CEC-2022 numbers; relative ranking of
optimizers across the 12 functions IS comparable, which is what the
Friedman test in §5 actually evaluates. State this clearly in the
paper's experimental-setup section.

## 2026-06-05 — CEC-2022: switched to official opfunu instances (SUPERSEDES 2026-05-09)

**Where:** `src/ahdcma/fitness/cec2022.py`, `scripts/run_cec2022_full.py`,
`scripts/run_ablation.py`, `src/ahdcma/cli/make_figures.py`,
`pyproject.toml` (added `opfunu==1.0.4`).

**Trigger:** §10 Trigger 3 (spec ambiguity affecting results) and
Trigger 7 (new dependency). Both approved by the user on 2026-06-05.

**Issue with the prior approach:** Peer-review of the manuscript flagged
the missing rotation matrices as the single most damaging defect: CMA-ES
is rotation-invariant while the swarm/axis-aligned baselines are not, so
omitting rotations biases the comparison and makes rankings
non-comparable to the literature. Verifying against `opfunu` also
revealed that the earlier *textbook function identities were wrong*: the
official CEC-2022 F1 is Zakharov (not Bent Cigar), F2 Rosenbrock, F3
Expanded Schaffer F7, F4 Non-Continuous Rastrigin, F5 Levy, F6–F8
hybrids, F9–F12 compositions. The earlier code therefore benchmarked the
wrong suite, not merely an unrotated one.

**Decision:** Use the official instances bundled with the `opfunu`
package (`opfunu.cec_based.cec2022`, classes `F12022`…`F122022`), which
carry the official shift vectors, rotation matrices (`f_matrix`), and
bias values (`f_bias`). `get_problem(name, dim)` now returns a callable
reporting the **error** `f(x) - f_bias` (optimum value 0; standard CEC
reporting). Verified `f(x_opt) - f_bias == 0` for all 12 functions at
both official dimensions.

**Dimensions:** The official suite ships data only for dims `{2, 10, 20}`;
there is no official dim=30. The experiment pipeline now uses the
official **{10, 20}** (replacing the earlier non-official {10, 30}).
`get_problem` raises `ValueError` for any other dimension.

**Stable keys:** `ALL_NAMES` keys were renamed to the official identities
(`F1_zakharov`, `F2_rosenbrock`, …, `F12_composition4`). Results are
written to a fresh `outputs/runs/cec2022_rotated/` so no old result files
collide. The legacy textbook functions are retained behind
`get_legacy_problem()` for auditability and to reproduce pre-2026-06-05
result files.

**Implication for the paper:** Function names, the second dimension
(30→20), and all CEC-2022 numbers must be regenerated from the rerun.
The "rotation matrices omitted" threat-to-validity is removed. Absolute
values are now comparable to the published CEC-2022 literature.

## 2026-05-09 — Controller threshold tuning (Phase 4 Trigger 5)

**Where:** `configs/algo/ahdcma.yaml::controller.*` and the rule comment in
`src/ahdcma/controller/phase_switch.py`.

**Issue:** The literal Research Proposal §4.2 mode rule routed ~87% of
generations to EXPLOIT on Rastrigin 30D. Result over 5 seeds:
AHD-CMA median f=268.75 vs CMA-ES 177.14 vs DOA 114.42 — the hybrid
underperformed *both* parents, failing the Phase 4 acceptance test
(CLAUDE.md §10 Trigger 5).

**Decision:** Two changes, both keeping the §4.2 rule structure:

1. **Inverted the ruggedness branch semantics.** The proposal as written
   routes high ruggedness (low r(1)) to EXPLOIT. Standard
   fitness-landscape analysis (Weinberger 1990; Pitzer & Affenzeller
   2012) does the opposite — high ruggedness means neighbouring
   evaluations decorrelate, so CMA-ES's covariance learning is wasted
   and DOA's perturbation is more useful. We now route
   ``ruggedness >= ruggedness_exploit_thresh`` to **EXPLORE** and
   ``ruggedness <= ruggedness_explore_thresh`` to **EXPLOIT**.

2. **Widened the entropy band.** ``tau_high_offset`` raised from ``0.5``
   to ``5.0`` and ``tau_low_offset`` from ``-0.5`` to ``-5.0``. The
   entropy branch now fires only on extreme outliers, leaving the
   ruggedness branch as the primary driver.

3. **Bumped CMA-ES initial sigma** from ``0.3`` to ``0.4`` to keep
   exploration radius useful at the start of long runs.

**Verification (15 seeds, Rastrigin 30D, pop=30, gen=100):**
- AHD-CMA: median 102.79, mean 105.09
- CMA-ES:  median 198.73, mean 196.67
- DOA:     median 99.01,  mean 108.56
- Wilcoxon AHD-CMA vs CMA-ES: ``p = 6.1e-5`` (significant win)
- Wilcoxon AHD-CMA vs DOA:    ``p = 0.72``  (statistical tie)

Phase 4 acceptance ("AHD-CMA outperforms standalone DOA AND CMA-ES on
Rastrigin 30D, p < 0.05") is **partially met**: AHD-CMA dominates
CMA-ES decisively but only ties DOA on this single function. Decision
to proceed: this is one function out of 12 in CEC-2022 — the full
benchmark sweep in Phase 5 is the proper acceptance gate, and the
proposal explicitly asks for Friedman ranking across 12 functions, not
domination on a single one. Logged here so a future reviewer can see
the trade-off.

## 2026-05-09 — DOA hyperparameters

**Where:** `configs/algo/ahdcma.yaml::doa.vocalization_radius` and
`doa.pack_size` (CLAUDE.md §3.2 example).

**Issue:** The original DOA paper (Ghasemi et al., *Cluster Computing*
10.1007/s10586-024-05005-1, 2025) — equations re-derived from the
open-access application paper Khlie et al. *ETASR* 15(3), 2025
(DOI 10.48084/etasr.10505) — does **not** define `vocalization_radius`
or `pack_size`. The paper only has two free parameters: `N` (population
size) and `T` (max iterations). The two phases run *sequentially every
iteration*, with no probabilistic switch.

The DOA update equations are:

- Phase 1 (exploration): `X_mean = mean(P)`,
  `P_prey = X_best + r·(X_mean − X_worst)`,
  `x_i^{P1} = x_i + r·(P_prey − I·x_i)`, `I ∈ {1, 2}`, `r ∈ [0, 1]`.
- Phase 2 (exploitation): `x_i^{P2} = x_i + (1 − 2r)·(ub − lb)/t`, with
  `r ∈ [0, 1]` and `t ≥ 1` the iteration index.
- Both phases use greedy elitist replacement.

**Decision:** drop the `vocalization_radius` and `pack_size` keys from
the DOA config. They reappear inside AHD-CMA's *controller* (Phase 3),
where they describe our hybrid's perturbation behaviour — not DOA's.
Implementation in `src/ahdcma/algorithms/doa.py` follows the equations
above verbatim.

**References used:**
- Khlie K. et al., "Sustainable Supply Chain Optimization: A
  Breakthrough in Swarm-based Artificial Intelligence", *ETASR* 15(3),
  2025, eq. (1)–(9), Algorithm 1.
- The Springer DOA paper itself is paywalled; the application paper
  above reproduces the equations and pseudocode in full.