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:

Probe phase -- the first stag_window generations always run pure CMA-ES (mode = exploit, k_top = N).
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.
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.
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:

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