Update doc

Change Genotype mutability effects, add reset_scale_index() to be sure

Author: basvanwesting

CHANGELOG.md

@@ -24,28 +24,29 @@ for later use, when zero-copy actually becomes viable.
 
 Now the library is restructured to a simpler form, moving a lot of
 responsibilities away from `Genotype` which was becoming too heavy and
-centralized: All genes are now `Vec<Allele>` and stored on the `Chromosome`
+centralized: All genes are now `Vec<Allele>` and owned by the `Chromosome`
 (which now only has one implementation, no genotype specific variants anymore).
 
 Chromosome recycling has been moved from the `Genotype` (`ChromosomeManager`)
 to the `Population`, the enabling flag is on `Genotype`. So when making custom
 implementations remember to use the population's `new_chromosome()`,
 `drop_chromomsome()`, `truncate()`, `truncate_external()` &
-`extend_from_within()` methods for the chromosomes.
-
-However, `Genotype` unification proved impossible - each type has fundamentally
-different requirements. So the best route to allow for easier custom `Mutate`
-and `Crossover` implementations, was to make them user-genotype specific using
-an associated type `Genotype` on `Mutate` and `Crossover` traits (following
-existing `Fitness` pattern). The Genotypes now also have some
+`extend_from_within()` methods for the chromosomes. Or just disable the
+recycling (no risk of errors).
+
+However, `Genotype` unification still proved impossible - each type has
+fundamentally different requirements. So the best route to allow for easier
+custom `Mutate` and `Crossover` implementations, was to make them user-genotype
+specific using an associated type `Genotype` on `Mutate` and `Crossover` traits
+(following existing `Fitness` pattern). The Genotypes now also have some
 implementation-specific helper methods to support custom implementations:
 `sample_allele()`, `sample_gene_delta()`, `sample_gene_index()`,
 `sample_gene_indices()`.
 
 Skip the associated type `Genotype` on `Select` and `Extension` for now, as
 these mainly work with the chromosome metadata and are not genotype specific.
 
-General usage by client is hardly impacted, most is internal.
+General usage by client has little impact, most is internal.
 
 ### Changed
 * Add associated type `Genotype` to `Mutate` and `Crossover` traits (following
@@ -55,16 +56,17 @@ General usage by client is hardly impacted, most is internal.
   trait responsible for the hashing implementation (with `impl_allele!` macro
   for default implementation)
 * Moved `current_scale_index` from `StrategyState` to `Genotype`. This is the
-  only change towards `Genotype`. The scaling is only implemented by
+  only change adding `Genotype` logic. The scaling is only implemented by
   `RangeGenotype` and `MultiRangeGenotype`, so it felt more genotype specific.
   It does make the `Genotype` mutable again, which is an accepted tradeoff.
 
 ### Removed
 * Remove matrix genotypes (`DynamicMatrixGenotype`, `StaticMatrixGenotype`)
 * Remove `ChromosomeManager` trait
+* Remove `GenesOwner` and `GenesPointer` traits
 * Remove `BitGenotype` - use `BinaryGenotype` with `Vec<bool>` instead
 * Remove `calculate_for_population()` as the population-level fitness calculation user
-  hook. All is now `calculate_for_chromosome()`
+  hook. All is now `calculate_for_chromosome()` which can now be compile time guarded
 
 ## [0.20.5] - 2025-05-21
 ### Added

README.md

@@ -158,7 +158,7 @@ See [examples/evolve_large_genotype](../main/examples/evolve_large_genotype.rs)
 
 Default configuration for correctness AND performance
 * .with_genes_hashing(true)        // Required for proper GA dynamics
-* .with_chromosome_recycling(true) // Still worth it for large chromosomes
+* .with_chromosome_recycling(true) // Still worth it for large chromosomes, maybe disable for easier custom implementations
 
 ## Tests
 Run tests with `cargo test`

src/genotype.rs

@@ -64,7 +64,7 @@ pub trait Genotype:
     fn builder() -> GenotypeBuilder<Self> {
         GenotypeBuilder::<Self>::default()
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self;
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>);
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>>;
 
     fn max_scale_index(&self) -> Option<usize> {
@@ -73,6 +73,7 @@ pub trait Genotype:
     fn current_scale_index(&self) -> Option<usize> {
         None
     }
+    fn reset_scale_index(&mut self) {}
     fn increment_scale_index(&mut self) -> bool {
         false
     }

src/genotype/binary.rs

@@ -107,10 +107,8 @@ impl Genotype for Binary {
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list

src/genotype/list.rs

@@ -178,10 +178,8 @@ impl<T: Allele + PartialEq + Hash> Genotype for List<T> {
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list

src/genotype/multi_list.rs

@@ -204,10 +204,8 @@ impl<T: Allele + PartialEq + Hash> Genotype for MultiList<T> {
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list

src/genotype/multi_range.rs

@@ -276,10 +276,8 @@ where
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
@@ -296,6 +294,9 @@ where
             None
         }
     }
+    fn reset_scale_index(&mut self) {
+        self.current_scale_index = 0;
+    }
     fn increment_scale_index(&mut self) -> bool {
         if let Some(max_scale_index) = self.max_scale_index() {
             if self.current_scale_index < max_scale_index {

src/genotype/multi_unique.rs

@@ -237,10 +237,8 @@ impl<T: Allele + Hash> Genotype for MultiUnique<T> {
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list

src/genotype/range.rs

@@ -231,10 +231,8 @@ where
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list
@@ -251,6 +249,9 @@ where
             None
         }
     }
+    fn reset_scale_index(&mut self) {
+        self.current_scale_index = 0;
+    }
     fn increment_scale_index(&mut self) -> bool {
         if let Some(max_scale_index) = self.max_scale_index() {
             if self.current_scale_index < max_scale_index {

src/genotype/unique.rs

@@ -143,10 +143,8 @@ impl<T: Allele + Hash> Genotype for Unique<T> {
         }
         chromosome.reset_metadata(self.genes_hashing);
     }
-    fn with_seed_genes_list(&self, seed_genes_list: Vec<Genes<Self::Allele>>) -> Self {
-        let mut new = self.clone();
-        new.seed_genes_list = seed_genes_list;
-        new
+    fn set_seed_genes_list(&mut self, seed_genes_list: Vec<Genes<Self::Allele>>) {
+        self.seed_genes_list = seed_genes_list;
     }
     fn seed_genes_list(&self) -> &Vec<Genes<Self::Allele>> {
         &self.seed_genes_list