added better and correct documentation

jkhanGitHub · jkhanGitHub · commit 7c2d3dda3b81 · 2026-02-03T04:05:05.000+01:00
diff --git a/pygad/pygad.py b/pygad/pygad.py
@@ -91,7 +91,10 @@ def __init__(self,
         # It is OK to set the value of the 2 parameters ('init_range_low' and 'init_range_high') to be equal, higher or lower than the other parameter (i.e. init_range_low is not needed to be lower than init_range_high).
 
         gene_type: The type of the gene. It is assigned to any of these types (int, numpy.int8, numpy.int16, numpy.int32, numpy.int64, numpy.uint, numpy.uint8, numpy.uint16, numpy.uint32, numpy.uint64, float, numpy.float16, numpy.float32, numpy.float64) and forces all the genes to be of that type.
-        complex_gene_type: A multi value objects like a lists or an arrays are going to be treated a gene_type when set True
+        gene_structure: A List of containing positive integers, that indicate the number of int/floats inside a single gene_type/index of the gene
+            Example: num_genes=10; gene_structure=[1,2,5,1,1] -> 5 genes in total, first gene has 1 int/float, second gene has 2 int/floats, third gene has 5 int/floats, fourth gene has 1 int/float, and fifth gene has 1 int/float.
+            Note: The sum of the values in the 'gene_structure' list must be equal to the value assigned to the 'num_genes' parameter.
+
 
         parent_selection_type: Type of parent selection.
         keep_parents: If 0, this means no parent in the current population will be used in the next population. If -1, this means all parents in the current population will be used in the next population. If set to a value > 0, then the specified value refers to the number of parents in the current population to be used in the next population. Some parent selection operators such as rank selection, favor population diversity and therefore keeping the parents in the next generation can be beneficial. However, some other parent selection operators, such as roulette wheel selection (RWS), have higher selection pressure and keeping more than one parent in the next generation can seriously harm population diversity. This parameter have an effect only when the keep_elitism parameter is 0. Thanks to Prof. Fernando Jiménez (http://webs.um.es/fernan) for editing this sentence.
diff --git a/pygad/utils/mutation.py b/pygad/utils/mutation.py
@@ -368,6 +368,14 @@ def inversion_mutation(self, offspring):
         It accepts:
             -offspring: The offspring to mutate.
         It returns an array of the mutated offspring.
+        
+        If gene_structure is used, we do NOT invert the order of the blocks themselves,
+        as that might violate structural integrity (different block sizes/types).
+        Instead, we select a range of logical blocks and invert the content WITHIN each block.
+        Example: Block A=[0, 1, 0], B=[1, 1, 0]. Logic selects range [A, B].
+        Result: A becomes [1, 0, 1], B becomes [0, 0, 1]. The blocks stay in positions A, B.
+        Might be confusing, when shown with binary values, but basically we still use the numpy.flip function, which when 
+        applied to a numpy array, reverses the order of the elements in the array.
         """
 
         for idx in range(offspring.shape[0]):
@@ -378,14 +386,9 @@ def inversion_mutation(self, offspring):
                 genes_to_scramble = numpy.flip(offspring[idx, mutation_gene1:mutation_gene2])
                 offspring[idx, mutation_gene1:mutation_gene2] = genes_to_scramble
             else:
+                # gene_structure is used to define the structure of the gene.
+                # The inversion mutation is applied to the gene structure.
                 num_logical = len(self.gene_structure)
-
-                # Intra-Block Inversion Logic
-                # When gene_structure is used, we do NOT invert the order of the blocks themselves,
-                # as that might violate structural integrity (different block sizes/types).
-                # Instead, we select a range of logical blocks and invert the content WITHIN each block.
-                # Example: Block A=[0, 1], B=[2]. Logic selects range [A, B].
-                # Result: A becomes [1, 0], B becomes [2] (its own reverse). The blocks stay in positions A, B.
                 
                 mutation_block1 = numpy.random.randint(low=0, high=num_logical, size=1)[0]
                 # Default "range logic" from standard method is somewhat arbitrary (roughly half).
