Enum Distribution 

pub enum Distribution {
    LatinHypercube {
        population_size: u32,
    },
    Random {
        population_size: u32,
    },
}

Strategy for generating initial populations in genetic algorithms.

The distribution strategy determines how the initial population is spread across the search space. Different strategies have distinct characteristics that can significantly impact optimization performance, especially during early generations.

Strategy Comparison

Latin Hypercube Sampling: Provides superior space coverage by ensuring each parameter dimension is evenly sampled. This typically leads to better initial diversity and faster convergence.

Random Sampling: Simple uniform random distribution across the search space. May result in clustered solutions or gaps in coverage, but requires no additional computation.

When to Choose Each Strategy

• Latin Hypercube: Recommended for most optimization problems, especially when:

  • You have limited population budget (small population sizes)
  • The search space is large or complex
  • You need consistent, reproducible space coverage
  • You want faster initial convergence

• Random: Consider when:

  • You have very large population sizes (>1000)
  • Computational efficiency is critical
  • You’re comparing against baseline random methods
  • The search space has unusual constraints that Latin Hypercube might not handle well

Performance Impact

Latin Hypercube sampling typically provides 10-30% better initial population quality (measured by best fitness found) compared to random sampling, with the advantage being most pronounced for smaller populations (20-200 individuals).

Examples

use fx_durable_ga::models::Distribution;

// Recommended: Latin Hypercube for better space coverage
let lhc_dist = Distribution::latin_hypercube(50);

// Simple random distribution
let random_dist = Distribution::random(50);

// Large population where random is acceptable
let large_random = Distribution::random(1000);

// Small population where Latin Hypercube shines
let small_lhc = Distribution::latin_hypercube(20);

Variants

LatinHypercube

Latin Hypercube sampling ensures even coverage across all parameter dimensions.

This method divides each parameter’s range into equal intervals and ensures exactly one sample falls in each interval. The intervals are then randomly shuffled across dimensions to decorrelate parameters while maintaining uniform marginal distributions.

Advantages:

• Superior space coverage with fewer samples
• More consistent results across runs
• Better representation of parameter interactions
• Typically finds better initial solutions

Best for: Small to medium population sizes (10-500), complex search spaces

Fields

population_size: u32

Number of individuals in the initial population. Each individual will be positioned to maximize overall space coverage.

Random

Pure random sampling generates individuals uniformly at random across the search space.

Each parameter is independently sampled from its allowed range without coordination between dimensions or individuals. This can result in uneven coverage with potential clusters and gaps.

Advantages:

• Simple and fast generation
• No assumptions about search space structure
• Familiar and well-understood behavior

Best for: Very large populations (>1000), simple search spaces, baseline comparisons

Fields

population_size: u32

Number of individuals to generate randomly. Larger populations help compensate for potential clustering and coverage gaps.

Implementations

impl Distribution

pub fn latin_hypercube(population_size: u32) -> Self

Creates a Latin Hypercube distribution strategy for superior space coverage.

Latin Hypercube sampling provides better initial population diversity by ensuring that each parameter dimension is sampled evenly across its range. This typically results in better optimization performance, especially for smaller populations.

Parameters

• population_size: Number of individuals to generate. For best results, use 10-500. Very small populations (<10) may not fully benefit from the structured sampling, while very large populations (>1000) may not justify the additional computation.

When to Use

• Recommended default for most optimization problems
• Complex, multi-dimensional search spaces
• When population budget is limited
• When you need consistent, reproducible coverage

Examples

use fx_durable_ga::models::Distribution;

// Standard population size with excellent coverage
let dist = Distribution::latin_hypercube(50);

// Small population where coverage is critical  
let small_dist = Distribution::latin_hypercube(20);

// Medium population for complex problems
let medium_dist = Distribution::latin_hypercube(200);

Examples found in repository

examples/regression_model.rs (line 249)

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 203)

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 431)

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 random(population_size: u32) -> Self

Creates a random distribution strategy for simple uniform sampling.

Random sampling generates each individual independently by sampling each parameter uniformly from its allowed range. While simple, this can result in uneven coverage with potential clustering or gaps in the search space.

Parameters

• population_size: Number of individuals to generate. Larger populations (>100) help compensate for potential clustering effects.

When to Use

• Very large populations (>1000) where coverage gaps are less significant
• Computational efficiency is critical
• Comparing against baseline random methods
• Simple, low-dimensional search spaces
• When search space has constraints that might interfere with structured sampling

Examples

use fx_durable_ga::models::Distribution;

// Large population where random sampling is acceptable
let large_dist = Distribution::random(1000);

// Baseline comparison distribution
let baseline_dist = Distribution::random(50);

// High-speed generation for simple problems
let fast_dist = Distribution::random(100);

Trait Implementations

impl Clone for Distribution

fn clone(&self) -> Distribution

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Distribution

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Distribution

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Distribution

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

where __S: Serializer,

Serialize this value into the given Serde serializer.