Expose remaining unbound Python APIs for evaluation and benchmarking

[Copilot]

The issue asks to expose functionality that existed in C++ but was still unavailable in Python bindings. This PR closes the remaining practical gaps by binding evaluation utilities and benchmark APIs, and updating the guide to reflect the actual Python surface.

• Parallel/distributed evaluation bindings

  • Added Python bindings for:
    • ga.ParallelEvaluator
    • ga.LocalDistributedExecutor
  • Bound Python callables safely for threaded execution (GIL-acquire in callback path, GIL-release during batch execution).

• Benchmark suite bindings

  • Added Python bindings for benchmark types:
    • ga.BenchmarkConfig
    • ga.BenchmarkResult
    • ga.OperatorBenchmark
    • ga.FunctionBenchmark
    • ga.GABenchmark
  • Exposed benchmark execution/report APIs and result accessors:
    • run_all_benchmarks, run_operator_benchmarks, run_function_benchmarks, run_scalability_benchmarks
    • generate_report, export_to_csv
    • operator_results, function_results, scalability_results

• C++ surface support for Python result access

  • Added const getters on GABenchmark for operator/function/scalability result vectors to enable direct Python retrieval.

• Build/link integration

  • Updated Python module target to include benchmark/ga_benchmark.cc, ensuring benchmark symbols are linked into ga_python_module.

• Docs + binding sanity coverage

  • Updated USER_GUIDE.md coverage table and sections 19/25 to document newly exposed Python APIs.
  • Extended python/bindings_sanity.py with focused checks for new evaluator and benchmark bindings.

import ga

def sphere(x): return 1000.0 / (1.0 + sum(v*v for v in x))

pe = ga.ParallelEvaluator(sphere, threads=4)
scores = pe.evaluate([[0.1, 0.2], [0.3, 0.4]])

cfg = ga.BenchmarkConfig()
cfg.warmup_iterations = 1
cfg.benchmark_iterations = 3
cfg.verbose = False

bench = ga.GABenchmark(cfg)
bench.run_operator_benchmarks()
rows = bench.operator_results()
bench.export_to_csv("benchmark_results.csv")

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[Rahuldrabit]

@copilot review

[Copilot]

@copilot review

Reviewed the latest branch state at ecc89b3; there are no additional code changes needed from this comment, and the current implementation remains valid as submitted.

[Copilot]

Pull request overview

Exposes previously C++-only evaluation and benchmarking functionality through the Python bindings, and updates documentation/sanity checks to reflect the expanded Python surface.

Changes:

• Added Python bindings for threaded evaluation utilities (ParallelEvaluator, LocalDistributedExecutor) and benchmark suite types/APIs (BenchmarkConfig, GABenchmark, result structs).
• Added const result getters to GABenchmark to enable Python access to benchmark results.
• Updated build integration, user guide, and Python bindings sanity checks for the new APIs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
python/ga_bindings.cpp	Adds pybind11 bindings for evaluation helpers, benchmark suite, and selection helper functions.
python/bindings_sanity.py	Extends sanity script to exercise new evaluator/selection/benchmark Python APIs and CSV export.
benchmark/ga_benchmark.h	Adds const getters for benchmark result vectors to support Python retrieval.
USER_GUIDE.md	Updates coverage table + adds Python usage docs for selection helpers, evaluation helpers, and benchmark suite.
CMakeLists.txt	Links benchmark implementation into the Python extension module target.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

std::thread::hardware_concurrency() is allowed to return 0; if that happens, the Python-visible default for threads becomes 0 (even though the C++ implementation later clamps to >=1). Consider setting the binding default to max(1, hardware_concurrency()) (or using None/omitting the default) so the Python signature and runtime behavior are not misleading.

[Copilot]

Same issue as threads: std::thread::hardware_concurrency() may return 0, which makes the Python-visible default workers=0 even though the executor clamps to >=1 internally. Prefer a default that is always at least 1 so Python users don’t accidentally run with an unexpected setting.

[Copilot]

TournamentSelection::selectIndices(...) returns a vector<unsigned int> containing a single winner index, so this binding returns a Python list (length 1), not a single integer. Either unwrap and return the scalar index, or update the docstring/name to make the list-of-one behavior explicit (to match the actual return type).

Suggested change

	"Tournament selection helper: returns one winner index from the tournament");
	"Tournament selection helper: returns a list containing one winner index from the tournament");

[Copilot]

The guide says selection_tournament_indices(...) “returns one index”, but the Python API actually returns a list containing one index (consistent with the other *_indices helpers). Please clarify in the documentation (e.g., “returns a list of length 1”) or adjust the API to return an int.

[Copilot]

Since these evaluators call a Python callback, each callback invocation must hold the GIL; that means a pure-Python fitness function will not execute concurrently across threads (speedups generally require native code that releases the GIL, e.g. NumPy/Cython). Consider adding a short note here so users don’t assume CPU-parallel execution for pure Python callables.

Suggested change

	> **Note:** These evaluators invoke a Python callback while holding the GIL, so a pure-Python `fitness` function will not execute CPU-bound work concurrently across threads. For real CPU parallelism, use native code that releases the GIL (e.g. NumPy, Cython), or a process-based executor.