A high-performance, unified framework for Multi-Objective Evolutionary Algorithms (MOEA) in Python.
Official repository: vamos-optimization/VAMOS. Issues, pull requests, releases, and development are coordinated there. See repository governance. Documentation: vamos-optimization.org.
VAMOS bridges the gap between simple research scripts and large-scale optimization studies. It provides a unified API for running state-of-the-art algorithms across diverse problems, backed by vectorized kernels with NumPy as the exact reference path and optional Numba acceleration for core kernels.
VAMOS 1.0.0 is the first official public release and compatibility baseline. VAMOS 1.2.0 brings many built-in algorithms, operators, problems and indicators back to their published definitions, which changes results of affected experiments, and adds 115 constrained benchmark problems, jMetal's constraint-handling techniques and the CCMO, C-TAEA, ToP and CMOEA-MS algorithms. It supports Python 3.13 and 3.14 and is the last minor release for Python 3.10. VAMOS 1.2.1 corrects C2-DTLZ2's default radius with two objectives and keeps persistent Optuna studies from mixing with earlier versions. VAMOS 1.3.0 requires Python 3.11 or newer, corrects operators whose fixes change results, rebuilds the tuning spaces and racing's statistics, and adds a wall-clock time limit, problem options by name and jMetal's reference fronts as an option. VAMOS 1.4.0 turns the tuning spaces into YAML grammars with defaults, which the tuning backends and Studio read, gives MOEA/D and SMS-EMOA the choices that Evolver offers, and removes VAMOS Assist and the LLM extras. VAMOS 1.5.0 corrects NSGA-III's parent selection, which changes its results, and the packaged MOEA/D weight files, and adds AGE-MOEA-II, the authors' reading of RVEA, one source of reference vectors for MOEA/D, NSGA-III and RVEA, the CTP and IDTLZ problems and DTLZ reference fronts with up to eight objectives. See the 1.5.0 release notes, the 1.4.0 release notes, the 1.3.0 release notes, the 1.2.1 release notes, the 1.2.0 release notes, including which results to rerun, and the earlier 1.1.0 release notes. Earlier version strings and Git tags were internal pre-public development markers, not prior public releases. See the stability policy and known limitations.
- Unified API: A clear, fluent interface
vamos.optimize()for all workflows. - Nine Algorithms: NSGA-II/III, MOEA/D, SMS-EMOA, SPEA2, IBEA, SMPSO, AGE-MOEA, RVEA. Known limitations lists those not yet validated independently against a reference implementation. VAMOS 1.2.0: CCMO (Tian et al., 2021), a coevolutionary algorithm for constrained problems whose fitness and selection are checked against jMetal's port and whose IGD on MW1, MW3 and C1-DTLZ1 matches the published values. VAMOS 1.2.0: C-TAEA (Li et al., 2019), a two-archive algorithm for constrained problems whose weight vectors, archive updates and mating selection are checked against jMetal's port and whose IGD+ on C1-DTLZ1, C3-DTLZ4 and MW3 and IGD on MW1, MW3 and LIR-CMOP7 match jMetal's runs and the published values. VAMOS 1.2.0: ToP (Liu and Wang, 2019), a two-phase framework for constrained problems whose sorting, crowding distance, differential evolution and switch between phases are checked against jMetal's port and whose IGD on MW1, MW3, MW11, LIR-CMOP2, LIR-CMOP7, LIR-CMOP10 and C1-DTLZ1 matches jMetal's runs. VAMOS 1.2.0: CMOEA-MS (Tian et al., 2022), an algorithm for constrained problems whose fitness has two stages, whose violation, density, fitness, selections, stage rule and differential evolution are checked against jMetal's port and whose IGD on MW1, MW3, MW7, LIR-CMOP2, LIR-CMOP7, LIR-CMOP8, LIR-CMOP10 and C1-DTLZ1 matches jMetal's runs.
- Unified Archiving: Consistent external archive configuration via
.external_archive(capacity=..., pruning=...), with bounded or unbounded archives and pruning policiescrowding,hv,mc_hv,knn,maxmin, andref_dirs. When an external archive is enabled, top-level results come from it by default unlessresult_mode="population"is requested. - Multi-Fidelity Tuning: Hyperband-style racing with warm-start checkpoints for sample-efficient algorithm configuration.
- Ready-to-use Tuning Backends:
racingandrandomwork out of the box; install the optionaltuningextra to enableoptuna,bohb_optuna,smac3, andbohbviavamos tune. - Performance Driven: Vectorized NumPy kernels with optional Numba JIT acceleration for core kernels.
- Interactive Analysis: Built-in dashboards with
explore_result_front(result)and publication-ready LaTeX tables. - Extensible: Standardized protocols for adding custom problems, operators, and algorithms.
Canonical customization guide: Extending VAMOS.
pip install vamos-optimizationVAMOS 1.3.0: VAMOS requires Python 3.11 or newer; VAMOS 1.2 is the last minor release for Python 3.10.
For development and extras (Windows PowerShell):
# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# Install core + essential extras
pip install "vamos-optimization[compute,analysis]"For development and extras (Linux / macOS):
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install core + essential extras
pip install "vamos-optimization[compute,analysis]"Optional model-based tuning backends (optuna, smac3, bohb):
pip install "vamos-optimization[tuning]"smac3 in VAMOS is provided by the PyPI package smac (SMAC3):
pip install "smac>=2.0"| Backend | Status | Role |
|---|---|---|
numpy |
Stable | Exact reference backend and deterministic default. |
numba |
Stable optional | Accelerates core numeric kernels such as variation, tournament selection, and MOEA/D neighborhood updates. |
moocore |
Stable optional | Adds accelerated quality-indicator support, especially hypervolume-style metrics. |
In VAMOS 1.5.0, use engine="auto" (CLI: --engine auto)
to prefer loadable Numba for all nine built-in algorithms, with a NumPy fallback.
Numba remains optional. Omitting engine still selects NumPy, preserving the 1.x
default; explicit engine="numba" fails if unavailable. First use can spend more
time compiling than a short optimization takes. See the
selection and replay policy
before comparing timings or moving runs between environments.
Operator shorthand accepts either numeric probabilities or the string literal "1/n" for per-variable mutation rates.
max_evaluationsis a strict evaluation budget. It must be at least the resolved population size, and the final generation is truncated when needed so budget-terminated runs report exactlyresult.data["evaluations"] == max_evaluations.- Public algorithm results expose
evaluationsas the evaluation-count metric. Internal checkpoints may still storen_eval. - VAMOS 1.2.0:
hypervolumeleaves out the points that the reference point does not dominate, as the two-objective helpercompute_hypervolumedoes.allow_ref_expandis accepted for compatibility only; it is ignored with aFutureWarning. - VAMOS 1.2.0: NSGA-III needs at least one individual per reference direction (
pop_sizeat least the number of directions). RVEA and MOEA/D need exactly one individual per reference or weight vector. Incompatible configurations fail early with an actionable error.
Solve the ZDT1 benchmark problem with NSGA-II in just a few lines:
from vamos import optimize
result = optimize(
"zdt1",
algorithm="nsgaii",
max_evaluations=10000,
pop_size=100,
engine="numpy",
seed=42,
)
front = result.front()
print(f"Non-dominated solutions: {len(front) if front is not None else 0}")Prefer a guided CLI? Run:
vamos quickstartThis wizard writes a reusable config and stores results under results/quickstart/.
Use vamos quickstart --template list to inspect domain templates.
New to Python? Start with the Minimal Python Track.
After a run, summarize results with:
vamos summarize --results results/quickstartInspect, fully verify, or exactly replay a canonical built-in run:
vamos results inspect RUN_DIR
vamos results verify RUN_DIR --require-level exact
vamos reproduce RUN_DIRFor a small study in one call, compare the seeds with a quality indicator. Every
run spends exactly max_evaluations, so the evaluation count cannot tell them
apart. The hypervolume below uses MooCore, installed by the compute extra:
import numpy as np
from moocore import hypervolume
from vamos import optimize
study = optimize("zdt1", algorithm="nsgaii", max_evaluations=4000, seed=[0, 1, 2])
reference_point = np.array([1.1, 1.1]) # fixed: ZDT1's Pareto-front nadir plus 10%
hv = np.array([hypervolume(run.front(), ref=reference_point) for run in study])
print(f"Hypervolume: mean {hv.mean():.4f}, std {hv.std(ddof=1):.4f}")
print("Best seed:", study[int(hv.argmax())].meta["seed"])Compare values computed against the same reference point only. For durable, resumable experiment matrices, use studies.
All functionality lives under one command. Run vamos help to list everything:
| Command | What it does |
|---|---|
vamos quickstart |
Guided wizard that writes a config |
vamos create-problem |
Scaffold a custom problem file |
vamos summarize |
Table/JSON summary of recent runs |
vamos results |
Inspect or verify one canonical run |
vamos reproduce |
Execute an exact same-environment built-in replay |
vamos check |
Verify installation and backends |
vamos bench |
Benchmark suite across algorithms |
vamos studio |
Launch interactive dashboard |
vamos tune |
Hyperparameter tuning |
vamos profile |
Performance profiling |
vamos zoo |
Problem zoo presets |
You can use the implemented tuning backends directly from vamos tune:
racing, random, optuna, bohb_optuna, smac3, bohb.
Check backend availability in your current environment:
vamos tune --list-backendsQuick verification with the built-in backend and tiny budgets:
vamos tune --instances zdt1,zdt2,zdt3,dtlz1,dtlz2,wfg1 --algorithm nsgaii --backend random --smoke --output-dir report/tuning_smokeNote: racing and random require no extra dependencies. The model-based backends (optuna, bohb_optuna, smac3, bohb) require the optional tuning extra: pip install "vamos-optimization[tuning]". The smac3 backend uses the smac package.
For paper-grade comparisons against other frameworks, install them yourself (VAMOS depends on none) and record a pinned environment or lockfile alongside reported results.
Recommended robust command (fallback + suite-stratified split):
vamos tune \
--instances zdt1,zdt2,zdt3,dtlz1,dtlz2,wfg1 \
--algorithm nsgaii \
--backend optuna \
--backend-fallback random \
--split-strategy suite_stratified \
--budget 5000 \
--tune-budget 200 \
--n-jobs -1Canonical tuning reference: Hyperparameter tuning.
New to hands-on learning? Open the interactive tutorial notebook:
jupyter notebook notebooks/0_basic/05_interactive_tutorial.ipynbUse make_problem() to turn any Python function into a VAMOS-compatible problem
-- no classes, no protocols, no NumPy vectorization required:
from vamos import make_problem, optimize
problem = make_problem(
lambda x: [x[0], (1 + x[1]) * (1 - x[0] ** 0.5)],
n_var=2,
n_obj=2,
bounds=[(0, 1), (0, 1)],
encoding="real",
)
result = optimize(problem, algorithm="nsgaii", max_evaluations=5000, seed=42)Your function receives a single solution x (array of length n_var) and returns
a list of n_obj objective values. When vectorized=False, VAMOS adapts that
scalar callable by evaluating one row at a time.
For actual batch performance, pass vectorized=True and write a function that
handles (N, n_var) batches directly.
Prefer a file template? The CLI wizard scaffolds a ready-to-run .py file:
vamos create-problem
# Prompts for: name, variables, objectives, bounds, style
# Generates a .py file with TODO markers -- fill in your math and run itSee Adding a problem for all approaches (function, class, or registry).
Preferred path: start with optimize(...). Use config objects only when you need fully specified, reproducible runs or plugin algorithms.
See Getting started for a short decision guide.
Advanced path (explicit config objects):
from vamos import optimize
from vamos.algorithms import NSGAIIConfig
from vamos.problems import ZDT1
problem = ZDT1(n_var=30)
algo = NSGAIIConfig.default(pop_size=100, n_var=problem.n_var)
result = optimize(
problem,
algorithm="nsgaii",
algorithm_config=algo,
max_evaluations=10000,
seed=42,
engine="numpy",
)Reminder: plain dict configs are intentionally not accepted (use GenericAlgorithmConfig for plugin algorithms).
For comparative evidence against pymoo on fixed seeded cases, install it (pip install -c constraints/ci.txt pymoo in a source checkout) and run:
python tools/benchmark_compare_pymoo.py --output artifacts/performance/pymoo_comparison.json --markdown artifacts/performance/pymoo_comparison.md- For reproducible results, set
seed; NumPy/Numba/MooCore backends share the same RNG-driven stochastic operators. - Troubleshooting guide: Troubleshooting.
- Algorithm-specific notes (reference directions, operator defaults): Algorithms & Backends.
- Release packaging smoke checklist: Release verification.
The repository's notebooks/ folder holds a comprehensive suite of Jupyter notebooks organized by tier:
- 0. Basic: Essential concepts and API basics.
notebooks/INDEX.ipynb-- Maintained catalog of the full learning surfacenotebooks/0_basic/01_quickstart.ipynb-- First optimization runnotebooks/0_basic/05_interactive_tutorial.ipynb-- Guided hands-on walkthroughnotebooks/0_basic/06_optuna_tuning_basics.ipynb-- Introductory Optuna tuning
- 1. Intermediate: Real-world problems, constraints, and deeper analysis.
notebooks/1_intermediate/10_discrete_problems.ipynb-- Binary, integer, and permutation encodingsnotebooks/1_intermediate/11_constrained_optimization.ipynb-- Constraint handlingnotebooks/1_intermediate/15_mcdm.ipynb-- Multi-criteria decision makingnotebooks/1_intermediate/16_interactive_explorer.ipynb-- Interactive Pareto front explorernotebooks/1_intermediate/19_algorithm_families_beyond_nsgaii.ipynb-- Current recipes for the other VAMOS MOEAs
- 2. Advanced: Custom extensions, tuning, and research benchmarks.
notebooks/2_advanced/21_programmatic_tuning.ipynb-- Canonical Optuna tuning workflownotebooks/2_advanced/23_backends_and_performance.ipynb-- Backend tradeoffs and benchmarkingnotebooks/2_advanced/30_paper_benchmarking.ipynb-- Inspect retained benchmark datanotebooks/2_advanced/27_operator_efficacy.ipynb-- Operator efficacy analysisnotebooks/2_advanced/32_ablation_planning.ipynb-- Ablation studiesnotebooks/2_advanced/33_optuna_tuning_advanced.ipynb-- Multi-fidelity and persistent Optuna workflowsnotebooks/2_advanced/34_extension_workflows.ipynb-- Custom problem and custom algorithm extension patterns
All tools are available as vamos <subcommand>. Run vamos help for the full list.
vamos profile: Analyze the performance overhead of your experiments.vamos profile --problem zdt1 --engines numpy,numba --budget 2000 --output report/profile.csv
vamos bench: Generate full reports comparing multiple algorithms, plus jMetalPy-compatible lab outputs (summary/lab/QualityIndicatorSummary.csv, Wilcoxon tables, boxplots). Boxplots requirematplotlib.vamos bench ZDT_small --algorithms nsgaii moead --output report/
vamos bench ZDT_small --algorithms nsgaii --output report/ --smoke
vamos tune: You can use the implemented tuners directly from CLI (racing,random,optuna,bohb_optuna,smac3,bohb).--tune-budgetcounts configuration evaluations;--budgetis per-run evaluations.vamos tune --problem zdt1 --algorithm nsgaii --budget 5000 --tune-budget 200 --n-seeds 5
-
Quick verification path:
vamos tune --instances zdt1,zdt2,zdt3,dtlz1,dtlz2,wfg1 --algorithm nsgaii --backend random --smoke --output-dir report/tuning_smoke
-
Recommended robust invocation (backend fallback + suite-stratified split):
vamos tune --instances zdt1,zdt2,zdt3,dtlz1,dtlz2,wfg1 --algorithm nsgaii --backend optuna --backend-fallback random --split-strategy suite_stratified --budget 5000 --tune-budget 200 --n-jobs -1
-
- Full tuning reference (canonical docs): Hyperparameter tuning.
vamos check: Verify your installation and backend availability.
The retained benchmark data guide documents the available scientific inputs and their provenance. Manuscript sources and author revision materials are maintained separately from this public repository.
If you use VAMOS in published work, cite the paper that describes it, published in Neurocomputing (doi:10.1016/j.neucom.2026.135657):
@article{uribe2026vamos,
title = {{VAMOS}: A framework for fast, configurable and accessible multiobjective optimization in python},
author = {Uribe, Nicol{\'a}s R. and Herr{\'a}n, Alberto and Nebro, Antonio J. and Del Ser, Javier and Colmenar, J. Manuel},
journal = {Neurocomputing},
pages = {135657},
year = {2026},
month = nov,
issn = {0925-2312},
doi = {10.1016/j.neucom.2026.135657},
url = {https://doi.org/10.1016/j.neucom.2026.135657}
}The maintained citation metadata lives in CITATION.cff.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Found a bug? Open an issue.
- Want to add an algorithm? Check Adding an algorithm in the docs.
- Using AI tools? Read AGENTS.md for our AI coding standards.
- Troubleshooting: Troubleshooting.
- Security issues: See SECURITY.md for private reporting.
- Contributors: See AUTHORS.md.
VAMOS is a research-oriented multi-objective optimization framework.
