More operators & support of benchmarks

Author: ahmedfgad

docs/source/benchmarks.md

@@ -0,0 +1,129 @@
+# Benchmark Problems
+
+PyGAD ships a small collection of standard benchmark problems under `pygad.benchmarks`. Each problem is a class that can be called with the PyGAD fitness signature `(ga, solution, sol_idx)` and returns a fitness value in PyGAD's maximization format (the original minimization values are negated for you).
+
+Each class also exposes the attributes you usually need to set up the GA:
+
+- `num_genes`: number of decision variables.
+- `num_objectives`: number of objectives. `1` for single-objective problems.
+- `bounds`: `(low, high)` tuple of variable bounds.
+
+For ZDT problems and ZDT4 / ZDT6, the class also has a `pareto_front(num_points)` method that returns reference points on the true Pareto front. Pass these to the IGD or GD indicators as the `reference_front` argument.
+
+## Single-Objective Problems
+
+Available in `pygad.benchmarks.classic`:
+
+| Class | Global minimum | Bounds |
+|---|---|---|
+| `Sphere` | f(0, ..., 0) = 0 | `(-5.12, 5.12)` |
+| `Rastrigin` | f(0, ..., 0) = 0 | `(-5.12, 5.12)` |
+| `Rosenbrock` | f(1, ..., 1) = 0 | `(-5.0, 10.0)` |
+| `Griewank` | f(0, ..., 0) = 0 | `(-600.0, 600.0)` |
+| `Schwefel` | f(420.97, ..., 420.97) ≈ 0 | `(-500.0, 500.0)` |
+| `Ackley` | f(0, ..., 0) = 0 | `(-32.768, 32.768)` |
+| `Himmelblau` | four equal minima at f = 0 (2D only) | `(-5.0, 5.0)` |
+
+## Multi-Objective Problems (ZDT family)
+
+Available in `pygad.benchmarks.zdt`. All ZDT problems have two objectives and variables in `[0, 1]` (except ZDT4 which uses `[-5, 5]` for the rest of the variables).
+
+| Class | Pareto front shape |
+|---|---|
+| `ZDT1` | convex |
+| `ZDT2` | non-convex |
+| `ZDT3` | disconnected (five pieces) |
+| `ZDT4` | convex, many local minima in the search space |
+| `ZDT6` | non-uniform |
+
+## Many-Objective Problems (DTLZ family)
+
+Available in `pygad.benchmarks.dtlz`. All DTLZ problems support an arbitrary number of objectives `M`. The number of decision variables is `M + k - 1` where `k` is a "distance" variable count.
+
+| Class | Default M | Pareto front shape |
+|---|---|---|
+| `DTLZ1` | 3 | linear hyperplane (`sum(f_i) = 0.5`) |
+| `DTLZ2` | 3 | unit sphere first orthant |
+| `DTLZ3` | 3 | unit sphere with hard multimodal g-function |
+| `DTLZ4` | 3 | unit sphere with strong bias toward one corner |
+
+## Combinatorial Problems
+
+Available in `pygad.benchmarks.knapsack`. The 0/1 `Knapsack` class takes three arguments: a 1D array of item `weights`, a 1D array of item `values`, and a numeric `capacity`. A solution is a binary vector where a 1 means the item is picked. The fitness is the total value when the candidate is within the capacity, and a negative penalty scaled by how much the candidate is over the limit otherwise.
+
+The class exposes `gene_space=[0, 1]` and `gene_type=int` so you can plug it directly into PyGAD:
+
+```python
+import pygad
+from pygad.benchmarks.knapsack import Knapsack
+
+problem = Knapsack(weights=[2, 3, 4, 5],
+                   values=[3, 4, 5, 6],
+                   capacity=5)
+
+ga = pygad.GA(
+    num_generations=50,
+    num_parents_mating=10,
+    fitness_func=problem,
+    sol_per_pop=30,
+    num_genes=problem.num_genes,
+    gene_space=problem.gene_space,
+    gene_type=problem.gene_type,
+)
+ga.run()
+```
+
+## Example: SOO
+
+```python
+import pygad
+from pygad.benchmarks.classic import Sphere
+
+problem = Sphere(num_genes=10)
+
+ga = pygad.GA(
+    num_generations=100,
+    num_parents_mating=10,
+    fitness_func=problem,
+    sol_per_pop=20,
+    num_genes=problem.num_genes,
+    init_range_low=problem.bounds[0],
+    init_range_high=problem.bounds[1],
+    crossover_type='sbx',
+    sbx_crossover_eta=30,
+    mutation_type='polynomial',
+    polynomial_mutation_eta=20,
+)
+ga.run()
+```
+
+## Example: MOO
+
+```python
+import pygad
+from pygad.benchmarks.zdt import ZDT1
+from pygad.utils.indicators import inverted_generational_distance
+
+problem = ZDT1(num_genes=10)
+
+ga = pygad.GA(
+    num_generations=200,
+    num_parents_mating=20,
+    fitness_func=problem,
+    sol_per_pop=30,
+    num_genes=problem.num_genes,
+    init_range_low=problem.bounds[0],
+    init_range_high=problem.bounds[1],
+    parent_selection_type='nsga2',
+    crossover_type='sbx',
+    sbx_crossover_eta=30,
+    mutation_type='polynomial',
+    polynomial_mutation_eta=20,
+)
+ga.run()
+
+# Measure how close the final population is to the true Pareto front
+true_front = problem.pareto_front(num_points=100)
+igd = inverted_generational_distance(ga.last_generation_fitness, true_front)
+print(f'IGD = {igd}')
+```

