Examples¶

Find complete Python scripts by topic, open their source on GitHub, or download examples that need no companion files. Each entry links back to its documentation guide. The same examples appear in Python example cards beside the relevant explanations in those guides.

Running the Examples¶

For examples from this documentation revision, use the matching version of PyGAD. The PyGAD 3.8.0 examples can use the published package:

python -m pip install "pygad[visualize]==3.8.0"

For development examples, including features in the Unreleased notes, clone or download the matching repository revision, then install it from the repository root:

python -m pip install -e ".[visualize]"

Run a script using its path, for example:

python examples/plots/example_plot_lifecycle.py

For a script downloaded separately, run python with the path where you saved it. It still requires a compatible installed version of PyGAD. Plotting examples need Matplotlib; PDF reports need pygad[report]. Keras and PyTorch examples need their respective frameworks. The Run this example dropdowns in the guides give additional requirements and working directories.

Examples requiring datasets link to their folders instead of offering a standalone download. Their datasets are not bundled with PyGAD or the repository. Follow the linked data setup instructions and keep the repository directory layout. The TSP notebook is listed alongside the Python scripts; it uses Google Colab and a user-supplied CSV. Adapt its Colab-specific imports and CSV path before running it locally with Jupyter.

Use documentation search or your browser’s find command to locate a topic or filename on this page.

Getting Started¶

Python script	What it shows	Related information
example.py	First GA run. Optimize a linear equation, inspect the best solution, plot fitness, and save and reload the GA.	Guide · `Download`

Population and Genes¶

Python script	What it shows	Related information
example_initial_population.py	Initial populations. Generate values from per-gene ranges and nested spaces, or supply values and infer the dimensions.	Guide · `Download`
example_gene_space.py	Gene spaces. Compare shared and per-gene choices, ranges, dictionaries, fixed values, and None entries.	Guide · `Download`
example_gene_constraint.py	Gene constraints. Filter gene candidates with constraints that depend on other genes.	Guide · `Download`
example_duplicate_gene_repair.py	Duplicate repair. Repair duplicates through a chain of replacements while respecting each gene space.	Guide · `Download`
example_gene_type_conversion.py	Gene types and rounding. Preserve mixed numeric types, apply precision, and convert custom mutation outputs.	Guide · `Download`
example_dynamic_population_size.py	Changing population size. Adjust the population and related runtime settings during evolution.	Guide · `Download`

Operators and Configuration¶

Python script	What it shows	Related information
example_custom_operators.py	Custom GA operators. Implement parent selection, crossover, and mutation functions.	Guide · `Download`
example_constructor_parameters.py	Constructor settings and random seeds. Use callable fitness signatures, NumPy counts, and independent seeded GA instances.	Guide · `Download`

Fitness and Parallel Processing¶

Python script	What it shows	Related information
example_fitness_batch_size.py	Batch fitness. Return one fitness result per solution, including a shorter final batch.	Guide · `Download`
example_parallel_processing.py	Parallel fitness. Evaluate population fitness with process workers and report the run time.	Guide · `Download`
benchmarks/parallel_processing.py	Compare fitness execution modes. Measure complete runs for CPU, I/O, and NumPy workloads with serial, thread, process, and batch evaluation.	Guide · `Download`
example_fitness_wrapper.py	Extra fitness arguments. Wrap a fitness function to pass additional values while preserving its PyGAD signature.	Guide · `Download`

Lifecycle and Saved Runs¶

Python script	What it shows	Related information
pygad_lifecycle.py	Lifecycle callbacks. Trace fitness, parent selection, crossover, mutation, generation, and stop callbacks.	Guide · `Download`
example_lifecycle_methods.py	Callbacks as methods. Implement fitness and lifecycle callbacks with bound methods.	Guide · `Download`
example_lifecycle_classes.py	Callbacks as callable classes. Implement fitness and lifecycle callbacks with callable class instances.	Guide · `Download`
example_summary.py	Text lifecycle summary. Print the configured GA stages and their parameters.	Guide · `Download`
example_logger.py	Logging. Send progress and GA messages to a configured logger.	Guide · `Download`
example_repeated_runs.py	Repeated runs and checkpoints. Continue from a saved GA and inspect the actual generation numbers in its histories.	Guide · `Download`
example_load_fitness_function.py	Change a loaded fitness function. Replace the fitness callable after loading, or start fresh when the objective changes.	Guide · `Download`

