diff --git a/README.md b/README.md index 7cb466d..1145c41 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,24 @@ Inspired by traditional genetic algorithms and cellular automata principles with For more information, please visit the project repository. ## Citation -Please cite our work using the citation info -Karakaya, Sevgi Akten, and Mehmet Hakan Satman. "An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems." Journal of Engineering Research and Applied Science 13.1 (2024): 2500-2514. \ No newline at end of file +If you use `pycellga` in your research, please cite it as follows: + +**APA Format** + +Karakaya, S. A., & Satman, M. H. (2024). An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems. *Journal of Engineering Research and Applied Science, 13*(1), 2500-2514. + +**BibTeX Format** + +For LaTeX users, please use the following BibTeX entry to cite `pycellga`: + +```bibtex +@article{karakaya2024improved, + title={An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems}, + author={Karakaya, Sevgi Akten and Satman, Mehmet Hakan}, + journal={Journal of Engineering Research and Applied Science}, + volume={13}, + number={1}, + pages={2500--2514}, + year={2024} +} diff --git a/docs/citing.rst b/docs/citing.rst new file mode 100644 index 0000000..9f83b0e --- /dev/null +++ b/docs/citing.rst @@ -0,0 +1,45 @@ +Citing +====== + +If you use `pycellga` in your research, please cite it as follows: + +**APA Format** + +Karakaya, S. A., & Satman, M. H. (2024). An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems. *Journal of Engineering Research and Applied Science, 13*(1), 2500-2514. + +**BibTeX Format** + +For LaTeX users, please use the following BibTeX entry to cite `pycellga`: + +.. code-block:: bibtex + + @article{karakaya2024improved, + title={An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems}, + author={Karakaya, Sevgi Akten and Satman, Mehmet Hakan}, + journal={Journal of Engineering Research and Applied Science}, + volume={13}, + number={1}, + pages={2500--2514}, + year={2024} + } + +**Citation Examples in Various Formats** + +1. **MLA Format** + + Karakaya, Sevgi Akten, and Mehmet Hakan Satman. "An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems." *Journal of Engineering Research and Applied Science* 13.1 (2024): 2500-2514. + +2. **Chicago Style** + + Karakaya, Sevgi Akten, and Mehmet Hakan Satman. "An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems." *Journal of Engineering Research and Applied Science* 13, no. 1 (2024): 2500-2514. + +3. **Harvard Format** + + Karakaya, S.A. and Satman, M.H., 2024. An Improved Cellular Genetic Algorithm with Machine-Coded Operators for Real-Valued Optimisation Problems. *Journal of Engineering Research and Applied Science*, 13(1), pp.2500-2514. + + +**Why Cite `pycellga`?** + +Citing `pycellga` in your research helps other researchers identify and reference the software, supports continued development, and acknowledges the work that went into creating the package. Your citations also contribute to the visibility and impact of the `pycellga` project in the scientific community. + +--- \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index ef4ff10..47355e2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,11 +19,12 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.napoleon"] +extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.autosectionlabel"] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +add_module_names = False # -- Options for HTML output ------------------------------------------------- @@ -32,6 +33,13 @@ html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] +html_theme_options = { + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'titles_only': False +} + autodoc_default_options = { 'members': True, 'undoc-members': True, diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..8a27dbe --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,116 @@ +Contributing +============ + +We’re thrilled that you’re considering contributing to `pycellga`! Community contributions drive innovation and help us improve the software. Whether it’s reporting bugs, suggesting enhancements, or submitting pull requests, your support is invaluable. + + +Ways to Contribute +------------------ + +Here are some ways you can make meaningful contributions to `pycellga`: + +- **Report Bugs**: If you encounter an issue, create a detailed bug report in our `issue tracker `_. +- **Suggest Features**: Have ideas for new features or enhancements? Submit a feature request to help guide our roadmap. +- **Fix Bugs or Implement Features**: Browse open issues, pick one, and submit a pull request with your solution. +- **Improve Documentation**: Documentation is key to helping users understand the software. Fix typos, clarify steps, or add examples to make it even better. + +Development Setup +----------------- + +To begin contributing code, set up your development environment as follows: + +**Step 1: Fork the Repository** + +Create your own copy of `pycellga` by forking the repository: + +1. Visit the `repository `_. +2. Click the "Fork" button in the upper-right corner. +3. Select your GitHub account to create the fork. + +For a step-by-step guide on forking, visit GitHub’s `Fork a Repo `_ page. + +**Step 2: Clone Your Fork** + +Clone your forked repository to your local machine: + +.. code-block:: bash + + git clone https://github.com/username/pycellga.git + cd pycellga + +**Step 3: Install Dependencies** + +Install the required dependencies: + +.. code-block:: bash + + pip install -r requirements.txt + +**Step 4: Create a New Branch** + +Create a branch for your changes: + +.. code-block:: bash + + git checkout -b feature-or-bugfix-name + +Use descriptive names for branches, such as `add-new-feature` or `fix-bug`. + +Pull Request Guidelines +----------------------- + +When you’re ready to submit your changes, follow these guidelines to ensure a smooth review process: + +1. **Write Clear Commit Messages**: Each commit message should be clear and descriptive. +2. **Run Tests**: Verify that all tests pass. Tests can be run from the `tests` folder or main directory: + + - From the `tests` folder: + + .. code-block:: bash + + cd tests + pytest * # or + pytest -v + + - From the main project directory: + + .. code-block:: bash + + pytest -v + +3. **Submit a Pull Request**: Push your branch to GitHub, navigate to the main repository, and open a pull request. + +4. **Respond to Reviews**: Be responsive to feedback during the review process, and make any requested changes to ensure your contribution is merged smoothly. + +Coding Standards +---------------- + +To maintain a consistent and readable codebase, please adhere to the following guidelines: + +- **PEP 8**: Follow PEP 8 coding style standards for Python code. +- **Type Annotations**: Include type hints for function arguments and return values. +- **Docstrings**: Provide clear docstrings for functions and classes. We recommend using the Google docstring style. + +Running Tests +------------- + +Before submitting a pull request, ensure that all tests pass. Tests can be run in the `tests` folder or from the main directory as follows: + +1. **From the `tests` folder**: + + .. code-block:: bash + + cd tests + pytest * # or + pytest -v + +2. **From the main project directory**: + + .. code-block:: bash + + pytest -v + +If you add new functionality, consider adding tests to cover your changes. + + +Thank you for considering a contribution to `pycellga`. We’re excited to see what you’ll bring to the project! diff --git a/docs/index.rst b/docs/index.rst index 878b373..353d557 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PYCELLGA Documentation +PYCELLGA Documentation ==================================== `pycellga`: A Python Package for Improved Cellular Genetic Algorithms @@ -14,11 +14,14 @@ utilizing a spatially structured population organized in a grid-like topology. This structure allows each individual to interact only with its neighboring individuals, promoting diversity and maintaining a balance between exploration and exploitation during the optimization process. `pycellga` has machine coded operators with byte implementations. Beside it has Alpha-male CGA, -Machine Coded Compact CGA and Improved CGA with Machine Coded Operaors for real-valued optimization problems. +Machine Coded Compact CGA and Improved CGA with Machine Coded Operators for real-valued optimization problems. .. toctree:: - :maxdepth: 2 - :caption: Contents: - - modules + :maxdepth: 1 + :caption: Table of Contents: + installation + pycellga + usage_examples + contributing + citing diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..d3107d9 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,101 @@ +Installation +============ + +This section provides detailed instructions for installing `pycellga` and its dependencies. + +Requirements +------------ + +Before installing `pycellga`, make sure you have the following installed: + +- Python 3.7 or higher +- `pip` package manager + +Installing from PyPI +--------------------- + +The easiest way to install `pycellga` is via PyPI. You can use `pip` to install it directly from the Python Package Index: + +.. code-block:: bash + + pip install pycellga + +Installing from Source +---------------------- + +To install `pycellga` from source, follow these steps: + +1. Clone the repository from GitHub: + + .. code-block:: bash + + git clone https://github.com/SevgiAkten/pycellga.git + +2. Navigate to the cloned repository directory: + + .. code-block:: bash + + cd pycellga + +3. Install the package using `pip`: + + .. code-block:: bash + + pip install . + +Optional Dependencies +--------------------- + +`pycellga` has optional dependencies for certain features. To use these features, you may need to install additional packages: + +- **Jupyter Notebooks**: If you plan to use Jupyter Notebooks for tutorials or examples, install `jupyter`: + + .. code-block:: bash + + pip install jupyter + +- **Matplotlib**: For visualizing optimization results, install `matplotlib`: + + .. code-block:: bash + + pip install matplotlib + +Verifying the Installation +-------------------------- + +To verify that `pycellga` is installed correctly, you can import it in Python: + +.. code-block:: python + + import pycellga + print(pycellga.__version__) + +If no errors occur, the installation is successful. + +Troubleshooting +--------------- + +If you encounter any issues during installation, try the following steps: + +1. Ensure you are using Python 3.7 or higher by running: + + .. code-block:: bash + + python --version + +2. Make sure `pip` is up-to-date: + + .. code-block:: bash + + pip install --upgrade pip + +3. If issues persist, refer to the GitHub repository for troubleshooting tips or to submit an issue. + +Uninstallation +-------------- + +To uninstall `pycellga`, you can use the following command: + +.. code-block:: bash + + pip uninstall pycellga diff --git a/docs/modules.rst b/docs/modules.rst deleted file mode 100644 index 452e130..0000000 --- a/docs/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -pycellga -======== - -.. toctree:: - :maxdepth: 4 - - pycellga diff --git a/docs/pycellga.example.rst b/docs/pycellga.example.rst index fb2219f..c35cf41 100644 --- a/docs/pycellga.example.rst +++ b/docs/pycellga.example.rst @@ -1,51 +1,64 @@ -pycellga.example package -======================== +Example Implementations in pycellga +=================================== -Submodules ----------- +The `pycellga.example` package includes example implementations of various cellular genetic algorithms (CGAs) and their variants. These examples demonstrate how to set up and run different CGA methods using the `pycellga` framework, providing users with practical insights into the application of these algorithms. -pycellga.example.example\_alpha\_cga module -------------------------------------------- +Available Example Modules +------------------------- + +### Example: Alpha-CGA +**Module**: `pycellga.example.example_alpha_cga` + +Demonstrates the Alpha Cellular Genetic Algorithm (Alpha-CGA), an enhanced version of CGA that incorporates an "alpha male" mechanism for improved convergence and exploration. .. automodule:: pycellga.example.example_alpha_cga :members: :undoc-members: :show-inheritance: -pycellga.example.example\_ccga module -------------------------------------- +### Example: Compact-CGA (CCGA) +**Module**: `pycellga.example.example_ccga` + +Provides an example of the Compact Cellular Genetic Algorithm (CCGA), which utilizes a compact population structure to minimize memory usage and improve computational efficiency. .. automodule:: pycellga.example.example_ccga :members: :undoc-members: :show-inheritance: -pycellga.example.example\_cga module ------------------------------------- +### Example: Standard CGA +**Module**: `pycellga.example.example_cga` + +Illustrates the implementation of a standard Cellular Genetic Algorithm (CGA), highlighting the core principles of CGA with basic settings. .. automodule:: pycellga.example.example_cga :members: :undoc-members: :show-inheritance: -pycellga.example.example\_mcccga module ---------------------------------------- +### Example: Machine-Coded Compact CGA (MCC-CGA) +**Module**: `pycellga.example.example_mcccga` + +Demonstrates the Machine-Coded Compact Cellular Genetic Algorithm (MCC-CGA), which uses byte-level encoding for efficient real-valued optimization in a compact population setting. .. automodule:: pycellga.example.example_mcccga :members: :undoc-members: :show-inheritance: -pycellga.example.example\_sync\_cga module ------------------------------------------- +### Example: Synchronous CGA (Sync-CGA) +**Module**: `pycellga.example.example_sync_cga` + +Illustrates the Synchronous Cellular Genetic Algorithm (Sync-CGA), where all individuals in the population are updated simultaneously, providing an alternative synchronization mechanism in CGA. .. automodule:: pycellga.example.example_sync_cga :members: :undoc-members: :show-inheritance: -Module contents ---------------- +## Full Module Overview + +For a comprehensive overview of the example implementations available in the `example` package, refer to the module documentation below: .. automodule:: pycellga.example :members: diff --git a/docs/pycellga.mutation.rst b/docs/pycellga.mutation.rst index 123848b..29e367d 100644 --- a/docs/pycellga.mutation.rst +++ b/docs/pycellga.mutation.rst @@ -1,85 +1,88 @@ -pycellga.mutation package -========================= +Mutation Operators +============================== -Submodules ----------- +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. -pycellga.mutation.bit\_flip\_mutation module --------------------------------------------- +This module includes the following mutation operators: + +**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. .. automodule:: pycellga.mutation.bit_flip_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.byte\_mutation module ---------------------------------------- +**Byte-Level 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. .. automodule:: pycellga.mutation.byte_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.byte\_mutation\_random module ------------------------------------------------ +**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. .. automodule:: pycellga.mutation.byte_mutation_random :members: :undoc-members: :show-inheritance: -pycellga.mutation.float\_uniform\_mutation module -------------------------------------------------- +**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. .. automodule:: pycellga.mutation.float_uniform_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.insertion\_mutation module --------------------------------------------- +**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. .. automodule:: pycellga.mutation.insertion_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.mutation\_operator module -------------------------------------------- -.. automodule:: pycellga.mutation.mutation_operator - :members: - :undoc-members: - :show-inheritance: +**Shuffle Mutation** +-------------- -pycellga.mutation.shuffle\_mutation module ------------------------------------------- +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. .. automodule:: pycellga.mutation.shuffle_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.swap\_mutation module ---------------------------------------- +**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. .. automodule:: pycellga.mutation.swap_mutation :members: :undoc-members: :show-inheritance: -pycellga.mutation.two\_opt\_mutation module -------------------------------------------- +**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: -Module contents ---------------- - -.. automodule:: pycellga.mutation - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/pycellga.neighborhoods.rst b/docs/pycellga.neighborhoods.rst index 4df161d..a6c23e7 100644 --- a/docs/pycellga.neighborhoods.rst +++ b/docs/pycellga.neighborhoods.rst @@ -1,61 +1,66 @@ -pycellga.neighborhoods package -============================== +Neighborhood Operators +================================== -Submodules ----------- +The `pycellga.neighborhoods` module provides various neighborhood structures that define how individuals interact with their neighbors in the cellular genetic algorithm (CGA). These neighborhood operators are essential for managing the flow of information and maintaining diversity within the population. +Each neighborhood module defines a specific spatial structure. Depending on the problem and the desired interaction level, users can select different neighborhood sizes and arrangements. -pycellga.neighborhoods.compact\_13 module ------------------------------------------ -.. automodule:: pycellga.neighborhoods.compact_13 - :members: - :undoc-members: - :show-inheritance: +**Linear 5** +-------------- -pycellga.neighborhoods.compact\_21 module ------------------------------------------ +Defines a linear neighborhood where each individual interacts with 5 neighbors arranged in a line. This structure is suitable for problems where limited, sequential interaction is beneficial. -.. automodule:: pycellga.neighborhoods.compact_21 +.. automodule:: pycellga.neighborhoods.linear_5 :members: :undoc-members: :show-inheritance: -pycellga.neighborhoods.compact\_25 module ------------------------------------------ +**Linear 9** +-------------- -.. automodule:: pycellga.neighborhoods.compact_25 +A linear arrangement with 9 neighbors, encouraging a higher level of information flow along a line. This structure is ideal for applications that require extended sequential interactions. + +.. automodule:: pycellga.neighborhoods.linear_9 :members: :undoc-members: :show-inheritance: -pycellga.neighborhoods.compact\_9 module ----------------------------------------- +**Compact 9** +-------------- + +A compact neighborhood structure with 9 neighbors. This layout offers dense interaction among individuals, facilitating rapid convergence while maintaining diversity. .. automodule:: pycellga.neighborhoods.compact_9 :members: :undoc-members: :show-inheritance: -pycellga.neighborhoods.linear\_5 module ---------------------------------------- +**Compact 13** +-------------- -.. automodule:: pycellga.neighborhoods.linear_5 +Defines a compact neighborhood structure where each individual interacts with its immediate and extended neighbors in a 13 grid. This structure allows moderate information sharing across neighboring cells. + +.. automodule:: pycellga.neighborhoods.compact_13 :members: :undoc-members: :show-inheritance: -pycellga.neighborhoods.linear\_9 module ---------------------------------------- +**Compact 21** +-------------- -.. automodule:: pycellga.neighborhoods.linear_9 +Provides a compact arrangement where individuals have a 21 neighborhood structure. This layout encourages local exploration and is useful in tightly clustered populations. + +.. automodule:: pycellga.neighborhoods.compact_21 :members: :undoc-members: :show-inheritance: -Module contents ---------------- +**Compact 25** +-------------- + +An extended compact neighborhood that includes more neighbors, with a 25 structure. This layout promotes broader information sharing, enhancing convergence in larger populations. -.. automodule:: pycellga.neighborhoods +.. automodule:: pycellga.neighborhoods.compact_25 :members: :undoc-members: - :show-inheritance: + :show-inheritance: \ No newline at end of file diff --git a/docs/pycellga.problems.rst b/docs/pycellga.problems.rst index a59cb89..cb939a6 100644 --- a/docs/pycellga.problems.rst +++ b/docs/pycellga.problems.rst @@ -1,29 +1,24 @@ -pycellga.problems package -========================= +Problem Definitions +=============================== -Subpackages ------------ +The `pycellga.problems` package provides a collection of problem definitions for optimization tasks. Each problem is structured as a class inheriting from a common abstract base, ensuring consistency and flexibility across various types of optimization tasks. This module includes both single-objective and multi-objective problems, designed to serve as benchmarks or examples for testing and applying genetic algorithms. -.. toctree:: - :maxdepth: 4 - - pycellga.problems.single_objective -Submodules ----------- +**Abstract Problem Base** +-------------- -pycellga.problems.abstract\_problem module ------------------------------------------- +This module defines an abstract base class, `AbstractProblem`, which provides a standard interface for defining optimization problems. By inheriting from this base class, users can create custom problem definitions that are compatible with the rest of the `pycellga` framework. Key components of the base class include methods for evaluating objective values, setting constraints, and managing design variables. .. automodule:: pycellga.problems.abstract_problem :members: :undoc-members: :show-inheritance: -Module contents ---------------- +**Single-Objective Problems** +-------------- +The `single_objective` subpackage includes a set of benchmark functions commonly used to evaluate optimization algorithms in terms of convergence speed, accuracy, and robustness. These problems are designed for scenarios where only one objective needs to be optimized. -.. automodule:: pycellga.problems - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + :maxdepth: 2 + + pycellga.problems.single_objective diff --git a/docs/pycellga.problems.single_objective.continuous.rst b/docs/pycellga.problems.single_objective.continuous.rst index 7c9be72..5ca4ffe 100644 --- a/docs/pycellga.problems.single_objective.continuous.rst +++ b/docs/pycellga.problems.single_objective.continuous.rst @@ -1,205 +1,225 @@ -pycellga.problems.single\_objective.continuous package -====================================================== +Continuous Optimization Problems +============================================ -Submodules ----------- +The `pycellga.problems.single_objective.continuous` package offers a range of continuous, single-objective benchmark functions. These functions are commonly used to evaluate the performance of optimization algorithms in terms of convergence accuracy, robustness, and computation speed. Below is a list of available benchmark functions in this package, each addressing unique aspects of optimization. -pycellga.problems.single\_objective.continuous.ackley module ------------------------------------------------------------- + +**Ackley Function** +-------------- +A multimodal function known for its large number of local minima. Used to evaluate an algorithm's ability to escape local optima. .. automodule:: pycellga.problems.single_objective.continuous.ackley :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.bentcigar module ---------------------------------------------------------------- +**Bent Cigar Function** +-------------- +A unimodal function that is rotationally invariant, used to test convergence speed and robustness. .. automodule:: pycellga.problems.single_objective.continuous.bentcigar :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.bohachevsky module ------------------------------------------------------------------ +**Bohachevsky Function** +-------------- +Characterized by its simple structure with some local minima, making it ideal for testing fine-tuning capabilities. .. automodule:: pycellga.problems.single_objective.continuous.bohachevsky :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.chichinadze module ------------------------------------------------------------------ +**Chichinadze Function** +-------------- +A complex landscape with both smooth and steep regions, suitable for testing algorithms on challenging landscapes. .. automodule:: pycellga.problems.single_objective.continuous.chichinadze :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.dropwave module --------------------------------------------------------------- +**Drop Wave Function** +-------------- +A multimodal function often used to evaluate the balance between exploration and exploitation. .. automodule:: pycellga.problems.single_objective.continuous.dropwave :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.fms module ---------------------------------------------------------- +**Frequency Modulation Sound Function (FMS)** +-------------- +A complex, multimodal function commonly used to test the robustness of optimization algorithms. .. automodule:: pycellga.problems.single_objective.continuous.fms :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.griewank module --------------------------------------------------------------- +**Griewank Function** +-------------- +A continuous, nonlinear function with numerous local minima, commonly used to test an algorithm's global search capability. .. automodule:: pycellga.problems.single_objective.continuous.griewank :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.holzman module -------------------------------------------------------------- +**Holzman Function** +-------------- +An experimental function that provides various levels of difficulty for different optimization approaches. .. automodule:: pycellga.problems.single_objective.continuous.holzman :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.levy module ----------------------------------------------------------- +**Levy Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.levy :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.matyas module ------------------------------------------------------------- +**Matyas Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.matyas :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.pow module ---------------------------------------------------------- +**Pow Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.pow :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.powell module ------------------------------------------------------------- + +**Powell Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.powell :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.rastrigin module ---------------------------------------------------------------- +**Rastrigin Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.rastrigin :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.rosenbrock module ----------------------------------------------------------------- + +**Rosenbrock Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.rosenbrock :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.rothellipsoid module -------------------------------------------------------------------- +**Rothellipsoid Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.rothellipsoid :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.schaffer module --------------------------------------------------------------- + +**Schaffer Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.schaffer :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.schaffer2 module ---------------------------------------------------------------- +**Schaffer2 Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.schaffer2 :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.schwefel module --------------------------------------------------------------- +**Schwefel Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.schwefel :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.sphere module ------------------------------------------------------------- +**Sphere Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.sphere :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.styblinskitang module --------------------------------------------------------------------- +**Styblinskitang Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.styblinskitang :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.sumofdifferentpowers module --------------------------------------------------------------------------- +**Sumofdifferentpowers Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.sumofdifferentpowers :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.threehumps module ----------------------------------------------------------------- +**Threehumps Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.threehumps :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.zakharov module --------------------------------------------------------------- +**Zakharov Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.zakharov :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.continuous.zettle module ------------------------------------------------------------- +**Zettle Function** +-------------- +This function is used to test the efficiency of algorithms on smooth, differentiable landscapes. .. automodule:: pycellga.problems.single_objective.continuous.zettle :members: :undoc-members: :show-inheritance: -Module contents ---------------- - -.. automodule:: pycellga.problems.single_objective.continuous - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/pycellga.problems.single_objective.discrete.binary.rst b/docs/pycellga.problems.single_objective.discrete.binary.rst index ea2e50d..9e71cb8 100644 --- a/docs/pycellga.problems.single_objective.discrete.binary.rst +++ b/docs/pycellga.problems.single_objective.discrete.binary.rst @@ -1,85 +1,95 @@ -pycellga.problems.single\_objective.discrete.binary package -=========================================================== +Binary Optimization Problems +======================================== -Submodules ----------- +The `pycellga.problems.single_objective.discrete.binary` package provides a set of binary, single-objective benchmark functions. These discrete problems are commonly used to assess the performance of optimization algorithms on binary-encoded solutions. Each function presents unique challenges, such as local optima, multimodality, and rugged landscapes. -pycellga.problems.single\_objective.discrete.binary.count\_sat module ---------------------------------------------------------------------- + +**Count SAT** +-------------- + +A binary satisfaction problem, often used to evaluate an algorithm’s ability to solve constraint satisfaction problems in a discrete search space. .. automodule:: pycellga.problems.single_objective.discrete.binary.count_sat :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.ecc module --------------------------------------------------------------- +**ECC Problem** +-------------- + +The ECC problem tests the efficiency of algorithms in solving problems related to error-correcting codes, which have discrete solution spaces and are commonly encountered in communication systems. .. automodule:: pycellga.problems.single_objective.discrete.binary.ecc :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.fms module --------------------------------------------------------------- +**Fletcher-Powell (FMS) Binary Problem** +-------------- + +A binary version of the Fletcher-Powell function, used to evaluate robustness and efficiency in finding optimal solutions within a binary space. .. automodule:: pycellga.problems.single_objective.discrete.binary.fms :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.maxcut100 module --------------------------------------------------------------------- +**Max-Cut (100 nodes)** +-------------- + +A max-cut problem involving 100 nodes, often used in graph partitioning. This problem challenges algorithms in finding optimal binary partitions. .. automodule:: pycellga.problems.single_objective.discrete.binary.maxcut100 :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.maxcut20\_01 module ------------------------------------------------------------------------ +**Max-Cut (20 nodes, Density 0.1)** +-------------- + +A max-cut problem with 20 nodes and a sparsity factor of 0.1. Suitable for testing performance on sparse graphs with limited connections. .. automodule:: pycellga.problems.single_objective.discrete.binary.maxcut20_01 :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.maxcut20\_09 module ------------------------------------------------------------------------ +**Max-Cut (20 nodes, Density 0.9)** +-------------- + +A denser version of the max-cut problem with a density of 0.9, requiring algorithms to manage numerous connections and find optimal partitions. .. automodule:: pycellga.problems.single_objective.discrete.binary.maxcut20_09 :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.mmdp module ---------------------------------------------------------------- +**Multi-modal Deceptive Problem (MMDP)** +-------------- + +A challenging binary problem with deceptive local optima, commonly used to assess an algorithm's ability to escape local traps in a binary landscape. .. automodule:: pycellga.problems.single_objective.discrete.binary.mmdp :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.one\_max module -------------------------------------------------------------------- +**One-Max Problem** +-------------- + +A classic benchmark in binary optimization, where the objective is to maximize the number of ones in a binary string. This problem tests the algorithm's ability to drive binary values towards an optimum. .. automodule:: pycellga.problems.single_objective.discrete.binary.one_max :members: :undoc-members: :show-inheritance: -pycellga.problems.single\_objective.discrete.binary.peak module ---------------------------------------------------------------- +**Peak Problem** +-------------- -.. automodule:: pycellga.problems.single_objective.discrete.binary.peak - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- +A binary optimization problem featuring multiple peaks. This problem is suitable for evaluating an algorithm’s performance in a rugged binary landscape with multiple local optima. -.. automodule:: pycellga.problems.single_objective.discrete.binary +.. automodule:: pycellga.problems.single_objective.discrete.binary.peak :members: :undoc-members: :show-inheritance: diff --git a/docs/pycellga.problems.single_objective.discrete.permutation.rst b/docs/pycellga.problems.single_objective.discrete.permutation.rst index 6f63f68..97d3d7a 100644 --- a/docs/pycellga.problems.single_objective.discrete.permutation.rst +++ b/docs/pycellga.problems.single_objective.discrete.permutation.rst @@ -1,21 +1,16 @@ -pycellga.problems.single\_objective.discrete.permutation package -================================================================ +Permutation-Based Optimization Problems +=================================================== -Submodules ----------- +The `pycellga.problems.single_objective.discrete.permutation` package provides a set of benchmark problems that involve permutation-based solutions. These problems are particularly useful in evaluating optimization algorithms designed for sequencing and ordering tasks, where the solution is represented as a permutation. -pycellga.problems.single\_objective.discrete.permutation.tsp module -------------------------------------------------------------------- -.. automodule:: pycellga.problems.single_objective.discrete.permutation.tsp - :members: - :undoc-members: - :show-inheritance: +**Traveling Salesman Problem (TSP)** +-------------- -Module contents ---------------- +The Traveling Salesman Problem (TSP) is a classic optimization problem where the goal is to find the shortest possible route that visits each city exactly once and returns to the origin city. TSP is widely used to evaluate the efficiency of algorithms that handle combinatorial and sequencing problems. This module provides a standard implementation of TSP for testing purposes. -.. automodule:: pycellga.problems.single_objective.discrete.permutation +.. automodule:: pycellga.problems.single_objective.discrete.permutation.tsp :members: :undoc-members: :show-inheritance: + diff --git a/docs/pycellga.problems.single_objective.discrete.rst b/docs/pycellga.problems.single_objective.discrete.rst index 620fe43..6f199e2 100644 --- a/docs/pycellga.problems.single_objective.discrete.rst +++ b/docs/pycellga.problems.single_objective.discrete.rst @@ -1,19 +1,23 @@ -pycellga.problems.single\_objective.discrete package -==================================================== +Discrete Optimization Problems +========================================== -Subpackages ------------ +The `pycellga.problems.single_objective.discrete` package contains discrete, single-objective optimization problems. These problems are specifically designed to evaluate optimization algorithms on discrete search spaces, where solutions are typically represented in binary or permutation forms. This package includes both binary-based and permutation-based subpackages, each tailored for different types of optimization tasks. + + +**Binary-Based Problems** +-------------- +The `binary` subpackage contains a set of benchmark problems where solutions are represented as binary strings. These problems are widely used to test algorithms’ performance on discrete, combinatorial spaces with binary encoding. .. toctree:: - :maxdepth: 4 + :maxdepth: 2 pycellga.problems.single_objective.discrete.binary - pycellga.problems.single_objective.discrete.permutation -Module contents ---------------- +**Permutation-Based Problems** +-------------- +The `permutation` subpackage focuses on problems where the solution is a permutation of elements, such as sequencing or ordering tasks. This subpackage is particularly useful for evaluating algorithms that work on combinatorial optimization problems, such as the Traveling Salesman Problem (TSP). -.. automodule:: pycellga.problems.single_objective.discrete - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + :maxdepth: 2 + + pycellga.problems.single_objective.discrete.permutation diff --git a/docs/pycellga.problems.single_objective.rst b/docs/pycellga.problems.single_objective.rst index 4561c68..d42898a 100644 --- a/docs/pycellga.problems.single_objective.rst +++ b/docs/pycellga.problems.single_objective.rst @@ -1,19 +1,22 @@ -pycellga.problems.single\_objective package -=========================================== +Single-Objective Optimization Problems +================================================== -Subpackages ------------ +The `pycellga.problems.single_objective` package includes a diverse collection of single-objective optimization problems. These problems are commonly used to benchmark and evaluate the performance of optimization algorithms. The package is organized into two main subpackages, each addressing different types of problem structures: continuous and discrete. + +**Continuous Optimization Problems** +-------------- +The `continuous` subpackage provides a set of continuous benchmark functions designed to evaluate algorithms on continuous search spaces. These functions are ideal for testing an algorithm’s performance in terms of accuracy, convergence speed, and robustness on smooth, differentiable landscapes. .. toctree:: - :maxdepth: 4 + :maxdepth: 2 pycellga.problems.single_objective.continuous - pycellga.problems.single_objective.discrete -Module contents ---------------- +**Discrete Optimization Problems** +-------------- +The `discrete` subpackage includes binary and permutation-based problems where solutions are represented as discrete values or permutations. This subpackage is particularly useful for assessing algorithms that handle combinatorial and discrete optimization challenges. -.. automodule:: pycellga.problems.single_objective - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + :maxdepth: 2 + + pycellga.problems.single_objective.discrete diff --git a/docs/pycellga.recombination.rst b/docs/pycellga.recombination.rst index 19e4c58..478e05a 100644 --- a/docs/pycellga.recombination.rst +++ b/docs/pycellga.recombination.rst @@ -1,109 +1,116 @@ -pycellga.recombination package -============================== +Recombination Operators +=================================== -Submodules ----------- +The `pycellga.recombination` package includes various recombination (crossover) operators used to combine genetic information from parent chromosomes to create offspring in genetic algorithms. Each crossover operator serves a unique purpose and is suitable for different types of genetic representations, including binary, real-valued, and permutation-based chromosomes. -pycellga.recombination.arithmetic\_crossover module ---------------------------------------------------- + + +**Arithmetic Crossover** +-------------- + +Performs arithmetic operations on parent genes to produce offspring. Often used in real-valued genetic algorithms to create intermediate values between parent genes. .. automodule:: pycellga.recombination.arithmetic_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.blxalpha\_crossover module -------------------------------------------------- +**BLX-Alpha Crossover** +-------------- + +Generates offspring by creating genes within a specified range around parent genes, controlled by the `alpha` parameter. Effective in real-valued optimization for maintaining diversity. .. automodule:: pycellga.recombination.blxalpha_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.byte\_one\_point\_crossover module ---------------------------------------------------------- +**Byte One-Point Crossover** +-------------- + +A one-point crossover operator specifically designed for byte-based chromosomes, suitable for machine-coded genetic algorithms. .. automodule:: pycellga.recombination.byte_one_point_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.byte\_uniform\_crossover module ------------------------------------------------------- +**Byte Uniform Crossover** +-------------- + +Applies uniform crossover at the byte level, allowing fine control over gene mixing in machine-coded chromosomes. .. automodule:: pycellga.recombination.byte_uniform_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.flat\_crossover module ---------------------------------------------- +**Flat Crossover** +-------------- + +Creates offspring by generating random values within a range defined by the parent genes. Suitable for real-valued chromosomes. .. automodule:: pycellga.recombination.flat_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.linear\_crossover module ------------------------------------------------ +**Linear Crossover** +-------------- + +Generates offspring by linearly combining genes of the parents. This operator is useful in real-valued optimization for exploring intermediate values. .. automodule:: pycellga.recombination.linear_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.one\_point\_crossover module ---------------------------------------------------- +**One-Point Crossover** +-------------- + +A classic crossover technique where a single crossover point is chosen to swap segments between parents. Commonly used in binary-encoded genetic algorithms. .. automodule:: pycellga.recombination.one_point_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.pmx\_crossover module --------------------------------------------- +**Partially Matched Crossover (PMX)** +-------------- + +A crossover method designed for permutation-based chromosomes, such as sequencing problems. Maintains gene order by partially matching segments between parents. .. automodule:: pycellga.recombination.pmx_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.recombination\_operator module ------------------------------------------------------ - -.. automodule:: pycellga.recombination.recombination_operator - :members: - :undoc-members: - :show-inheritance: +**Two-Point Crossover** +-------------- -pycellga.recombination.two\_point\_crossover module ---------------------------------------------------- +A crossover method with two crossover points, allowing for a higher level of gene exchange between parents. Widely used in binary-encoded algorithms. .. automodule:: pycellga.recombination.two_point_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.unfair\_avarage\_crossover module --------------------------------------------------------- +**Unfair Average Crossover** +-------------- + +Calculates the average of parent genes with a slight bias, leading to offspring that retain more traits of one parent. Used in real-valued genetic algorithms. .. automodule:: pycellga.recombination.unfair_avarage_crossover :members: :undoc-members: :show-inheritance: -pycellga.recombination.uniform\_crossover module ------------------------------------------------- +**Uniform Crossover** +-------------- -.. automodule:: pycellga.recombination.uniform_crossover - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- +Swaps genes randomly between parents, creating diverse offspring. Suitable for both binary and real-valued genetic representations. -.. automodule:: pycellga.recombination +.. automodule:: pycellga.recombination.uniform_crossover :members: :undoc-members: - :show-inheritance: + :show-inheritance: \ No newline at end of file diff --git a/docs/pycellga.rst b/docs/pycellga.rst index 2630155..4f0acac 100644 --- a/docs/pycellga.rst +++ b/docs/pycellga.rst @@ -1,66 +1,76 @@ -pycellga package -================ +pycellga: A Comprehensive Guide +=============================== -Subpackages ------------ +The `pycellga` package is a Python library for implementing and testing cellular genetic algorithms (CGAs). This guide provides an in-depth look at each module, offering descriptions and use cases to help users understand and utilize the library effectively. .. toctree:: - :maxdepth: 4 + :maxdepth: 1 - pycellga.example - pycellga.mutation pycellga.neighborhoods - pycellga.problems + pycellga.mutation pycellga.recombination pycellga.selection + pycellga.problems + pycellga.example -Submodules ----------- -pycellga.byte\_operators module -------------------------------- +**Core Modules** +-------------- -.. automodule:: pycellga.byte_operators - :members: - :undoc-members: - :show-inheritance: +Population Management +-------------- -pycellga.grid module --------------------- +Handles the initialization and management of the population in CGA. It includes methods for population updates, replacement, and neighborhood interactions within the grid structure. -.. automodule:: pycellga.grid +.. automodule:: pycellga.population :members: :undoc-members: :show-inheritance: -pycellga.individual module --------------------------- + + +Individual Representation +-------------- + +Represents an individual in the population, encapsulating attributes like the chromosome and fitness value. This module provides the fundamental building blocks for individuals used within the CGA framework. .. automodule:: pycellga.individual :members: :undoc-members: :show-inheritance: -pycellga.optimizer module -------------------------- -.. automodule:: pycellga.optimizer + +Grid Structure +-------------- + +Defines the grid structure for the cellular genetic algorithm. The grid layout restricts interactions to neighboring individuals, which helps maintain population diversity and allows for more controlled exploration. + +.. automodule:: pycellga.grid :members: :undoc-members: :show-inheritance: -pycellga.population module --------------------------- -.. automodule:: pycellga.population + +Byte Operators +-------------- + +Implements low-level byte-based operations that support machine-coded genetic algorithms. These operators are used for efficient encoding and decoding of chromosome data, enhancing the speed and memory usage for real-valued optimizations. + +.. automodule:: pycellga.byte_operators :members: :undoc-members: :show-inheritance: -Module contents ---------------- -.. automodule:: pycellga + +Optimizer +-------------- + +The core optimization module that manages the genetic algorithm's execution. This includes processes like selection, mutation, recombination, and evaluation of individuals. The `optimizer` module serves as the main interface for running different CGA variants. + +.. automodule:: pycellga.optimizer :members: :undoc-members: - :show-inheritance: + :show-inheritance: \ No newline at end of file diff --git a/docs/pycellga.selection.rst b/docs/pycellga.selection.rst index adab0ab..48fce2a 100644 --- a/docs/pycellga.selection.rst +++ b/docs/pycellga.selection.rst @@ -1,37 +1,25 @@ -pycellga.selection package -========================== +Selection Operators +=============================== -Submodules ----------- +The `pycellga.selection` package provides various selection operators that determine how individuals are chosen from the population to act as parents in genetic algorithms. Selection operators play a key role in balancing exploration and exploitation during the optimization process, directly impacting convergence and diversity. -pycellga.selection.roulette\_wheel\_selection module ----------------------------------------------------- -.. automodule:: pycellga.selection.roulette_wheel_selection - :members: - :undoc-members: - :show-inheritance: +**Tournament Selection** +-------------- -pycellga.selection.selection\_operator module ---------------------------------------------- - -.. automodule:: pycellga.selection.selection_operator - :members: - :undoc-members: - :show-inheritance: - -pycellga.selection.tournament\_selection module ------------------------------------------------ +Implements a tournament selection method, where a subset of individuals competes, and the best-performing individual is selected as a parent. This method is useful in maintaining diversity and is effective in multimodal optimization landscapes. .. automodule:: pycellga.selection.tournament_selection :members: :undoc-members: :show-inheritance: -Module contents ---------------- +**Roulette Wheel Selection** +-------------- -.. automodule:: pycellga.selection +Implements a roulette wheel selection mechanism where each individual’s chance of being selected is proportional to its fitness. This method is widely used for its simplicity and is effective in problems where fitness proportionate selection is beneficial. + +.. automodule:: pycellga.selection.roulette_wheel_selection :members: :undoc-members: :show-inheritance: diff --git a/docs/pycellga.tests.rst b/docs/pycellga.tests.rst deleted file mode 100644 index 4f676b7..0000000 --- a/docs/pycellga.tests.rst +++ /dev/null @@ -1,573 +0,0 @@ -pycellga.tests package -====================== - -Submodules ----------- - -pycellga.tests.conftest module ------------------------------- - -.. automodule:: pycellga.tests.conftest - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_ackley module ----------------------------------- - -.. automodule:: pycellga.tests.test_ackley - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_arithmetic\_crossover module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_arithmetic_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_bentcigar\_function module ------------------------------------------------ - -.. automodule:: pycellga.tests.test_bentcigar_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_bit\_flip\_mutation module ------------------------------------------------ - -.. automodule:: pycellga.tests.test_bit_flip_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_blxalpha\_crossover module ------------------------------------------------ - -.. automodule:: pycellga.tests.test_blxalpha_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_bohachevsky module ---------------------------------------- - -.. automodule:: pycellga.tests.test_bohachevsky - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_byte\_mutation module ------------------------------------------- - -.. automodule:: pycellga.tests.test_byte_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_byte\_mutation\_random module --------------------------------------------------- - -.. automodule:: pycellga.tests.test_byte_mutation_random - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_byte\_one\_point\_crossover module -------------------------------------------------------- - -.. automodule:: pycellga.tests.test_byte_one_point_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_byte\_operators module -------------------------------------------- - -.. automodule:: pycellga.tests.test_byte_operators - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_byte\_uniform\_crossover module ----------------------------------------------------- - -.. automodule:: pycellga.tests.test_byte_uniform_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_chichinadze\_function module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_chichinadze_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_compact\_13 module ---------------------------------------- - -.. automodule:: pycellga.tests.test_compact_13 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_compact\_21 module ---------------------------------------- - -.. automodule:: pycellga.tests.test_compact_21 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_compact\_25 module ---------------------------------------- - -.. automodule:: pycellga.tests.test_compact_25 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_compact\_9 module --------------------------------------- - -.. automodule:: pycellga.tests.test_compact_9 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_count\_sat module --------------------------------------- - -.. automodule:: pycellga.tests.test_count_sat - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_dropwave\_function module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_dropwave_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_ecc module -------------------------------- - -.. automodule:: pycellga.tests.test_ecc - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_flat\_crossover module -------------------------------------------- - -.. automodule:: pycellga.tests.test_flat_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_float\_uniform\_mutation module ----------------------------------------------------- - -.. automodule:: pycellga.tests.test_float_uniform_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_fms module -------------------------------- - -.. automodule:: pycellga.tests.test_fms - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_grid module --------------------------------- - -.. automodule:: pycellga.tests.test_grid - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_griewank\_function module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_griewank_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_holzman\_function module ---------------------------------------------- - -.. automodule:: pycellga.tests.test_holzman_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_individual module --------------------------------------- - -.. automodule:: pycellga.tests.test_individual - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_insertion\_mutation module ------------------------------------------------ - -.. automodule:: pycellga.tests.test_insertion_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_levy\_function module ------------------------------------------- - -.. automodule:: pycellga.tests.test_levy_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_linear\_5 module -------------------------------------- - -.. automodule:: pycellga.tests.test_linear_5 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_linear\_9 module -------------------------------------- - -.. automodule:: pycellga.tests.test_linear_9 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_linear\_crossover module ---------------------------------------------- - -.. automodule:: pycellga.tests.test_linear_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_matyas\_function module --------------------------------------------- - -.. automodule:: pycellga.tests.test_matyas_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_maxcut100 module -------------------------------------- - -.. automodule:: pycellga.tests.test_maxcut100 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_maxcut20\_01 module ----------------------------------------- - -.. automodule:: pycellga.tests.test_maxcut20_01 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_maxcut20\_09 module ----------------------------------------- - -.. automodule:: pycellga.tests.test_maxcut20_09 - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_mmdp module --------------------------------- - -.. automodule:: pycellga.tests.test_mmdp - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_one\_max module ------------------------------------- - -.. automodule:: pycellga.tests.test_one_max - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_one\_point\_crossover module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_one_point_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_optimizer\_alpha\_cga module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_optimizer_alpha_cga - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_optimizer\_ccga module -------------------------------------------- - -.. automodule:: pycellga.tests.test_optimizer_ccga - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_optimizer\_cga module ------------------------------------------- - -.. automodule:: pycellga.tests.test_optimizer_cga - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_optimizer\_mccga module --------------------------------------------- - -.. automodule:: pycellga.tests.test_optimizer_mccga - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_optimizer\_sync\_cga module ------------------------------------------------- - -.. automodule:: pycellga.tests.test_optimizer_sync_cga - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_peak module --------------------------------- - -.. automodule:: pycellga.tests.test_peak - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_pmx\_crossover module ------------------------------------------- - -.. automodule:: pycellga.tests.test_pmx_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_population module --------------------------------------- - -.. automodule:: pycellga.tests.test_population - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_pow\_function module ------------------------------------------ - -.. automodule:: pycellga.tests.test_pow_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_powell\_function module --------------------------------------------- - -.. automodule:: pycellga.tests.test_powell_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_rastrigin module -------------------------------------- - -.. automodule:: pycellga.tests.test_rastrigin - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_rosenbrock module --------------------------------------- - -.. automodule:: pycellga.tests.test_rosenbrock - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_rothellipsoid\_function module ---------------------------------------------------- - -.. automodule:: pycellga.tests.test_rothellipsoid_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_roulette\_wheel\_selection module ------------------------------------------------------- - -.. automodule:: pycellga.tests.test_roulette_wheel_selection - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_schaffer2\_function module ------------------------------------------------ - -.. automodule:: pycellga.tests.test_schaffer2_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_schaffer\_function module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_schaffer_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_schwefel module ------------------------------------- - -.. automodule:: pycellga.tests.test_schwefel - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_shuffle\_mutation module ---------------------------------------------- - -.. automodule:: pycellga.tests.test_shuffle_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_sphere module ----------------------------------- - -.. automodule:: pycellga.tests.test_sphere - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_styblinskitang\_function module ----------------------------------------------------- - -.. automodule:: pycellga.tests.test_styblinskitang_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_sumofdifferentpowers\_function module ----------------------------------------------------------- - -.. automodule:: pycellga.tests.test_sumofdifferentpowers_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_swap\_mutation module ------------------------------------------- - -.. automodule:: pycellga.tests.test_swap_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_threehumps\_function module ------------------------------------------------- - -.. automodule:: pycellga.tests.test_threehumps_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_tournament\_selection module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_tournament_selection - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_tsp module -------------------------------- - -.. automodule:: pycellga.tests.test_tsp - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_two\_opt\_mutation module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_two_opt_mutation - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_two\_point\_crossover module -------------------------------------------------- - -.. automodule:: pycellga.tests.test_two_point_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_unfair\_average\_crossover module ------------------------------------------------------- - -.. automodule:: pycellga.tests.test_unfair_average_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_uniform\_crossover module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_uniform_crossover - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_zakharov\_function module ----------------------------------------------- - -.. automodule:: pycellga.tests.test_zakharov_function - :members: - :undoc-members: - :show-inheritance: - -pycellga.tests.test\_zettle\_function module --------------------------------------------- - -.. automodule:: pycellga.tests.test_zettle_function - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pycellga.tests - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/usage_examples.rst b/docs/usage_examples.rst new file mode 100644 index 0000000..363605e --- /dev/null +++ b/docs/usage_examples.rst @@ -0,0 +1,65 @@ +Usage Examples +============== + +In this section, we'll explain the `cga` method in the optimizer and provide an example of how to use it. The package includes various ready-to-use crossover and mutation operators, along with real-valued, binary, and permutation functions that you can run directly. Examples for other methods are available in the `example` folder, while an example for `cga` is provided below. + +cga (Cellular Genetic Algorithm) +-------------------------------- + +**cga** is a type of genetic algorithm where the population is structured as a grid (or other topologies), and each individual interacts only with its neighbors. This structure helps maintain diversity in the population and can prevent premature convergence. To specialize the CGA for real-valued optimization problems, ICGA (Improved CGA) with machine-coded representation can be used, applying byte operators. The encoding and decoding of numbers follow the IEEE 754 standard for floating-point arithmetic, yielding better results for continuous functions. + +Example Problem +--------------- + +Suppose we have a problem that we want to minimize using a Cellular Genetic Algorithm (CGA). The problem is defined as a simple sum of squares function, where the goal is to find a chromosome (vector) that minimizes the function. + +The sum of squares function computes the sum of the squares of each element in the chromosome. This function reaches its global minimum when all elements of the chromosome are equal to 0. The corresponding function value at this point is 0. + +ExampleProblem Class +-------------------- + +Here’s how we can define this problem in Python using the `ExampleProblem` class: + +.. code-block:: python + + from mpmath import power as pw + import pycellga + + class ExampleProblem: + + def __init__(self): + pass + + def f(self, x): + return sum(pw(xi, 2) for xi in x) + +Usage +----- + +.. code-block:: python + + result = pycellga.optimizer.cga( + n_cols = 5, + n_rows = 5, + n_gen = 100, + ch_size = 5, + gen_type = pycellga.optimizer.GeneType.REAL, + p_crossover = 0.9, + p_mutation = 0.2, + problem = ExampleProblem(), # Replace with a real problem instance as needed + selection = pycellga.optimizer.TournamentSelection, + recombination = pycellga.optimizer.ByteOnePointCrossover, + mutation = pycellga.optimizer.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("Best solution:", result[1], "\nBest solution chromosome:", result[0]) + + # The result is + # Best solution: 0.0 + # Best solution chromosome: [0.0, 0.0, 0.0, 0.0, 0.0] + +We have provided a basic example above. If you're interested in exploring more examples: + +- `Click here to see the other examples `_ available directly in the repository.