Skip to content

Optimization

Run an optimization through vamos.optimize. For a first execution rather than a signature lookup, start with the Quickstart.

Stable public API. The 1.x compatibility policy defines the supported surface; import from the public facade shown below.

from vamos import optimize

Quickstart · Results · Algorithm configuration

When pop_size or max_evaluations is omitted, optimize uses quick defaults derived from the problem size, and algorithm="auto" selects NSGA-II for two objectives and NSGA-III for more:

  • pop_size is min(max(50, 10 * n_var), 200), at least 100 with three or more objectives. MOEA/D, NSGA-III and RVEA, and so algorithm="auto" with three or more objectives, take the population from their reference directions instead: 100 with two objectives and 91 with three.
  • max_evaluations is min(max(1000, 100 * n_var), 50000), at least 5000 with three or more objectives.

For ZDT1 (30 variables) the quick defaults are 200 individuals and 3000 evaluations, 15 generations: enough for a first run, not for a converged front. Pass both for an experiment you report.

max_evaluations is a hard evaluation budget subject to documented algorithm cardinality requirements. An explicit integer seed controls the built-in stochastic path in the same materially relevant environment; cross-backend bitwise equality is not promised. The generated reference below defines the arguments and their defaults.

VAMOS 1.2.0: optimize raises ConfigurationError for arguments it would ignore or apply only in part: n_var, n_obj or problem_kwargs with a problem instance; problem_kwargs other than n_var and n_obj with a registered problem name (build the instance yourself to pass other arguments); max_evaluations together with a termination that does not stop at the same number of evaluations; the configuration class of another algorithm (algorithm="moead" with an NSGAIIConfig); GenericAlgorithmConfig with a built-in algorithm, whose generic keys, such as SMPSO's coefficient bounds, the typed configuration does not record and a replay cannot rebuild; and an empty seed sequence. termination no longer needs an algorithm_config. StudyResult.std takes ddof (default 0, the population standard deviation; pass ddof=1 for the sample standard deviation). VAMOS 1.1.0 ran these calls and recorded the requested values, raised a TypeError naming an internal function or a false "unexpected keyword argument 'termination'", or returned an empty StudyResult. Study plans likewise reject, with INVALID_STUDY_SPEC, algorithm_configs keys that name no algorithm of the study, compared with the exact case; an empty seeds list remains a valid zero-task plan.

VAMOS 1.3.0: with a registered problem name, problem_kwargs also takes the problem's options besides n_var and n_obj: the keyword-only parameters of its registry factory, such as capacity_ratio for bin_knapsack and complicated_pareto_set, level, bias and imbalance for zcat1–zcat20 (see Problems). They are recorded in resolved_spec.problem.config, so verify_run and reproduce rebuild the same problem, and a study's problem_kwargs passes them the same way. An option the factory does not declare, or a value other than None, a boolean, a string, an integer or a finite number that a float represents exactly (a Fraction that float would round is rejected), raises ConfigurationError. The problem is built with the values as the run records them: another integer type as int, another real type as float.

optimize(problem, *, algorithm='auto', max_evaluations=None, termination=None, pop_size=None, engine=None, seed=DEFAULT_SEED, verbose=False, n_var=None, n_obj=None, problem_kwargs=None, algorithm_config=None, eval_strategy=None, live_viz=None, checkpoint=None)

optimize(problem: str | ProblemProtocol, *, algorithm: AlgorithmName | str = 'auto', max_evaluations: int | None = None, termination: TerminationSpec | None = None, pop_size: int | None = None, engine: EngineName | str | None = None, seed: int | None = 42, verbose: bool = False, n_var: int | None = None, n_obj: int | None = None, problem_kwargs: Mapping[str, object] | None = None, algorithm_config: AlgorithmConfigProtocol | None = None, eval_strategy: EvaluationBackend | str | None = None, live_viz: LiveVisualization | None = None, checkpoint: CheckpointPayload | None = None) -> OptimizationResult
optimize(problem: str | ProblemProtocol, *, algorithm: AlgorithmName | str = 'auto', max_evaluations: int | None = None, termination: TerminationSpec | None = None, pop_size: int | None = None, engine: EngineName | str | None = None, seed: list[int] | tuple[int, ...], verbose: bool = False, n_var: int | None = None, n_obj: int | None = None, problem_kwargs: Mapping[str, object] | None = None, algorithm_config: AlgorithmConfigProtocol | None = None, eval_strategy: EvaluationBackend | str | None = None, live_viz: LiveVisualization | None = None, checkpoint: CheckpointPayload | None = None) -> StudyResult