Multi-Objective Optimization¶

Python script	What it shows	Related information
example_multi_objective.py	NSGA-II optimization. Optimize two objectives and inspect the resulting trade-offs.	Guide · `Download`
example_multi_objective_nsga3.py	NSGA-III optimization. Configure reference points and optimize two objectives with NSGA-III.	Guide · `Download`

Plots¶

Python script	What it shows	Related information
plots/example_plot_fitness.py	Best-fitness curve. Plot best fitness across generations on the Sphere benchmark.	Guide · `Download`
plots/example_plot_fitness_band.py	Fitness band. Plot per-generation minimum, mean, and maximum fitness with a shaded band.	Guide · `Download`
plots/example_plot_genes.py	Gene histories. Show how gene values change across saved generations.	Guide · `Download`
plots/example_plot_lifecycle.py	Configured lifecycle. Draw detailed and compact lifecycle charts and export SVG and PNG files.	Guide · `Download`
plots/example_plot_new_solution_rate.py	New-solution rate. Count previously unseen solutions in each generation.	Guide · `Download`
plots/example_plot_non_dominated_hypervolume.py	Hypervolume history. Track the hypervolume of the non-dominated set across generations.	Guide · `Download`
plots/example_plot_pareto_front_curve_2d.py	2D Pareto front. Plot a two-objective Pareto front after NSGA-II optimization.	Guide · `Download`
plots/example_plot_pareto_front_curve_3d.py	3D Pareto front. Plot a three-objective Pareto front after NSGA-III optimization.	Guide · `Download`
plots/example_plot_pareto_front_evolution.py	Pareto-front evolution. Overlay the non-dominated fronts from selected generations.	Guide · `Download`
plots/example_plot_pareto_front_heatmap.py	Pareto heatmap. Compare objective values with a solutions-by-objectives heatmap.	Guide · `Download`
plots/example_plot_pareto_front_pcp.py	Parallel coordinates. Compare Pareto solutions across objective axes.	Guide · `Download`
plots/example_plot_pareto_front_scatter_matrix.py	Pareto scatter matrix. Compare every pair of objectives in a many-objective run.	Guide · `Download`
plots/example_plot_population_diversity.py	Population diversity. Track mean pairwise distance between solutions across generations.	Guide · `Download`

Reports¶

Python script	What it shows	Related information
example_generate_report.py	PDF report. Export the run configuration, summary, best solution, and applicable plots to PDF.	Guide · `Download`

Benchmarks¶

Python script	What it shows	Related information
benchmarks/example_classic_sphere.py	Sphere. Optimize the Sphere single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_rastrigin.py	Rastrigin. Optimize the Rastrigin single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_rosenbrock.py	Rosenbrock. Optimize the Rosenbrock single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_griewank.py	Griewank. Optimize the Griewank single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_schwefel.py	Schwefel. Optimize the Schwefel single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_ackley.py	Ackley. Optimize the Ackley single-objective benchmark.	Guide · `Download`
benchmarks/example_classic_himmelblau.py	Himmelblau. Optimize the Himmelblau single-objective benchmark.	Guide · `Download`
benchmarks/example_zdt1.py	ZDT1. Optimize the ZDT1 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_zdt2.py	ZDT2. Optimize the ZDT2 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_zdt3.py	ZDT3. Optimize the ZDT3 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_zdt4.py	ZDT4. Optimize the ZDT4 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_zdt6.py	ZDT6. Optimize the ZDT6 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_dtlz1.py	DTLZ1. Optimize the DTLZ1 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_dtlz2.py	DTLZ2. Optimize the DTLZ2 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_dtlz3.py	DTLZ3. Optimize the DTLZ3 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_dtlz4.py	DTLZ4. Optimize the DTLZ4 problem and plot its Pareto front.	Guide · `Download`
benchmarks/example_knapsack.py	Knapsack. Select items to maximize value within a weight capacity.	Guide · `Download`
benchmarks/example_tsp.py	Travelling salesman. Find a short tour using a permutation of four cities.	Guide · `Download`
example_travelling_salesman.ipynb	Travelling-salesman Colab notebook. Explore a city-tour problem using a user-supplied CSV and interactive maps. Requires external data.	Guide · Folder · Data setup

