A Python implementation of the CLONal selection ALGorithm (CLONALG) — a nature-inspired metaheuristic from the field of artificial immune systems. This project demonstrates how biological principles of immunity can be applied to solve continuous function optimization problems.
Clonal selection algorithms are inspired by the adaptive immune system's response to antigens. When the body encounters a pathogen, B-cells with the highest affinity (binding strength) to the antigen are selected, cloned, and subjected to somatic hypermutation — a process that refines the response over successive generations. CLONALG applies this mechanism to optimization: candidate solutions act as antibodies, and the objective function plays the role of the antigen.
- Clean, modular implementation separated into pure-function core and a high-level runner
- Injectable objective function — apply the algorithm to any continuous minimization problem
CLONALGConfigandCLONALGResultdataclasses for ergonomic configuration and result inspection- Bug-free cloning: clone count is inversely proportional to rank, not raw affinity score, following the standard CLONALG formulation
- Interactive Streamlit app for parameter exploration with a live convergence chart
- Dependency management with
uvand code quality enforced withruff
src/clonalg/
├── core.py # Pure algorithmic functions: evaluate, create_population, clone, hypermutate, select, replace
├── runner.py # CLONALGConfig, CLONALGResult, and the main run() loop
└── __init__.py # Public API
app.py # Streamlit app
notebooks/
└── CLONALG - Implementation and Execution.ipynb # Demo notebook
| Step | Biological analogy | Implementation |
|---|---|---|
| Initialize population | Naive B-cell repertoire | create_population() |
| Evaluate affinity | Antigen-antibody binding | evaluate() with injectable objective_fn |
| Select top candidates | Clonal selection | population_scored[:selection_size] |
| Clone | Cell proliferation | clone(individual, rank, clone_rate) |
| Hypermutate | Somatic hypermutation | hypermutate() — mutation rate ∝ affinity |
| Reselect survivors | Affinity maturation | select() |
| Replace worst | Repertoire diversity | replace() with new random cells |
This project uses uv for dependency management.
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/christianrfg/clonalg.git
cd clonalg
# Install dependencies
uv sync --all-groupsuv run streamlit run app.py
The app lets you explore how different parameters affect the algorithm's convergence without writing any code:
- Objective function — choose between Sphere (unimodal), Rastrigin (highly multimodal), or Rosenbrock (narrow curved valley)
- All algorithm parameters — population size, selection size, clone rate, mutation rate, number of iterations, and more, all configurable via sidebar sliders
- Live convergence chart — an interactive Plotly chart updates in real time as the algorithm runs, showing the best affinity and top-5 mean per iteration on a log scale
- Live metrics — current iteration, best affinity, and top-5 mean update alongside the chart
- Final result — after convergence, the best solution vector and objective value are displayed per dimension
uv run jupyter notebook notebooks/The notebook demonstrates the algorithm on a chosen objective function (Sphere, Rastrigin, or Rosenbrock), runs it once, and displays a final interactive convergence chart.
import sys
sys.path.insert(0, "src")
import numpy as np
from clonalg import CLONALGConfig, run
def sphere(x: np.ndarray) -> float:
return float(np.sum(x ** 2))
config = CLONALGConfig(
problem_size=3,
b_lo=-5.0,
b_up=5.0,
population_size=100,
selection_size=10,
clone_rate=20,
mutation_rate=0.2,
max_iterations=1000,
)
result = run(sphere, config)
print(result.best_solution) # np.ndarray — best solution found
print(result.best_affinity) # float — objective value at best solutionuv run ruff format src/ app.py # format
uv run ruff check src/ app.py # lint
uv run ruff check src/ app.py --fix # lint and auto-fix- Clonal Selection Algorithm — Clever Algorithms
- Clonal Selection Algorithm — Wikipedia
- de Castro, L. N., & Von Zuben, F. J. (2002). Learning and optimization using the clonal selection principle. IEEE Transactions on Evolutionary Computation.
Distributed under the MIT License. See LICENSE.md for details.