feat(mab): integrate Lin-Kernighan with Multi-Armed Bandit scheduler

[lv416e]

Summary

Implements Task 6.2: Integration of Lin-Kernighan local search with Multi-Armed Bandit (MAB) scheduler for adaptive local search operator selection in memetic algorithms.

Changes

Core Implementation

• LocalSearchOperator concept: Type-safe interface for local search algorithms

  • Requires improve(problem, genome, rng) -> Fitness method
  • Works with LinKernighan, TwoOpt, Random2Opt, and future local search operators

• AdaptiveLocalSearchSelector: Template class for adaptive local search selection

  • Mirrors AdaptiveOperatorSelector design pattern for consistency
  • Supports both UCB and Thompson Sampling schedulers
  • Type aliases: UCBLocalSearchSelector<Problem>, ThompsonLocalSearchSelector<Problem>

Performance Tracking

• Execution time measurement: Uses std::chrono::steady_clock
• Improvement rate tracking: Leverages existing OperatorStats infrastructure
• Reward-based learning: UCB and Thompson Sampling learn which local search works best

Testing

• New test suite: tests/test_mab_local_search.cpp (21 tests, all passing)
• Enhanced test helper: Added assert_le and assert_gt(double) methods
• All existing tests pass (14/14 test suites)

Integration

• Added include/evolab/local_search/lk.hpp to main evolab.hpp header
• Formatted with clang-format, passes all lint checks

Usage Example

#include <evolab/evolab.hpp>
using namespace evolab;

// Create MAB local search selector
schedulers::UCBLocalSearchSelector<problems::TSP> ls_selector(3, 2.0, rng);

// Add local search operators
ls_selector.add_operator(local_search::LinKernighan(20, 5), "LK");
ls_selector.add_operator(local_search::TwoOpt(), "2opt");
ls_selector.add_operator(local_search::Random2Opt(100), "Random2opt");

// Apply adaptive local search
auto fitness = ls_selector.apply_local_search(tsp, tour, rng);
ls_selector.report_fitness_improvement(old_fitness - fitness.value);

// Check performance stats
const auto& stats = ls_selector.get_operator_stats();
for (size_t i = 0; i < stats.size(); ++i) {
    std::cout << ls_selector.get_operator_names()[i] 
              << ": " << stats[i].success_rate << std::endl;
}

Known Limitations (Pre-v1.0)

⚠️ Important: This feature is currently experimental and requires additional validation before being considered research-grade.

Thread Safety

• NOT THREAD-SAFE: Both AdaptiveOperatorSelector and AdaptiveLocalSearchSelector maintain mutable state
• Sharing a selector across threads will cause race conditions and corrupt MAB learning
• Solution: Create one selector instance per thread (e.g., one per island in Island Model GAs)
• Impact: Incorrect results in parallel GAs if not properly isolated

Minimization Problems Only

• report_fitness_change(old_fitness, new_fitness) assumes minimization (lower = better)
• Calculates improvement as: old_fitness - new_fitness
• For maximization problems: Calculate improvement manually and use report_fitness_improvement() directly:

  double improvement = new_fitness - old_fitness;  // For maximization
  selector.report_fitness_improvement(improvement);

Empirical Validation Pending

