update docs

Author: basvanwesting

README.md

@@ -73,8 +73,8 @@ impl Fitness for CountTrue {
 // 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 and drop excess population above target_population_size
-    .with_crossover(CrossoverUniform::new(0.7, 0.8))  // crossover all individual genes between 2 chromosomes for offspring with 40% parent selection (60% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
+    .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
@@ -137,32 +137,16 @@ For the Evolve strategy:
   sorting of some kind. This is relatively fast compared to the rest of the
   operations.
 * Crossover: the workhorse of internal parts. Crossover touches most genes each
-  generation and clones up to the whole population to restore lost population
-  size in selection. See performance tips below.
-  It also calculates new genes hashes if enabled on the Genotype,
-  which has a relatively high overhead on the main Evolve loop.
+  generation and clones up to the whole population to produce offspring
+  (depending on selection-rate). It also calculates
+  new genes hashes if enabled on the Genotype, which has a relatively high
+  overhead on the main Evolve loop.
 * Mutate: no considerations. It touches genes like crossover does, but should
   be used sparingly anyway; with low gene counts (<10%) and low probability (5-20%)
 * Fitness: can be anything. This fully depends on the user domain. Parallelize
   it using `with_par_fitness()` in the Builder. But beware that parallelization
   has it's own overhead and is not always faster.
 
-**Performance Tips**
-* Small genes sizes
-  * It seems that CrossoverMultiGene with `number_of_crossovers = genes_size / 2`
-  and `allow_duplicates = true` is the best tradeoff between performance and
-  effect. CrossoverUniform is an alias for the same approach, taking the
-  genes_size from the genotype at runtime.
-  * Restoring the population doesn't matter that much as the cloning is
-  relatively less pronounced (but becomes more prominent for larger population
-  sizes)
-* Large genes sizes
-  * It seems that CrossoverMultiPoint with `number_of_crossovers = genes_size / 9` 
-  and `allow_duplicates = false` is the best tradeoff between performance and effect.
-  * Restoring the population has considerable performance effects.
-  Use a high selection_rate or even 100%, so there is little parent
-  cloning. Explore non-Vec based genotypes like BitGenotype.
-
 **GPU acceleration**
 
 There are two genotypes where Genes (N) and Population (M) are a stored in single contiguous

src/extension/mass_degeneration.rs

@@ -5,7 +5,7 @@ use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use rand::Rng;
 use std::time::Instant;
 
-/// Simulates a cambrian explosion. The controlling metric is fitness score cardinality in the
+/// Simulates a cambrian explosion. The controlling metric is population cardinality in the
 /// population after selection. When this cardinality drops to the threshold, the full population
 /// is mutated the provided number of times, where the [Genotype](crate::genotype::Genotype)
 /// determines whether this is random, relative or scaled.

src/extension/mass_extinction.rs

@@ -5,12 +5,11 @@ use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use rand::Rng;
 use std::time::Instant;
 
-/// Simulates a cambrian explosion. The controlling metric is fitness score cardinality in the
+/// Simulates a cambrian explosion. The controlling metric is population cardinality in the
 /// population after selection. When this cardinality drops to the threshold, the population is
 /// randomly reduced regardless of fitness using the survival_rate (fraction of population).
 ///
-/// Ensure you have some population growth in select/crossover by setting the
-/// [Select](crate::select::Select) selection_rate > 0.5 in order for the population to recover
+/// Population will recover in the following generations
 #[derive(Debug, Clone)]
 pub struct MassExtinction {
     pub cardinality_threshold: usize,

src/extension/mass_genesis.rs

@@ -9,8 +9,7 @@ use std::time::Instant;
 /// A version of [MassExtinction](crate::extension::ExtensionMassExtinction), where only an adam
 /// and eve of current best chromosomes survive
 ///
-/// Ensure you have some population growth in select/crossover by setting the
-/// [Select](crate::select::Select) selection_rate > 0.5 in order for the population to recover
+/// Population will recover in the following generations
 #[derive(Debug, Clone)]
 pub struct MassGenesis {
     pub cardinality_threshold: usize,

src/genotype/static_matrix.rs

@@ -44,7 +44,9 @@ use std::ops::{Bound, Range, RangeBounds, RangeInclusive};
 ///
 /// # Panics
 ///
-/// Will panic if more chromosomes are instantiated than the population (M) allows.
+/// Will panic if more chromosomes are instantiated than the population (M) allows. M should
+/// account for the target_population_size and the crossover selection_rate which adds offspring on
+/// top of that.
 ///
 /// # Example (f32):
 /// ```

src/lib.rs

@@ -50,8 +50,8 @@
 //! // 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 and drop excess population above target_population_size
-//!     .with_crossover(CrossoverUniform::new(0.7, 0.8))  // crossover all individual genes between 2 chromosomes for offspring with 40% parent selection (60% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
+//!     .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
@@ -118,34 +118,15 @@
 //!   sorting of some kind. This is relatively fast compared to the rest of the
 //!   operations.
 //! * [Crossover](crossover): the workhorse of internal parts. Crossover touches most genes each
-//!   generation and clones up to the whole population to restore lost population size in selection.
-//!   See performance tips below.
-//!   It also calculates new genes hashes if enabled on the [Genotype](genotype), which has a
-//!   relatively high overhead on the main Evolve loop.
+//!   generation and clones up to the whole population to produce offspring (depending on
+//!   selection-rate). It also calculates new genes hashes if enabled on the [Genotype](genotype),
+//!   which has a relatively high overhead on the main Evolve loop.
 //! * [Mutate](mutate): no considerations. It touches genes like crossover does, but should
 //!   be used sparingly anyway; with low gene counts (<10%) and low probability (5-20%)
 //! * [Fitness](fitness): can be anything. This fully depends on the user domain. Parallelize
 //!   it using `with_par_fitness()` in the Builder. But beware that parallelization
 //!   has it's own overhead and is not always faster.
 //!
-//! **Performance Tips**
-//!
-//! * Small genes sizes
-//!   * It seems that [CrossoverMultiGene](crossover::CrossoverMultiGene) with
-//!     `number_of_crossovers = genes_size / 2` and `allow_duplicates = true`
-//!     is the best tradeoff between performance and effect.
-//!     [CrossoverUniform](crossover::CrossoverUniform) is an alias for the same approach,
-//!     taking the genes_size from the genotype at runtime.
-//!   * Restoring the population doesn't matter that much as the cloning is relatively less
-//!     pronounced (but becomes more prominent for larger population sizes)
-//! * Large genes sizes
-//!   * It seems that [CrossoverMultiPoint](crossover::CrossoverMultiPoint) with
-//!     `number_of_crossovers = genes_size / 9` and `allow_duplicates = false` is
-//!     the best tradeoff between performance and effect.
-//!   * Restoring the population has considerable performance effects. Use a high
-//!     selection_rate or even 100%, so there is little parent cloning. Explore non-Vec based
-//!     genotypes like [BitGenotype](genotype::BitGenotype).
-//!
 //! **GPU acceleration**
 //!
 //! There are two genotypes where Genes (N) and Population (M) are a stored in single contiguous

src/strategy.rs

@@ -40,9 +40,9 @@
 //! // 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 and drop excess population above target_population_size
-//!     .with_extension(ExtensionMassExtinction::new(10, 0.1))  // (E) optional builder step, simulate cambrian explosion by mass extinction, when fitness score 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 40% parent selection (60% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
+//!     .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))  // (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

src/strategy/evolve.rs

@@ -53,6 +53,37 @@ pub enum EvolveVariant {
 /// * max_stale_generations: when the ultimate goal in terms of fitness score is unknown and one depends on some convergion
 ///   threshold, or one wants a duration limitation next to the target_fitness_score
 ///
+/// General Hyper-parameters:
+/// * `replacement_rate` (selection): 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.
+/// * `elitism_rate` (selection): 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`
+/// * `selection_rate` (crossover): 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.
+/// * `crossover_rate (or recombination-rate)` (crossover): 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
+/// * `mutation_probability` (mutation): the fraction of offspring which gets mutated.
+///   Typically low, between 0.01 and 0.10. High values reduces convergence
+///   ability. Low have a risk of stagnation.
+///
+///
 /// There are optional mutation distance limitations for
 /// [RangeGenotype](crate::genotype::RangeGenotype) and
 /// [MultiRangeGenotype](crate::genotype::MultiRangeGenotype) chromosomes. Listed in descending
@@ -114,9 +145,9 @@ pub enum EvolveVariant {
 /// let evolve = Evolve::builder()
 ///     .with_genotype(genotype)
 ///
-///     .with_select(SelectElite::new(0.5, 0.02))               // sort the chromosomes by fitness to determine crossover order and drop excess population above target_population_size
-///     .with_extension(ExtensionMassExtinction::new(10, 0.1))  // optional builder step, simulate cambrian explosion by mass extinction, when fitness score 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 40% parent selection (60% do not produce offspring) and 80% chance of crossover (20% of parents just clone)
+///     .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))  // 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