update documentation

Author: basvanwesting

src/genotype/multi_range.rs

@@ -39,6 +39,10 @@ pub type DefaultAllele = f32;
 /// The discrete mutations traverse all allowed values for every scale (see
 /// [MutationType::Discrete])
 ///
+/// ** Note: ** When all parameters are discrete, prefer
+/// [MultiListGenotype](crate::genotype::MultiListGenotype) as this is more optimized and also
+/// balance the mutation probablity per allowed value, not per gene.
+///
 /// # Heterogeneous Genotype Support
 ///
 /// MultiRangeGenotype supports heterogeneous chromosomes that mix different gene semantics
@@ -55,8 +59,6 @@ pub type DefaultAllele = f32;
 ///   * Useful for encoding: enums (0.0..=4.0), booleans (0.0..=1.0), or discrete choices
 ///   * Neighbours and permutations include all integer values in the allele range
 ///
-/// Explicit `.with_mutation_types()` overrides any auto-detected mutation range settings.
-///
 /// # Example (f32, default, random mutation):
 /// ```
 /// use genetic_algorithm::genotype::{Genotype, MultiRangeGenotype};

src/genotype/mutation_type.rs

@@ -74,8 +74,9 @@ use crate::allele::Allele;
 /// **Example:** With `Step(5)` on range `0..=100`, a gene value of `50` becomes
 /// either `45` or `55` (50% probability each), never values in between.
 ///
-/// **Use case:** Grid-aligned search spaces, discrete optimization where specific
-/// increments are meaningful, systematic exploration patterns.
+/// **Use case:** Grid-aligned search spaces, discrete optimization where specific increments are
+/// meaningful, systematic exploration patterns. Allows [Permutation](crate::strategy::permutate)
+/// for (Multi)RangeGenotype
 ///
 /// ## `RangeScaled(Vec<T>)`
 /// Multi-phase range mutation with strategy-controlled progression. Each element
@@ -121,8 +122,7 @@ use crate::allele::Allele;
 /// - Phase 1: Mutations of exactly ±1
 ///
 /// **Use case:** Grid-like search spaces, systematic parameter sweeps, problems requiring exact
-/// step sizes. Allows for [Permutation](crate::strategy::permutate) and
-/// [HillClimb](crate::strategy::hill_climb)/steepest-ascent for (Multi)RangeGenotype
+/// step sizes. Allows [Permutation](crate::strategy::permutate) for (Multi)RangeGenotype
 ///
 /// Prolonged periods of the same step size can be achieved by setting multiple scales with the
 /// same bandwidth value. You could also alternate between exploration and exploitation several
@@ -137,6 +137,7 @@ use crate::allele::Allele;
 /// which could map to enum variants or categorical options.
 ///
 /// **Use case:** Heterogeneous chromosomes mixing categorical choices with continuous parameters.
+/// Allows [Permutation](crate::strategy::permutate) for (Multi)RangeGenotype
 ///
 /// ** Note: ** When all parameters are discrete, prefer
 /// [ListGenotype](crate::genotype::ListGenotype) or
@@ -298,8 +299,8 @@ pub enum MutationType<T: Allele> {
     /// Step mutation size (exactly +step or -step, clamped)
     Step(T),
     /// Range bandwidths for scaled mutations (strategy controls phase advancement)
+    Discrete,
     RangeScaled(Vec<T>),
     /// Step sizes for scaled mutations (strategy controls phase advancement)
     StepScaled(Vec<T>),
-    Discrete,
 }

src/genotype/range.rs

@@ -22,7 +22,7 @@ pub type DefaultAllele = f32;
 ///
 /// # Permutation
 ///
-/// Supports Permutation for scaled mutations only. This approach implements a
+/// Supports Permutation for scaled and discrete mutations only. This approach implements a
 /// increasingly localized grid search with increasing precision using the
 /// [MutationType::StepScaled]
 /// to define the search scope and grid steps
@@ -33,6 +33,12 @@ pub type DefaultAllele = f32;
 ///   the upper bound of the current scale as step size.
 /// * Scale down and repeat after grid is fully traversed
 ///
+/// The discrete mutations traverse all allowed values for every scale (see
+/// [MutationType::Discrete])
+///
+/// ** Note: ** When all parameters are discrete, prefer
+/// [ListGenotype](crate::genotype::ListGenotype) as this is more optimized.
+///
 /// # Example (f32, default):
 /// ```
 /// use genetic_algorithm::genotype::{Genotype, RangeGenotype, MutationType};

src/strategy/evolve.rs

@@ -53,6 +53,9 @@ 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
 /// * max_generations: when the ultimate goal in terms of fitness score is unknown and there is a effort constraint
+/// * With a scaled [crate::genotype::MutationType]:
+///   * Scale down after max_generations or max_stale_generations is reached and reset scale_generations and stale_generations to zero
+///   * Only trigger max_generations or max_stale_generations ending condition when already reached the smallest scale
 ///
 /// General Hyper-parameters:
 /// * `replacement_rate` (selection): the target fraction of the population which exists of

src/strategy/hill_climb.rs