docs/source/pygad.md

@@ -55,12 +55,16 @@ Introduced in [PyGAD 2.0.0](https://pygad.readthedocs.io/en/latest/releases.html
 
 One or more conditions that stop the evolution early. Each criterion is a string made of a stop word and a number, like `"reach_40"`.
 
-Two stop words are supported:
+Four stop words are supported:
 
 - `reach`: stop when the fitness is greater than or equal to a given value. Example: `"reach_40"` stops once the fitness is `>= 40`.
 - `saturate`: stop when the fitness does not change for a given number of generations. Example: `"saturate_7"` stops if the fitness stays the same for 7 generations in a row.
+- `time`: stop when the time spent inside `run()` is at least the given number of seconds. Example: `"time_30"` stops the run after 30 seconds.
+- `evaluations`: stop when the number of fitness function calls made inside `run()` reaches the given count. Example: `"evaluations_1000"` stops the run once 1000 calls have been made.
 
-Added in [PyGAD 2.15.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-15-0).
+You can also pass a list of criteria; the run stops as soon as any one of them is met.
+
+Added in [PyGAD 2.15.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-15-0). The `time` and `evaluations` keywords were added in PyGAD 3.6.0.
 :::
 
 #### Fitness Function
@@ -251,12 +255,19 @@ The built-in types are:
 - `two_points`: two-point crossover.
 - `uniform`: uniform crossover.
 - `scattered`: scattered crossover (since [PyGAD 2.9.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-9-0)).
+- `sbx`: simulated binary crossover. The standard real-coded operator. Requires the `sbx_crossover_eta` parameter.
 
 You can also pass your own crossover function (since [PyGAD 2.16.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-16-0)). See [User-Defined Crossover, Mutation, and Parent Selection Operators](https://pygad.readthedocs.io/en/latest/user_defined_operators.html#user-defined-crossover-mutation-and-parent-selection-operators).
 
 If `crossover_type=None`, the crossover step is skipped and no offspring are created, so the next generation reuses the current population (since [PyGAD 2.2.2](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-2-2)).
 :::
 
+:::{dropdown} `sbx_crossover_eta=30`: Distribution index for SBX crossover.
+:animate: fade-in-slide-down
+
+Only used when `crossover_type` is `'sbx'`. Sets how close the children stay to the parents. A higher value means children stay closer. Must be a positive number. Defaults to `30`.
+:::
+
 :::{dropdown} `crossover_probability=None`: Chance a parent is used for crossover.
 :animate: fade-in-slide-down
 
@@ -281,12 +292,19 @@ The built-in types are:
 - `inversion`: inversion mutation.
 - `scramble`: scramble mutation.
 - `adaptive`: adaptive mutation (since [PyGAD 2.10.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-10-0)). See [Adaptive Mutation](https://pygad.readthedocs.io/en/latest/adaptive_mutation.html#adaptive-mutation) and [Use Adaptive Mutation in PyGAD](https://pygad.readthedocs.io/en/latest/adaptive_mutation.html#use-adaptive-mutation-in-pygad).
+- `polynomial`: polynomial mutation. The standard real-coded operator used together with SBX. Requires the `polynomial_mutation_eta` parameter.
 
 You can also pass your own mutation function (since [PyGAD 2.16.0](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-16-0)). See [User-Defined Crossover, Mutation, and Parent Selection Operators](https://pygad.readthedocs.io/en/latest/user_defined_operators.html#user-defined-crossover-mutation-and-parent-selection-operators).
 
 If `mutation_type=None`, the mutation step is skipped and the offspring are used unchanged (since [PyGAD 2.2.2](https://pygad.readthedocs.io/en/latest/releases.html#pygad-2-2-2)).
 :::
 
+:::{dropdown} `polynomial_mutation_eta=20`: Distribution index for polynomial mutation.
+:animate: fade-in-slide-down
+
+Only used when `mutation_type` is `'polynomial'`. Sets the size of the change. A higher value means a smaller change. Must be a positive number. Defaults to `20`.
+:::
+
 :::{dropdown} `mutation_probability=None`: Per-gene chance of mutation.
 :animate: fade-in-slide-down
 

docs/source/pygad_more.md

@@ -47,6 +47,13 @@ Print a Keras-like summary and log the outputs.
 Pass your own functions, methods, or classes for the fitness and callbacks.
 :::
 
+:::{grid-item-card} Benchmark Problems
+:link: benchmarks
+:link-type: doc
+
+Built-in single, multi, and many-objective benchmark problems to plug into the GA.
+:::
+
 ::::
 
 :::{toctree}
@@ -58,4 +65,5 @@ generations
 fitness_calculation
 logging
 custom_functions
+benchmarks
 :::

docs/source/releases.md

@@ -657,7 +657,11 @@ Release Date April 8, 2026
 22. Two new parent selection methods are added to support NSGA-III: 1) `nsga3_selection()` for plain NSGA-III selection, and 2) `tournament_selection_nsga3()` for the tournament variant. Use them by setting `parent_selection_type` to `'nsga3'` or `'tournament_nsga3'`.
 23. A new parameter `nsga3_num_divisions` is added to the `pygad.GA` constructor. It is required when `parent_selection_type` is `'nsga3'` or `'tournament_nsga3'` and sets the number of divisions per objective axis used to build the structured reference points (the `p` parameter from Deb & Jain 2014). The total number of reference points is `C(M + p - 1, p)` where `M` is the number of objectives.
 24. When `sol_per_pop` is smaller than the number of NSGA-III reference points, PyGAD raises a warning and grows the population to match before the generational loop starts.
-
+25. A new crossover operator: Simulated Binary Crossover (SBX). Use it by setting `crossover_type='sbx'`. The shape of the spread is controlled by the new `sbx_crossover_eta` parameter (default 30).
+26. A new mutation operator: polynomial mutation. Use it by setting `mutation_type='polynomial'`. The size of the change is controlled by the new `polynomial_mutation_eta` parameter (default 20).
+27. Two new stop criteria: `time_<seconds>` stops the run when the time inside `run()` is at least the given number of seconds; `evaluations_<N>` stops the run when the number of fitness function calls reaches the given count. New instance attribute `num_fitness_evaluations` counts the calls.
+28. A new submodule `pygad.utils.indicators` with four functions to measure the quality of a Pareto front: `hypervolume`, `inverted_generational_distance`, `generational_distance`, and `spacing`.
+29. A new submodule `pygad.benchmarks` with built-in benchmark problems. `pygad.benchmarks.classic` has Sphere, Rastrigin, Rosenbrock, Griewank, Schwefel, Ackley, and Himmelblau. `pygad.benchmarks.zdt` has the ZDT family (ZDT1, ZDT2, ZDT3, ZDT4, ZDT6). `pygad.benchmarks.dtlz` has DTLZ1, DTLZ2, DTLZ3, and DTLZ4. `pygad.benchmarks.knapsack` has the 0/1 Knapsack problem. Each class is callable with the PyGAD fitness signature and returns negated values (for the minimization-style problems) so PyGAD can maximize toward the original minimum.
 21. Instead of using repeated code for converting the data type and rounding the genes during crossover and mutation, the `change_gene_dtype_and_round()` method is called from the `pygad.helper.misc.Helper` class.
 22. Fix some documentation issues. https://github.com/ahmedfgad/GeneticAlgorithmPython/pull/336
 23. Update the documentation to reflect the recent additions and changes to the library structure.

docs/source/utils.md

@@ -12,6 +12,7 @@ The submodules in the `pygad.utils` module are:
 4. `parent_selection`: Has the `ParentSelection` class that implements the parent selection operators.
 5. `nsga2`: Has the `NSGA2` class that implements the Non-Dominated Sorting Genetic Algorithm II (NSGA-II).
 6. `nsga3`: Has the `NSGA3` class that implements the Non-Dominated Sorting Genetic Algorithm III (NSGA-III).
+7. `indicators`: Has functions to measure the quality of a Pareto front: `hypervolume`, `inverted_generational_distance`, `generational_distance`, and `spacing`.
 
 Note that the `pygad.GA` class extends all of these classes. So, the user can access any of the methods in such classes directly by the instance/object of the `pygad.GA` class.
 
@@ -342,6 +343,32 @@ The `pygad.utils.nsga3` module has a class named `NSGA3` that implements NSGA-II
 8. `nsga3_selection()`: Top-level NSGA-III parent selection routine.
 9. `tournament_selection_nsga3()`: Tournament-style NSGA-III parent selection routine.
 
+## `pygad.utils.indicators` Submodule
+
+The `pygad.utils.indicators` module has functions to measure the quality of a Pareto front. All functions take fitness values in PyGAD's maximization format. The functions are:
+
+1. `hypervolume(fitness, reference_point)`: Volume of the objective space dominated by the front. The reference point must be worse than every solution on every objective. A larger value is better.
+2. `inverted_generational_distance(fitness, reference_front)`: Mean distance from each reference-front point to its nearest approximation point. Reports both convergence and diversity. A smaller value is better.
+3. `generational_distance(fitness, reference_front)`: Mean distance from each approximation point to its nearest reference point. Reports convergence only. A smaller value is better.
+4. `spacing(fitness)`: Standard deviation of the distance from each solution to its nearest neighbour. A smaller value means the solutions are spread more evenly.
+
+Example:
+
+```python
+from pygad.utils.indicators import hypervolume, inverted_generational_distance
+
+# After ga.run()
+fitness = ga.last_generation_fitness
+reference_point = [-10.0, -10.0]   # worse than every solution
+hv = hypervolume(fitness, reference_point)
+
+# If the true Pareto front is known
+from pygad.benchmarks.zdt import ZDT1
+problem = ZDT1()
+true_front = problem.pareto_front(num_points=100)
+igd = inverted_generational_distance(fitness, true_front)
+```
+
 ## More about the Operators
 
 ::::{grid} 1 2 2 2

pygad/__init__.py

@@ -1,3 +1,5 @@
 from .pygad import * # Relative import.
 
+from pygad import benchmarks
+
 from ._version import __version__

pygad/benchmarks/__init__.py

@@ -0,0 +1,17 @@
+"""
+Standard benchmark problems for PyGAD.
+
+Every problem class can be called with the standard PyGAD fitness
+function signature (ga, solution, sol_idx) and returns a fitness in
+PyGAD's maximization format. The original minimization values are
+negated so the user can plug the problem directly into PyGAD without
+extra wrapping. Each class also has the attributes num_genes,
+num_objectives, and bounds.
+"""
+
+from pygad.benchmarks import classic
+from pygad.benchmarks import zdt
+from pygad.benchmarks import dtlz
+from pygad.benchmarks import knapsack
+
+__all__ = ["classic", "zdt", "dtlz", "knapsack"]