do another round ot AGENTS.md updates

basvanwesting · basvanwesting · commit df119019b2ec · 2026-02-23T13:52:02.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/examples/hill_climb_milp.rs b/examples/hill_climb_milp.rs
@@ -52,7 +52,6 @@ fn main() {
             MutationType::StepScaled(vec![0.1, 0.01, 0.001, 0.0001, 0.00001, 0.000001]),
             MutationType::StepScaled(vec![0.1, 0.01, 0.001, 0.0001, 0.00001, 0.000001]),
         ])
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/examples/hill_climb_nqueens.rs b/examples/hill_climb_nqueens.rs
@@ -37,7 +37,6 @@ fn main() {
 
     let genotype = UniqueGenotype::builder()
         .with_allele_list((0..BOARD_SIZE).collect())
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/examples/hill_climb_range.rs b/examples/hill_climb_range.rs
@@ -30,7 +30,6 @@ fn main() {
         .with_mutation_type(MutationType::StepScaled(vec![
             0.1, 0.01, 0.001, 0.0001, 0.00001,
         ]))
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/examples/hill_climb_recess.rs b/examples/hill_climb_recess.rs
@@ -372,7 +372,6 @@ fn main() {
                 .flat_map(|(index, adult)| vec![index; adult.number_of_assigns])
                 .collect(),
         )
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/examples/hill_climb_scrabble.rs b/examples/hill_climb_scrabble.rs
@@ -266,7 +266,6 @@ fn main() {
 
     let genotype = MultiListGenotype::builder()
         .with_allele_lists(allele_lists)
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/examples/hill_climb_table_seating.rs b/examples/hill_climb_table_seating.rs
@@ -81,7 +81,6 @@ fn main() {
 
     let genotype = MultiUniqueGenotype::builder()
         .with_allele_lists(allele_lists)
-        .with_genes_hashing(false) // not useful for HillClimb
         .build()
         .unwrap();
 
diff --git a/src/fitness.rs b/src/fitness.rs
@@ -25,6 +25,21 @@ use thread_local::ThreadLocal;
 /// detection. For float-based fitness, scale manually: `(score / precision) as FitnessValue`.
 pub type FitnessValue = isize;
 
+/// Convert a float score to [`FitnessValue`] with the given precision.
+///
+/// Shorthand for `(score / precision) as FitnessValue`.
+/// Accepts both f32 and f64 (and any type implementing `Into<f64>`).
+///
+/// # Example
+/// ```
+/// use genetic_algorithm::fitness::fitness_value;
+/// assert_eq!(fitness_value(3.14159_f32, 0.001_f32), 3141);
+/// assert_eq!(fitness_value(3.14159_f64, 0.001_f64), 3141);
+/// ```
+pub fn fitness_value(score: impl Into<f64>, precision: impl Into<f64>) -> FitnessValue {
+    (score.into() / precision.into()) as FitnessValue
+}
+
 /// Whether to maximize or minimize fitness scores. Default is Maximize.
 #[derive(Copy, Clone, Debug)]
 pub enum FitnessOrdering {
diff --git a/src/fitness/prelude.rs b/src/fitness/prelude.rs
@@ -2,8 +2,8 @@
 pub use crate::chromosome::{Chromosome, GenesHash};
 #[doc(no_inline)]
 pub use crate::fitness::{
-    Fitness, FitnessChromosome, FitnessGenes, FitnessGenotype, FitnessOrdering, FitnessPopulation,
-    FitnessValue,
+    fitness_value, Fitness, FitnessChromosome, FitnessGenes, FitnessGenotype, FitnessOrdering,
+    FitnessPopulation, FitnessValue,
 };
 #[doc(no_inline)]
 pub use crate::genotype::{
diff --git a/src/genotype.rs b/src/genotype.rs
@@ -62,6 +62,7 @@ pub trait Genotype:
 
     fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>);
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>>;
+    fn set_genes_hashing(&mut self, genes_hashing: bool);
     fn max_scale_index(&self) -> Option<usize> {
         None
     }
diff --git a/src/genotype/binary.rs b/src/genotype/binary.rs
@@ -118,6 +118,9 @@ impl Genotype for Binary {
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn random_genes_factory<R: Rng>(&self, rng: &mut R) -> Vec<bool> {
         if self.seed_genes_list.is_empty() {
             rng.sample_iter(Standard).take(self.genes_size).collect()
diff --git a/src/genotype/list.rs b/src/genotype/list.rs
@@ -102,7 +102,13 @@ impl<T: Allele + PartialEq + Hash> TryFrom<Builder<Self>> for List<T> {
                 "ListGenotype requires a genes_size > 0",
             ))
         } else if builder.allele_list.is_none() {
-            Err(TryFromBuilderError("ListGenotype requires allele_list"))
+            if builder.allele_lists.is_some() {
+                Err(TryFromBuilderError(
+                    "ListGenotype requires with_allele_list (singular), not with_allele_lists",
+                ))
+            } else {
+                Err(TryFromBuilderError("ListGenotype requires allele_list"))
+            }
         } else if builder.allele_list.as_ref().map(|o| o.is_empty()).unwrap() {
             Err(TryFromBuilderError(
                 "ListGenotype requires non-empty allele_list",
@@ -186,6 +192,9 @@ impl<T: Allele + PartialEq + Hash> Genotype for List<T> {
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn random_genes_factory<R: Rng>(&self, rng: &mut R) -> Vec<T> {
         if self.seed_genes_list.is_empty() {
             (0..self.genes_size)
diff --git a/src/genotype/multi_list.rs b/src/genotype/multi_list.rs
@@ -108,16 +108,27 @@ impl<T: Allele + PartialEq + Hash> TryFrom<Builder<Self>> for MultiList<T> {
 
     fn try_from(builder: Builder<Self>) -> Result<Self, Self::Error> {
         if builder.allele_lists.is_none() {
-            Err(TryFromBuilderError(
-                "MultiListGenotype requires a allele_lists",
-            ))
+            if builder.allele_list.is_some() {
+                Err(TryFromBuilderError(
+                    "MultiListGenotype requires with_allele_lists (plural), not with_allele_list",
+                ))
+            } else {
+                Err(TryFromBuilderError(
+                    "MultiListGenotype requires allele_lists",
+                ))
+            }
         } else if builder.allele_lists.as_ref().map(|o| o.is_empty()).unwrap() {
             Err(TryFromBuilderError(
                 "MultiListGenotype requires non-empty allele_lists",
             ))
         } else {
             let allele_lists = builder.allele_lists.unwrap();
             let genes_size = allele_lists.len();
+            if builder.genes_size.is_some_and(|s| s != genes_size) {
+                return Err(TryFromBuilderError(
+                    "MultiListGenotype genes_size is derived from allele_lists, don't set it explicitly",
+                ));
+            }
             let allele_list_sizes: Vec<usize> = allele_lists.iter().map(|v| v.len()).collect();
             Ok(Self {
                 genes_size,
@@ -210,6 +221,9 @@ impl<T: Allele + PartialEq + Hash> Genotype for MultiList<T> {
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn random_genes_factory<R: Rng>(&self, rng: &mut R) -> Vec<T> {
         if self.seed_genes_list.is_empty() {
             (0..self.genes_size)
diff --git a/src/genotype/multi_range.rs b/src/genotype/multi_range.rs
@@ -171,7 +171,7 @@ where
     fn try_from(builder: Builder<Self>) -> Result<Self, Self::Error> {
         if builder.allele_ranges.is_none() {
             Err(TryFromBuilderError(
-                "MultiRangeGenotype requires a allele_ranges",
+                "MultiRangeGenotype requires allele_ranges",
             ))
         } else if builder
             .allele_ranges
@@ -185,6 +185,11 @@ where
         } else {
             let allele_ranges = builder.allele_ranges.unwrap();
             let genes_size = allele_ranges.len();
+            if builder.genes_size.is_some_and(|s| s != genes_size) {
+                return Err(TryFromBuilderError(
+                    "MultiRangeGenotype genes_size is derived from allele_ranges, don't set it explicitly",
+                ));
+            }
             let mutation_types = builder
                 .mutation_types
                 .unwrap_or(vec![MutationType::Random; genes_size]);
@@ -408,6 +413,9 @@ where
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn max_scale_index(&self) -> Option<usize> {
         self.mutation_types
             .iter()
diff --git a/src/genotype/multi_unique.rs b/src/genotype/multi_unique.rs
@@ -91,9 +91,15 @@ impl<T: Allele + Hash> TryFrom<Builder<Self>> for MultiUnique<T> {
 
     fn try_from(builder: Builder<Self>) -> Result<Self, Self::Error> {
         if builder.allele_lists.is_none() {
-            Err(TryFromBuilderError(
-                "MultiUniqueGenotype requires a allele_lists",
-            ))
+            if builder.allele_list.is_some() {
+                Err(TryFromBuilderError(
+                    "MultiUniqueGenotype requires with_allele_lists (plural), not with_allele_list",
+                ))
+            } else {
+                Err(TryFromBuilderError(
+                    "MultiUniqueGenotype requires allele_lists",
+                ))
+            }
         } else if builder.allele_lists.as_ref().map(|o| o.is_empty()).unwrap() {
             Err(TryFromBuilderError(
                 "MultiUniqueGenotype requires non-empty allele_lists",
@@ -117,6 +123,17 @@ impl<T: Allele + Hash> TryFrom<Builder<Self>> for MultiUnique<T> {
                 Some(Uniform::from(0..crossover_points.len()))
             };
             let genes_size = allele_list_sizes.iter().sum();
+            // with_allele_lists() auto-sets genes_size to allele_lists.len(), which differs
+            // from the derived sum. Only error if user explicitly set a different value.
+            let auto_set_genes_size = allele_lists.len();
+            if builder
+                .genes_size
+                .is_some_and(|s| s != genes_size && s != auto_set_genes_size)
+            {
+                return Err(TryFromBuilderError(
+                    "MultiUniqueGenotype genes_size is derived from allele_lists, don't set it explicitly",
+                ));
+            }
 
             Ok(Self {
                 genes_size,
@@ -248,6 +265,9 @@ impl<T: Allele + Hash> Genotype for MultiUnique<T> {
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn random_genes_factory<R: Rng>(&self, rng: &mut R) -> Vec<T> {
         if self.seed_genes_list.is_empty() {
             self.allele_lists
diff --git a/src/genotype/range.rs b/src/genotype/range.rs
@@ -313,6 +313,9 @@ where
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn max_scale_index(&self) -> Option<usize> {
         match &self.mutation_type {
             MutationType::RangeScaled(scales) | MutationType::StepScaled(scales) => {
diff --git a/src/genotype/unique.rs b/src/genotype/unique.rs
@@ -72,14 +72,25 @@ impl<T: Allele + Hash> TryFrom<Builder<Self>> for Unique<T> {
 
     fn try_from(builder: Builder<Self>) -> Result<Self, Self::Error> {
         if builder.allele_list.is_none() {
-            Err(TryFromBuilderError("UniqueGenotype requires allele_list"))
+            if builder.allele_lists.is_some() {
+                Err(TryFromBuilderError(
+                    "UniqueGenotype requires with_allele_list (singular), not with_allele_lists",
+                ))
+            } else {
+                Err(TryFromBuilderError("UniqueGenotype requires allele_list"))
+            }
         } else if builder.allele_list.as_ref().map(|o| o.is_empty()).unwrap() {
             Err(TryFromBuilderError(
                 "UniqueGenotype requires non-empty allele_list",
             ))
         } else {
             let allele_list = builder.allele_list.unwrap();
             let genes_size = allele_list.len();
+            if builder.genes_size.is_some_and(|s| s != genes_size) {
+                return Err(TryFromBuilderError(
+                    "UniqueGenotype genes_size is derived from allele_list length, don't set it explicitly",
+                ));
+            }
             Ok(Self {
                 genes_size,
                 allele_list: allele_list.clone(),
@@ -152,6 +163,9 @@ impl<T: Allele + Hash> Genotype for Unique<T> {
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
     }
+    fn set_genes_hashing(&mut self, genes_hashing: bool) {
+        self.genes_hashing = genes_hashing;
+    }
     fn random_genes_factory<R: Rng>(&self, rng: &mut R) -> Vec<T> {
         if self.seed_genes_list.is_empty() {
             let mut genes = self.allele_list.clone();
diff --git a/src/strategy.rs b/src/strategy.rs
@@ -56,7 +56,7 @@
 //!     .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
-//!     .with_replace_on_equal_fitness(true)                    // (E,H,P) optional, defaults to false, maybe useful to avoid repeatedly seeding with the same best chromosomes after mass extinction events
+//!     .with_replace_on_equal_fitness(true)                    // (E,H,P) optional, defaults to true
 //!     .with_rng_seed_from_u64(0);                             // (E,H) for testing with deterministic results
 //!
 //! // the search strategy (specified)
diff --git a/src/strategy/builder.rs b/src/strategy/builder.rs
@@ -12,8 +12,9 @@ use crate::strategy::{Strategy, StrategyReporter, StrategyReporterNoop, Strategy
 
 /// The superset builder for all strategies.
 ///
-/// *Note: Only Genotypes which implement all strategies are eligable for the superset builder.*
-/// *RangeGenotype and other floating point range based genotypes currently do not support Permutation unless scaled*
+/// *Note: Only Genotypes which implement all strategies are eligible for the superset builder.*
+/// *All standard genotypes qualify. RangeGenotype/MultiRangeGenotype support Permutation only*
+/// *with MutationType::Step, StepScaled, or Discrete (runtime check via allows_permutation()).*
 #[derive(Clone, Debug)]
 pub struct Builder<
     G: EvolveGenotype + HillClimbGenotype + PermutateGenotype,
@@ -66,7 +67,7 @@ impl<
             fitness_ordering: FitnessOrdering::Maximize,
             fitness_cache: None,
             par_fitness: false,
-            replace_on_equal_fitness: false,
+            replace_on_equal_fitness: true,
             mutate: None,
             fitness: None,
             crossover: None,
diff --git a/src/strategy/evolve.rs b/src/strategy/evolve.rs
@@ -193,7 +193,7 @@ pub enum EvolveVariant {
 ///     .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
-///     .with_replace_on_equal_fitness(true)                    // optional, defaults to false, maybe useful to avoid repeatedly seeding with the same best chromosomes after mass extinction events
+///     .with_replace_on_equal_fitness(true)                    // optional, defaults to true
 ///     .with_rng_seed_from_u64(0)                              // for testing with deterministic results
 ///     .call()
 ///     .unwrap();
@@ -769,7 +769,7 @@ impl Default for EvolveConfig {
             fitness_ordering: FitnessOrdering::Maximize,
             fitness_cache: None,
             par_fitness: false,
-            replace_on_equal_fitness: false,
+            replace_on_equal_fitness: true,
         }
     }
 }
diff --git a/src/strategy/evolve/builder.rs b/src/strategy/evolve/builder.rs
@@ -63,7 +63,7 @@ impl<
             fitness_ordering: FitnessOrdering::Maximize,
             fitness_cache: None,
             par_fitness: false,
-            replace_on_equal_fitness: false,
+            replace_on_equal_fitness: true,
             mutate: None,
             fitness: None,
             crossover: None,
diff --git a/src/strategy/evolve/prelude.rs b/src/strategy/evolve/prelude.rs
@@ -13,8 +13,8 @@ pub use crate::extension::{
 };
 #[doc(no_inline)]
 pub use crate::fitness::{
-    Fitness, FitnessChromosome, FitnessGenes, FitnessGenotype, FitnessOrdering, FitnessPopulation,
-    FitnessValue,
+    fitness_value, Fitness, FitnessChromosome, FitnessGenes, FitnessGenotype, FitnessOrdering,
+    FitnessPopulation, FitnessValue,
 };
 #[doc(no_inline)]
 pub use crate::genotype::{
diff --git a/src/strategy/hill_climb.rs b/src/strategy/hill_climb.rs
@@ -140,7 +140,7 @@ pub enum HillClimbVariant {
 /// // the search space
 /// let genotype = RangeGenotype::builder()     // f32 alleles
 ///     .with_genes_size(16)                    // 16 genes
-///     .with_genes_hashing(false)              // store genes_hash on chromosome (required for fitness_cache and deduplication extension, both not useful here)
+///     // genes_hashing is auto-disabled for HillClimb (unless fitness_cache is set)
 ///     .with_chromosome_recycling(true)        // recycle genes memory allocations, maybe useful
 ///     .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
@@ -160,7 +160,7 @@ pub enum HillClimbVariant {
 ///     .with_valid_fitness_score(100)                    // block ending conditions until at least the sum of genes <= 0.00100 is reached 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_replace_on_equal_fitness(true)              // optional, defaults to true, crucial for some type of problems with discrete fitness steps like nqueens
+///     .with_replace_on_equal_fitness(true)              // optional, defaults to true
 ///     .with_reporter(HillClimbReporterSimple::new(100)) // optional, report every 100 generations
 ///     .with_rng_seed_from_u64(0)                        // for testing with deterministic results
 ///     .call()
@@ -626,7 +626,10 @@ impl<G: HillClimbGenotype, F: Fitness<Genotype = G>, SR: StrategyReporter<Genoty
             ))
         } else {
             let rng = builder.rng();
-            let genotype = builder.genotype.unwrap();
+            let mut genotype = builder.genotype.unwrap();
+            if builder.fitness_cache.is_none() {
+                genotype.set_genes_hashing(false);
+            }
             let state = HillClimbState::new(&genotype);
 
             Ok(Self {
@@ -662,7 +665,7 @@ impl Default for HillClimbConfig {
             max_generations: None,
             target_fitness_score: None,
             valid_fitness_score: None,
-            replace_on_equal_fitness: false,
+            replace_on_equal_fitness: true,
         }
     }
 }
diff --git a/src/strategy/hill_climb/prelude.rs b/src/strategy/hill_climb/prelude.rs
diff --git a/src/strategy/permutate.rs b/src/strategy/permutate.rs
diff --git a/src/strategy/permutate/builder.rs b/src/strategy/permutate/builder.rs
diff --git a/src/strategy/permutate/prelude.rs b/src/strategy/permutate/prelude.rs
diff --git a/src/strategy/prelude.rs b/src/strategy/prelude.rs
diff --git a/workspace.txt b/workspace.txt

Original file line number	Diff line number	Diff line change
`@@ -372,7 +372,6 @@ fn main() {`
`372`	`372`	`.flat_map(\|(index, adult)\| vec![index; adult.number_of_assigns])`
`373`	`373`	`.collect(),`
`374`	`374`	`)`
`375`		`- .with_genes_hashing(false) // not useful for HillClimb`
`376`	`375`	`.build()`
`377`	`376`	`.unwrap();`
`378`	`377`
Original file line number	Diff line number	Diff line change
`@@ -62,6 +62,7 @@ pub trait Genotype:`
`62`	`62`
`63`	`63`	`fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>);`
`64`	`64`	`fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>>;`
	`65`	`+ fn set_genes_hashing(&mut self, genes_hashing: bool);`
`65`	`66`	`fn max_scale_index(&self) -> Option<usize> {`
`66`	`67`	`None`
`67`	`68`	`}`