Format docstrings

Author: Ahmed Gad

example.py

@@ -1,5 +1,5 @@
 """
-The pygad.helper.helper module has some generic helper methods.
+The pygad.helper.misc module has some generic helper methods.
 """
 
 import numpy
@@ -14,8 +14,10 @@ def change_population_dtype_and_round(self,
         """
         Change the data type of the population. It works with iterables (e.g. lists or NumPy arrays) of shape 2D.
         It does not handle single numeric values or 1D arrays.
+
         It accepts:
             -population: The iterable to change its dtype.
+
         It returns the iterable with the data type changed for all genes.
         """
 
@@ -60,9 +62,11 @@ def change_gene_dtype_and_round(self,
                                     gene_value):
         """
         Change the data type and round a single gene value or a vector of values FOR THE SAME GENE. E.g., the input could be 6 or [6, 7, 8].
+
         It accepts 2 parameters:
             -gene_index: The index of the target gene.
             -gene_value: The gene value.
+
         If gene_value has a single value, then it returns a single number with the type changed and value rounded. If gene_value is a vector, then a vector is returned after changing the data type and rounding.
         """
 
@@ -103,11 +107,13 @@ def mutation_change_gene_dtype_and_round(self,
                                              mutation_by_replacement):
         """
         Change the data type and round the random value used to apply mutation.
+
         It accepts:
             -random_value: The random value to change its data type.
             -gene_index: The index of the target gene.
             -gene_value: The gene value before mutation. Only used if mutation_by_replacement=False and gene_type_single=False.
             -mutation_by_replacement: A flag indicating whether mutation by replacement is enabled or not. The reason is to make this helper method usable while generating the initial population. In this case, mutation_by_replacement does not matter and should be considered False.
+
         It returns the new value after changing the data type and being rounded.
         """
 
@@ -129,10 +135,12 @@ def filter_gene_values_by_constraint(self,
 
         """
         Filter the random values generated for mutation based on whether they meet the gene constraint in the gene_constraint parameter.
+
         It accepts:
             -values: The values to filter.
             -solution: The solution containing the target gene.
             -gene_idx: The index of the gene in the solution.
+
         It returns None if no values satisfy the constraint. Otherwise, an array of values that satisfy the constraint is returned.
         """
 
@@ -166,8 +174,10 @@ def get_gene_dtype(self, gene_index):
 
         """
         Returns the data type of the gene by its index.
+
         It accepts a single parameter:
             -gene_index: The index of the gene to get its data type. Only used if each gene has its own data type.
+
         It returns the data type of the gene.
         """
 
@@ -181,8 +191,10 @@ def get_random_mutation_range(self, gene_index):
 
         """
         Returns the minimum and maximum values of the mutation range.
+
         It accepts a single parameter:
             -gene_index: The index of the gene to get its range. Only used if the gene has a specific mutation range.
+
         It returns the minimum and maximum values of the gene mutation range.
         """
 
@@ -199,8 +211,10 @@ def get_initial_population_range(self, gene_index):
 
         """
         Returns the minimum and maximum values of the initial population range.
+
         It accepts a single parameter:
             -gene_index: The index of the gene to get its range. Only used if the gene has a specific range
+
         It returns the minimum and maximum values of the gene initial population range.
         """
 
@@ -221,6 +235,7 @@ def generate_gene_value_from_space(self,
                                        sample_size=1):
         """
         Generate/select one or more values for the gene from the gene space.
+
         It accepts:
             -gene_idx: The index of the gene in the solution.
             -mutation_by_replacement: A flag indicating whether mutation by replacement is enabled or not. The reason is to make this helper method usable while generating the initial population. In this case, mutation_by_replacement does not matter and should be considered False.
@@ -508,7 +523,6 @@ def get_valid_gene_constraint_values(self,
             -None if no value found that satisfies the constraint.
         """
 
-        print("AAAA", sample_size)
         # Either generate the values randomly or from the gene space.
         values = self.generate_gene_value(range_min=range_min,
                                           range_max=range_max,

pygad/__pycache__/__init__.cpython-310.pyc

@@ -87,14 +87,16 @@ def solve_duplicate_genes_by_space(self,
                                        mutation_by_replacement,
                                        sample_size=100,
                                        build_initial_pop=False):
-    
+
         """
         Resolves duplicates in a solution by selecting new values for the duplicate genes from the gene space.
 
         Args:
             solution (list): A solution containing genes, potentially with duplicate values.
             gene_type (type): The data type of the gene (e.g., int, float).
-            sample_size (int): The maximum number of attempts to resolve duplicates by selecting values from the gene space.
+            mutation_by_replacement (bool): Indicates if mutation is performed by replacement.
+            sample_size (int, optional): The maximum number of attempts to resolve duplicates by selecting values from the gene space.
+            build_initial_pop (bool, optional): Indicates if initial population should be built.
 
         Returns:
             tuple:
@@ -247,7 +249,10 @@ def unique_float_gene_from_range(self,
                                                   gene_index=gene_index)
         return selected_value
 
-    def select_unique_value(self, gene_values, solution, gene_index):
+    def select_unique_value(self,
+                            gene_values,
+                            solution,
+                            gene_index):
 
         """
         Select a unique value (if possible) from a list of gene values.
@@ -293,7 +298,9 @@ def unique_genes_by_space(self,
             solution (list): A solution containing genes with duplicate values.
             gene_type (type): The data type of the all the genes (e.g., int, float).
             not_unique_indices (list): The indices of genes with duplicate values.
+            mutation_by_replacement (bool): Indicates if mutation is performed by replacement.
             sample_size (int): The maximum number of attempts to resolve duplicates for each gene. Only works for floating-point numbers.
+            build_initial_pop (bool, optional): Indicates if initial population should be built.
 
         Returns:
             tuple:
@@ -338,7 +345,9 @@ def unique_gene_by_space(self,
             solution (list): A solution containing genes with duplicate values.
             gene_idx (int): The index of the gene that has a duplicate value.
             gene_type (type): The data type of the gene (e.g., int, float).
+            mutation_by_replacement (bool): Indicates if mutation is performed by replacement.
             sample_size (int): The maximum number of attempts to resolve duplicates for each gene. Only works for floating-point numbers.
+            build_initial_pop (bool, optional): Indicates if initial population should be built.
 
         Returns:
             Any: A unique value for the gene, if one exists; otherwise, the original gene value.            
@@ -387,10 +396,13 @@ def find_two_duplicates(self,
         """
         Identifies the first occurrence of a duplicate gene in the solution.
 
+        Args:
+            solution: The solution containing genes with duplicate values.
+            gene_space_unpacked: A list of values from the gene space to choose the values that resolve duplicates.
+
         Returns:
-            tuple:
-                int: The index of the first gene with a duplicate value.
-                Any: The value of the duplicate gene.
+            int: The index of the first gene with a duplicate value.
+            Any: The value of the duplicate gene.
         """
 
         for gene in set(solution):
@@ -538,9 +550,6 @@ def solve_duplicates_deeply(self,
 
         Args:
             solution (list): The current solution containing genes, potentially with duplicates.
-            gene_idx1 (int): The index of the first gene involved in the duplication.
-            gene_idx2 (int): The index of the second gene involved in the duplication.
-            assist_gene_idx (int): The index of the third gene used to assist in resolving the duplication.
 
         Returns:
             list or None: The updated solution with duplicates resolved, or `None` if the duplicates cannot be resolved.
@@ -565,10 +574,6 @@ def solve_duplicates_deeply(self,
         # This removes all the occurrences of this value.
         gene_other_values = [v for v in gene_other_values if v != duplicate_value]
 
-        # The remove() function only removes the first occurrence of the value.
-        # Do not use it.
-        # gene_other_values.remove(duplicate_value)
-    
         # Two conditions to solve the duplicates of the value D:
             # 1. From gene_other_values, select a value V such that it is available in the gene space of another gene X.
             # 2. Find an alternate value for the gene X that will not cause any duplicates.

pygad/__pycache__/pygad.cpython-310.pyc

@@ -108,7 +108,7 @@ def __init__(self,
         gene_space: It accepts a list of all possible values of the gene. This list is used in the mutation step. Should be used only if the gene space is a set of discrete values. No need for the 2 parameters (random_mutation_min_val and random_mutation_max_val) if the parameter gene_space exists. Added in PyGAD 2.5.0. In PyGAD 2.11.0, the gene_space can be assigned a dict.
 
         gene_constraint: It accepts a list of constraints for the genes. Each constraint is a Python function. Added in PyGAD 3.5.0.
-        sample_size: To select a gene value that respects a constraint, this variable defines the size of the sample from which a value is selected. Useful if either allow_duplicate_genes or gene_constraint is used. Added in PyGAD 3.5.0.
+        sample_size: To select a gene value that respects a constraint, this variable defines the size of the sample from which a value is selected randomly. Useful if either allow_duplicate_genes or gene_constraint is used. Added in PyGAD 3.5.0.
 
         on_start: Accepts a function/method to be called only once before the genetic algorithm starts its evolution. If functioned, then it must accept a single parameter representing the instance of the genetic algorithm. If method, then it must accept 2 parameters where the second one refers to the method's object. Added in PyGAD 2.6.0.
         on_fitness: Accepts a function/method to be called after calculating the fitness values of all solutions in the population. If functioned, then it must accept 2 parameters: 1) a list of all solutions' fitness values 2) the instance of the genetic algorithm. If method, then it must accept 3 parameters where the third one refers to the method's object. Added in PyGAD 2.6.0.
@@ -429,7 +429,6 @@ def __init__(self,
                     # Number of solutions in the population.
                     self.sol_per_pop = sol_per_pop
                     self.initialize_population(allow_duplicate_genes=allow_duplicate_genes,
-                                               mutation_by_replacement=True,
                                                gene_type=self.gene_type,
                                                gene_constraint=gene_constraint)
                 else:
@@ -1354,15 +1353,13 @@ def round_genes(self, solutions):
 
     def initialize_population(self,
                               allow_duplicate_genes,
-                              mutation_by_replacement,
                               gene_type,
                               gene_constraint):
         """
         Creates an initial population randomly as a NumPy array. The array is saved in the instance attribute named 'population'.
 
         It accepts:
             -allow_duplicate_genes: Whether duplicate genes are allowed or not.
-            -mutation_by_replacement: Whether mutation by replacement is enabled or not.
             -gene_type: The data type of the genes.
             -gene_constraint: The constraints of the genes.
 
@@ -1450,14 +1447,14 @@ def initialize_population(self,
                     self.population[solution_idx], _, _ = self.solve_duplicate_genes_randomly(solution=self.population[solution_idx],
                                                                                               min_val=self.init_range_low,
                                                                                               max_val=self.init_range_high,
-                                                                                              mutation_by_replacement=True,
                                                                                               gene_type=gene_type,
+                                                                                              mutation_by_replacement=True,
                                                                                               sample_size=self.sample_size)
                 else:
                     self.population[solution_idx], _, _ = self.solve_duplicate_genes_by_space(solution=self.population[solution_idx].copy(),
                                                                                               gene_type=self.gene_type,
-                                                                                              sample_size=self.sample_size,
                                                                                               mutation_by_replacement=True,
+                                                                                              sample_size=self.sample_size,
                                                                                               build_initial_pop=True)
 
         # Change the data type and round all genes within the initial population.