genetic_algorithms 2.2.0

Library for solving genetic algorithm problems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Configuration traits for the GA builder pattern.
//!
//! These traits define the fluent API used to configure a [`Ga`](crate::ga::Ga)
//! instance. Each trait groups related settings (selection, crossover, mutation,
//! stopping, niching, elitism), and [`ConfigurationT`] combines them all into a
//! single supertrait.

use crate::configuration::{LogLevel, ProblemSolving, StoppingCriteria};
use crate::operations::{Crossover, Extension, Mutation, Selection, Survivor};

/// Configuration for parent selection.
pub trait SelectionConfig {
    /// Sets how many parent pairs are formed each generation.
    fn with_number_of_couples(self, number_of_couples: usize) -> Self;
    /// Sets the selection strategy (e.g., tournament, roulette wheel).
    fn with_selection_method(self, selection_method: Selection) -> Self;
}

/// Configuration for crossover operators.
pub trait CrossoverConfig {
    /// Sets the number of crossover points (for multi-point crossover).
    fn with_crossover_number_of_points(self, number_of_points: usize) -> Self;
    /// Sets the maximum crossover probability (also the static probability when adaptive GA is off).
    fn with_crossover_probability_max(self, probability_max: f64) -> Self;
    /// Sets the minimum crossover probability (used only by adaptive GA).
    fn with_crossover_probability_min(self, probability_min: f64) -> Self;
    /// Sets the crossover method (e.g., uniform, single-point, SBX).
    fn with_crossover_method(self, method: Crossover) -> Self;
    /// Sets the distribution index (eta) for SBX crossover.
    fn with_sbx_eta(self, eta: f64) -> Self;
    /// Sets the alpha parameter for BLX-α crossover.
    fn with_blend_alpha(self, alpha: f64) -> Self;
}

/// Configuration for mutation operators.
pub trait MutationConfig {
    /// Sets the maximum mutation probability (also the static probability when adaptive GA is off).
    fn with_mutation_probability_max(self, probability_max: f64) -> Self;
    /// Sets the minimum mutation probability (used only by adaptive GA).
    fn with_mutation_probability_min(self, probability_min: f64) -> Self;
    /// Sets the mutation method (e.g., swap, inversion, Gaussian).
    fn with_mutation_method(self, method: Mutation) -> Self;
    /// Sets the step size for Creep mutation.
    fn with_mutation_step(self, step: f64) -> Self;
    /// Sets the sigma for Gaussian mutation.
    fn with_mutation_sigma(self, sigma: f64) -> Self;
    /// Enables or disables dynamic mutation probability adjustment based on population cardinality.
    fn with_dynamic_mutation(self, enabled: bool) -> Self;
    /// Sets the target cardinality ratio for dynamic mutation (0.0..1.0).
    fn with_mutation_target_cardinality(self, target: f64) -> Self;
    /// Sets the probability step size for dynamic mutation adjustment.
    fn with_mutation_probability_step(self, step: f64) -> Self;
}

/// Configuration for stopping / termination criteria.
pub trait StoppingConfig {
    /// Sets the maximum number of generations before the GA stops.
    fn with_max_generations(self, max_generations: usize) -> Self;
    /// Sets the target fitness value (used with [`ProblemSolving::FixedFitness`]).
    fn with_fitness_target(self, fitness_target: f64) -> Self;
    /// Sets compound stopping criteria. These are checked in addition to
    /// max_generations and fitness_target.
    fn with_stopping_criteria(self, criteria: StoppingCriteria) -> Self;
}

/// Configuration for fitness sharing / niching.
pub trait NichingConfig {
    /// Enables or disables fitness sharing (niching).
    fn with_niching_enabled(self, enabled: bool) -> Self;
    /// Sets the sharing radius for fitness sharing.
    fn with_niching_sigma_share(self, sigma_share: f64) -> Self;
    /// Sets the alpha parameter for the sharing function shape.
    fn with_niching_alpha(self, alpha: f64) -> Self;
}

/// Configuration for elitism.
pub trait ElitismConfig {
    /// Sets the number of top individuals preserved unchanged between generations.
    fn with_elitism(self, elitism_count: usize) -> Self;
}

/// Configuration for extension strategies (population diversity control).
pub trait ExtensionConfig {
    /// Sets the extension strategy method.
    fn with_extension_method(self, method: Extension) -> Self;
    /// Sets the diversity threshold (fitness standard deviation).
    /// Extension triggers when fitness_std_dev drops below this value.
    fn with_extension_diversity_threshold(self, threshold: f64) -> Self;
    /// Sets the survival rate for MassExtinction (0.0..1.0).
    fn with_extension_survival_rate(self, rate: f64) -> Self;
    /// Sets the number of mutation rounds for MassDegeneration.
    fn with_extension_mutation_rounds(self, rounds: usize) -> Self;
    /// Sets the number of elite individuals protected from the extension event.
    fn with_extension_elite_count(self, count: usize) -> Self;
}

/// Full GA configuration supertrait.
///
/// Combines all focused sub-traits (`SelectionConfig`, `CrossoverConfig`,
/// `MutationConfig`, `StoppingConfig`, `NichingConfig`, `ElitismConfig`)
/// with general GA settings (population size, threading, logging, etc.).
pub trait ConfigurationT:
    SelectionConfig
    + CrossoverConfig
    + MutationConfig
    + StoppingConfig
    + NichingConfig
    + ElitismConfig
    + ExtensionConfig
{
    /// Creates a new instance with default configuration values.
    fn new() -> Self;
    /// Enables or disables the adaptive GA (crossover/mutation probabilities adjust dynamically).
    fn with_adaptive_ga(self, adaptive_ga: bool) -> Self;
    /// Sets the number of threads used for parallel fitness evaluation.
    fn with_threads(self, number_of_threads: usize) -> Self;
    /// Sets the logging verbosity level.
    fn with_logs(self, log_level: LogLevel) -> Self;
    /// Sets the survivor-selection strategy (fitness-based or age-based).
    fn with_survivor_method(self, method: Survivor) -> Self;

    // --- Limit configuration ---

    /// Sets the optimization direction (minimization, maximization, or fixed-fitness target).
    fn with_problem_solving(self, problem_solving: ProblemSolving) -> Self;
    /// Sets the population size (number of individuals per generation).
    fn with_population_size(self, population_size: usize) -> Self;
    /// Sets the number of genes in each chromosome.
    fn with_genes_per_chromosome(self, genes_per_chromosome: usize) -> Self;
    /// If `true`, each chromosome is assigned a unique ID during initialization.
    fn with_needs_unique_ids(self, needs_unique_ids: bool) -> Self;
    /// If `true`, the same allele value may appear more than once in a chromosome.
    fn with_alleles_can_be_repeated(self, alleles_can_be_repeated: bool) -> Self;

    // --- Save progress configuration ---

    /// Enables or disables periodic checkpoint saving (requires `serde` feature).
    fn with_save_progress(self, save_progress: bool) -> Self;
    /// Sets how often (in generations) a checkpoint is written.
    fn with_save_progress_interval(self, save_progress_interval: usize) -> Self;
    /// Sets the directory path where checkpoint files are written.
    fn with_save_progress_path(self, save_progress_path: String) -> Self;

    /// Sets the RNG seed for reproducible runs.
    ///
    /// Two runs with the same seed (and thread count) produce identical results.
    fn with_rng_seed(self, seed: u64) -> Self;
}