Examples

VAMOS keeps executable learning material in examples/ and notebooks/, while the documentation explains the supported workflow around that code. This separation avoids maintaining several slightly different copies of the same example.

Three executable journeys

The three homepage journeys each have one deliberately small script. They use only public VAMOS facades, explicit evaluation budgets, and explicit random seeds. The documentation smoke suite executes these scripts, so they are checked as runnable learning paths rather than illustrative pseudocode.

Run the commands from the repository root after installing VAMOS.

Try VAMOS

python examples/journeys/try_vamos.py

This runs NSGA-II on ZDT1 with the NumPy reference backend and prints the shapes of the objective and decision matrices together with the evaluation count. It is the smallest end-to-end optimization path.

View the executable source · Read the Quickstart

Solve my problem

python examples/journeys/solve_my_problem.py

This maps two domain variables, two objective scores, bounds, and one inequality requirement into make_problem(...), then optimizes the resulting teaching surrogate through the same optimize(...) facade used for built-in benchmarks. It also extracts the matching decision rows for the non-dominated subset.

View the executable source · Read Solve your own problem

Run a reproducible study

python examples/journeys/reproducible_study.py --output results/journeys/study

This builds a bounded 2 problems × 2 algorithms × 2 seeds matrix, inspects the planned task count and evaluation budget before execution, publishes the exact reviewed plan, runs it, and prints the canonical run identity and manifest path for every summary row. The tiny budget and two-seed schedule are for teaching the workflow, not for making comparative performance claims.

Use a new output directory: durable studies are not silently overwritten.

View the executable source · Read Run a reproducible study

Choose by task

Goal	Start here	Repository material
Run a first optimization	Quickstart	examples/journeys/try_vamos.py and examples/basics/quickstart.py
Compare built-in algorithms	Algorithms & Backends	examples/basics/algorithm_showcase.py
Define your own objectives	Solve your own problem	examples/journeys/solve_my_problem.py and examples/problems/
Work with constraints	Constraints	notebooks/1_intermediate/11_constrained_optimization.ipynb
Persist and inspect runs	Run artifacts & replay	canonical run-artifact examples referenced by that guide
Plan and trace a persistent experiment matrix	Run a reproducible study	examples/journeys/reproducible_study.py
Tune an algorithm configuration	Hyperparameter tuning	vamos tune CLI workflow and advanced tuning notebooks
Optimize model hyperparameters as decision variables	Hyperparameter tuning	examples/tuning/hyperparam_tuning.py
Use distributed evaluation	Scaling with Dask	examples/distributed/
Build a plugin	Plugin Guide	examples/plugins/

Notebooks

The notebook suite is organized by learning level:

• notebooks/0_basic/ — first runs, API comparisons, and guided learning.
• notebooks/1_intermediate/ — discrete problems, constraints, MCDM, and interactive analysis.
• notebooks/2_advanced/ — tuning, performance, extension workflows, ablations, and publication-oriented benchmarking.

notebooks/INDEX.ipynb is the maintained notebook catalog in a repository checkout. The CI smoke suite executes selected notebooks; a notebook being present in the repository is not, by itself, a claim that every cell is part of the stable public API.

Cookbook

Use the Cookbook for short task-oriented recipes. When a recipe establishes supported behavior, its public imports should come from the curated facades (vamos, vamos.algorithms, vamos.problems, or vamos.ux.api) rather than implementation modules.

Reproducibility rule

Examples intended to support scientific results should make the evaluation budget and random seed explicit. For comparative studies, preserve the complete problem–algorithm–seed design and the run provenance behind every reported row. Paper-grade comparisons should also record the environment used for the run and define the statistical analysis separately; see Run artifacts & replay and the repository's pinned publication environment where applicable.