@@ -54,33 +54,43 @@ pub enum HillClimbVariant {
 ///   there is a replace_on_equal_fitness consideration or some remaining randomness in the neighbouring population (see RangeGenotype
 ///   below)
 /// * max_generations: when the ultimate goal in terms of fitness score is unknown and there is a effort constraint
+/// * With a scaled [crate::genotype::MutationType]:
+///   * Scale down after max_generations or max_stale_generations is reached and reset scale_generations and stale_generations to zero
+///   * Only trigger max_generations or max_stale_generations ending condition when already reached the smallest scale
 ///
 /// There are optional mutation distance limitations for
 /// [RangeGenotype](crate::genotype::RangeGenotype) and
 /// [MultiRangeGenotype](crate::genotype::MultiRangeGenotype) neighbouring chromosomes, see [crate::genotype::MutationType].
-/// * With MutationType::Scaled
-///     * Mutation distance only on edges of current scale (e.g. -1 and +1 for -1..-1 scale)
+/// * With MutationType::StepScaled
+///     * Mutation distance one step up and down
 ///         * Pick random edge for [HillClimbVariant::Stochastic]
 ///         * Take both edges per gene for [HillClimbVariant::SteepestAscent]
-///     * Scale down after max_stale_generations is reached and reset stale_generations to zero
-///     * Only trigger max_stale_generations ending condition when already reached the smallest scale
 ///     * max_stale_generations could be set to 1, as there is no remaining randomness
-/// * With MutationType::Relative
-///     * Mutation distance taken uniformly from mutation range
+/// * With MutationType::StepScaled
+///     * Mutation distance one step up and down of current scale step
+///         * Pick random edge for [HillClimbVariant::Stochastic]
+///         * Take both edges per gene for [HillClimbVariant::SteepestAscent]
+///     * max_stale_generations could be set to 1, as there is no remaining randomness
+/// * With MutationType::Range
+///     * Mutation distance taken uniformly from bandwidth
 ///         * Sample single random value for [HillClimbVariant::Stochastic]
 ///         * Ensure to sample both a higer and lower value per gene for [HillClimbVariant::SteepestAscent]
-///     * Standard max_stale_generations ending condition
+///     * max_stale_generations should be set somewhat higher than 1 as there is some remaining randomness
+/// * With MutationType::RangeScaled
+///     * Mutation distance taken uniformly from current scale bandwidth
+///         * Pick random edge for [HillClimbVariant::Stochastic]
+///         * Take both edges per gene for [HillClimbVariant::SteepestAscent]
 ///     * max_stale_generations should be set somewhat higher than 1 as there is some remaining randomness
 /// * With MutationType::Random (not advised for hill climbing):
 ///     * Mutate uniformly over the complete allele range
 ///         * Sample single random value for [HillClimbVariant::Stochastic]
 ///         * Ensure to sample both a higer and lower value per gene for [HillClimbVariant::SteepestAscent]
-///     * Standard max_stale_generations ending condition
 ///     * max_stale_generations should be set substantially higher than 1 as there is a lot remaining randomness
 /// * With MutationType::Discrete
 ///     * All values are neighbours, just like ListGenotype
-/// * With MutationType::Transition
-///     * Behaves like Random and then slowly transitions to Relative
+///         * Sample single random value for [HillClimbVariant::Stochastic]
+///         * Traverse all values for [HillClimbVariant::SteepestAscent]
+///     * max_stale_generations could be set to 1, as there is no remaining randomness
 ///
 /// There are reporting hooks in the loop receiving the [HillClimbState], which can by handled by an
 /// [StrategyReporter] (e.g. [HillClimbReporterDuration], [HillClimbReporterSimple]). But you are encouraged to

src/strategy/permutate.rs

@@ -44,18 +44,16 @@ pub enum PermutateVariant {
 /// There is a method to permutate
 /// [RangeGenotype](crate::genotype::RangeGenotype) and
 /// [MultiRangeGenotype](crate::genotype::MultiRangeGenotype) chromosomes, see [crate::genotype::MutationType].
-/// * With MutationType::Scaled
-///     * First scale (index = 0) traverses the whole allele_range(s) with the upper bound of the
-///     first scale as step size.
+/// * With MutationType::Step
+///     * Traverses the whole allele_range(s) with the step size.
+/// * With MutationType::StepScaled
+///     * First scale (index = 0) traverses the whole allele_range(s) with the first scale as step size.
 ///     * Other scales (index > 0) center around the best chromomsome of the previous scale,
-///     traversing the previous scale bounds around the best chromosome with the upper bound of the
-///     current scale as step size.
+///     traversing the previous scale step as bounds around the best chromosome with the
+///     current scale as inner step size.
 ///     * Scale down after grid is fully traversed
 /// * With MutationType::Discrete
 ///     * Always permutate all values, just like ListGenotype
-/// * With MutationType::Range: Permutation not supported
-/// * With MutationType::Transition: Permutation not supported
-/// * With MutationType::Random:  Permutation not supported
 ///
 /// There are reporting hooks in the loop receiving the [PermutateState], which can by handled by an
 /// [StrategyReporter] (e.g. [PermutateReporterDuration], [PermutateReporterSimple]). But you are encouraged to