(#71) (#81) (#68) edit problem configuration, imports, and documentation

README.md

@@ -56,45 +56,49 @@ Here’s how we can define this problem in Python using the `ExampleProblem` cla
 
 ```python
 from mpmath import power as pw
+from typing import List
 
 from pycellga.optimizer import cga
-from pycellga.individual import GeneType
-from pycellga.selection import TournamentSelection
 from pycellga.recombination import ByteOnePointCrossover
 from pycellga.mutation import ByteMutationRandom
+from pycellga.selection import TournamentSelection
+from pycellga.problems import AbstractProblem
+from pycellga.common import GeneType
 
-class ExampleProblem:
-
-    def __init__(self):
-        pass
-
-    def f(self, x):
-
-        return sum(pw(xi, 2) for xi in x)
+class ExampleProblem(AbstractProblem):
+
+    def __init__(self, n_var):
+
+        super().__init__(
+            gen_type=GeneType.REAL,
+            n_var=n_var,
+            xl=-100, 
+            xu=100
+        )
+
+    def f(self, x: List[float]) -> float:
+        return round(sum(pw(xi, 2) for xi in x),3)
 ```
 **Usage:**
 
 ```python
 result = cga(
-    n_cols=5,
-    n_rows=5,
-    n_gen=100,
-    ch_size=5,
-    gen_type=GeneType.REAL,
-    p_crossover=0.9,
-    p_mutation=0.2,
-    problem=ExampleProblem(),  # Replace with a real problem instance as needed
-    selection=TournamentSelection,
-    recombination=ByteOnePointCrossover,
-    mutation=ByteMutationRandom,
-    mins=[-32.768] * 5,  # Minimum values for each gene
-    maxs=[32.768] * 5,    # Maximum values for each gene
-    seed_par=100  # Ensures the random number generation is repeatable
-)
-
-# Print the best solution details
-print("Best solution chromosome:", result.chromosome)
-print("Best fitness value:", result.fitness_value)
+        n_cols=5,
+        n_rows=5,
+        n_gen=100,
+        ch_size=5,
+        p_crossover=0.9,
+        p_mutation=0.2,
+        problem=ExampleProblem(n_var=5),
+        selection=TournamentSelection,
+        recombination=ByteOnePointCrossover,
+        mutation=ByteMutationRandom,
+        seed_par=100
+    )
+
+    # Print the results
+    print("Best solution chromosome:", result.chromosome)
+    print("Best fitness value:", result.fitness_value)
 
 # Expected Output:
 # Best solution chromosome: [0.0, 0.0, 0.0, 0.0, 0.0]

docs/conf.py

@@ -31,7 +31,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_static_path = ['_static', 'images']
+
 
 html_theme_options = {
     'collapse_navigation': False,

docs/index.rst

@@ -17,6 +17,14 @@ promoting diversity and maintaining a balance between exploration and exploitati
 `pycellga` has machine coded operators with byte implementations. Beside it has Alpha-male CGA, 
 Machine Coded Compact CGA and Improved CGA with Machine Coded Operators for real-valued optimization problems.
 
+.. image:: images/cycle_cga.png
+   :scale: 40%
+   :alt: Reproductive cycle of an individual in cGA
+   :align: center
+
+
+A representation of the reproductive cycle of an individual in a cellular genetic algorithm.
+
 .. toctree::
    :maxdepth: 1
    :caption: Table of Contents :

docs/pycellga.mutation.rst

@@ -1,12 +1,54 @@
 Mutation Operators
-==============================
+==================
 
-The `pycellga.mutation` module provides a comprehensive set of mutation operators designed to introduce variation into the population during the genetic algorithm optimization process. Each operator serves a unique purpose based on the representation of the chromosome (binary, real-valued, or permutation-based) and the specific requirements of the optimization problem.
+Mutation operators introduce variation into the population by modifying one or more genes of an individual. In cellular genetic algorithms (CGAs), mutation is a key mechanism that ensures diversity and enables exploration of the solution space, preventing premature convergence.
 
-This module includes the following mutation operators:
+**Understanding Mutation**
+--------------------------
+
+Mutation in genetic algorithms mimics the natural process of genetic mutation, where random changes occur in an individual’s genome. These changes help the algorithm discover new solutions and improve its overall performance.
+
+**The Role of Mutation in CGA**
+
+- **Diversity Preservation**: Mutation ensures that the population does not converge prematurely to suboptimal solutions.
+- **Exploration**: Introduces new solutions to explore unexplored regions of the solution space.
+- **Fine-Tuning**: Makes small adjustments to solutions, aiding in reaching optimal solutions.
+
+**Mutation Examples**
+--------------------------
+
+Below is an example of a **Bit-Flip Mutation** applied to a binary chromosome:
+
+.. image:: images/bit_flip_mutation.png
+   :scale: 50%
+   :alt: Bit-flip Mutation Structure
+   :align: center
+
+Figure 1: Bit-flip mutation flips a single gene in a binary chromosome.
+
+Another example is the **Swap Mutation**, often used for permutation-based problems. It swaps two genes, introducing a small but significant change in the chromosome:
+
+.. image:: images/swap_mutation.png
+   :scale: 50%
+   :align: center
+
+Figure 2: Swap mutation changes the order of two genes in a chromosome.
+
+**Common Mutation Types**
+
+1. **Bit-Flip Mutation**: Flips a bit in binary-encoded chromosomes.
+2. **Swap Mutation**: Exchanges two genes in permutation-based chromosomes.
+3. **Byte Mutation**: Applies byte-level changes to real-valued genes.
+4. **Two-Opt Mutation**: Reverses a segment of the chromosome, particularly useful in path optimization.
+
+
+**API References**
+------------------
+
+The following sections provide detailed documentation for the mutation operators available in the `pycellga.mutation` package.
 
 **Bit Flip Mutation**
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Applies a bitwise flip to binary-encoded chromosomes. This operator is a classic choice for binary genetic algorithms, offering a simple yet effective mutation approach.
 
@@ -15,8 +57,8 @@ Applies a bitwise flip to binary-encoded chromosomes. This operator is a classic
    :undoc-members:
    :show-inheritance:
 
-**Byte-Level Mutation**
-------------------------------
+**Byte Mutation**
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Performs mutations at the byte level for real-valued chromosomes. This operator leverages byte manipulation to create small, precise adjustments in the solution space, optimizing the algorithm's performance for continuous functions.
 
@@ -26,7 +68,7 @@ Performs mutations at the byte level for real-valued chromosomes. This operator
    :show-inheritance:
 
 **Randomized Byte Mutation**
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Introduces randomness at the byte level, enabling broader exploration in real-valued optimization tasks. This operator is particularly effective when a high degree of variation is desirable.
 
@@ -36,7 +78,7 @@ Introduces randomness at the byte level, enabling broader exploration in real-va
    :show-inheritance:
 
 **Uniform Float Mutation**
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Applies uniform random mutations across real-valued chromosomes. This operator is suitable for continuous optimization, where each gene is adjusted within a defined range to enhance solution diversity.
 
@@ -46,7 +88,7 @@ Applies uniform random mutations across real-valued chromosomes. This operator i
    :show-inheritance:
 
 **Insertion-Based Mutation**
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A mutation strategy tailored for permutation-based representations, such as in sequencing and scheduling problems. This operator repositions a randomly selected gene within the chromosome, altering the order while preserving elements.
 
@@ -57,7 +99,7 @@ A mutation strategy tailored for permutation-based representations, such as in s
 
 
 **Shuffle Mutation**
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Randomly rearranges a subset of genes in the chromosome. This operator is effective in permutation-based problems, promoting diversity by shuffling segments without altering individual gene values.
 
@@ -67,7 +109,7 @@ Randomly rearranges a subset of genes in the chromosome. This operator is effect
    :show-inheritance:
 
 **Swap Mutation**
--------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Swaps the positions of two genes, introducing subtle changes ideal for permutation-based optimizations. This operator is commonly applied in combinatorial problems where order is significant.
 
@@ -77,12 +119,11 @@ Swaps the positions of two genes, introducing subtle changes ideal for permutati
    :show-inheritance:
 
 **Two-Opt Mutation**
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 A mutation operator frequently used in path optimization problems, such as the Traveling Salesman Problem. It reverses a segment of the chromosome, allowing for new path configurations without altering the gene order.
 
 .. automodule:: pycellga.mutation.two_opt_mutation
    :members:
    :undoc-members:
-   :show-inheritance:
-
+   :show-inheritance: