Skip to content

Adding an algorithm

Add an algorithm when VAMOS needs a new search/update lifecycle. A new crossover, mutation, repair, or numerical primitive belongs at its narrower extension boundary.

Built-in workflow

  1. Study AlgorithmLike in src/vamos/engine/algorithm/registry.py and the closest built-in package. The run method accepts a problem, termination, seed, evaluation strategy, and optional live visualization, and returns the current result mapping.
  2. Implement the lifecycle under src/vamos/engine/algorithm/<name>/. Reuse shared builders/components without importing orchestration or CLI modules into engine.
  3. Add a typed config under src/vamos/engine/algorithm/config/ when the algorithm has a supported declarative configuration. Its serialized form must contain every choice needed by execution and exact replay.
  4. Add a builder with the registry signature (config_mapping, kernel) -> AlgorithmLike, then register the canonical lower-case name in _register_algorithms(...) and get_builtin_algorithm_names().
  5. Wire current construction in src/vamos/engine/algorithm/builders.py and related focused builder modules. Validate encoding, reference directions, population size, operator choices, and backend capability before entering the run loop. If the algorithm runs permutation problems, add it to PERMUTATION_COMPATIBLE_ALGORITHMS in src/vamos/engine/algorithm/variants.py, which the command line and the experiment runner check before a run.
  6. Export a stable config through vamos.algorithms only if public callers need it. Update CLI/spec parsing, artifact reconstruction, and public API snapshots whenever the public/resolved configuration surface changes.
  7. Add the name to every list of built-in algorithms; tests/architecture/test_builtin_component_lists.py keeps them equal:
  8. ENABLED_ALGORITHMS, ALGORITHM_MINIMUMS and _LABELS in src/vamos/engine/algorithm/catalog.py;
  9. _register_algorithms(...) and get_builtin_algorithm_names() in src/vamos/engine/algorithm/registry.py;
  10. _DEFAULT_FACTORIES in src/vamos/engine/algorithm/config/defaults.py, which vamos.optimize uses;
  11. the builders of build_algorithm in src/vamos/engine/algorithm/factory.py, which the command line uses;
  12. the fields of VariationConfigs in src/vamos/experiment/_execution_support.py, which the command line fills;
  13. BUILT_IN_ALGORITHMS in src/vamos/experiment/artifacts/component_support.py, which run specifications and exact replay read.

The implementation must honor exact evaluation budgets and explicit seed/RNG ownership. It must not switch backends silently. Reference-direction algorithms must define and validate how direction count constrains population size.

Parse termination with parse_termination(termination, name, pop_size) from src/vamos/engine/algorithm/components/termination.py, so the algorithm accepts max_evaluations, n_gen and hv like the built-ins, and report hv_reached in the result. Besides the ask and tell of InteractiveAlgorithmProtocol (src/vamos/engine/algorithm/components/protocol.py), give it initialize, should_terminate and result, as every built-in has: tell returns whether the HV target is reached, and result equals what run returns for the same seed.

Use VariationPipeline from src/vamos/engine/variation/ for shared operator orchestration. If the algorithm exposes an external result archive, use ExternalArchiveConfig from src/vamos/engine/archive/config.py; experiment specifications contain only archive.external, parsed by build_archive_cfg in src/vamos/engine/hooks/config_parse.py.

Package plugin workflow

External packages may expose a builder using the vamos.algorithms entry-point group. Discovery is lazy through vamos.algorithms.available_algorithms(), resolve_algorithm(...), or explicit plugin discovery. A plugin is not automatically eligible for exact replay.

[project.entry-points."vamos.algorithms"]
my_algorithm = "my_package.vamos_plugin:build_my_algorithm"

VAMOS 1.2.0: a plugin whose name is that of a built-in algorithm (nsgaii, moead, and the others, in any case) is ignored with a RuntimeWarning; VAMOS 1.1.0 ignored it silently. Setting the environment variable VAMOS_DISABLE_PLUGINS=1 stops the first use of the algorithm registry (optimize, available_algorithms(), resolve_algorithm(...)) from loading installed plugins, for example to rule a plugin out of a run; discover_algorithm_plugins() still loads them when called. The VAMOS 1.0 compatibility snapshot lists only the built-in algorithms, whatever plugins are installed.

Required tests

  • Registry name and builder resolution.
  • Tiny exact-budget smoke with deterministic seed.
  • Supported and rejected encodings.
  • Config serialization/defaults and CLI/spec parsing when exposed.
  • Backend parity/capability, warm start, hooks/observers, and reference directions where applicable.
  • Replay reconstruction matrix when adding a supported built-in replay component.

Run:

python -m pytest -q tests/engine/test_algorithm_registry.py tests/engine/test_algorithms_smoke.py
python -m pytest -q tests/engine/test_algorithm_encodings.py tests/engine/test_algorithm_problem_matrix.py tests/engine/test_warm_start_algorithms.py

Add the focused algorithm tests and apply the full tier from /AGENTS.md before completion.

path: src/vamos/engine/algorithm/registry.py
path: src/vamos/engine/algorithm/builders.py
path: src/vamos/engine/algorithm/config
path: src/vamos/engine/variation
path: src/vamos/engine/archive/config.py
path: src/vamos/engine/hooks/config_parse.py
path: src/vamos/experiment/artifacts/reconstruction.py
path: src/vamos/algorithms.py
path: tests/engine/test_algorithm_registry.py
path: tests/engine/test_algorithms_smoke.py
path: tests/engine/test_algorithm_encodings.py
path: tests/engine/test_algorithm_problem_matrix.py
path: tests/engine/test_warm_start_algorithms.py
symbol: vamos.algorithms:available_algorithms
symbol: vamos.algorithms:resolve_algorithm
symbol: vamos.engine.algorithm.registry:AlgorithmLike
symbol: vamos.engine.algorithm.registry:AlgorithmBuilder
symbol: vamos.engine.variation:VariationPipeline
symbol: vamos.engine.archive.config:ExternalArchiveConfig
symbol: vamos.engine.hooks.config_parse:build_archive_cfg
command: python -m pytest -q tests/engine/test_algorithm_registry.py tests/engine/test_algorithms_smoke.py
command: python -m pytest -q tests/engine/test_algorithm_encodings.py tests/engine/test_algorithm_problem_matrix.py tests/engine/test_warm_start_algorithms.py