ATLAS

All-in-one Toolkit for Learning and Applying metaheuristicS

ATLAS is a modular Python framework for metaheuristic optimization research, benchmarking, and comparison. It is designed for quick experiments, repeatable benchmark studies, and easy extension with new algorithms or test functions.

Highlights

• 18 built-in algorithms: 18 modern metaheuristic algorithms, all supporting both iteration-based and NFE-based stopping criteria.
• 155 benchmark problems: 11 classic functions and 144 CEC benchmark functions.
• CEC suite aliases: run a whole suite with names such as cec2017 or cec2022.
• Multi-dimensional CEC testing: use --dim all or explicit dimensions.
• Dual stopping criteria: fixed iterations or maximum number of function evaluations.
• Automatic result saving: CSV summaries, convergence data, YAML configs, and figures.
• Decorator-based extension: add algorithms and problems with registration decorators.

Installation

cd ATLAS

conda create -n atlas python=3.8
conda activate atlas

pip install -r requirements.txt
pip install -e .

opfunu is included in requirements.txt for CEC benchmark support.

Quick Start

Run PSO on Sphere:

python experiments/run_benchmark.py --algorithms pso --problems sphere --dim 30 --max_iter 500 --runs 30

Compare several algorithms on classic benchmarks:

python experiments/run_benchmark.py --algorithms pso ga de dp tjo --problems sphere rastrigin ackley --dim 30 --max_iter 500 --runs 30

Run a whole CEC suite:

python experiments/run_benchmark.py --algorithms de --problems cec2017 --dim 30 --max_iter 500 --runs 30

Run all supported dimensions for a CEC suite:

python experiments/run_benchmark.py --algorithms de --problems cec2017 --dim all --max_iter 500 --runs 30

Use maximum function evaluations instead of iterations:

python experiments/run_benchmark.py --algorithms de_nfe dp_nfe tjo_nfe --problems cec2022 --dim 10 --max_nfe 10000 --runs 30

Comprehensive CLI Example

This command shows all major runtime parameters in one place:

python experiments/run_benchmark.py ^
  --algorithms pso ga de dp tjo lgc ppo lea psa woa sa aco ^
  --problems sphere rastrigin ackley cec2017_f1 cec2022_f1 ^
  --dim 10 30 50 ^
  --max_iter 1000 ^
  --stopping_criterion iterations ^
  --max_nfe 10000 ^
  --runs 30 ^
  --seed 42 ^
  --pop_size 50 ^
  --plots convergence boxplot heatmap ^
  --save_results ^
  --verbose ^
  --base_dir results

PowerShell and CMD use ^ for line continuation. On Linux/macOS, replace ^ with \.

To disable disk output:

python experiments/run_benchmark.py --algorithms pso --problems sphere --dim 30 --max_iter 100 --runs 5 --no_save_results

CLI Reference

Argument	Default	Description
--algorithms	pso	Algorithm names, e.g. pso ga de_nfe tjo_nfe.
--problems	sphere	Problem names or CEC suite aliases, e.g. sphere cec2017.
--dim	30	One or more dimensions, or all for all supported CEC dimensions.
--max_iter	500	Maximum iterations for iteration-based algorithms.
--stopping_criterion	iterations	Metadata flag: iterations or nfe. Algorithm name still chooses the variant.
--max_nfe	10000	Maximum function evaluations for _nfe algorithms.
--runs	30	Number of independent runs.
--seed	42	Base random seed. Run i uses seed + i.
--pop_size	None	Override algorithm population size.
--plots	convergence boxplot heatmap	Figure types to generate.
--save_results	enabled	Save CSV, YAML, and figures.
--no_save_results	disabled	Disable all disk output.
--verbose	disabled	Print per-iteration progress.
--base_dir	results	Output directory.

Algorithms

Each algorithm has two variants:

• Iteration-based: algorithm_name
• NFE-based: algorithm_name_nfe

Algorithm	Iteration name	NFE name	Main parameters
Particle Swarm Optimization	pso	pso_nfe	w, c1, c2
Genetic Algorithm	ga	ga_nfe	crossover_prob, mutation_prob, tournament_size
Differential Evolution	de	de_nfe	F, CR, strategy
Delta Plus	dp	dp_nfe	delta_weight, peer_weight, noise_weight
Traffic Jam Optimizer	tjo	tjo_nfe	a, c
Logistic-Gauss Circle Optimizer	lgc	lgc_nfe	u_max
Philoponella Prominens Optimizer	ppo	ppo_nfe	population size
Love Evolution Algorithm	lea	lea_nfe	population size
PID-based Search Algorithm	psa	psa_nfe	kp, ki, kd
Whale Optimization Algorithm	woa	woa_nfe	b
Simulated Annealing	sa	sa_nfe	T_init, T_min, alpha, step_size
Ant Colony Optimization, continuous	aco	aco_nfe	n_ants, q, xi

