update Changelog and docs

Author: basvanwesting

CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.2] - 2025-05-12
+### Added
+* Add `max_generations` ending condition on `Evolve` and `HillClimb` strategies
+  (also blocked by optional `valid_fitness_score,` as `max_stale_generations` is)
+* Add `ExtensionMassDeduplication` which requires `with_genes_hashing(true)` on
+  the `Genotype` (otherwise ignored)
+* Add `Population` `unique_chromosome_indices()` and
+  `best_unique_chromosome_indices()` support functions
+
+### Changed
+* Nuance `ExtensionMassGenesis` trying to use unique Adam en Eve Chromosomes
+  when genes_hashes are availble, otherwise just take 2 best chromosomes
+  (possibly duplicates)
+* Decided not to use unique best chromosomes for the elitism_rate in
+  `ExtensionMassDegeneration` and `ExtensionMassExtinction`. Just use the best
+  chromosomes (possibly duplicates), as uniqueness hard-limits the amount of selected
+  elites in the typical low cardinality situation, which seems unwanted behaviour
+
 ## [0.20.1] - 2025-05-08
 ### Added
 * Add `elitism_rate` to `ExtensionMassExtinction` and

src/crossover.rs

@@ -2,17 +2,20 @@
 //! [selection](crate::select) phase determines the order the parent pairing (overall with fitter
 //! first).
 //!
-//! For the selection-rate, typically set between 0.2 and 0.5 (20%-50% of the population is
-//! selected for reproduction). A higher selection rate (closer to 50%) can accelerate convergence
-//! but risks premature convergence (getting stuck in local optima). A lower selection rate (closer
-//! to 20%) maintains diversity but may slow down the algorithm. Other sources suggest a higher
-//! selection-rate, somewhere in the 0.75-1.0 range. Apparantly there is no broad consensus.
+//! The selection_rate is the fraction of parents which are selected for
+//! reproduction. This selection adds offspring to the population, the other
+//! parents do not. The population now grows by the added offspring, as the
+//! parents are not replaced yet. Value should typically be between 0.4 and
+//! 0.8. High values risk of premature convergence. Low values reduce diversity
+//! if overused.
 //!
-//! For the crossover-rate, typically set between 0.7 and 0.9 (70%-90% of the population undergoes
-//! crossover). Higher crossover rates promote exploration and recombination of genetic material.
+//! The crossover_rate (or recombination-rate) is the fraction of selected parents to crossover,
+//! the remaining parents just clone as offspring. Value should typically be between 0.5 and 0.8.
+//! High values converge faster, but risk losing good solutions. Low values have poor exploration
+//! and risk of premature convergence
 //!
-//! The crossover adds children, thus potentially increasing the population_size above the
-//! target_population_size
+//! Normally the crossover adds children to the popluation, thus increasing the population_size
+//! above the target_population_size. Selection will reduce this again in the next generation
 mod clone;
 mod multi_gene;
 mod multi_point;

src/crossover/rejuvenate.rs

@@ -6,9 +6,9 @@ use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use rand::Rng;
 use std::time::Instant;
 
-/// Drop non-selected parents, then clone top parents to repopulate, then rejuvenate selected
-/// parents to children in place. No copying of chromosomes for creating the offspring itself, only
-/// for repopulating the dropped non-selected parents (smaller fraction)
+/// Drop non-selected parents, then clone top parents to repopulate up to target_population_size,
+/// then rejuvenate selected parents to children in place. No copying of chromosomes for creating
+/// the offspring itself, only for repopulating the dropped non-selected parents (smaller fraction)
 /// Allowed for unique genotypes.
 #[derive(Clone, Debug)]
 pub struct Rejuvenate {

src/extension.rs

@@ -40,7 +40,7 @@ pub trait Extension: Clone + Send + Sync + std::fmt::Debug {
         config: &EvolveConfig,
         elitism_size: usize,
     ) -> Vec<G::Chromosome> {
-        let mut elite_chromosomes: Vec<G::Chromosome> = Vec::new();
+        let mut elite_chromosomes: Vec<G::Chromosome> = Vec::with_capacity(elitism_size);
         for index in state
             .population
             .best_chromosome_indices(elitism_size, config.fitness_ordering)
@@ -60,17 +60,17 @@ pub trait Extension: Clone + Send + Sync + std::fmt::Debug {
         config: &EvolveConfig,
         elitism_size: usize,
     ) -> Vec<G::Chromosome> {
-        let mut unique_elite_chromosomes: Vec<G::Chromosome> = Vec::new();
+        let mut elite_chromosomes: Vec<G::Chromosome> = Vec::with_capacity(elitism_size);
         for index in state
             .population
             .best_unique_chromosome_indices(elitism_size, config.fitness_ordering)
             .into_iter()
             .rev()
         {
             let chromosome = state.population.chromosomes.swap_remove(index);
-            unique_elite_chromosomes.push(chromosome);
+            elite_chromosomes.push(chromosome);
         }
-        unique_elite_chromosomes
+        elite_chromosomes
     }
 
     fn extract_unique_chromosomes<G: EvolveGenotype>(

src/extension/mass_genesis.rs

@@ -7,9 +7,9 @@ use rand::Rng;
 use std::time::Instant;
 
 /// A version of [MassExtinction](crate::extension::ExtensionMassExtinction), where only an Adam
-/// and Eve of current best chromosomes survive. Tries to select distinct Adem and Eve when
+/// and Eve of current best chromosomes survive. Tries to select distinct Adam and Eve when
 /// genes_hash is stored on chromosome, otherwise it will just take 2 of the best (possibly
-/// dupicates).
+/// duplicates).
 ///
 /// Population will recover in the following generations
 #[derive(Debug, Clone)]

src/select.rs

@@ -1,6 +1,22 @@
 //! The selection phase, where chromosomes are lined up for pairing in the
 //! [crossover](crate::crossover) phase, dropping the chromosomes outside of the
 //! target_population_size.
+//!
+//! The replacement_rate is the target fraction of the population which exists of
+//! children. Generational Replacement and Steady-State Replacement can both be
+//! modelled with this parameter by setting it respectively to 1.0 and 0.2-0.8.
+//! High values converge faster, but risk losing good solutions. Low values
+//! convergence slower. If there is a shortage of population after the ideal
+//! fraction, firstly remaining non-selected children and secondly remaining
+//! non-selected parents will be used to fill the shortage to avoid population
+//! collapse.
+//!
+//! The elitism_rate is a non-generational elite gate, which ensures passing of the
+//! best chromosomes before selection and replacement takes place. Value should
+//! typically be very low, between 0.01 and 0.05. Relevant for
+//! `SelectTournament` where the best chromosome is not guaranteed to be
+//! selected for a tournament if the `population_size` is larger than the
+//! `target_population_size`
 mod elite;
 mod tournament;
 mod wrapper;