Ant Colony Optimization#

Ant Colony Optimization (ACO) is a family of metaheuristics inspired by the foraging behavior of real ants, which lay down pheromone trails that bias the paths taken by other ants, reinforcing shorter or better paths over time. In the library, this idea is split into a shared driver, AntColonyOptimization, and two concrete strategies that differ in how solutions are represented and how “pheromones” are stored and used:

ContinuousAntColonyOptimization (ACOR) for continuous, box-constrained real-valued problems.
CombinatorialAntColonyOptimization (Ant System) for permutation problems defined over a distance matrix, such as the Traveling Salesman Problem (TSP).

See Ant Colony Optimization (ACO) for an explanation of how the two algorithms work, and worked examples for both.

class sigmaepsilon.math.optimize.aco.AntSolution(*, phenotype: list[float] = <factory>, fitness: float, index: int = -1)[source]#

A data class for ant solutions.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sigmaepsilon.math.optimize.aco.AntColonyOptimization(fnc: Callable, ranges: Iterable, *, nAnts: int = 50, maxiter: int = 200, miniter: int = 0, rho: float = 0.1, minimize: bool = False, seed: int | SeedSequence | Generator | None = None, vectorized: bool = False, n_jobs: int = 1, maxage: int = 10)[source]#

Base class for Ant Colony Optimization (ACO) algorithms.

This class provides the common framework for ACO algorithms, with two extension points that subclasses must implement: construct_solutions() and update_pheromones().

Parameters:

fnc (Callable) – The objective function to optimize. It should accept an N-dimensional input and return a scalar fitness value.
ranges (Iterable) – Ranges for each dimension of the search space, as a list of [min, max] pairs.
nAnts (int, Optional) – Number of ants in the colony. Default is 50.
maxiter (int, Optional) – Maximum number of iterations. Default is 200.
miniter (int, Optional) – Minimum number of iterations before stopping criteria can trigger. Default is 0.
rho (float, Optional) – Pheromone evaporation rate. Default is 0.1.
minimize (bool, Optional) – If True, minimize the objective function. Default is False (maximize).
seed (int | numpy.random.SeedSequence | numpy.random.Generator | None, Optional) – Random seed for reproducibility. Default is None.
vectorized (bool, Optional) – If True, the objective function accepts batched inputs. Default is False.
n_jobs (int, Optional) – Number of parallel jobs for evaluation. -1 uses all CPUs. Default is 1.
maxage (int, Optional) – Maximum number of iterations without improvement before convergence. Default is 10.

Note

This is an abstract base class. Use ContinuousAntColonyOptimization for real-valued optimization or CombinatorialAntColonyOptimization for discrete/graph-based problems.

class Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#: Status codes for the ACO algorithm.

best_candidate() → AntSolution[source]#: Return the best solution found (alias for champion).

best_phenotype() → ndarray[source]#: Return the phenotype of the best solution found.

property champion: AntSolution#: Return the best solution found so far.

construct_solutions() → ndarray[source]#: Construct solutions using the ACO mechanism. Must be implemented by subclass.

evaluate(phenotypes: ndarray | None = None) → ndarray[source]#: Evaluate the objective function for a set of solutions.

evolve(cycles: int = 1) → ndarray[source]#: Perform a number of evolution cycles.

reset() → AntColonyOptimization[source]#: Reset the solver and return the object.

property rng: Generator#: Return the random number generator of the instance.

set_solution_params(**kwargs) → AntColonyOptimization[source]#: Set the hyperparameters of the algorithm.

solve(recycle: bool = False, **kwargs) → AntSolution[source]#: Solve the optimization problem and return the best solution.

property state: OptimizerState#: Return the state of the optimizer.

stopping_criteria() → bool[source]#: Check if the algorithm should stop (stagnation-based).

update_pheromones(solutions: ndarray, fitness: ndarray) → None[source]#: Update pheromone information. Must be implemented by subclass.