• No experimental validation of research value (convergence, overhead, comparison with baselines)
• No performance characterization for real-world use cases
• Not publication-ready until validation complete (see Issue MAB Scheduler: Empirical Validation #33)
• Current status: Functionally correct, unit-tested, but unvalidated for research use

Future Work

Before v1.0 Release (Blocking)

• Empirical validation (Issue MAB Scheduler: Empirical Validation #33) - HIGH PRIORITY
  • Convergence validation: Verify MAB learns operator quality
  • Performance overhead: Quantify selection cost vs operator cost
  • Baseline comparisons: MAB vs random/round-robin selection
  • Real-world GA integration: TSPLIB benchmarks
  • Est. effort: 2-3 days of experimental work

Post-v1.0 (Enhancement)

• Selector refactoring (Issue MAB Scheduler: Refactor Selector Classes #32) - MEDIUM PRIORITY

  • Eliminate ~110 lines of code duplication
  • Templated base class or CRTP pattern
  • Trigger: When 3rd selector type is added

• Configuration system integration - MEDIUM PRIORITY

  • Requires runtime operator selection (std::variant or type erasure)
  • Enable TOML-based operator configuration
  • Example: scheduler.operators = ["LK", "2-opt"] in config files

• Maximization support - LOW PRIORITY

  • Enhanced API or automatic problem type detection
  • Or simply document current minimization-only constraint

Testing Results

=== EvoLab MAB Local Search Integration Tests ===
Passed: 21
Failed: 0
Total:  21

All test suites: 14/14 passed

Related Work

• Task 6.1: Lin-Kernighan implementation (completed)
• Task 2.2: Configuration system (needs enhancement for runtime operator selection)
• Issue MAB Scheduler: Empirical Validation #33: Empirical validation roadmap
• Issue MAB Scheduler: Refactor Selector Classes #32: Selector refactoring

Checklist

• All tests passing
• Code formatted with clang-format
• Lint checks passing
• Documentation updated (tasks.md, code comments)
• Git hooks passing (format, lint, build-check)
• Pre-push hooks passing (changed-check, build, test)
• Thread-safety warnings added
• Minimization assumption documented
• Empirical validation roadmap documented (Issue MAB Scheduler: Empirical Validation #33)
• Known limitations clearly stated

---

Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• New Features
  • Adaptive local‑search integrated into the MAB workflow with UCB and Thompson Sampling; Lin‑Kernighan, 2‑Opt, and Random 2‑Opt available.
• Performance
  • Per‑operator execution‑time, improvement‑rate and expanded success/reward metrics.
• Bug Fixes
  • Stronger validation, clearer error handling and safer thread‑local RNG defaults.
• Tests
  • New comprehensive local‑search test suite (21 passing tests) and double‑value assertion helpers.
• Documentation
  • Specs updated; runtime configuration templates deferred.

[gemini-code-assist]

Summary of Changes

Hello @lv416e, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the evolab framework by introducing an adaptive mechanism for selecting local search operators within memetic algorithms. It implements a Multi-Armed Bandit (MAB) approach, allowing the system to intelligently learn and apply the most effective local search strategies (such as Lin-Kernighan, TwoOpt, and Random2Opt) based on their observed performance in terms of fitness improvement and execution time. This change provides a more flexible and efficient way to optimize complex problems by dynamically adjusting the local search components.

Highlights

• Adaptive Local Search Integration: Introduced AdaptiveLocalSearchSelector to dynamically choose local search operators (Lin-Kernighan, TwoOpt, Random2Opt) using Multi-Armed Bandit (MAB) strategies like UCB and Thompson Sampling.
• New LocalSearchOperator Concept: Defined a type-safe C++ concept for local search algorithms, requiring an improve method, ensuring compile-time validation of operator interfaces.
• Enhanced Performance Tracking: Implemented tracking of local search operator performance, including execution time using std::chrono and fitness improvement rates via OperatorStats, enabling the MAB schedulers to learn effectively.
• Comprehensive Testing: Added a new test suite (test_mab_local_search.cpp) with 21 passing tests to validate the new MAB local search integration, covering various aspects of its functionality.
• Core Header Update: Included the Lin-Kernighan header (lk.hpp) in the main evolab.hpp for broader accessibility of the local search algorithm.
• Deferred Features: Noted that integration with the configuration system and creation of hybrid Memetic GA templates are deferred for future work due to current C++ template limitations requiring runtime operator selection design.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Adds AdaptiveLocalSearchSelector (UCB/Thompson) and LocalSearchOperator support with chrono-based timing and expanded OperatorStats; exposes Lin–Kernighan via public include; introduces thread-local RNG accessor; expands tests, test helpers, and CTest entry for MAB local-search integration. (≤50 words)

Changes

Cohort / File(s)	Summary
Specs update .kiro/specs/evolab/tasks.md	Marks Lin–Kernighan MAB integration as completed; documents LocalSearchOperator, AdaptiveLocalSearchSelector, timing/improvement instrumentation, supported operators (LinKernighan, TwoOpt, Random2Opt), expanded tests, and deferred configuration/templates.
Public include surface include/evolab/evolab.hpp	Adds public include for local-search header (local_search/lk.hpp) to expose Lin–Kernighan.
MAB schedulers & selectors include/evolab/schedulers/mab.hpp	Adds inline std::mt19937& get_thread_rng() (thread-local RNG) and uses it as default; expands OperatorStats with timing/success metrics; instruments timing in apply paths; strengthens runtime guards; introduces AdaptiveOperatorSelector enhancements and new AdaptiveLocalSearchSelector (UCB/Thompson aliases) with add/apply/report/reset and operator-stats APIs.
Test build config tests/CMakeLists.txt	Adds test_mab_local_search executable and CTest MABLocalSearchTests with labels integration;mab;local-search;adaptive.
Test helpers tests/test_helper.hpp	Adds TestResult overloads for double comparisons: assert_ge, assert_gt, assert_le, assert_lt.
Local-search tests tests/test_mab_local_search.cpp	New comprehensive test suite (~21 tests) covering LocalSearchOperator concept, AdaptiveLocalSearchSelector (UCB/Thompson), operator registration/names/counts, apply_local_search timing/improvement tracking, error cases, and hybrid memetic scenarios.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant GA as GeneticAlgorithm
  participant ALS as AdaptiveLocalSearchSelector
  participant SCH as Scheduler (UCB/Thompson)
  participant OP as LocalSearchOperator
  participant RNG as ThreadRNG
  participant T as Timer

  rect rgb(230,245,255)
  GA->>ALS: apply_local_search(problem, genome, RNG)
  end

  rect rgb(255,250,230)
  ALS->>T: start timing
  ALS->>SCH: select_operator(operator_stats)
  SCH-->>ALS: selected_index
  end

  rect rgb(240,255,240)
  ALS->>OP: invoke selected operator(problem, genome, RNG)
  OP-->>ALS: new_fitness
  ALS->>T: stop timing
  ALS->>ALS: compute improvement & record execution time
  ALS->>SCH: report_reward(improvement)
  ALS-->>GA: return new_fitness
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• MAB Scheduler: Empirical Validation #33 — The PR’s AdaptiveLocalSearchSelector, enhanced OperatorStats, timing instrumentation, and public RNG accessor directly address the scheduler improvements and TODOs described in this issue.

Possibly related PRs

• feat: implement Lin-Kernighan local search for memetic algorithms #26 — Adds Lin–Kernighan implementation that this PR exposes via public include and integrates into local-search selectors.
• feat(local-search): add delta evaluation optimization for 2-opt #24 — Overlaps on TwoOpt/Random2Opt and TSP helper changes used by the new local-search operators.
• feat(parallel): implement TBB parallel fitness evaluation #17 — Related to the thread-local RNG/determinism work; this PR adds get_thread_rng() and migrates schedulers to it.

Poem

I nibble through tours with nimble little paws, 🥕
I time each hop and tally every clause.
LK trims the track, Two‑Opt smooths the map,
Bandits pick, I cheer, then tidy my lap.
A rabbit’s joy: select, report, and nap.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the primary enhancement of integrating the Lin-Kernighan local search operator with the existing Multi-Armed Bandit scheduler, matching the core changes in the pull request and following conventional commit style.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/lk-mab-integration

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c5de55f and daa8aa9.

📒 Files selected for processing (1)

• tests/test_helper.hpp (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_helper.hpp

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}