Unified entry point for VAMOS optimization.

This function consolidates multiple APIs into a single powerful interface: - Accepts problem names (strings) or instances - Quick defaults for algorithm="auto" and an omitted pop_size or max_evaluations - Handles multi-run studies with seed=[0,1,2,...] - Prefer optimize(...) for all runs (explicit options are available).

The quick defaults suit a first run, not a converged front: 200 individuals and 3000 evaluations on ZDT1. The Optimization reference page gives their rules. Pass pop_size and max_evaluations for an experiment you report.

Parameters:

Name Type Description Default
problem str | ProblemProtocol

Problem name (for registered problems) or a problem instance.

required
algorithm AlgorithmName | str

Algorithm name or "auto" for automatic selection.

"auto"
max_evaluations int | None

Maximum function evaluations. Auto-determined when omitted.

None
termination TerminationSpec | None

Explicit termination pair: ("max_evaluations", n), ("n_gen", g) (g * pop_size evaluations, the initial population included), ("hv", {"target_value": t, "reference_point": r, "max_evaluations": n}) or ("max_time", seconds), a wall-clock limit that makes the run not reproducible. Every built-in algorithm accepts all four; counts must be positive integers. With max_evaluations too, it must be ("max_evaluations", max_evaluations).

None
pop_size int | None

Population size. Auto-determined when omitted.

None
engine EngineName | str | None

Backend engine (for example "numpy", "numba", "moocore", or "auto"). Omission keeps the NumPy reference default. "auto" prefers loadable Numba for built-in algorithms, otherwise NumPy.

None
seed int | None | list[int] | tuple[int, ...]

Random seed for one run, None to generate and record a seed before execution, or a sequence of explicit seeds for multi-run studies.

``42``
verbose bool

Enable VAMOS logging for the run.

``False``
n_var int | None

Override problem dimensions of a registered problem name or a problem class; a problem instance rejects them.

None
n_obj int | None

Override problem dimensions of a registered problem name or a problem class; a problem instance rejects them.

None
problem_kwargs Mapping[str, object] | None

Keyword arguments for a problem class; for a registered name, n_var, n_obj and the options its factory declares (capacity_ratio for "bin_knapsack"); an instance none.

None
algorithm_config AlgorithmConfigProtocol | None

Explicit algorithm config object of algorithm's configuration class; GenericAlgorithmConfig only for plugin algorithms.

None
eval_strategy EvaluationBackend | str | None

Evaluation backend name or instance; with "multiprocessing", call optimize under if name == "main": (Windows, macOS).

None
live_viz LiveVisualization | None

Live visualization callback.

None
checkpoint CheckpointPayload | None

Warm-start checkpoint (result.data["checkpoint"]) for NSGA-II and MOEA/D. Resumed with the same configuration and seed, both continue exactly as the uninterrupted run, archive constraints included. A checkpoint that cannot be restored raises ConfigurationError. max_evaluations is the resumed run's total budget, the checkpoint's evaluations included; a smaller budget raises ConfigurationError. Multi-seed runs do not accept checkpoints.

None

Returns:

Type Description
OptimizationResult | StudyResult

A single-run result for scalar seed input, or a sequence-compatible StudyResult when seed is a list/tuple.

Raises:

Type Description
ConfigurationError

If inputs are invalid or the algorithm/engine combination is not supported. A problem object is checked before any evaluation: integer n_var and n_obj, finite xl and xu (scalars or arrays of shape (n_var,)) with xl <= xu, a known encoding and a callable evaluate.

Examples:

Quick defaults

result = vamos.optimize("zdt1")

Specify algorithm

result = vamos.optimize("zdt1", algorithm="moead", max_evaluations=5000)

Multi-seed study

study = vamos.optimize("zdt1", seed=[0, 1, 2, 3, 4]) study.mean("evaluations")