Genetic Algorithm

https://docs.rs/genetic_algorithm/0.26.0/
Admin
A Rust implementation of genetic algorithms, providing tools for defining genotypes, fitness...
Tokens:1,520,291
Snippets:7,752
Trust Score:9.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Rust Documentation Search Examples

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/enum.StrategyVariant_search=u32+-%3E+bool

Provides examples of effective search queries for the Rust documentation. These examples demonstrate how to search for specific types, type conversions, and generic type transformations.

```text
std::vec
u32 -> bool
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Evolve Setup and Cleanup in Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/evolve/struct.Evolve_search=std%3A%3Avec

Illustrates the `setup` and `cleanup` methods for managing the Evolve instance's state, particularly concerning thread-local fitness calculation. The `setup` method initializes resources, while `cleanup` releases them, ensuring proper resource management during the evolution lifecycle.

```rust
pub fn setup(&mut self, fitness_thread_local: Option<&ThreadLocal<RefCell<F>>>)

pub fn cleanup( &mut self, fitness_thread_local: Option<&mut ThreadLocal<RefCell<F>>>, )
```

--------------------------------

### Rust Permutate Setup and Cleanup Methods

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/permutate.rs_search=u32+-%3E+bool

Implements the `setup` and `cleanup` methods for the `Permutate` strategy. Setup initializes the state, calculates the initial fitness, and updates the best chromosome. Cleanup resets state variables and clears the population.

```rust
impl<G: PermutateGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genotype = G>>
    Permutate<G, F, SR>
{
    pub fn setup(&mut self) {
        let now = Instant::now();
        self.state.chromosome = self.genotype.chromosome_permutations_into_iter(None).next();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
        self.fitness
            .call_for_state_chromosome(&self.genotype, &mut self.state, &self.config);
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
    pub fn cleanup(&mut self) {
        let now = Instant::now();
        self.state.chromosome.take();
        self.state.population.chromosomes.clear();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
    }
    fn is_finished(&self) -> bool {
        self.is_finished_by_max_scale_generation()
    }
    fn is_finished_by_max_scale_generation(&self) -> bool {
        self.state.scale_generation > 0
    }

    fn call_sequential(&mut self) {
        self.genotype
            .clone()
    }
}
```

--------------------------------

### Implement Setup Method for Permutate Strategy (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/permutate.rs_search=std%3A%3Avec

Implements the `setup` method for the `Permutate` struct. This method initializes the state for a new run, including setting the initial chromosome, calculating its fitness, and updating the best known chromosome if it's the first or an improved one. It records the setup duration.

```rust
impl<G: PermutateGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genotype = G>>
    Permutate<G, F, SR>
{
    pub fn setup(&mut self) {
        let now = Instant::now();
        self.state.chromosome = self.genotype.chromosome_permutations_into_iter(None).next();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
        self.fitness
            .call_for_state_chromosome(&self.genotype, &mut self.state, &self.config);
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
// ... other methods ...
```

--------------------------------

### Hill Climb Strategy Configuration Example

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/hill_climb/struct.HillClimb_search=std%3A%3Avec

Provides a comprehensive example of configuring the Hill Climb strategy using `HillClimbBuilder`. It covers genotype setup, variant selection, fitness function definition, ordering, caching, parallel fitness calculation, termination conditions, and reporting.

```rust
use genetic_algorithm::strategy::hill_climb::prelude::*;
use genetic_algorithm::fitness::placeholders::SumGenes;

// the search space
let genotype = RangeGenotype::builder()     // f32 alleles
    .with_genes_size(16)                    // 16 genes
    .with_genes_hashing(false)              // store genes_hash on chromosome
    .with_chromosome_recycling(true)        // recycle genes memory allocations
    .with_allele_range(0.0..=1.0)           // allow gene values between 0.0 and 1.0
    .with_mutation_type(MutationType::Range(0.1)) // optional, neighbouring step size randomly sampled from range
    .with_mutation_type(MutationType::StepScaled(vec![0.1, 0.01, 0.001])) // optional, neighbouring step size equal to start/end of each scaled range
    .build()
    .unwrap();

// the search strategy
let hill_climb = HillClimb::builder()
    .with_genotype(genotype)
    .with_variant(HillClimbVariant::SteepestAscent)   // check all neighbours for each round
    .with_fitness(SumGenes::new_with_precision(1e-5)) // sum the gene values of the chromosomes with precision 0.00001
    .with_fitness_ordering(FitnessOrdering::Minimize) // aim for the lowest sum
    .with_fitness_cache(1000)                         // enable caching of fitness values (LRU size 1000)
    .with_par_fitness(true)                           // optional, use parallel fitness calculation
    .with_target_fitness_score(0)                     // ending condition if sum of genes is <= 0.00001
    .with_valid_fitness_score(100)                    // block ending conditions until sum of genes <= 0.00100 is reached
    .with_max_stale_generations(1000)                 // stop searching if no improvement for 1000 generations
    .with_max_generations(1_000_000)                  // optional, stop searching after 1M generations
    .with_replace_on_equal_fitness(true)              // optional, crucial for some problems with discrete fitness steps
    .with_reporter(HillClimbReporterSimple::new(100)) // optional, report every 100 generations
    .with_rng_seed_from_u64(0)                        // for testing with deterministic results
    .call()
    .unwrap();

// it's all about the best genes after all
let (best_genes, best_fitness_score) = hill_climb.best_genes_and_fitness_score().unwrap();
assert_eq!(best_genes.into_iter().map(|v| v <= 1e-3).collect::<Vec<_>>(), vec![true; 16]);
assert_eq!(best_fitness_score, 0);

```

--------------------------------

### BinaryGenotype Initialization Example

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/evolve.rs_search=u32+-%3E+bool

Provides a practical example of how to initialize a `BinaryGenotype` with specific configurations using the `EvolveBuilder`. It demonstrates setting the number of genes, enabling gene hashing for caching and cardinality estimation, and enabling chromosome recycling for memory efficiency.

```rust
use genetic_algorithm::strategy::evolve::prelude::*;
use genetic_algorithm::fitness::placeholders::CountTrue;

// the search space
let genotype = BinaryGenotype::builder() // boolean alleles
    .with_genes_size(100)                // 100 genes per chromosome
    .with_genes_hashing(true)            // store genes_hash on chromosome (required for fitness_cache and deduplication extension, optional for better population cardinality estimation)
    .with_chromosome_recycling(true)     // recycle genes memory allocations
    .build()
    .unwrap();
```

--------------------------------

### Permutate Setup and Cleanup

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/permutate/struct.Permutate_search=u32+-%3E+bool

Provides the signatures for the `setup` and `cleanup` methods within the `Permutate` struct's implementation. These methods are responsible for initializing and finalizing the state of the permutation strategy before and after the main algorithm loop, respectively.

```rust
pub fn setup(&mut self)
pub fn cleanup(&mut self)
```

--------------------------------

### Permutate Setup and Cleanup Methods in Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/permutate.rs

Implements the `setup` and `cleanup` methods for the `Permutate` struct. `setup` initializes the state, calculates the initial chromosome's fitness, and updates the best chromosome if necessary. `cleanup` resets the current chromosome and clears the population.

```rust
impl<G: PermutateGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genotype = G>>
    Permutate<G, F, SR>
{
    pub fn setup(&mut self) {
        let now = Instant::now();
        self.state.chromosome = self.genotype.chromosome_permutations_into_iter(None).next();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
        self.fitness
            .call_for_state_chromosome(&self.genotype, &mut self.state, &self.config);
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
    pub fn cleanup(&mut self) {
        let now = Instant::now();
        self.state.chromosome.take();
        self.state.population.chromosomes.clear();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
    }
    fn is_finished(&self) -> bool {
        self.is_finished_by_max_scale_generation()
    }
    fn is_finished_by_max_scale_generation(&self) -> bool {
        self.state.scale_generation > 0
    }

    fn call_sequential(&mut self) {

```

--------------------------------

### Rust Genetic Algorithm: Hill Climb Setup Example

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/hill_climb.rs_search=

This code snippet demonstrates how to initialize and configure a Hill Climb strategy for a genetic algorithm. It includes setting up the genotype with specific parameters like gene size, allele range, and mutation types, and then configuring the Hill Climb builder with the chosen variant, fitness function, and termination conditions. Dependencies include the genetic_algorithm crate and its prelude.

```rust
use genetic_algorithm::strategy::hill_climb::prelude::*;
use genetic_algorithm::fitness::placeholders::SumGenes;

// the search space
let genotype = RangeGenotype::builder()
    .with_genes_size(16)
    .with_genes_hashing(false)
    .with_chromosome_recycling(true)
    .with_allele_range(0.0..=1.0)
    .with_mutation_type(MutationType::Range(0.1))
    .with_mutation_type(MutationType::StepScaled(vec![0.1, 0.01, 0.001]))
    .build()
    .unwrap();

// the search strategy
let hill_climb = HillClimb::builder()
    .with_genotype(genotype)
    .with_variant(HillClimbVariant::SteepestAscent)
    .with_fitness(SumGenes::new_with_precision(1e-5))
    .with_fitness_ordering(FitnessOrdering::Minimize)
    .with_fitness_cache(1000)
    .with_par_fitness(true)
    .with_target_fitness_score(0)
    .build();
```

--------------------------------

### Permutate Setup Method - Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/permutate/struct.Permutate_search=

Implementation of the `setup` method for the `Permutate` strategy, which prepares the strategy for execution. This method is part of the `Strategy` trait.

```rust
pub fn setup(&mut self)
```

--------------------------------

### Setup and Cleanup Evolutionary State - Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/evolve/struct.Evolve_search=

These methods, `setup` and `cleanup`, manage the state of the genetic algorithm evolution process. `setup` takes an optional thread-local reference to a fitness calculator, likely for initializing or preparing fitness evaluation. `cleanup` performs necessary deallocations or finalization steps, also accepting an optional mutable thread-local fitness calculator.

```rust
pub fn setup(&mut self, fitness_thread_local: Option<&ThreadLocal<RefCell<F>>>)
```

```rust
pub fn cleanup( &mut self, fitness_thread_local: Option<&mut ThreadLocal<RefCell<F>>>, )
```

--------------------------------

### Implement Setup and Cleanup Methods for Permutate in Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/permutate.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements the `setup` and `cleanup` methods for the `Permutate` struct. `setup` initializes the state by processing the first chromosome permutation, evaluating its fitness, and updating the best chromosome found. `cleanup` resets the current chromosome and clears the population.

```rust
impl<G: PermutateGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genotype = G>>
    Permutate<G, F, SR>
{
    pub fn setup(&mut self) {
        let now = Instant::now();
        self.state.chromosome = self.genotype.chromosome_permutations_into_iter(None).next();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
        self.fitness
            .call_for_state_chromosome(&self.genotype, &mut self.state, &self.config);
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
    pub fn cleanup(&mut self) {
        let now = Instant::now();
        self.state.chromosome.take();
        self.state.population.chromosomes.clear();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
    }
    // ... other methods ...
}
```

--------------------------------

### StrategyBuilder Example (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm_search=

Demonstrates the use of `StrategyBuilder` for simplifying the implementation and switching between different genetic algorithm strategies (e.g., Evolve, HillClimb, Permutate). This pattern promotes cleaner code and easier experimentation. The example is located in `examples/explore_strategies`.

```rust
/*
// Example structure for using StrategyBuilder:

use genetic_algorithm::strategy::StrategyBuilder;
use genetic_algorithm::strategy::Strategy;

fn main() {
    // Create a builder
    let mut builder = StrategyBuilder::new();

    // Configure strategies
    builder.set_evolve_strategy(); // Default or explicitly set
    // Or builder.set_hill_climb_strategy();
    // Or builder.set_permutate_strategy();

    // Get the configured strategy
    let strategy = builder.build();

    // Use the strategy in the population evolution
    // population.evolve(generations, &strategy);

    // Easily switch strategies by reconfiguring the builder
    // builder.set_hill_climb_strategy();
    // let new_strategy = builder.build();
    // population.evolve(generations, &new_strategy);
}
*/

// To run this specific example:
// cargo run --example explore_strategies --release
```

--------------------------------

### Setup Algorithm State (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/evolve.rs_search=

Initializes the genetic algorithm's state, including constructing the initial population, calculating fitness scores, and reporting the initial best chromosome. It measures the time taken for setup.

```rust
pub fn setup(&mut self, fitness_thread_local: Option<&ThreadLocal<RefCell<F>>>) {
        let now = Instant::now();
        self.state.population = self
            .genotype
            .population_constructor(self.config.target_population_size, &mut self.rng);
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());

        self.fitness.call_for_state_population(
            &self.genotype,
            &mut self.state,
            &self.config,
            fitness_thread_local,
        );
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            let chromosome = &self.state.population.chromosomes[0];
            self.state.best_generation = self.state.current_generation;
            self.state.best_chromosome = Some(chromosome.clone());
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
```

--------------------------------

### Custom Reporting Implementation Example

Source: https://docs.rs/genetic_algorithm/0.26.0/index

Provides an example of implementing custom reporting mechanisms within the genetic algorithm framework. This specific instance is related to the scrabble problem in `examples/permutate_scrabble`.

```Rust
trait Reporter { fn report(&self, generation: usize, population: &[impl Clone]); } 

struct MyCustomReporter;

impl Reporter for MyCustomReporter {
    fn report(&self, generation: usize, population: &[impl Clone]) {
        // Custom reporting logic here
        println!("Generation {}: Reporting...", generation);
    }
}

fn main() {
    // Setup involving custom reporting
    // let reporter = MyCustomReporter;
    // ...
    println!("Implementing custom reporting...");
    // ... (example specific code)
}
```

--------------------------------

### Custom Reporting Implementation Example (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm_search=

Demonstrates how to implement custom reporting mechanisms within the genetic algorithm framework. This allows users to define specific ways to log, monitor, or analyze the progress and results of the evolutionary process. The example is found in `examples/permutate_scrabble`.

```rust
/*
// Example structure for custom reporting:

use genetic_algorithm::reporting::{Reporter, Report}; // Assuming these traits exist
use genetic_algorithm::population::Population;

// Define a custom reporter struct
struct MyCustomReporter {
    // Fields to store statistics or log data
    best_fitness_history: Vec<f64>,
}

impl Reporter for MyCustomReporter {
    fn report(&mut self, population: &Population) {
        if let Some(best_individual) = population.get_best() {
            self.best_fitness_history.push(best_individual.fitness);
            // Log other relevant information
            println!("Generation {}: Best Fitness = {}", population.get_current_generation(), best_individual.fitness);
        }
    }
}

// Add this reporter when setting up the population or evolution process
// let mut reporter = MyCustomReporter { best_fitness_history: Vec::new() };
// population.add_reporter(Box::new(reporter));
// ... run evolution ...
// Access the history after evolution: reporter.best_fitness_history
*/

// To run this specific example:
// cargo run --example permutate_scrabble --release
```

--------------------------------

### Permutate Setup Method (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/permutate.rs_search=

Handles the initial setup phase of the Permutate strategy. It sets the initial chromosome, calculates its fitness, and updates the best chromosome if it's the first one or has a better fitness score.

```rust
impl<G: PermutateGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genotype = G>> Permutate<G, F, SR> {
    pub fn setup(&mut self) {
        let now = Instant::now();
        self.state.chromosome = self.genotype.chromosome_permutations_into_iter(None).next();
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());
        self.fitness
            .call_for_state_chromosome(&self.genotype, &mut self.state, &self.config);
        self.state.update_best_chromosome_and_report(
            &self.genotype,
            &self.config,
            &mut self.reporter,
        );

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
    }
    // ... other methods ...
```

--------------------------------

### Permutation Strategy Example (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm_search=

Showcases the permutation strategy for genetic algorithms, suitable for smaller search spaces. This strategy guarantees finding the optimal solution by systematically exploring all possible gene orderings. Examples include `examples/permutate_knapsack` and `examples/permutate_scrabble`.

```rust
use genetic_algorithm::strategy::Strategy;
use genetic_algorithm::population::Population;
use genetic_algorithm::genotype::{Genotype, PermutationGenotype};
use rand::thread_rng;

// Assume Item struct and KnapsackFitness are defined as above
// Or ScrabbleFitness for the scrabble example

// Example for Knapsack with permutation strategy
// fn run_permutate_knapsack() {
//     let items = vec![...];
//     let weight_limit = 100;
//     let fitness = KnapsackFitness { items: &items, weight_limit };
//     let mut genotype_template = PermutationGenotype::<Item>::new(); // Example
//     genotype_template.set_genes(items.clone()); // Initialize with items to permute
//     let mut population = Population::new_with_template(10, &fitness, &genotype_template, &mut thread_rng());
//     let permutation_strategy = Strategy::Permutate;
//     population.evolve(100, &permutation_strategy);
//     println!("Best solution: {:?}", population.get_best().unwrap());
// }

```

--------------------------------

### Setup Genetic Algorithm State (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/hill_climb.rs

Initializes the genetic algorithm's state, including creating the initial chromosome or population and evaluating fitness. This function handles the setup for both 'Stochastic' and 'SteepestAscent' variants, ensuring the algorithm is ready for evolution.

```rust
let now = Instant::now();

        self.state.chromosome = Some(self.genotype.chromosome_constructor_random(&mut self.rng));
        self.state
            .add_duration(StrategyAction::SetupAndCleanup, now.elapsed());

        match self.config.variant {
            HillClimbVariant::Stochastic => {
                self.fitness.call_for_state_chromosome(
                    &self.genotype,
                    &mut self.state,
                    &self.config,
                );
                self.state.update_best_chromosome_from_state_chromosome(
                    &self.genotype,
                    &self.config,
                    &mut self.reporter,
                );
            }
            HillClimbVariant::SteepestAscent => {
                let population_size = self.genotype.seed_genes_list().len().max(1);
                self.state.population = self
                    .genotype
                    .population_constructor(population_size, &mut self.rng);

                self.fitness.call_for_state_population(
                    &self.genotype,
                    &mut self.state,
                    &self.config,
                    None,
                );
                self.state.update_best_chromosome_from_state_population(
                    &self.genotype,
                    &self.config,
                    &mut self.reporter,
                    &mut self.rng,
                );
            }
        }

        if self.state.best_fitness_score().is_none() {
            self.state.best_generation = self.state.current_generation;
            self.state
                .best_chromosome
                .clone_from(&self.state.chromosome);
            self.reporter
                .on_new_best_chromosome(&self.genotype, &self.state, &self.config);
            self.state.reset_stale_generations();
        }
```

--------------------------------

### Custom Mutate Implementation Example (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm_search=

Shows how to implement custom mutation operators beyond the standard library offerings. This provides flexibility to design unique ways of introducing variation into the population, tailored to specific problem domains. The example is found in `examples/evolve_milp_custom_mutate`.

```rust
/*
// Example structure for a custom mutation implementation:

use genetic_algorithm::mutation::{Mutation, MutationType};
use genetic_algorithm::genotype::Genotype;
use rand::Rng;

// Define a custom mutation struct
struct MyCustomMutation {
    // Parameters specific to this mutation type
    custom_param: f64,
}

impl Mutation for MyCustomMutation {
    fn mutate<G: Genotype, R: Rng>(&self, genotype: &mut G, rng: &mut R) -> bool {
        // Logic for applying the custom mutation
        // This should modify the genotype in place and return true if a mutation occurred.
        // Example: Mutate a single gene based on custom_param
        let genes = genotype.get_mut_genes();
        if genes.is_empty() { return false; }

        let index_to_mutate = rng.gen_range(0..genes.len());
        // ... apply custom mutation logic to genes[index_to_mutate] ...
        // For demonstration, let's assume it always mutates and returns true
        true
    }
}

// When configuring the genetic algorithm, specify the custom mutation:
// let custom_mutate_op = MyCustomMutation { custom_param: 0.1 };
// let mut population = Population::new(...);
// population.set_mutation(Box::new(custom_mutate_op));
// ... evolve ...
*/

// To run this specific example:
// cargo run --example evolve_milp_custom_mutate --release
```

--------------------------------

### Get TypeId using Rust's Any trait

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/evolve/struct.EvolveReporterSimple_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides an example of using the `type_id` method from the `Any` trait in Rust. This method returns the `TypeId` of an object, which is a unique identifier for its type at runtime.

```rust
impl<T> Any for T where T: 'static + ?Sized {
    fn type_id(&self) -> TypeId {
        // Implementation omitted for brevity
    }
}
```

--------------------------------

### EvolveBuilder Configuration Example

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/evolve/struct.Evolve_search=

This example demonstrates how to initialize and configure the EvolveBuilder for a genetic algorithm. It covers setting up the genotype, selection, extension, crossover, mutation, fitness function, and various evolutionary control parameters like population size, fitness score targets, and generation limits.

```rust
use genetic_algorithm::strategy::evolve::prelude::*;
use genetic_algorithm::fitness::placeholders::CountTrue;

// the search space
let genotype = BinaryGenotype::builder() // boolean alleles
    .with_genes_size(100)                // 100 genes per chromosome
    .with_genes_hashing(true)            // store genes_hash on chromosome (required for fitness_cache and deduplication extension, optional for better population cardinality estimation)
    .with_chromosome_recycling(true)     // recycle genes memory allocations
    .build()
    .unwrap();

// the search strategy
let evolve = Evolve::builder()
    .with_genotype(genotype)

    .with_select(SelectElite::new(0.5, 0.02))               // sort the chromosomes by fitness to determine crossover order. Strive to replace 50% of the population with offspring. Allow 2% through the non-generational best chromosomes gate before selection and replacement
    .with_extension(ExtensionMassExtinction::new(10, 0.1, 0.02)) // optional builder step, simulate cambrian explosion by mass extinction, when population cardinality drops to 10 after the selection, trim to 10% of population
    .with_crossover(CrossoverUniform::new(0.7, 0.8))        // crossover all individual genes between 2 chromosomes for offspring with 70% parent selection (30% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
    .with_mutate(MutateSingleGene::new(0.2))                // mutate offspring for a single gene with a 20% probability per chromosome
    .with_fitness(CountTrue)                                // count the number of true values in the chromosomes
    .with_fitness_ordering(FitnessOrdering::Minimize)       // aim for the least true values
    .with_fitness_cache(1000)                               // enable caching of fitness values (LRU size 1000), only works when genes_hash is stored in chromosome. Only useful for long stale runs, but better to increase population diversity
    .with_par_fitness(true)                                 // optional, defaults to false, use parallel fitness calculation
    .with_target_population_size(100)                       // evolve with 100 chromosomes
    .with_target_fitness_score(0)                           // ending condition if 0 times true in the best chromosome
    .with_valid_fitness_score(10)                           // block ending conditions until at most a 10 times true in the best chromosome
    .with_max_stale_generations(1000)                       // stop searching if there is no improvement in fitness score for 1000 generations (per scaled_range)
    .with_max_generations(1_000_000)                        // optional, stop searching after 1M generations
    .with_max_chromosome_age(10)                            // kill chromosomes after 10 generations
    .with_reporter(EvolveReporterSimple::new(100))          // optional builder step, report every 100 generations
;
```

--------------------------------

### Get Builder (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy/hill_climb.rs

Provides a builder for creating a `HillClimb` instance with a `StrategyReporterNoop` reporter. This is a convenience function for users who want to start building a genetic algorithm with a no-operation reporter.

```rust
HillClimbBuilder::new()
```

--------------------------------

### Get Slice View of Rust Vec

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/chromosome/type.Genes_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides examples of obtaining immutable (`as_slice`) and mutable (`as_mut_slice`) views of a Rust Vec as slices. These methods are equivalent to slicing the entire vector (`&s[..]` and `&mut s[..]`). They are useful for interacting with APIs that expect slices.

```rust
use std::io::{self, Write};
let buffer = vec![1, 2, 3, 5, 8];
io::sink().write(buffer.as_slice()).unwrap();
```

```rust
use std::io::{self, Read};
let mut buffer = vec![0; 3];
io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
```

--------------------------------

### Genetic Algorithm Strategy Builder Example (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/strategy.rs_search=

Demonstrates how to use the `StrategyBuilder` to configure and build a genetic algorithm strategy. This example sets up a `BinaryGenotype`, defines selection, crossover, mutation, and fitness functions, and specifies various execution parameters like population size, fitness score targets, and generation limits. It also enables parallel fitness calculation and uses a simple reporter.

```Rust
use genetic_algorithm::strategy::prelude::*;
use genetic_algorithm::fitness::placeholders::CountTrue;

// the search space
let genotype = BinaryGenotype::builder()
    .with_genes_size(10)
    .with_genes_hashing(true)        // store genes_hash on chromosome (required for fitness_cache and deduplication extension, optional for better population cardinality estimation)
    .with_chromosome_recycling(true) // recycle genes memory allocations
    .build()
    .unwrap();

// the search strategy (superset), steps marked (E)volve, (H)illClimb and (P)ermutate
let builder = StrategyBuilder::new()
    .with_genotype(genotype)                                // (E,H,P) the genotype
    .with_select(SelectElite::new(0.5, 0.02))               // (E) sort the chromosomes by fitness to determine crossover order. Strive to replace 50% of the population with offspring. Allow 2% through the non-generational best chromosomes gate before selection and replacement
    .with_extension(ExtensionMassExtinction::new(10, 0.1, 0.02))  // (E) optional builder step, simulate cambrian explosion by mass extinction, when population cardinality drops to 10 after the selection, trim to 10% of population
    .with_crossover(CrossoverUniform::new(0.7, 0.8))        // (E) crossover all individual genes between 2 chromosomes for offspring with 70% parent selection (30% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
    .with_mutate(MutateSingleGene::new(0.2))                // (E) mutate offspring for a single gene with a 20% probability per chromosome
    .with_fitness(CountTrue)                                // (E,H,P) count the number of true values in the chromosomes
    .with_fitness_ordering(FitnessOrdering::Minimize)       // (E,H,P) aim for the least true values
    .with_fitness_cache(1000)                               // (E) enable caching of fitness values, only works when genes_hash is stored in chromosome.
    .with_par_fitness(true)                                 // (E,H,P) optional, defaults to false, use parallel fitness calculation
    .with_target_population_size(100)                       // (E) evolve with 100 chromosomes
    .with_target_fitness_score(0)                           // (E,H) ending condition if 0 times true in the best chromosome
    .with_valid_fitness_score(1)                            // (E,H) block ending conditions until at most a 1 times true in the best chromosome
    .with_max_stale_generations(100)                        // (E,H) stop searching if there is no improvement in fitness score for 100 generations
    .with_max_generations(1_000_000)                        // (E,H) optional, stop searching after 1M generations
    .with_max_chromosome_age(10)                            // (E) kill chromosomes after 10 generations
    .with_reporter(StrategyReporterSimple::new(usize::MAX)); // (E,H,P) optional builder step, report on new best chromosomes only

```

--------------------------------

### Set and Get Seed Genes List in Unique Genotype (Rust)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/genotype/unique.rs_search=

Functions to set and retrieve the list of seed genes for the genotype. The `set_seed_genes_list` method updates the internal list, while `seed_genes_list` provides read access. These are crucial for initializing or guiding the population.

```rust
fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
        self.seed_genes_list = seed_genes_list;
    }
    fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
        &self.seed_genes_list
    }
```

--------------------------------

### Build RangeGenotype with Scaled Range Mutation (i32)

Source: https://docs.rs/genetic_algorithm/0.26.0/src/genetic_algorithm/genotype/mutation_type.rs_search=std%3A%3Avec

Example of a RangeGenotype for i32 alleles using `RangeScaled` mutation. The `vec![50, 20, 5, 1]` defines mutation bandwidths for different phases, starting broad and narrowing down, with pre-clamping in early phases and post-clamping in the final phase.

```rust
// Scaled exploration with proper clamping strategy
// Strategy controls when to advance phases
let genotype = RangeGenotype::<i32>::builder()
    .with_allele_range(0..=100)
    .with_mutation_type(MutationType::RangeScaled(vec![
        50,  // Broad exploration (pre-clamped, no boundary bias)
        20,  // Medium range (pre-clamped)
        5,   // Focused search (pre-clamped)
        1,   // Fine-tuning (post-clamped, can reach boundaries)
    ]))
    .build();
```

--------------------------------

### Get Best Genes and Fitness Score - Rust

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/permutate/struct.Permutate_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the best genes and their corresponding fitness score from a `Permutate` strategy instance. This method is called after the permutation process has been completed. The example asserts that the best genes are all `false` and the best fitness score is `0` when minimizing the count of true values in a 12-gene binary genotype.

```rust
let (best_genes, best_fitness_score) = permutate.best_genes_and_fitness_score().unwrap();
assert_eq!(best_genes, vec![false; 12]);
assert_eq!(best_fitness_score, 0);
```

--------------------------------

### Rust Builder Initialization Methods

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/strategy/builder/struct.Builder_search=

Provides methods for initializing and configuring the `Builder` for genetic algorithms. Includes a basic `new` constructor and several `with_...` methods to set specific parameters like genotype, variant, target population size, and generation limits. These methods allow for fluent, step-by-step construction of the algorithm strategy.

```rust
pub fn new() -> Self
```

```rust
pub fn with_genotype(self, genotype: G) -> Self
```

```rust
pub fn with_variant(self, variant: StrategyVariant) -> Self
```

```rust
pub fn with_target_population_size(self, target_population_size: usize) -> Self
```

```rust
pub fn with_max_stale_generations(self, max_stale_generations: usize) -> Self
```

```rust
pub fn with_max_stale_generations_option( self, max_stale_generations_option: Option<usize>, ) -> Self
```

```rust
pub fn with_max_generations(self, max_generations: usize) -> Self
```

```rust
pub fn with_max_generations_option( self, max_generations_option: Option<usize>, ) -> Self
```

```rust
pub fn with_max_chromosome_age(self, max_chromosome_age: usize) -> Self
```

```rust
pub fn with_max_chromosome_age_option( self, max_chromosome_age_option: Option<usize>, ) -> Self
```

```rust
pub fn with_target_fitness_score( self, target_fitness_score: FitnessValue, ) -> Self
```

```rust
pub fn with_target_fitness_score_option( self, target_fitness_score_option: Option<FitnessValue>, ) -> Self
```

```rust
pub fn with_valid_fitness_score(self, valid_fitness_score: FitnessValue) -> Self
```

```rust
pub fn with_valid_fitness_score_option( self, valid_fitness_score_option: Option<FitnessValue>, ) -> Self
```

```rust
pub fn with_fitness_ordering(self, fitness_ordering: FitnessOrdering) -> Self
```

```rust
pub fn with_fitness_cache(self, fitness_cache_size: usize) -> Self
```

```rust
pub fn with_par_fitness(self, par_fitness: bool) -> Self
```

```rust
pub fn with_replace_on_equal_fitness( self, replace_on_equal_fitness: bool, ) -> Self
```

```rust
pub fn with_mutate(self, mutate: M) -> Self
```

```rust
pub fn with_fitness(self, fitness: F) -> Self
```

```rust
pub fn with_crossover(self, crossover: S) -> Self
```

```rust
pub fn with_select(self, select: C) -> Self
```

```rust
pub fn with_extension<E2: Extension<Genotype = G>>( self, extension: E2, ) -> Builder<G, M, F, S, C, E2, SR>
```

```rust
pub fn with_reporter<SR2: StrategyReporter<Genotype = G>>( self, reporter: SR2, ) -> Builder<G, M, F, S, C, E, SR2>
```

```rust
pub fn with_rng_seed_from_u64(self, rng_seed: u64) -> Self
```

```rust
pub fn with_rng_seed_from_u64_option(self, rng_seed_option: Option<u64>) -> Self
```

--------------------------------

### MultiRangeGenotype Construction Examples

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/genotype/struct.MultiRangeGenotype

Examples demonstrating how to build a MultiRangeGenotype with different mutation strategies.

```APIDOC
## Example (f32, scaled mutation)

This example shows how to construct a `MultiRangeGenotype` with scaled mutation types for floating-point genes.

### Method

`MultiRangeGenotype::builder()...build()`

### Request Example

```rust
use genetic_algorithm::genotype::{Genotype, MultiRangeGenotype, MutationType};

let genotype = MultiRangeGenotype::builder()
    .with_allele_ranges(vec![
       0.0..=10.0,
       5.0..=20.0,
       0.0..=5.0,
       10.0..=30.0
    ])
    .with_mutation_types(vec![
       MutationType::StepScaled(vec![1.0,0.1]),
       MutationType::StepScaled(vec![2.0,0.2]),
       MutationType::StepScaled(vec![0.5,0.05]),
       MutationType::StepScaled(vec![3.0,0.3]),
    ]) // optional, restricts mutations to relative step up or down of each scale
    .with_genes_hashing(true) // optional, defaults to true
    .with_chromosome_recycling(true) // optional, defaults to true
    .build()
    .unwrap();
```

## Example (f32, heterogeneous mutation)

This example demonstrates constructing a `MultiRangeGenotype` with heterogeneous mutation types, suitable for genes with different characteristics like boolean flags, discrete choices, and continuous values.

### Method

`MultiRangeGenotype::builder()...build()`

### Request Example

```rust
use genetic_algorithm::genotype::{Genotype, MultiRangeGenotype, MutationType};

let genotype = MultiRangeGenotype::builder()
    .with_allele_ranges(vec![
        0.0..=1.0,    // Gene 0: Boolean flag
        0.0..=4.0,    // Gene 1: Algorithm choice (5 options)
        0.0..=100.0,  // Gene 2: Speed percentage
    ])
    .with_mutation_types(vec![
        MutationType::Discrete,  // Boolean as 0 or 1
        MutationType::Discrete,  // One of 5 algorithms
        MutationType::StepScaled(vec![10.0, 1.0, 0.1]), // Continuous refinement
    ])
    .with_genes_hashing(true) // optional, defaults to true
    .with_chromosome_recycling(true) // optional, defaults to true
    .build();
```
```

--------------------------------

### Rust Genetic Algorithm Quick Usage Example

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm_search=u32+-%3E+bool

Demonstrates the basic usage of the `genetic_algorithm` crate in Rust. It shows how to define a binary genotype, implement a fitness function to count true values, configure an evolution strategy with selection, crossover, and mutation, and then run the algorithm to find the best genes and fitness score. This example requires the `genetic_algorithm` crate and its `evolve::prelude::*` module.

```rust
use genetic_algorithm::strategy::evolve::prelude::*;

// the search space
let genotype = BinaryGenotype::builder() // boolean alleles
    .with_genes_size(100)                // 100 genes per chromosome
    .build()
    .unwrap();

println!("{}", genotype);

// the search goal to optimize towards (maximize or minimize)
#[derive(Clone, Debug)]
pub struct CountTrue;
impl Fitness for CountTrue {
    type Genotype = BinaryGenotype; // Genes = Vec<bool>
    fn calculate_for_chromosome(
        &mut self,
        chromosome: &FitnessChromosome<Self>,
        _genotype: &FitnessGenotype<Self>
    ) -> Option<FitnessValue> {
        Some(chromosome.genes.iter().filter(|&value| *value).count() as FitnessValue)
    }
}

// the search strategy
let evolve = Evolve::builder()
    .with_genotype(genotype)
    .with_select(SelectElite::new(0.5, 0.02))         // sort the chromosomes by fitness to determine crossover order. Strive to replace 50% of the population with offspring. Allow 2% through the non-generational best chromosomes gate before selection and replacement
    .with_crossover(CrossoverUniform::new(0.7, 0.8))  // crossover all individual genes between 2 chromosomes for offspring with 70% parent selection (30% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
    .with_mutate(MutateSingleGene::new(0.2))          // mutate offspring for a single gene with a 20% probability per chromosome
    .with_fitness(CountTrue)                          // count the number of true values in the chromosomes
    .with_fitness_ordering(FitnessOrdering::Maximize) // optional, default is Maximize, aim towards the most true values
    .with_target_population_size(100)                 // evolve with 100 chromosomes
    .with_target_fitness_score(100)                   // goal is 100 times true in the best chromosome
    .with_reporter(EvolveReporterSimple::new(100))    // optional builder step, report every 100 generations
    .call()
    .unwrap();

println!("{}", evolve);

// it's all about the best genes after all
let (best_genes, best_fitness_score) = evolve.best_genes_and_fitness_score().unwrap();
assert_eq!(best_genes, vec![true; 100]);
assert_eq!(best_fitness_score, 100);
```

--------------------------------

### CustomExtension Example

Source: https://docs.rs/genetic_algorithm/0.26.0/genetic_algorithm/extension/trait.Extension_search=

An example implementation of the `Extension` trait, demonstrating custom logic for deduplicating the population after selection.

```APIDOC
## Struct: CustomExtension

An example implementation of the `Extension` trait.

### Fields

- **`cardinality_threshold`** (usize) - The threshold for population cardinality to trigger deduplication.

### Implementation of `Extension` Trait

```rust
use genetic_algorithm::strategy::evolve::prelude::*;
use std::time::Instant;
use itertools::Itertools;
use rand::Rng;

#[derive(Clone, Debug)]
pub struct CustomExtension {
    pub cardinality_threshold: usize,
}

impl Extension for CustomExtension {
    type Genotype = MultiRangeGenotype<f32>;

    // Override specific extension points as needed
    fn after_selection_complete<R: Rng, SR: StrategyReporter<Genotype = Self::Genotype>>(
        &mut self,
        genotype: &mut Self::Genotype,
        state: &mut EvolveState<Self::Genotype>,
        config: &EvolveConfig,
        reporter: &mut SR,
        _rng: &mut R,
    ) {
        if genotype.genes_hashing() && state.population.size() >= config.target_population_size {
            let now = Instant::now();
            if let Some(cardinality) = state.population_cardinality() {
                if cardinality <= self.cardinality_threshold {
                    reporter.on_extension_event(
                        ExtensionEvent("DeduplicatePopulation".to_string()),
                        genotype,
                        state,
                        config,
                    );

                    let mut unique_chromosomes = self.extract_unique_chromosomes(genotype, state, config);
                    let unique_size = unique_chromosomes.len();

                    // Ensure there are always 2 chromosomes after appending, remove the rest
                    let remaining_size = 2usize.saturating_sub(unique_size);
                    state.population.truncate(remaining_size);
                    state.population.chromosomes.append(&mut unique_chromosomes);
                }
            }
            state.add_duration(StrategyAction::Extension, now.elapsed());
        }
    }
}
```
```
Tokens:
Raw