List algorithms from Python:

python -c "import atlas; print(atlas.list_algorithms())"

Benchmark Problems

Classic Functions

Group	Functions
Unimodal	sphere, rosenbrock, schwefel222, quartic
Multimodal	rastrigin, ackley, griewank, levy, schwefel, michalewicz
Engineering	pressure_vessel

CEC Suites

Suite names expand automatically into all functions in the suite.

Suite alias	Registered functions	Supported dimensions
cec2005	cec2005_f1 ... cec2005_f25	Common set: 10, 30, 50
cec2013	cec2013_f1 ... cec2013_f28	2, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100
cec2014	cec2014_f1 ... cec2014_f30	10, 20, 30, 50, 100
cec2017	cec2017_f1 ... cec2017_f29	2, 10, 20, 30, 50, 100
cec2019	cec2019_f1 ... cec2019_f10	9, 10, 16, 18 depending on function
cec2020	cec2020_f1 ... cec2020_f10	2, 5, 10, 15, 20, 30, 50, 100
cec2022	cec2022_f1 ... cec2022_f12	2, 10, 20

Examples:

python experiments/run_benchmark.py --algorithms tjo --problems cec2017 --dim 10 30 50 100 --runs 30
python experiments/run_benchmark.py --algorithms psa_nfe --problems cec2022 --dim all --max_nfe 20000 --runs 30

Python API

from experiments.run_benchmark import run_benchmark

results = run_benchmark(
    algorithms=["pso", "de", "tjo", "psa_nfe"],
    problems=["sphere", "cec2017_f1"],
    dims=[30],
    max_iter=500,
    max_nfe=10000,
    runs=30,
    seed=42,
    pop_size=50,
    plots=["convergence", "boxplot", "heatmap"],
    save_results=True,
    base_dir="results",
)

Use dims=[-1] to request all supported CEC dimensions from Python.

Result Layout

By default, results are saved under results/.

results/
  problem_name/
    timestamp_algorithm/
      config.yaml
      raw_results.csv
      summary.csv
      convergence.csv
      figures/
        convergence_problem_name.png
        boxplot_problem_name.png

For multi-algorithm experiments, comparison figures and heatmaps are also saved.

File	Contents
config.yaml	Experiment configuration.
raw_results.csv	One row per run: algorithm, problem, seed, best fitness, iterations, NFE, solution.
summary.csv	Mean, std, best, worst, median, and mean NFE.
convergence.csv	Best-so-far curve for each run.
figures/	Convergence, boxplot, and heatmap images.

Project Structure

ATLAS/
  atlas/
    algorithms/
      iteration/          # Iteration-based algorithms
      nfe/                # Function-evaluation-based algorithms
    core/                 # Base classes, Result, Experiment
    problems/
      benchmark/          # Classic benchmark functions
      cec/                # CEC 2005, 2013, 2014, 2017, 2019, 2020, 2022
      custom/             # Engineering/custom problems
    utils/                # Registry, saving, logging, problem groups
    visualization/        # Convergence, boxplot, heatmap, landscape plots
  experiments/
    run_benchmark.py
    compare_algorithms.py
    run_custom.py
  tests/

Add a New Algorithm

1. Add the algorithm file under atlas/algorithms/iteration/my_algo.py. Since ATLAS 0.2, only ONE file in iteration/ is needed — the BaseAlgorithm class handles both stopping modes automatically.
2. Register with @register_algorithm("my_algo", aliases=["my_algo_nfe"]) to preserve backward compatibility.
3. Import the classes in:
   • atlas/algorithms/iteration/__init__.py
   • atlas/algorithms/__init__.py
4. Add tests in tests/test_algorithms_all.py.

NFE implementations must call self._evaluate(x) instead of self.problem.evaluate_with_penalty(x) so function evaluations are counted.

Testing

python -m pytest tests -q

Run a quick smoke test:

python experiments/run_benchmark.py --algorithms pso tjo psa_nfe --problems sphere --dim 10 --max_iter 50 --max_nfe 500 --runs 3 --no_save_results

Notes

• All objectives are minimized.
• Boundary handling is implemented in BaseProblem with clip, reflect, or penalty.
• CEC functions are provided by opfunu; unsupported dimensions raise clear errors.
• Some CEC functions can overflow internally. ATLAS converts non-finite CEC values to a large penalty value.

License

This project is intended for research and educational use. Check the licenses of third-party dependencies and any algorithm source code before redistribution.