Reformat docs

Author: ahmedfgad

docs/md/pygad.md

@@ -62,13 +62,7 @@ It is OK to set the value of any of the 2 parameters `init_range_low` and `init_
 
 If the 2 parameters `mutation_type` and `crossover_type` are `None`, this disables any type of evolution the genetic algorithm can make. As a result, the genetic algorithm cannot find a better solution that the best solution in the initial population.
 
-The parameters are validated within the constructor. If at least a parameter is not correct, an exception is thrown.
-
-## Plotting Methods in `pygad.GA` Class
-
-- `plot_fitness()`: Shows how the fitness evolves by generation. 
-- `plot_genes()`: Shows how the gene value changes for each generation.
-- `plot_new_solution_rate()`: Shows the number of new solutions explored in each solution.
+The parameters are validated by calling the `validate_parameters()` method of the `utils.validation.Validation` class within the constructor. If at least a parameter is not correct, an exception is thrown and the `valid_parameters` attribute is set to `False`.
 
 ## Class Attributes
 
@@ -115,215 +109,20 @@ Note that the attributes with names starting with `last_generation_` are updated
 - `select_parents()`: Refers to a method that selects the parents based on the parent selection type specified in the `parent_selection_type` attribute.
 - `adaptive_mutation_population_fitness()`: Returns the average fitness value used in the adaptive mutation to filter the solutions.
 - `summary()`: Prints a Keras-like summary of the PyGAD lifecycle. This helps to have an overview of the architecture. Supported in [PyGAD 2.19.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-19-0). Check the [Print Lifecycle Summary](https://pygad.readthedocs.io/en/latest/pygad_more.html#print-lifecycle-summary) section for more details and examples.
-- 4 methods with names starting with `run_`. Their purpose is to keep the main loop inside the `run()` method clean. The details inside the loop are moved to 4 individual methods. Generally, any method with a name starting with `run_` is meant to be called by PyGAD from inside the `run()` method. Supported in [PyGAD 3.3.1](https://pygad.readthedocs.io/en/latest/releases.html#pygad-3-3-1).
-  1. `run_select_parents(call_on_parents=True)`: Select the parents and call the callable `on_parents()` if defined. If `call_on_parents` is `True`, then the callable `on_parents()` is called. It must be `False` when the `run_select_parents()` method is called to update the parents at the end of the `run()` method.
-  2. `run_crossover()`: Apply crossover and call the callable `on_crossover()` if defined.
-  3. `run_mutation()`: Apply mutation and call the callable `on_mutation()` if defined.
-  4. `run_update_population()`: Update the `population` attribute after completing the processes of crossover and mutation.
+- 5 methods with names starting with `run_`. Their purpose is to keep the main loop inside the `run()` method clean. The details inside the loop are moved to 4 individual methods. Generally, any method with a name starting with `run_` is meant to be called by PyGAD from inside the `run()` method. Supported in [PyGAD 3.3.1](https://pygad.readthedocs.io/en/latest/releases.html#pygad-3-3-1).
+  1. `run_loop_head()`: The code before the loop starts.
+  2. `run_select_parents(call_on_parents=True)`: Select the parents and call the callable `on_parents()` if defined. If `call_on_parents` is `True`, then the callable `on_parents()` is called. It must be `False` when the `run_select_parents()` method is called to update the parents at the end of the `run()` method.
+  3. `run_crossover()`: Apply crossover and call the callable `on_crossover()` if defined.
+  4. `run_mutation()`: Apply mutation and call the callable `on_mutation()` if defined.
+  5. `run_update_population()`: Update the `population` attribute after completing the processes of crossover and mutation.
 
 There are many methods that are not designed for user usage. Some of them are listed above but this is not a comprehensive list. The [release history](https://pygad.readthedocs.io/en/latest/releases.html) section usually covers them. Moreover, you can check the [PyGAD GitHub repository](https://github.com/ahmedfgad/GeneticAlgorithmPython) to find more.
 
 The next sections discuss the methods available in the `pygad.GA` class.
 
-## `initialize_population()`
-
-It creates an initial population randomly as a NumPy array. The array is saved in the instance attribute named `population`.
-
-Accepts the following parameters:
-
-- `low`: The lower value of the random range from which the gene values in the initial population are selected. It defaults to -4. Available in PyGAD 1.0.20 and higher.
-- `high`: The upper value of the random range from which the gene values in the initial population are selected. It defaults to -4. Available in PyGAD 1.0.20.
-
-This method assigns the values of the following 3 instance attributes:
-
-1. `pop_size`: Size of the population.
-2. `population`: Initially, it holds the initial population and later updated after each generation.
-3. `initial_population`: Keeping the initial population.
-
-## `cal_pop_fitness()`
-
-The `cal_pop_fitness()` method calculates and returns the fitness values of the solutions in the current population. 
-
-This function is optimized to save time by making fewer calls the fitness function. It follows this process:
-
-1. If the `save_solutions` parameter is set to `True`, then it checks if the solution is already explored and saved in the `solutions` instance attribute. If so, then it just retrieves its fitness from the `solutions_fitness` instance attribute without calling the fitness function.
-2. If `save_solutions` is set to `False` or if it is `True` but the solution was not explored yet, then the `cal_pop_fitness()` method checks if the `keep_elitism` parameter is set to a positive integer. If so, then it checks if the solution is saved into the `last_generation_elitism` instance attribute. If so, then it retrieves its fitness from the `previous_generation_fitness` instance attribute.
-3. If neither of the above 3 conditions apply (1. `save_solutions` is set to `False` or 2. if it is `True` but the solution was not explored yet or 3. `keep_elitism` is set to zero), then the `cal_pop_fitness()` method checks if the `keep_parents` parameter is set to `-1` or a positive integer. If so, then it checks if the solution is saved into the `last_generation_parents` instance attribute. If so, then it retrieves its fitness from the `previous_generation_fitness` instance attribute.
-4. If neither of the above 4 conditions apply, then we have to call the fitness function to calculate the fitness for the solution. This is by calling the function assigned to the `fitness_func` parameter. 
-
-This function takes into consideration:
-
-1. The `parallel_processing` parameter to check whether parallel processing is in effect.
-2. The `fitness_batch_size` parameter to check if the fitness should be calculated in batches of solutions.
-
-It returns a vector of the solutions' fitness values.
-
-## `run()`
-
-Runs the genetic algorithm. This is the main method in which the genetic algorithm is evolved through some generations. It accepts no parameters as it uses the instance to access all of its requirements.
-
-For each generation, the fitness values of all solutions within the population are calculated according to the `cal_pop_fitness()` method which internally just calls the function assigned to the `fitness_func` parameter in the `pygad.GA` class constructor for each solution.
-
-According to the fitness values of all solutions, the parents are selected using the `select_parents()` method. This method behaviour is determined according to the parent selection type in the `parent_selection_type` parameter in the `pygad.GA` class constructor
-
-Based on the selected parents, offspring are generated by applying the crossover and mutation operations using the `crossover()` and `mutation()` methods. The behaviour of such 2 methods is defined according to the `crossover_type` and `mutation_type` parameters in the `pygad.GA` class constructor.
-
-After the generation completes, the following takes place:
-
-- The `population` attribute is updated by the new population.
-- The `generations_completed` attribute is assigned by the number of the last completed generation.
-- If there is a callback function assigned to the `on_generation` attribute, then it will be called.
-
-After the `run()` method completes, the following takes place:
-
-- The `best_solution_generation` is assigned the generation number at which the best fitness value is reached.
-- The `run_completed` attribute is set to `True`.
-
-## Parent Selection Methods
-
-The `ParentSelection` class in the `pygad.utils.parent_selection` module has several methods for selecting the parents that will mate to produce the offspring. All of such methods accept the same parameters which are:
-
-* `fitness`: The fitness values of the solutions in the current population.
-* `num_parents`: The number of parents to be selected.
-
-All of such methods return an array of the selected parents.
-
-The next subsections list the supported methods for parent selection.
-
-### `steady_state_selection()`
-
-Selects the parents using the steady-state selection technique.
-
-### `rank_selection()`
-
-Selects the parents using the rank selection technique.
-
-### `random_selection()`
-
-Selects the parents randomly.
-
-### `tournament_selection()`
-
-Selects the parents using the tournament selection technique.
-
-### `roulette_wheel_selection()`
-
-Selects the parents using the roulette wheel selection technique.
-
-### `stochastic_universal_selection()`
-
-Selects the parents using the stochastic universal selection technique.
-
-### `nsga2_selection()`
-
-Selects the parents for the NSGA-II algorithm to solve multi-objective optimization problems. It selects the parents by ranking them based on non-dominated sorting and crowding distance.
-
-### `tournament_selection_nsga2()`
-
-Selects the parents for the NSGA-II algorithm to solve multi-objective optimization problems. It selects the parents using the tournament selection technique applied based on non-dominated sorting and crowding distance.
-
-## Crossover Methods
-
-The `Crossover` class in the `pygad.utils.crossover` module supports several methods for applying crossover between the selected parents. All of these methods accept the same parameters which are:
-
-* `parents`: The parents to mate for producing the offspring.
-* `offspring_size`: The size of the offspring to produce.
-
-All of such methods return an array of the produced offspring.
-
-The next subsections list the supported methods for crossover.
-
-### `single_point_crossover()`
-
-Applies the single-point crossover. It selects a point randomly at which crossover takes place between the pairs of parents.
-
-### `two_points_crossover()`
-
-Applies the 2 points crossover. It selects the 2 points randomly at which crossover takes place between the pairs of parents.
-
-### `uniform_crossover()`
-
-Applies the uniform crossover. For each gene, a parent out of the 2 mating parents is selected randomly and the gene is copied from it.
-
-### `scattered_crossover()`
-
-Applies the scattered crossover. It randomly selects the gene from one of the 2 parents. 
-
-## Mutation Methods
-
-The `Mutation` class in the `pygad.utils.mutation` module supports several methods for applying mutation. All of these methods accept the same parameter which is:
-
-* `offspring`: The offspring to mutate.
-
-All of such methods return an array of the mutated offspring.
-
-The next subsections list the supported methods for mutation.
-
-### `random_mutation()`
-
-Applies the random mutation which changes the values of some genes randomly. The number of genes is specified according to either the `mutation_num_genes` or the `mutation_percent_genes` attributes.
-
-For each gene, a random value is selected according to the range specified by the 2 attributes `random_mutation_min_val` and `random_mutation_max_val`. The random value is added to the selected gene.
-
-### `swap_mutation()`
-
-Applies the swap mutation which interchanges the values of 2 randomly selected genes.
-
-### `inversion_mutation()`
-
-Applies the inversion mutation which selects a subset of genes and inverts them.
-
-### `scramble_mutation()`
-
-Applies the scramble mutation which selects a subset of genes and shuffles their order randomly.
-
-### `adaptive_mutation()`
-
-Applies the adaptive mutation which selects the number/percentage of genes to mutate based on the solution's fitness. If the fitness is high (i.e. solution quality is high), then small number/percentage of genes is mutated compared to a solution with a low fitness.
-
-## `best_solution()`
-
-Returns information about the best solution found by the genetic algorithm. 
-
-It accepts the following parameters:
-
-* `pop_fitness=None`: An optional parameter that accepts a list of the fitness values of the solutions in the population. If `None`, then the `cal_pop_fitness()` method is called to calculate the fitness values of the population.
-
-It returns the following:
-
-* `best_solution`: Best solution in the current population.
-
-* `best_solution_fitness`: Fitness value of the best solution.
-
-* `best_match_idx`: Index of the best solution in the current population.
-
-## `plot_fitness()`
-
-Previously named `plot_result()`, this method creates, shows, and returns a figure that summarizes how the fitness value evolves by generation. 
-
-It works only after completing at least 1 generation. If no generation is completed (at least 1), an exception is raised.
-
-## `plot_new_solution_rate()`
-
-The `plot_new_solution_rate()` method creates, shows, and returns a figure that shows the number of new solutions explored in each generation. This method works only when `save_solutions=True` in the constructor of the `pygad.GA` class. 
-
-It works only after completing at least 1 generation. If no generation is completed (at least 1), an exception is raised.
-
-## `plot_genes()`
-
-The `plot_genes()` method creates, shows, and returns a figure that describes each gene. It has different options to create the figures which helps to:
-
-1. Explore the gene value for each generation by creating a normal plot. 
-2. Create a histogram for each gene.
-3. Create a boxplot.
-
-This is controlled by the `graph_type` parameter.
-
-It works only after completing at least 1 generation. If no generation is completed (at least 1), an exception is raised.
-
 ## `save()`
 
-Saves the genetic algorithm instance
+The `save()` method in the `pygad.GA` class saves the genetic algorithm instance as a pickled object.
 
 Accepts the following parameter:
 
@@ -343,6 +142,33 @@ Accepts the following parameter:
 
 Returns the genetic algorithm instance.
 
+# Extended Classes
+
+To make the library modular and structured, different scripts are created where each script has one or more classes. Each class has its own objective.
+
+This is the list of scripts and classes within them where the `pygad.GA` class extends:
+
+1. `utils/engine.py`:
+   1. `utils.engine.GAEngine`: 
+2. `utils/validation.py`
+   1. `utils.validation.Validation`
+3. `utils/parent_selection.py`
+   1. `utils.parent_selection.ParentSelection`
+4. `utils/crossover.py`
+   1. `utils.crossover.Crossover`
+5. `utils/mutation.py`
+   1. `utils.mutation.Mutation`
+6. `utils/nsga2.py`
+   1. `utils.nsga2.NSGA2`
+7. `helper/unique.py`
+   1. `helper.unique.Unique` 
+8. `helper/misc.py`
+   1. `helper.misc.Helper`
+9. `visualize/plot.py`
+   1. `visualize.plot.Plot` 
+
+Since the `pygad.GA` class extends such classes, the attributes and methods inside them can be retrieved by instances of the `pygad.GA` class.
+
 # Steps to Use `pygad`
 
 To use the `pygad` module, here is a summary of the required steps: 

docs/md/releases.md

@@ -552,7 +552,13 @@ Release Date 29 January 2024
 Release Date 17 February 2024
 
 1. After the last generation and before the `run()` method completes, update the 2 instance attributes: 1) `last_generation_parents` 2) `last_generation_parents_indices`. This is to keep the list of parents up-to-date with the latest population fitness `last_generation_fitness`.  https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/275
-2. 4 methods with names starting with `run_`. Their purpose is to keep the main loop inside the `run()` method clean. Check the [Other Methods](https://pygad.readthedocs.io/en/latest/pygad.html#other-methods) section for more information.
+2. 5 methods with names starting with `run_`. Their purpose is to keep the main loop inside the `run()` method clean. Check the [Other Methods](https://pygad.readthedocs.io/en/latest/pygad.html#other-methods) section for more information.
+   1. `run_loop_head()`: The code before the loop starts.
+   2. `run_select_parents()`: The parent selection-related code.
+   3. `run_crossover()`: The crossover-related code.
+   4. `run_mutation()`: The mutation-related code.
+   5. `run_update_population()`: Update the `population` instance attribute after completing the processes of crossover and mutation.
+
 
 ## PyGAD 3.4.0
 
@@ -616,16 +622,16 @@ Release Date 08 July 2025
   4. The `summary()` method was moved to `Helper` class in the `pygad/helper/misc.py` script.
   5. The validation code in the `__init__()` method of the `pygad.GA` class is moved to the new `validate_parameters()` method in the new `Validation` class in the new `pygad/utils/validation.py` script. Moreover, the `validate_multi_stop_criteria()` method is also moved to the same class.
   6. The GA main workflow is moved into the new `GAEngine` class in the new `pygad/utils/engine.py` script. Specifically, these methods are moved from the `pygad.GA` class to the new `GAEngine` class:
-           1. run()
-           2. run_loop_head()
-           3. run_select_parents()
-           4. run_crossover()
-           5. run_mutation()
-           6. run_update_population()
-           7. initialize_population()
-           8. cal_pop_fitness()
-           9. best_solution()
-           10. round_genes()
+             1. `run()`
+                  1. `run_loop_head()`
+                  2. `run_select_parents()`
+                  3. `run_crossover()`
+                  4. `run_mutation()`
+                  5. `run_update_population()`
+             2. `initialize_population()`
+             3. `cal_pop_fitness()`
+             4. `best_solution()`
+             5. `round_genes()`
 7. The `pygad.GA` class now extends the two new classes `utils.validation.Validation` and `utils.engine.GAEngine`.
 8. The version of the `pygad.utils` submodule is upgraded from `1.3.0` to `1.4.0`.
 9. The version of the `pygad.helper` submodule is upgraded from `1.2.0` to `1.3.0`.