Trait Engine 

pub trait Engine {
    type Epoch;
    type Ctx;

    // Required methods
    fn context(&self) -> &Self::Ctx;
    fn epoch(&self) -> Self::Epoch;
    fn step(&mut self) -> Result<()>;
    fn state(&self) -> EngineState;

    // Provided methods
    fn start(&mut self) { ... }
    fn stop(&mut self) { ... }
}

A trait representing an evolutionary computation engine.

The Engine trait defines the fundamental interface for evolutionary algorithms. Implementors define how the algorithm progresses from one generation/epoch to the next, encapsulating the core evolutionary logic.

It is intentionally essentially an iterator.

Generic Parameters

• Epoch: The type representing a single step or generation in the evolutionary process

Examples

use radiate_core::engine::{Engine, EngineExt, EngineState};
use radiate_error::RadiateError;

#[derive(Default)]
struct MyEngine {
    generation: usize,
    population: Vec<i32>,
}

#[derive(Debug, Clone)]
struct MyEpoch {
    generation: usize,
    population_size: usize,
}

impl Engine for MyEngine {
    type Epoch = MyEpoch;
    type Ctx = ();

    fn context(&self) -> &Self::Ctx {
       &()
    }

    fn epoch(&self) -> Self::Epoch {
       MyEpoch {
          generation: self.generation,
          population_size: self.population.len(),
        }
    }

    fn state(&self) -> EngineState {
        // Return the current state of the engine
        EngineState::Running
    }

    fn step(&mut self) -> Result<(), RadiateError> {
        // Perform one generation of evolution
        // ... evolve population ...
        self.generation += 1;
        Ok(())
    }
}

// Use the engine with a termination condition
let mut engine = MyEngine::default();
let final_epoch = engine.run(|epoch| epoch.generation >= 10);
println!("Final generation: {}", final_epoch.generation);

Design Philosophy

The Engine trait is intentionally minimal, focusing on the core concept of progression through evolutionary time. This allows for maximum flexibility in implementing different evolutionary algorithms while maintaining a small, consistent interface for execution control.

Required Associated Types

type Epoch

The type representing a single epoch or generation in the evolutionary process.

The epoch type should contain all relevant information about the current state of the evolutionary algorithm, such as:

• Generation number
• Population statistics
• Best fitness values
• Convergence metrics
• Any other state information needed for monitoring or decision-making

type Ctx

The type representing the context of the engine, which may include configuration, state, and other relevant information. This allows external systems to inspect the engine’s state without needing to clone or modify it.

Required Methods

fn context(&self) -> &Self::Ctx

Returns a reference to the current context of the engine. This is meant to provide a read-only view of the engine’s internal state, to allow external systems close to the engine level, to inspect the engine without cloning anything.

fn epoch(&self) -> Self::Epoch

Returns an epoch of the engine, which is intended to be a snapshot of the current state, or the current context. The Epoch here can be given to iterators, callers, or anyone else who needs it. Essentially to say, this shouldn’t borrow anything from the engine, but instead be an owned snapshot of the engine

fn step(&mut self) -> Result<()>

Advances the engine by one step, performing the necessary computations to progress the evolutionary algorithm. This may include evaluating fitness, selecting individuals, applying genetic operators, and updating the population. This intentionally does not return anything, that is left up to the epoch() method or the next() method. It’s done this way so we can advance the engine without having to clone or create any new data, and possibly perform operations outside of the engine which don’t require a snapshot of the engine state.

fn state(&self) -> EngineState

Returns the current state of the engine. This allows external systems to query the engine’s status without modifying it. This lets the Engine act as a state machine, while external systems can query the current state of the engine.

Provided Methods

fn start(&mut self)

Starts the engine, initializing any necessary state or resources. This is typically called before entering the main execution loop.

fn stop(&mut self)

Stops the engine, performing any necessary cleanup or finalization. This is typically called after exiting the main execution loop.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors