Struct MutationRate 

pub struct MutationRate { /* private fields */ }

Controls the probability that each gene will be mutated during reproduction.

Mutation rate determines how frequently genes are changed when creating offspring. Higher rates provide more genetic diversity but may disrupt good solutions, while lower rates preserve good solutions but may limit exploration.

When to Use Different Values

• High (0.7-1.0): Dense problems, escaping local optima, early exploration
• Medium (0.3-0.7): Balanced search, most general-purpose applications
• Low (0.0-0.3): Preserving good solutions, fine-tuning, convergence phase

Interaction with Population Size

• Small populations: Use higher mutation rates to maintain diversity
• Large populations: Can use lower mutation rates as diversity emerges naturally

Examples

use fx_durable_ga::models::MutationRate;

// Conservative mutation for stable problems
let rate = MutationRate::constant(0.1)?;

// Start diverse, converge to precision
let rate = MutationRate::linear(0.6, 0.05, 1.0)?;

// Rapid diversity reduction
let rate = MutationRate::exponential(0.8, 0.02, 1.5, 3)?;

Implementations

impl MutationRate

pub fn constant(value: f64) -> Result<Self, MutationRateError>

Creates a constant mutation rate that remains unchanged throughout optimization.

Parameters

• value: Mutation probability per gene in [0.0, 1.0]. Higher values increase genetic diversity.

When to Use

• Simple problems with stable optima
• Baseline testing and comparison
• When optimal mutation rate is already known
• Problems requiring consistent exploration level

Examples

use fx_durable_ga::models::MutationRate;

let conservative = MutationRate::constant(0.05)?;  // 5% mutation chance
let balanced = MutationRate::constant(0.3)?;       // 30% mutation chance
let aggressive = MutationRate::constant(0.7)?;     // 70% mutation chance

Examples found in repository

examples/regression_model.rs (line 247)

async fn main() -> Result<()> {
    dotenv::from_filename(".env.local").ok();
    tracing_subscriber::fmt()
        .pretty()
        .with_thread_ids(true)
        .with_max_level(Level::INFO)
        .init();

    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    let pool = PgPoolOptions::new()
        .max_connections(10)
        .connect(&database_url)
        .await?;

    // Run all default migrations
    fx_durable_ga::migrations::run_default_migrations(&pool).await?;

    let service = Arc::new(
        bootstrap(pool.clone())
            .await?
            .register::<NeuralArchitecture, _>(ArchitectureEvaluator)
            .await?
            .build(),
    );

    let mut registry = fx_event_bus::EventHandlerRegistry::new();
    register_event_handlers(
        Arc::new(Queries::new(FX_MQ_JOBS_SCHEMA_NAME)),
        service.clone(),
        &mut registry,
    );
    let mut listener = fx_event_bus::Listener::new(pool.clone(), registry);
    tokio::spawn(async move { listener.listen(None).await });

    let host_id = Uuid::parse_str("00000000-0000-0000-0000-123456789abc")?;
    let mut jobs_listener = fx_mq_jobs::Listener::new(
        pool.clone(),
        register_job_handlers(&service, fx_mq_jobs::RegistryBuilder::new()),
        WORKERS,
        host_id,
        Duration::from_secs(600),
    )
    .await?;
    tokio::spawn(async move { jobs_listener.listen().await });

    service
        .new_optimization_request(
            NeuralArchitecture::NAME,
            NeuralArchitecture::HASH,
            FitnessGoal::minimize(FITNESS_TARGET)?,
            Schedule::generational(10, 10),
            Selector::tournament(5, 15)?,
            Mutagen::new(Temperature::constant(0.8)?, MutationRate::constant(0.4)?),
            Crossover::uniform(0.5)?,
            Distribution::latin_hypercube(15),
            None::<()>,
        )
        .await?;

    tokio::time::sleep(Duration::from_secs(3600)).await;
    Ok(())
}

examples/point_search.rs (line 201)

async fn main() -> Result<()> {
    dotenv::from_filename(".env.local").ok();

    // Initialize logging to see optimization progress
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .init();

    // Database setup - genetic algorithms need persistent storage for populations
    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    let pool = PgPoolOptions::new()
        .max_connections(50)
        .connect(&database_url)
        .await?;

    fx_event_bus::run_migrations(&pool).await?;
    fx_mq_jobs::run_migrations(&pool, fx_mq_jobs::FX_MQ_JOBS_SCHEMA_NAME).await?;

    // Bootstrap the optimization service and register our problem type
    let target_point = Point {
        x: 1.0,
        y: 1.5,
        z: 2.5,
    }; // Target point to find
    let evaluator = PointDistanceEvaluator { target_point };
    let service = Arc::new(
        bootstrap(pool.clone())
            .await?
            .register::<Point, _>(evaluator)
            .await?
            .build(),
    );

    // setup event handling and spawn an event handling agent
    let mut registry = fx_event_bus::EventHandlerRegistry::new();
    register_event_handlers(
        Arc::new(Queries::new(FX_MQ_JOBS_SCHEMA_NAME)),
        service.clone(),
        &mut registry,
    );
    let mut listener = fx_event_bus::Listener::new(pool.clone(), registry);
    let _events_handle = tokio::spawn(async move {
        listener.listen(None).await?;
        Ok::<(), sqlx::Error>(())
    });

    // setup job handling and initiate workers
    let host_id = Uuid::parse_str("ba3a4752-c4ce-4129-aa1d-55a0b2107e68").expect("valid uuid");
    let hold_for = Duration::from_secs(TIMEOUT_SECONDS);
    let mut jobs_listener = fx_mq_jobs::Listener::new(
        pool.clone(),
        register_job_handlers(&service, fx_mq_jobs::RegistryBuilder::new()),
        8,
        host_id,
        hold_for,
    )
    .await?;
    let _jobs_handle = tokio::spawn(async move {
        jobs_listener.listen().await?;
        Ok::<(), anyhow::Error>(())
    });

    // Create multiple optimization requests with different genetic algorithm parameters
    for _ in 0..1 {
        service
            .new_optimization_request(
                Point::NAME,
                Point::HASH,
                FitnessGoal::minimize(0.01)?, // Stop when distance ≤ 0.01
                Schedule::generational(200, 30),
                Selector::tournament(7, 100)?,
                Mutagen::new(Temperature::constant(0.7)?, MutationRate::constant(0.3)?),
                Crossover::uniform(0.5)?,
                Distribution::latin_hypercube(1000),
                None::<()>,
            )
            .await?;
    }

    let timeout_duration = Duration::from_secs(TIMEOUT_SECONDS);
    let start_time = std::time::Instant::now();

    loop {
        tokio::time::sleep(Duration::from_secs(1)).await;

        // Check if we've exceeded the timeout
        if start_time.elapsed() >= timeout_duration {
            println!(
                "Timeout reached after {} seconds. Stopping optimization.",
                timeout_duration.as_secs()
            );
            break;
        }
    }

    Ok(())
}

examples/feature_engineering.rs (line 429)

