Metadata-Version: 2.4
Name: carmelolg-galib
Version: 0.3.0
Summary: A small, extensible library to build genetic algorithms.
Author: CARMELO LA GAMBA
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/carmelolg/GALib
Project-URL: Documentation, https://carmelolg.github.io/GALib/
Project-URL: Changelog, https://github.com/carmelolg/GALib/blob/main/CHANGELOG.md
Keywords: genetic algorithm,evolutionary computation,optimization,metaheuristics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Dynamic: license-file

# GALib

[![CI](https://github.com/carmelolg/GALib/actions/workflows/ci.yml/badge.svg)](https://github.com/carmelolg/GALib/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/carmelolg/GALib/graph/badge.svg)](https://codecov.io/gh/carmelolg/GALib)
[![PyPI](https://img.shields.io/pypi/v/carmelolg-galib)](https://pypi.org/project/carmelolg-galib/)
[![License: Apache 2.0](https://img.shields.io/github/license/carmelolg/GALib)](LICENSE)

A small, extensible library to build genetic algorithms in Python 3.10+.
Fully typed, no dependencies in the core, optional numpy acceleration.

**Documentation: <https://carmelolg.github.io/GALib/>**

| | |
|---|---|
| Distribution name (`pip install`) | `carmelolg-galib` |
| Import name | `carmelolg.galib` |

`carmelolg` is a [PEP 420](https://peps.python.org/pep-0420/) namespace package.

## Quick start

```python
import string
from carmelolg.galib import GeneticAlgorithm, Problem, TargetFitness

TARGET = "hello world"
ALPHABET = string.ascii_lowercase + " "


class Phrase(Problem[str]):
    def random_genome(self, rng):  # one random candidate
        return "".join(rng.choice(ALPHABET) for _ in TARGET)

    def random_gene(self, rng):  # enables the default mutation
        return rng.choice(ALPHABET)

    def fitness(self, genome):  # higher is better (set `maximize = False` to minimise)
        return sum(a == b for a, b in zip(genome, TARGET))


result = GeneticAlgorithm(Phrase(), stop=[TargetFitness(len(TARGET))], seed=1).run()
print(result.best.genome)  # hello world
```

## Features

- **Three levels of customisation**: parameters; pluggable operators (any callable, or methods on your
  `Problem`); subclasses of the engine overriding `select`, `crossover`, `mutate`, `reproduce`, `replace`, ...
- **Operators** for sequences (`OnePoint`, `TwoPoint`, `Uniform`, `RandomReset`), permutations
  (`OrderCrossover`, `PartiallyMappedCrossover`, `SwapMutation`, `InversionMutation`) and real values
  (`BlendCrossover`, `GaussianMutation`); selection by `Tournament`, `Roulette`, `Rank`.
- **Monitoring**: per-generation statistics and diversity, callbacks (`PrintProgress`), stop conditions
  (`TargetFitness`, `Stagnation`, `TimeLimit`), plots.
- **Performance**: vectorised `fitness_batch`, numpy array genomes, parallel evaluation in chunks (`workers=N`, or any executor).
- **Reproducible**: each run has its own seeded random generator.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,docs]"

python -m pytest --cov                     # tests with branch coverage
mypy                                       # strict type checking
ruff check src tests examples benchmarks   # lint
mkdocs serve                               # documentation preview on http://127.0.0.1:8000
python examples/tsp.py                     # examples: phrase, knapsack, tsp, rastrigin
```

The documentation sources are in `docs/` (MkDocs Material); `.github/workflows/docs.yml` publishes them to
GitHub Pages, `.github/workflows/ci.yml` runs tests, types, lint and the docs build.

## License

Copyright 2026 CARMELO LA GAMBA. Licensed under the [Apache License, Version 2.0](LICENSE).
Redistributions must keep the copyright notices and include the [NOTICE](NOTICE) file.
