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_sizeismin(max(50, 10 * n_var), 200), at least 100 with three or more objectives. MOEA/D, NSGA-III and RVEA, and soalgorithm="auto"with three or more objectives, take the population from their reference directions instead: 100 with two objectives and 91 with three.max_evaluationsismin(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"
|
max_evaluations
|
int | None
|
Maximum function evaluations. Auto-determined when omitted. |
None
|
termination
|
TerminationSpec | None
|
Explicit termination pair: |
None
|
pop_size
|
int | None
|
Population size. Auto-determined when omitted. |
None
|
engine
|
EngineName | str | None
|
Backend engine (for example |
None
|
seed
|
int | None | list[int] | tuple[int, ...]
|
Random seed for one run, |
``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, |
None
|
algorithm_config
|
AlgorithmConfigProtocol | None
|
Explicit algorithm config object of |
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 ( |
None
|
Returns:
| Type | Description |
|---|---|
OptimizationResult | StudyResult
|
A single-run result for scalar |
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
|
Examples:
|