Struct EvolutionaryHarness 

pub struct EvolutionaryHarness<B, S, F>
where
    B: Backend,
    S: Strategy<B>,
    F: BatchFitnessFn<B, S::Genome>,
{ /* private fields */ }

Wraps a Strategy into a BenchEnv so the benchmark harness can drive it.

Example

use burn::backend::Flex;
use rlevo_core::fitness::FitnessEvaluable;
use rlevo_core::evaluation::BenchEnv;
use rlevo_evolution::algorithms::ga::{GaConfig, GeneticAlgorithm};
use rlevo_evolution::fitness::FromFitnessEvaluable;
use rlevo_evolution::strategy::EvolutionaryHarness;

struct Sphere;
struct SphereFit;
impl FitnessEvaluable for SphereFit {
    type Individual = Vec<f64>;
    type Landscape = Sphere;
    fn evaluate(&self, x: &Self::Individual, _: &Self::Landscape) -> f64 {
        x.iter().map(|v| v * v).sum()
    }
}

let device = Default::default();
let mut harness = EvolutionaryHarness::<Flex, _, _>::new(
    GeneticAlgorithm::<Flex>::new(),
    GaConfig::default_for(32, 5),
    FromFitnessEvaluable::new(SphereFit, Sphere),
    0, device, 100,
).expect("valid params");
harness.reset();
while !harness.step(()).done {}

Each step runs one generation (ask → evaluate → tell). The harness is the sole canonicaliser: it reads the fitness fn’s ObjectiveSense, negates a Minimize objective into the engine’s maximise space before tell, and maps the metrics back to the declared sense for reporting. The reward returned is the canonical best_fitness_ever directly (already higher-is-better — no negation), so the per-episode cumulative return (Σ step rewards) integrates the optimization trajectory. The harness only exposes episode-level returns to reporters, so the “best at end” signal would otherwise be lost.

Determinism and parallel execution

Burn backends seed their tensor RNG through process-global state — the flex backend uses a Mutex<Option<FlexRng>>, the wgpu backend a per-device seeded stream. When multiple harness instances run in parallel threads (e.g. Evaluator::run_suite with the default rayon pool), their interleaved B::seed(...) → Tensor::random(...) call pairs race on that shared state and destroy bit-reproducibility across runs.

For deterministic reproduction, pass EvaluatorConfig::num_threads = Some(1) or run one harness per process. The tests/determinism.rs and tests/rastrigin_run_suite.rs integration tests both enforce serial execution for this reason.

Implementations

impl<B, S, F> EvolutionaryHarness<B, S, F>

where B: Backend, S: Strategy<B>, F: BatchFitnessFn<B, S::Genome>,

pub fn new( strategy: S, params: S::Params, fitness_fn: F, seed: u64, device: B::Device, max_generations: usize, ) -> Result<Self, ConfigError>

where S::Params: Validate,

Build a new harness from its parts.

The caller-supplied params are validated up front — this is the harness consumption chokepoint (ADR 0026), so an invalid configuration is rejected here rather than surfacing as a panic deep inside a strategy’s tensor code.

The harness is lazily initialized — the first reset call materializes the initial state on the supplied device.

Errors

Returns a ConfigError when params fails Validate::validate, naming the offending field and violated invariant.

pub fn with_observer(self, observer: SharedPopulationObserver) -> Self

Attach a per-generation PopulationObserver.

The observer is called once per step call, after the canonical tracing::info!("evolution generation", …) event. It receives a PopulationSnapshot carrying the full per-individual fitness vector for the completed generation. The intended consumer is a benchmark-tier recording sink that persists population-level data alongside the scalar metric stream.

Attaching an observer adds one device→host transfer of the fitness tensor per generation; runs without an observer pay nothing.

pub fn latest_metrics(&self) -> Option<&StrategyMetrics>

Snapshot of the most recent generation’s metrics, if any.

pub fn generation(&self) -> usize

Generation counter — number of completed tell calls.

pub fn state(&self) -> Option<&S::State>

Borrow the current strategy state if it exists.

pub fn best(&self) -> Option<(S::Genome, f32)>

Forward to Strategy::best when a state exists.

The strategy tracks the best genome in canonical (maximise) space; the returned fitness is mapped back to the objective’s declared sense so a Minimize landscape reads as its natural cost.

pub fn reset(&mut self)

Reset to a fresh initial state.

Inherent shape (infallible): EvolutionaryHarness cannot legitimately fail to reset — it is a deterministic optimization driver. The BenchEnv trait impl wraps this in Ok(()) so the harness is callable both directly (this method) and via the BenchEnv surface when fed to Evaluator::run_suite.

pub fn step(&mut self, _action: ()) -> BenchStep<()>

Run one ask → evaluate → tell generation.

Inherent shape (infallible). The BenchEnv trait impl wraps this in Ok(...). See Self::reset for the rationale.

Panics

Panics if reset has not been called first. Also panics if an observer is attached and the natural-fitness tensor cannot be read back to host as f32 (a device→host transfer failure).

Trait Implementations

impl<B, S, F> BenchEnv for EvolutionaryHarness<B, S, F>

where B: Backend, S: Strategy<B>, F: BatchFitnessFn<B, S::Genome>,

type Observation = ()

The observation type the environment produces on each step.

type Action = ()

The action type the environment accepts on each step.

fn reset(&mut self) -> Result<Self::Observation, BenchError>

Reset the environment to an initial state and return the first observation.

fn step( &mut self, action: Self::Action, ) -> Result<BenchStep<Self::Observation>, BenchError>

Apply action and advance the environment by one step.

impl<B, S, F> Debug for EvolutionaryHarness<B, S, F>

where B: Backend, S: Strategy<B>, F: BatchFitnessFn<B, S::Genome>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.