async fn main() -> Result<()> {
    dotenv::from_filename(".env.local").ok();
    tracing_subscriber::fmt()
        .pretty()
        .with_thread_ids(true)
        .with_max_level(Level::INFO)
        .init();

    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    let pool = PgPoolOptions::new()
        .max_connections(10)
        .connect(&database_url)
        .await?;

    // Run all default migrations
    fx_durable_ga::migrations::run_default_migrations(&pool).await?;

    let service = Arc::new(
        bootstrap(pool.clone())
            .await?
            .register::<FeatureConfig, _>(FeatureEvaluator)
            .await?
            .build(),
    );

    let mut registry = fx_event_bus::EventHandlerRegistry::new();
    register_event_handlers(
        Arc::new(Queries::new(FX_MQ_JOBS_SCHEMA_NAME)),
        service.clone(),
        &mut registry,
    );
    let mut listener = fx_event_bus::Listener::new(pool.clone(), registry);
    tokio::spawn(async move { listener.listen(None).await });

    let host_id = Uuid::parse_str("00000000-0000-0000-0000-123456789abc")?;
    let mut jobs_listener = fx_mq_jobs::Listener::new(
        pool.clone(),
        register_job_handlers(&service, fx_mq_jobs::RegistryBuilder::new()),
        WORKERS,
        host_id,
        Duration::from_secs(600),
    )
    .await?;
    tokio::spawn(async move { jobs_listener.listen().await });

    let request_id = service
        .new_optimization_request(
            FeatureConfig::NAME,
            FeatureConfig::HASH,
            FitnessGoal::minimize(FITNESS_TARGET)?,
            Schedule::generational(40, 10),
            Selector::tournament(5, 45)?,
            Mutagen::new(Temperature::constant(0.7)?, MutationRate::constant(0.35)?),
            Crossover::uniform(0.5)?,
            Distribution::latin_hypercube(40),
            None::<()>,
        )
        .await?;

    // Poll for completion every 15 seconds (timeout after 1 hour)
    let timeout = Duration::from_secs(7200);
    let poll_interval = Duration::from_secs(15);
    let start = std::time::Instant::now();

    loop {
        if service.is_request_concluded(request_id).await? {
            println!("\nOptimization completed!");
            break;
        }

        if start.elapsed() > timeout {
            println!("\nOptimization timed out after 1 hour.");
            break;
        }

        tokio::time::sleep(poll_interval).await;
    }

    // Get and print the best configuration
    if let Some((genotype, fitness)) = service.get_best_genotype(request_id).await? {
        let config = FeatureConfig::decode(&genotype.genome());
        println!("\n=== Best Configuration ===");
        println!("Fitness (MSE): {:.6}", fitness);
        println!("RMSE: {:.6}°C", fitness.sqrt());
        println!("\nHyperparameters:");
        println!("  Hidden Size: {}", config.hidden_size);
        println!("  Learning Rate: {}", config.learning_rate);
        println!("  Sequence Length: {}", config.sequence_length);
        println!("\nFeatures:");
        for (i, feature) in config.features.iter().enumerate() {
            let pipeline = feature
                .transforms
                .iter()
                .map(|t| t.to_string())
                .collect::<Vec<_>>()
                .join(" → ");
            if pipeline.is_empty() {
                println!("  feat_{}: {}", i, feature.source);
            } else {
                println!("  feat_{}: {} → {}", i, feature.source, pipeline);
            }
        }
    } else {
        println!("No genotypes were evaluated.");
    }

    Ok(())
}

pub fn linear( upper: f64, lower: f64, multiplier: f64, ) -> Result<Self, MutationRateError>

Creates a mutation rate that decays linearly to reduce disruption over time.

Linear decay starts with high genetic diversity and gradually reduces mutations to preserve promising solutions as they emerge.

Parameters

• upper: Starting mutation rate (0.0-1.0) for early diversity
• lower: Ending mutation rate (0.0-1.0) for solution preservation
• multiplier: Decay speed (1.0 = normal, >1.0 = faster, <1.0 = slower)

When to Use

• Most optimization problems benefit from this approach
• When good solutions emerge gradually over time
• Problems where early diversity and later stability both matter
• Balanced exploration-exploitation scenarios

Examples

use fx_durable_ga::models::MutationRate;

// Standard diversity-to-stability transition
let rate = MutationRate::linear(0.5, 0.1, 1.0)?;

// Slower transition for complex problems
let rate = MutationRate::linear(0.6, 0.2, 0.7)?;

// Rapid stabilization
let rate = MutationRate::linear(0.8, 0.05, 1.4)?;

pub fn exponential( upper: f64, lower: f64, multiplier: f64, exponent: i32, ) -> Result<Self, MutationRateError>

Creates a mutation rate that decays exponentially for rapid convergence.

Exponential decay maintains high genetic diversity initially, then rapidly reduces mutations to lock in promising solutions. This provides an intense early search followed by strong solution preservation.

Parameters

• upper: Starting mutation rate (0.0-1.0) for initial diversity
• lower: Ending mutation rate (0.0-1.0) for final stability
• multiplier: Controls timing of decay (higher = earlier/faster reduction)
• exponent: Controls decay aggressiveness (higher = more dramatic curve)

When to Use

• Time-constrained optimization requiring fast convergence
• Problems with clear early vs. late phases
• When disruption of good solutions is particularly costly
• Search spaces where early exploration is critical

Examples

use fx_durable_ga::models::MutationRate;

// Rapid diversity reduction
let rate = MutationRate::exponential(0.7, 0.05, 1.0, 3)?;

// Extreme early diversity, quick stabilization
let rate = MutationRate::exponential(0.9, 0.01, 1.3, 4)?;

// Gentler exponential curve
let rate = MutationRate::exponential(0.5, 0.1, 0.8, 2)?;

Trait Implementations

impl Clone for MutationRate

fn clone(&self) -> MutationRate

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MutationRate

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MutationRate

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for MutationRate

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.