Troubleshooting¶
These checks target the published VAMOS 1.4.0 package. See Installation for supported environments and extras, and Stability and versioning for the Stable, Experimental, and Internal labels.
Check the selected environment¶
Run these commands in the same terminal or notebook environment as your code:
python -c "import sys, vamos; print(sys.executable); print(vamos.__version__); print(vamos.__file__)"
python -m pip show vamos-optimization
The version should be 1.4.0 when following this release's examples. If the
package is missing, activate the intended virtual environment and follow
Installation. Use python -m pip so installation targets the
selected interpreter. Restart a notebook kernel after changing packages.
vamos check provides an additional Experimental diagnostic report.
Missing optional packages do not necessarily mean that the core NumPy backend
is unusable.
Missing optional dependencies¶
Install the relevant extra into the active environment; these commands work without a source checkout:
| Capability | Installation command | Status |
|---|---|---|
| Numba/MooCore kernels and Dask dependency | python -m pip install "vamos-optimization[compute]==1.4.0" |
Kernel selection is Stable; distributed evaluation is Experimental |
| Plots and pandas | python -m pip install "vamos-optimization[analysis]==1.4.0" |
Analysis helpers are Experimental |
| Notebooks | python -m pip install "vamos-optimization[analysis,examples]==1.4.0" |
Experimental |
| Local Studio | python -m pip install "vamos-optimization[studio]==1.4.0" |
Experimental |
| Selected domain examples | python -m pip install "vamos-optimization[examples]==1.4.0" |
Check the individual example |
| Optional tuning backends | python -m pip install "vamos-optimization[tuning]==1.4.0" |
Experimental |
VAMOS 1.2.0: the research extra and its third-party baselines
are removed, and notebooks need the examples extra besides analysis; see
optional extras.
An explicitly requested unavailable backend fails; it is not silently replaced
by NumPy. Choose engine="numpy" explicitly if you want a core-only run.
Unknown algorithm, engine, or incompatible encoding¶
- Consult the algorithm capability matrix for supported algorithms, encodings, constraints, and backends.
- Check exact
--algorithmand--enginespellings in the CLI reference. - Match the problem's encoding with the configured crossover and mutation. The problem catalog documents problem properties.
- Keep the budget at least as large as the initial population. For reference-direction algorithms, also respect their population/direction cardinality requirements.
Invalid values from a custom problem¶
Objective values must be finite throughout the declared bounds. Check boundary
points explicitly: a denominator must not become zero, and square roots and
logarithms must stay in their domains. A batched objective must return an array
of shape (batch_size, n_obj).
For constraints, g(x) <= 0 means feasible. Set n_constraints consistently
and return the corresponding number of constraint values. See
Solving your own problem.
A run or replay destination already exists¶
Canonical run writers do not overwrite or merge an existing result. Use a new
--output-root for a new CLI experiment, a new destination for save_result,
or a new --output for replay. Keep existing runs intact when comparing
settings. See Run artifacts.
Saving fails on Windows with a long path¶
Unless long paths are enabled, Windows rejects a path of 260 characters or
more (248 for a directory) and reports it as a missing path, with a
FileNotFoundError. Saving a run (save_result, reproduce,
vamos quickstart) writes through a staging directory next to the
destination, which adds about 60 characters to its path. Creating a study adds
about 130, because each task lives in tasks/<64-character task hash>/.
VAMOS 1.2.0: when the path is long enough to be the cause, the
error gives its length and the ways out listed below. A study reports them in
the actual field of its ATOMIC_PUBLICATION_FAILED error, which now also
carries the original message. In VAMOS 1.1.0 the error named only the missing
path, and a study reported only FileNotFoundError.
- Enable long paths: set
LongPathsEnabledto1underHKLM\SYSTEM\CurrentControlSet\Control\FileSystem(administrator rights needed). The "Disable path length limit" option of the Python installer sets it too. - Choose a shorter destination.
- Give the destination as an absolute path with the
\\?\prefix, for exampler"\\?\C:\long\path\to\run".
Numba writes its compiled-kernel cache next to the installed package, so in a
deeply nested environment its file names can reach the limit too. Set
NUMBA_CACHE_DIR to a short directory, such as C:\nbc, before starting
Python.
Replay is refused¶
First inspect and verify the source run:
vamos results inspect results/first-run/ZDT1/nsgaii/numpy/seed_7
vamos results verify results/first-run/ZDT1/nsgaii/numpy/seed_7 --require-level exact
These paths refer to the Minimal Python Track; replace
them with your actual run directory. Read the reported integrity, environment,
and reconstructability results. Exact replay requires supported built-ins
and matching material environment evidence. Loading arrays with load_result
is a separate data-only operation and does not require executing the problem.
Do not edit manifests to force compatibility.
Benchmark suite names¶
The benchmark command is Experimental. Use vamos bench --list to discover
available suites and match their names exactly. See the
CLI reference.