class sigmaepsilon.math.optimize.aco.ContinuousAntColonyOptimization(fnc: Callable, ranges: Iterable, *, archive_size: int = 50, q: float = 0.5, xi: float = 0.85, nAnts: int = 50, maxiter: int = 200, miniter: int = 0, rho: float = 0.1, minimize: bool = False, seed: int | SeedSequence | Generator | None = None, vectorized: bool = False, n_jobs: int = 1, maxage: int = 10)[source]#

Continuous Ant Colony Optimization (ACOR) for real-valued problems.

Implements the ACOR algorithm (Socha & Dorigo, 2008) which maintains a solution archive and samples new solutions using Gaussian kernels.

Parameters:

fnc (Callable) – The objective function to optimize.
ranges (Iterable) – Ranges for each dimension as [min, max] pairs.
archive_size (int, Optional) – Size of the solution archive. Default is 50.
q (float, Optional) – Locality of the search (smaller = more focused). Default is 0.5.
xi (float, Optional) – Convergence speed parameter. Default is 0.85.
nAnts (int, Optional) – Number of ants constructing solutions per iteration. Default is 50.
maxiter (int, Optional) – Maximum number of iterations. Default is 200.
miniter (int, Optional) – Minimum iterations before stopping. Default is 0.
rho (float, Optional) – Not used in ACOR but kept for API compatibility. Default is 0.1.
minimize (bool, Optional) – If True, minimize the objective. Default is False.
seed (int | numpy.random.SeedSequence | numpy.random.Generator | None, Optional) – Random seed for reproducibility. Default is None.
vectorized (bool, Optional) – If True, objective accepts batched inputs. Default is False.
n_jobs (int, Optional) – Number of parallel jobs. Default is 1.
maxage (int, Optional) – Stagnation threshold. Default is 10.

construct_solutions() → ndarray[source]#: Construct solutions using ACOR Gaussian kernel sampling.

reset() → ContinuousAntColonyOptimization[source]#: Reset the solver and initialize the archive with random solutions.

update_pheromones(solutions: ndarray, fitness: ndarray) → None[source]#: Update archive by merging new solutions and keeping the best.

class sigmaepsilon.math.optimize.aco.CombinatorialAntColonyOptimization(fnc: Callable, distance_matrix: ndarray, *, alpha: float = 1.0, beta: float = 2.0, Q: float = 1.0, nAnts: int = 50, maxiter: int = 200, miniter: int = 0, rho: float = 0.1, minimize: bool = True, seed: int | SeedSequence | Generator | None = None, maxage: int = 10, tau_init: float = 0.1)[source]#

Combinatorial Ant Colony Optimization (Ant System) for TSP-like problems.

Implements the classic Ant System algorithm (Dorigo et al., 1996) for solving traveling salesman-type problems on a distance matrix.

Parameters:

fnc (Callable) – Tour evaluation function. Takes a tour (array of node indices) and returns the tour cost/length.
distance_matrix (ndarray) – Symmetric distance matrix where distance_matrix[i,j] is the cost from node i to node j.
alpha (float, Optional) – Pheromone importance factor. Default is 1.0.
beta (float, Optional) – Heuristic importance factor. Default is 2.0.
Q (float, Optional) – Pheromone deposit factor. Default is 1.0.
nAnts (int, Optional) – Number of ants. Default is 50.
maxiter (int, Optional) – Maximum iterations. Default is 200.
miniter (int, Optional) – Minimum iterations. Default is 0.
rho (float, Optional) – Pheromone evaporation rate. Default is 0.1.
minimize (bool, Optional) – If True, minimize tour length. Default is True.
seed (int | numpy.random.SeedSequence | numpy.random.Generator | None, Optional) – Random seed. Default is None.
maxage (int, Optional) – Stagnation threshold. Default is 10.
tau_init (float, Optional) – Initial pheromone value. Default is 0.1.

construct_solutions() → ndarray[source]#: Construct tours using random-proportional rule.

evaluate(tours: ndarray) → ndarray[source]#: Evaluate tour lengths.

reset() → CombinatorialAntColonyOptimization[source]#: Reset the solver and initialize pheromone matrix.

update_pheromones(solutions: ndarray, fitness: ndarray) → None[source]#: Evaporate pheromones and deposit based on tour quality.