VAMOS Cookbook¶
Copy-paste recipes for the published VAMOS 1.5.0 package. Install the core package using Installation; recipes that need an extra say so explicitly. Budgets below are demonstrations, not evidence of convergence or comparative performance.
Stable identifies documented core APIs and CLI commands. Experimental identifies custom callbacks, analysis helpers, or optional integrations whose contracts may change. See Stability and versioning. Python recipes are self-contained except where an earlier recipe is explicitly required. Run file-writing examples in a fresh working folder; canonical run destinations must not already exist.
Recommended path (optimize)¶
Stable. Start with explicit algorithm, budget, population, backend, and seed:
from vamos import optimize
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
front = result.front()
assert front is not None
print(f"Returned: {len(result)} solutions; non-dominated: {len(front)}")
print(front[:3])
See Understanding results before interpreting the returned population as a Pareto-front approximation.
1. Custom problem definition¶
Stable. Use make_problem to wrap a batch objective. This formula is finite
at every point in the box, including x[0] = 0:
import numpy as np
from vamos import make_problem, optimize
def objectives(X):
f1 = X[:, 0]
f2 = (1.0 + X[:, 1]) * (1.0 - np.sqrt(X[:, 0]))
return np.column_stack([f1, f2])
problem = make_problem(
objectives, n_var=2, n_obj=2, bounds=[(0.0, 1.0), (0.0, 1.0)],
encoding="real", vectorized=True, name="two_objective_example",
)
assert np.isfinite(objectives(np.array([[0.0, 0.0], [1.0, 1.0]]))).all()
result = optimize(
problem, algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
print(result.front())
For a vectorized class implementation, see Solving your own problem.
2. Handling constraints¶
Stable. Bounds belong in bounds. Other constraints use g(x) <= 0 for
feasibility, with n_constraints matching the function output. Here the
requirement is x[0] + x[1] <= 1.5:
import numpy as np
from vamos import make_problem, optimize
problem = make_problem(
lambda x: [x[0], (1.0 + x[1]) * (1.0 - np.sqrt(x[0]))],
n_var=2, n_obj=2, bounds=[(0.0, 1.0), (0.0, 1.0)], encoding="real",
constraints=lambda x: [x[0] + x[1] - 1.5], n_constraints=1,
)
result = optimize(
problem, algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
G = result.data["G"]
feasible = np.all(G <= 0.0, axis=1)
print(f"Feasible returned solutions: {feasible.sum()} / {len(feasible)}")
result.front() filters objective-space dominance; it does not independently
check constraint feasibility. See Constraints
for handling modes and the algorithm matrix
for support. Internal symbolic-constraint modules are not part of this recipe's
public API.
3. Progress callback¶
Experimental custom interface. live_viz expects on_start,
on_generation, and on_end; it does not call __call__(algorithm).
A console observer needs no plotting extra:
from vamos import optimize
class Progress:
def __init__(self):
self.generations = []
self.finished = False
def on_start(self, ctx=None):
print("Run started")
def on_generation(self, generation, F=None, X=None, stats=None):
self.generations.append(generation)
if F is not None:
print(f"Generation {generation}: {len(F)} objective rows")
def on_end(self, final_F=None, final_stats=None):
self.finished = True
print("Run finished")
progress = Progress()
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7, live_viz=progress,
)
assert progress.generations and progress.finished
Observe the supplied arrays without modifying them. Custom callbacks are not covered by the built-in exact-replay contract.
VAMOS 1.2.0: every algorithm first calls on_generation with
generation 0, the evaluated initial population, and then once per generation.
NSGA-III, SMS-EMOA, IBEA, AGE-MOEA and RVEA used to start at generation 1, and
RVEA at 2. An exception raised by on_generation or by an optional
should_stop() stops the run with that exception, in every algorithm. The same
applies to NSGA-II's generation_callback, parent_selection_filter and
immigration skip_if. VAMOS 1.1.0 logged most of these failures at debug level
and carried on; MOEA/D, SPEA2 and SMPSO then called on_generation a second
time with the whole population. NSGA-II's live_callback_mode accepts
nd_only, population and population_archive.
VAMOS 1.3.0: every built-in algorithm sends the same payload.
F and X are the objective and decision vectors of the whole current
population, row by row (SPEA2's environmental archive, SMPSO's swarm), and
stats["evals"] counts the evaluations used so far. NSGA-II keeps sending its
first front with its default live_callback_mode="nd_only", and its population
with "population". MOEA/D, which replaces one subproblem at a time, reports one
generation per pop_size evaluations, as SMS-EMOA does, and a run resumed from
its checkpoint continues the numbering. In VAMOS 1.2.0 only
NSGA-II passed X, NSGA-II and SMPSO sent the first front while the others sent
the population, MOEA/D notified after every evaluation, and IBEA, NSGA-III,
SPEA2 and SMPSO left out stats in ask/tell runs.
VAMOS 1.3.0: only the default NoOpLiveVisualization itself is
skipped. A callback that subclasses it and overrides on_generation receives
every generation in every algorithm. In VAMOS 1.2.1 MOEA/D, SPEA2 and SMPSO
sent such a callback generation 0 only.
VAMOS 1.3.0: every algorithm that takes an external archive
has live_callback_mode, as NSGA-II does: population (their default) sends
the population, nd_only (NSGA-II's default) its first front, and
population_archive the population plus stats["archive"], the archive's
{"X": ..., "F": ...}. With an archive, the run returns that archive, so a
live view in this mode ends with what optimize returns. When the budget, the
HV target or a stop ends a run inside a generation, MOEA/D and SMS-EMOA send
the evaluations since their last notification as a final, shorter generation,
as the generational algorithms do with their last one, and every algorithm
notifies the generation that reaches the HV target before it stops. SMPSO without an
external archive sends its leaders, which it returns. Set it with the
builder, for example MOEADConfig.builder()...external_archive(capacity=None).live_callback_mode("population_archive").
Before, only NSGAIIConfig had the field.
4. Saving work and resuming a study¶
Stable: save completed results with save_result (recipe 13), and use the
durable study lifecycle to resume pending/interrupted tasks or
retry eligible failed tasks.
A saved run is a numerical result and its provenance, not a portable snapshot of an algorithm midway through a generation. Study resume does not promise to continue an interrupted algorithm at its last in-memory generation. Pickling algorithm objects is not a supported VAMOS checkpoint format. Internal checkpoint/state payloads have no public persistence guarantee.
VAMOS 1.2.0: within one process, optimize(..., checkpoint=...)
resumes NSGA-II and MOEA/D from result.data["checkpoint"]. With the same
configuration and seed, the resumed run continues exactly as the uninterrupted
one, and the external archive keeps its constraint values. A checkpoint that
cannot be restored, such as one with a different population size, missing
arrays or an unknown random state, raises ConfigurationError. VAMOS 1.1.0
logged a warning and started a fresh run instead. It also restored archives
without their constraint values, so those rows counted as feasible, and a
default MOEA/D run drifted from the uninterrupted one after resuming.
VAMOS 1.2.0: the resumed run's max_evaluations is its total
budget, the checkpoint's evaluations included: resuming a 1000-evaluation
checkpoint with max_evaluations=2000 adds 1000 evaluations. A budget below
the checkpoint's evaluations raises ConfigurationError; VAMOS 1.1.0 returned
the checkpoint's state, with more evaluations than max_evaluations, and no
warning.
5. Using Numba¶
Stable backend selection; optional dependency. Install the compute extra
from Installation, then request it explicitly:
from vamos import optimize
result = optimize(
"zdt1", algorithm="nsgaii", engine="numba",
max_evaluations=400, pop_size=40, seed=7,
)
print(result.F.shape)
The first use can include compilation time. Report warm-up separately in performance comparisons; cross-backend bitwise equality is not promised.
6. Comparing algorithms visually¶
Stable optimization; external plotting dependency. Install the analysis
extra. Keep the problem, evaluation budget, population, and seed explicit:
import matplotlib.pyplot as plt
from vamos import optimize
fig, ax = plt.subplots()
for algorithm, label in [("nsgaii", "NSGA-II"), ("moead", "MOEA/D")]:
result = optimize(
"zdt1", algorithm=algorithm, max_evaluations=4000,
pop_size=80, engine="numpy", seed=7,
)
front = result.front()
assert front is not None
ax.scatter(front[:, 0], front[:, 1], s=12, label=label)
ax.set(xlabel="f1 (minimize)", ylabel="f2 (minimize)")
ax.legend()
fig.savefig("algorithm-comparison.png", dpi=150, bbox_inches="tight")
plt.close(fig)
One seeded plot is illustrative, not an algorithm ranking. Use multiple seeds and problems for a comparative study; see Analysis.
7. Inspect resolved defaults¶
Stable. Keep a bounded budget while asking VAMOS to resolve the algorithm and population defaults:
from vamos import optimize
result = optimize("zdt1", max_evaluations=400, seed=7)
explanation = result.explain_defaults()
print(explanation["resolved_spec"])
print(explanation["default_sources"])
The resolved specification includes the problem, algorithm, operators, backend, termination, seed, and population. Default sources distinguish inferred values from explicit settings.
8. Discover and configure operators¶
Stable. Use operator identifiers through the public algorithm facade:
from vamos.algorithms import available_crossover_methods, available_mutation_methods
print(available_crossover_methods("real"))
print(available_mutation_methods("real"))
print(available_crossover_methods("permutation"))
Pass identifiers to a configuration builder as in recipe 10. Direct operator classes in internal engine modules are for contributors; see Adding an operator.
9. Multi-seed runs¶
Stable. A list of seeds returns an in-memory StudyResult:
from vamos import optimize
study = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=[0, 1, 2, 3],
)
for seed, result in zip([0, 1, 2, 3], study.runs):
print(seed, len(result.front()), result.data["evaluations"])
print("Mean evaluations:", study.mean("evaluations"))
This convenience does not create a durable study directory. For campaigns with saved plans, task history, and resume, use Studies.
10. Algorithm config objects¶
Stable. Make population and variation settings explicit:
from vamos import optimize
from vamos.algorithms import NSGAIIConfig
cfg = (
NSGAIIConfig.builder()
.pop_size(40)
.offspring_size(40)
.crossover("sbx", prob=1.0, eta=20.0)
.mutation("pm", prob="1/n", eta=20.0)
.selection("tournament", size=2)
.build()
)
result = optimize(
"zdt1", algorithm="nsgaii", algorithm_config=cfg,
max_evaluations=400, engine="numpy", seed=7,
)
print(result.F.shape)
11. Multiprocessing evaluation¶
Use the documented CLI options to select the evaluation strategy and worker count without importing an internal backend class. Parallel evaluation is for expensive independent objectives; process overhead can dominate this cheap demonstration:
vamos --problem zdt1 --algorithm nsgaii --engine numpy --population-size 40 --max-evaluations 400 --seed 7 --eval-strategy multiprocessing --n-workers 2 --output-root results/cookbook-multiprocessing
The single-run CLI is Stable; custom evaluators and distributed study ownership remain Experimental. This command distributes evaluations within one run, not concurrent mutation of a durable study.
From Python, pass eval_strategy="multiprocessing" to optimize. On Windows
and macOS the workers start by importing the main module, so put the call under
the main guard; without it, the run fails with BrokenProcessPool:
import vamos
if __name__ == "__main__":
result = vamos.optimize("zdt1", algorithm="nsgaii", max_evaluations=400, seed=7, eval_strategy="multiprocessing")
Such a run is recorded with replayability best_effort, so vamos reproduce
refuses it. To check it, run the same configuration serially with the same
seed; see parallel evaluation.
VAMOS 1.2.0: the multiprocessing backend starts its pool of
worker processes at the first evaluation and keeps it for the rest of the run.
optimize(..., eval_strategy="multiprocessing") and the CLI close the pool
when the run ends; a MultiprocessingEvalBackend that you create and pass is
yours to close with close() or a with block, and can serve several runs.
Without --n-workers (or n_workers), it uses the number of CPUs, at most 8.
n_workers must be a positive integer, and timeout, when given, bounds each
generation's evaluation in seconds: when it expires, the run fails with an
EvaluationError and the workers are stopped. In VAMOS 1.1.0 the backend
started and stopped a pool in every generation (about 1.5 s each on Windows,
against 5 ms for a serial ZDT1 generation), used every CPU, read
n_workers=0 as every CPU, and never applied timeout. Each evaluation still
pickles the population and the problem, so multiprocessing pays off only when
one evaluation takes much longer than that.
12. Hypervolume-based early stopping¶
Stable single-run CLI. For built-in ZDT1, stop at a fraction of its reference hypervolume, with a hard evaluation cap:
vamos --problem zdt1 --algorithm nsgaii --engine numpy --population-size 40 --max-evaluations 400 --seed 7 --hv-threshold 0.9 --output-root results/cookbook-hv-stop
The small budget can expire before the 0.9 target is reached. The target is a
reference-relative stopping criterion, not proof of convergence. See
CLI options for --hv-reference-front.
13. Save and load a run artifact¶
Stable. Save a complete canonical run and load its result without executing optimization again:
from vamos import load_result, load_run, optimize, save_result
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
stored = save_result(result, "results/cookbook-run")
loaded = load_result(stored.root)
run = load_run(stored.root)
print(loaded.F.shape, run.manifest.run_id)
The destination must not exist. See Run artifacts for the layout, integrity checks, resource limits, and non-destructive writes.
14. Select one solution¶
Stable. balanced_sum minimizes the sum after objective-wise normalization
within the returned non-dominated set:
from vamos import optimize
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
choice = result.best("balanced_sum")
print("Decision:", choice["X"])
print("Objectives:", choice["F"])
This choice reflects one preference rule, not a uniquely optimal trade-off. For constrained runs, check feasibility before applying a preference rule.
15. Verify and reproduce a stored run¶
Stable. Requires recipe 13 first. Loading reads stored data; verification checks integrity and compatibility; reproduction executes a new run using the stored resolved configuration and seed:
from vamos import load_run, reproduce, verify_run
run = load_run("results/cookbook-run", verify="all")
print(run.status, run.result.F.shape)
verification = verify_run("results/cookbook-run", require_level="exact")
print("Environment:", verification.environment.level)
replay = reproduce("results/cookbook-run", output="results/cookbook-replay")
assert replay.exact
print(replay.exact, replay.output_root)
Exact replay is available for supported built-ins in a matching material environment. Custom Python problems, plugins, and cross-backend replay are outside that contract. The output destination must not already exist.
16. Validate a config file¶
Stable. Save this as experiment.json in your working folder:
{
"version": "1",
"defaults": {
"problem": "zdt1",
"algorithm": "nsgaii",
"engine": "numpy",
"population_size": 40,
"max_evaluations": 400,
"seed": 7,
"output_root": "results/cookbook-config"
}
}
Validate first, then execute:
vamos --config experiment.json --validate-config
vamos --config experiment.json
See CLI and config files for overrides.
17. Export a DataFrame¶
Experimental analysis helper. Install the analysis extra. This exports
the returned result rows, which need not all be non-dominated:
from pathlib import Path
from vamos import optimize
from vamos.ux.api import result_to_dataframe
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
output = Path("exports/zdt1-results.csv")
output.parent.mkdir(parents=True, exist_ok=True)
df = result_to_dataframe(result)
df.to_csv(output, index=False)
print(output, df.shape)
18. Combine fronts from multiple runs¶
Stable result API. Form a pooled objective-space non-dominated set. The combined object below is an analysis container, not a new optimization run:
import numpy as np
from vamos import OptimizationResult, optimize
study = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=[0, 1, 2],
)
combined = np.vstack([result.F for result in study.runs])
front = OptimizationResult({"F": combined}).front()
assert front is not None
print(f"Pooled rows: {len(combined)}; non-dominated: {len(front)}")
Pool only the same objective definitions, units, and feasibility conventions. The pooled set is an empirical reference, not the known true Pareto front.
19. Compute hypervolume¶
Experimental third-party integration. The compute extra installs MooCore.
Use its public function instead of importing VAMOS's internal numerical helpers:
import numpy as np
from moocore import hypervolume
from vamos import optimize
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
front = result.front()
assert front is not None
reference_point = np.array([1.1, 11.0])
hv = float(hypervolume(front, ref=reference_point))
print("Hypervolume:", hv)
Both objectives are minimized. This fixed point is worse than the full ZDT1 objective bounds on its default box. Use the same reference point when comparing runs; changing it changes the indicator's meaning.
20. Reference-relative hypervolume for ZDT1¶
Experimental third-party integration; requires compute. Normalize using
a sampled analytical ZDT1 front and the same reference point in numerator and
denominator:
import numpy as np
from moocore import hypervolume
from vamos import optimize
result = optimize(
"zdt1", algorithm="nsgaii", max_evaluations=400,
pop_size=40, engine="numpy", seed=7,
)
front = result.front()
assert front is not None
f1 = np.linspace(0.0, 1.0, 1001)
reference_front = np.column_stack([f1, 1.0 - np.sqrt(f1)])
reference_point = np.array([1.1, 11.0])
hv = float(hypervolume(front, ref=reference_point))
reference_hv = float(hypervolume(reference_front, ref=reference_point))
print("Reference-relative HV:", hv / reference_hv)
This ratio depends on the reference point and the discretization of the analytical front. It is not a universal percentage of convergence. Record both when reporting results; values from different reference conventions are not directly comparable.