Quality Indicators¶

Python script	What it shows	Related information
quality_indicators/example_hypervolume.py	Hypervolume. Measure the objective-space volume dominated by the final population.	Guide · `Download`
quality_indicators/example_inverted_generational_distance.py	Inverted generational distance. Measure distance from a reference front to the approximation.	Guide · `Download`
quality_indicators/example_generational_distance.py	Generational distance. Measure distance from the approximation to a reference front.	Guide · `Download`
quality_indicators/example_spacing.py	Spacing. Measure how evenly the approximation points are spread.	Guide · `Download`

Neural Networks¶

Python script	What it shows	Related information
nn/example_regression.py	Regression. Fit a neural network to a small numeric regression problem.	Guide · `Download`
nn/example_XOR_classification.py	XOR classification. Train a neural network on the four XOR inputs.	Guide · `Download`
nn/example_classification.py	Image classification. Classify fruit images from prepared feature vectors. Requires external data.	Guide · Folder · Data setup
nn/example_regression_fish.py	Fish-weight regression. Predict fish weight from numeric measurements. Requires external data.	Guide · Folder · Data setup
nn/extract_features.py	Prepare image features. Extract fruit-image features and write the arrays used by the dense classifiers. Requires external data.	Guide · Folder · Data setup

Neural Networks with the GA¶

Python script	What it shows	Related information
gann/example_regression.py	Regression. Fit a neural network to a small numeric regression problem.	Guide · `Download`
gann/example_XOR_classification.py	XOR classification. Train a neural network on the four XOR inputs.	Guide · `Download`
gann/example_classification.py	Image classification. Classify fruit images from prepared feature vectors. Requires external data.	Guide · Folder · Data setup
gann/example_regression_fish.py	Fish-weight regression. Predict fish weight from numeric measurements. Requires external data.	Guide · Folder · Data setup

Convolutional Networks¶

Python script	What it shows	Related information
cnn/example_image_classification.py	Build a CNN. Classify fruit images using prepared image arrays. Requires external data.	Guide · Folder · Data setup
gacnn/example_image_classification.py	Optimize a CNN with the GA. Classify fruit images using prepared image arrays. Requires external data.	Guide · Folder · Data setup

Keras¶

Python script	What it shows	Related information
KerasGA/regression_example.py	Regression. Optimize neural-network weights with the genetic algorithm.	Guide · `Download`
KerasGA/XOR_classification.py	XOR classification. Optimize neural-network weights with the genetic algorithm.	Guide · `Download`
KerasGA/image_classification_Dense.py	Dense image classifier. Train an image classifier with the genetic algorithm. Requires external data.	Guide · Folder · Data setup
KerasGA/image_classification_CNN.py	Convolutional image classifier. Train an image classifier with the genetic algorithm. Requires external data.	Guide · Folder · Data setup
KerasGA/cancer_dataset.py	Image-directory classification. Use directory-based image input for a two-class Keras CNN. Requires external data.	Guide · Folder · Data setup
KerasGA/cancer_dataset_generator.py	Batched image-directory classification. Use directory-based image input for a two-class Keras CNN. Requires external data.	Guide · Folder · Data setup

PyTorch¶

Python script	What it shows	Related information
TorchGA/regression_example.py	Regression. Optimize neural-network weights with the genetic algorithm.	Guide · `Download`
TorchGA/XOR_classification.py	XOR classification. Optimize neural-network weights with the genetic algorithm.	Guide · `Download`
TorchGA/image_classification_Dense.py	Dense image classifier. Train an image classifier with the genetic algorithm. Requires external data.	Guide · Folder · Data setup
TorchGA/image_classification_CNN.py	Convolutional image classifier. Train an image classifier with the genetic algorithm. Requires external data.	Guide · Folder · Data setup

Clustering¶

Python script	What it shows	Related information
clustering/example_clustering_2.py	2-cluster example. Optimize 2 cluster centers for generated two-dimensional data.	Guide · `Download`
clustering/example_clustering_3.py	3-cluster example. Optimize 3 cluster centers for generated two-dimensional data.	Guide · `Download`