Algorithms and backends¶
Choose a built-in algorithm through its public identifier in optimize(). Start with the NSGA-II guide for a complete executable example and an explanation of the result. The configuration pages below document exact interfaces; they are not performance rankings.
Algorithm catalogue¶
| Algorithm | Identifier | Teaching guide | Configuration reference |
|---|---|---|---|
| NSGA-II | nsgaii |
Run and understand NSGA-II | NSGAIIConfig |
| NSGA-III | nsgaiii |
Reference directions and DTLZ2 | NSGAIIIConfig |
| MOEA/D | moead |
Decomposition and ZDT1 | MOEADConfig |
| SMS-EMOA | smsemoa |
Run and interpret SMSEMOA | SMSEMOAConfig |
| SPEA2 | spea2 |
Run and interpret SPEA2 | SPEA2Config |
| IBEA | ibea |
Run and interpret IBEA | IBEAConfig |
| SMPSO | smpso |
Run and interpret SMPSO | SMPSOConfig |
| AGE-MOEA | agemoea |
Run and interpret AGEMOEA | AGEMOEAConfig |
| RVEA | rvea |
Run and interpret RVEA | RVEAConfig |
| CCMO | ccmo |
Two populations for constrained problems | CCMOConfig |
| C-TAEA | ctaea |
Two archives for constrained problems | CTAEAConfig |
| ToP | top |
Two phases for constrained problems | ToPConfig |
| CMOEA-MS | cmoeams |
Two stages for constrained problems | CMOEAMSConfig |
To query the installed registry, use available_algorithms() from vamos.algorithms; see discovery. All nine built-in identifiers of VAMOS 1.1.0 and their public configuration classes are Stable under the 1.x stability policy. VAMOS 1.2.0: ccmo, ctaea, top, cmoeams, CCMOConfig, CTAEAConfig, ToPConfig and CMOEAMSConfig are new and not yet covered by the 1.0 compatibility baseline. Stable API status is a compatibility commitment, not evidence that every combination of algorithm, operator and problem has been validated.
Capability matrix¶
This table describes the VAMOS 1.4.0 package. Changes since 1.0.0 are listed below. “R / B / I / P / M” means real, binary, integer, permutation and mixed encodings. An encoding requires compatible variation operators and, for mixed problems, the problem's variable specification; a real-coded default configuration does not convert a discrete problem.
| Algorithm | Encodings | Constraint-aware survival in 1.4.0 | Archive | Backends | API status |
|---|---|---|---|---|---|
| NSGA-II | R / B / I / P / M | Feasibility-based | Optional external result archive | NumPy / Numba / MooCore | Stable |
| NSGA-III | R / B / I / P / M | Feasibility-first with reference-direction niching (details) | Optional external result archive | NumPy / Numba / MooCore | Stable |
| MOEA/D | R / B / I / P / M | Feasibility-based replacement | Optional external result archive | NumPy / Numba / MooCore | Stable |
| SMS-EMOA | R / B / I / P / M | Feasibility-based | Optional external result archive | NumPy / Numba / MooCore | Stable |
| SPEA2 | R / B / I / P / M | Feasibility-based | Internal environmental archive; optional external result archive | NumPy / Numba / MooCore | Stable |
| IBEA | R / B / I / P / M | Feasibility-based | Optional external result archive | NumPy / Numba / MooCore | Stable |
| SMPSO | R / M | Feasibility-based leaders/personal-best selection | Internal leaders archive; optional external result archive | NumPy / Numba / MooCore | Stable |
| AGE-MOEA | R / B / I / P / M | Feasibility-based when enabled | Optional external result archive | NumPy / Numba / MooCore | Stable |
| RVEA | R / B / I / P / M | Feasibility-based when enabled | Optional external result archive | NumPy / Numba / MooCore | Stable |
| CCMO | R / B / I / P / M (DE variation: R) | Violation-first SPEA2 selection in population 1; population 2 ignores constraints | Optional external result archive | NumPy / Numba / MooCore | New in 1.2.0 |
| C-TAEA | R / B / I / P / M (two-parent crossovers) | Convergence archive driven by feasibility; diversity archive ignores constraints | Optional external result archive | NumPy / Numba / MooCore | New in 1.2.0 |
| ToP | R (differential evolution) | Feasibility rule on the mean objective in phase 1; constrained-domination NSGA-II in phase 2 | Optional external result archive | NumPy / Numba / MooCore | New in 1.2.0 |
| CMOEA-MS | R / B / I / P / M (two-parent crossovers; DE variation: R) | SPEA2 fitness on [density, normalized violation] in stage A; violation first in stage B | Optional external result archive | NumPy / Numba / MooCore | New in 1.2.0 |
Evidence and scope. The encoding families are exercised by repository operator-combination tests and encoding integration tests. Historical real-coded, unconstrained ZDT1 smoke runs were checked for all nine algorithms on each of the three backends against the installed 1.0.0 package. That is not a validation of the full encoding × constraints × archive × backend Cartesian product, nor a convergence or speed benchmark. Custom operators and untested combinations require a representative check before a large study. SMPSO rejects standalone binary, integer and permutation encodings; its mixed path requires mixed-variable mutation.
VAMOS 1.2.0: every XConfig.default() takes an optional encoding, and optimize(problem, algorithm=...) passes the problem's encoding to it. Discrete and mixed problems then get the operators of the shared encoding table: uniform crossover and bit-flip mutation for binary, OX and swap for permutations, SBX (probability 0.9) and polynomial mutation for integers, and the mixed operators for mixed problems. In VAMOS 1.1.0 only NSGA-II and MOEA/D did this, so 22 of the 33 supported combinations of the nine algorithms with bin_knapsack, tsp6, int_alloc and mixed_design failed with an error about sbx or pm; integer runs of IBEA, AGE-MOEA and RVEA, which worked, now use the table's SBX(0.9, 20) instead of their real-coded crossover. Every default() also accepts pop_size=None (100, or the lattice size for MOEA/D, NSGA-III and RVEA), and builder().pop_size() rejects anything but a positive integer.
VAMOS 1.3.0: three crossovers no longer bias the search or
collapse its diversity. The integer SBX (sbx on integer variables, and
int_crossover="sbx" in mixed problems) rounds each child to the nearest
integer. jMetal and jMetalPy truncate it with int(), which pulls the children
towards zero: parents 3 and 4 got children with mean 3.25 instead of 3.5. The
integer arithmetic crossover (arithmetic, also blend) and the real part of
the mixed crossover, which is the default for mixed problems, draw a random
weight lam for each mated pair and give the complementary children
lam * p1 + (1 - lam) * p2 and (1 - lam) * p1 + lam * p2. In VAMOS 1.2.1
and earlier both children were the parents' mean, which halved the variance of those
variables at every mating; real_crossover="mean" still asks for the mean.
blx_alpha_beta defaults to alpha = beta = 0.5, jMetal's values. It extends
the parents' interval by alpha below the smaller value and by beta above the
larger one, not towards the better parent as in the published operator, so the
former defaults of 0.75 and 0.25 drove an unselected population towards the
lower bounds.
VAMOS 1.2.0: the default real-coded crossover of every algorithm that uses SBX is SBX with probability 0.9, as in Deb et al. (2002), jMetal and pymoo, in XConfig.default(), in the CLI and in build_algorithm. Each algorithm keeps its distribution index: 20, 30 for NSGA-III and RVEA, and 15 for AGE-MOEA. VAMOS 1.1.0 used probability 1.0 in NSGA-II, NSGA-III, SMS-EMOA, SPEA2, IBEA and RVEA, so their default runs follow a different trajectory now; .crossover("sbx", prob=1.0, eta=...) reproduces the earlier setting. MOEA/D (differential evolution by default) and SMPSO are unchanged.
Constraints use G <= 0, with positive residuals representing violation. Consult the constraint reference for residual construction; an accepted constraint_mode field alone does not establish constraint enforcement. NSGA-III now uses the same feasibility-first contract in both survival and parent selection.
Constraint handling in 1.1.0¶
VAMOS 1.1.0 includes the following constraint corrections.
constraint_modeaccepts only"feasibility"(the default) and"none". Every built-in algorithm treated any other value, including"penalty"and"epsilon", exactly like"feasibility"; such values are now rejected withValueErrorinstead of being accepted without effect.- NSGA-III applies feasibility-first survival: when more solutions are feasible than survive, reference-direction niching selects among the feasible ones; otherwise every feasible solution survives and the least violated infeasible ones fill the population. Its parent tournament ranks feasible solutions first as well.
- IBEA penalized infeasible solutions in the wrong direction, so its environmental selection removed feasible solutions before infeasible ones. It now removes infeasible solutions first, in decreasing order of violation.
- With
result_mode="non_dominated", every algorithm returns the non-dominated feasible solutions whenever the final population contains a feasible one, and the least violated solutions otherwise. NSGA-II, NSGA-III, MOEA/D, SMS-EMOA, IBEA and SPEA2 used to return non-dominated solutions regardless of feasibility; AGE-MOEA, RVEA and SMPSO already did this. - SPEA2 runs with
constraint_mode="none"on constrained problems; it used to fail after the first generation.
Runs of constrained problems with these algorithms therefore differ from 1.0.2 runs with the same seed. Unconstrained runs are unchanged.
SPEA2 environmental selection¶
VAMOS 1.2.0: SPEA2's environmental selection and mating follow Zitzler, Laumanns and Thiele (2001) and jMetal.
- When the non-dominated solutions exceed the archive, the truncation operator repeatedly removes the solution whose distances to the others, sorted in ascending order, are lexicographically smallest. VAMOS 1.1.0 compared only the distance to the k-th nearest neighbour and broke ties by row order, so it could remove an extreme solution of a crowded pair.
- When they fall short, the dominated solutions with the best fitness
F = R + 1 / (sigma_k + 2)fill the archive. VAMOS 1.1.0 added whole raw fitness levels and truncated the last one by distance. - The mating tournament compares the raw fitness and the k-th nearest-neighbour distance that each archive member had among the previous archive and the offspring, not values recomputed over the new archive.
- With
result_mode="non_dominated"and no external archive, the result keeps only the non-dominated members of the archive, feasible ones first. VAMOS 1.1.0 returned the whole archive, dominated solutions included.
k_neighbors defaults to 1, as in jMetal; the paper uses the square root of
the population plus archive size. The knn pruning of external archives uses
the same truncation operator.
With jMetal's settings (population and archive 100, SBX 0.9, 30 000 evaluations, 10 seeds), the hypervolume goes from 0.7259 to 0.7326 on DTLZ2 and from 0.6665 to 0.6832 on C2-DTLZ2, against 0.7354 and 0.6837 for jMetal 7.9's SPEA2; ZDT1 does not change significantly. The remaining DTLZ2 gap comes from jMetal's mating tournament, which compares by dominance alone and picks at random between non-dominated solutions, whereas VAMOS compares the paper's fitness. SPEA2 results from VAMOS 1.1.0 and earlier differ with the same seed.
IBEA indicator corrections in 1.1.0¶
- With
indicator="hypervolume", IBEA used the hypervolume-difference indicator with the opposite orientation. It removed the solutions with the largest exclusive hypervolume first and kept dominated ones. It now usesI_HDas defined by Zitzler and Künzli (2004) and as in jMetal, with the adaptive scaling of their IBEA: objectives are normalized over the population and the indicator is divided by its largest magnitude. Its final fronts match jMetal 7.9's IBEA on ZDT1, DTLZ2 and DTLZ1 within seed variation. Hypervolume-based IBEA results from VAMOS 1.0.2 and earlier are not valid; rerun them. - An exponential indicator contribution that exceeded the float64 range counted as zero, so a solution dominated by a wide margin looked like the best one. When a contribution would overflow, selection works in the log domain: each fitness is recomputed from the remaining solutions after every removal, and feasibility ranks still come first. Overflow therefore no longer changes the removal order; solutions whose fitness differs by less than floating-point resolution are ordered as in runs without overflow, and as in jMetal and jMetalPy. The epsilon indicator remains unscaled, as in jMetalPy, and runs without overflow are unchanged.
VAMOS 1.2.0: IBEA accepts the indicator values "eps",
"epsilon", "additive_epsilon" and "hypervolume", in any letter case, and
rejects any other value with ConfigurationError. VAMOS 1.1.0 ran every other
value with the epsilon indicator without warning, "hv" and "HV" included,
so runs configured with "hv" used the epsilon indicator.
AGE-MOEA survival score¶
VAMOS 1.2.0: AGE-MOEA follows its author's PlatEMO code in two places.
- The binary mating tournament compares rank, then the survival score: the diversity and proximity score on the first front and the inverse distance to the ideal point on later fronts. VAMOS 1.1.0 used NSGA-II crowding distance instead.
- The front that is truncated to fill the population is scored by proximity to the ideal point and cut by that score. VAMOS 1.1.0, like pymoo 0.6.2, left it unscored and kept its last rows, which are usually offspring.
The rest follows pymoo, with PlatEMO's distance normalization. Unlike PlatEMO, later fronts are measured from the ideal point in the same translated and normalized coordinates as the first front, so the selection does not depend on where the objectives' origin lies; objectives are not rounded to 6 decimals before non-dominated sorting, the geometry exponent is capped at 20 and the default variation is SBX (probability 0.9, eta 15) with polynomial mutation.
Over 30 seeds with population 100, the hypervolume goes from 0.8496 to 0.8545 on ZDT1, from 0.7426 to 0.7443 on DTLZ2 and from 0.1880 to 0.1892 on DTLZ1, within seed variation of jMetal 7.9's AGE-MOEA (0.8545, 0.7446 and 0.1890). AGE-MOEA results from VAMOS 1.1.0 and earlier differ with the same seed.
AGE-MOEA-II¶
Development after 1.4.0: AGEMOEAConfig.builder().variant("agemoea_ii") runs
AGE-MOEA-II (Panichella, GECCO 2022). Its survival differs from AGE-MOEA's in two
steps of the first-front score, which are those that jMetal's
AGEMOEA2EnvironmentalSelection, written by the author, overrides:
- the exponent
pof the front is the one whose Minkowski norm of the non-extreme point nearest to the ideal point is 1, found by Newton-Raphson fromp = 1(precision 0.001, at most 100 steps), instead of a closed form from the point nearest to the diagonal; - the diversity uses geodesic distances on the estimated
L_pmanifold: both points and their midpoint are projected on it, and the distance is the length of the path through the projected midpoint.
Everything else, the extreme points, the normalization, the scores of later
fronts and the mating tournament, is AGE-MOEA's above, with that p. The
exponents and distances agree with jMetal's on every case of
tests/engine/data/agemoea2_jmetal_values.json, and so do the survival scores
on the fronts where AGE-MOEA's shared steps agree with jMetal's. They do not
agree where AGE-MOEA's extreme points or its tie-breaking (on exactly linear
fronts) depart from jMetal, as described above for AGE-MOEA. As in AGE-MOEA,
p is capped at 20, which pymoo's AGE-MOEA-II also does and jMetal does not; a
point at the ideal point is not projected. pymoo takes the straight Euclidean
distance when 0.95 < p < 1.05; VAMOS, like jMetal, always goes through the
midpoint, and both coincide when p = 1.
The tuning spaces of AGE-MOEA choose it with replacement: agemoea_ii, the
name of Evolver's parameter (agemoeaII in Evolver).
Where the variants depart from their references¶
These are declared VAMOS choices, not defects; report them when comparing with published results or with another framework.
- NSGA-III parents are chosen by binary tournament on non-dominated rank and crowding distance (feasibility first under constraints), as in NSGA-II and in jMetal's NSGA-III example. Deb and Jain (2014) choose parents at random. See NSGA-III.
- NSGA-III nadir estimate: when an intercept of the extreme-point hyperplane lies beyond the worst point found so far, VAMOS uses the worst point of the first front for every objective, as pymoo up to 0.4 did; pymoo 0.6 replaces only those objectives by the worst point.
- SMS-EMOA contributions are exact, with no Monte Carlo or HypE approximation, so each step's cost grows exponentially with the number of objectives. See SMS-EMOA.
- MOEA/D defaults to differential evolution with PBI aggregation;
aggregation("tchebycheff")reproduces jMetal's MOEA/D-DE. VAMOS 1.3.0:MOEADConfig.default(variant="de")gives MOEA/D-DE andvariant="sbx"jMetal's MOEA/D with SBX and PBI; VAMOS 2.0 will make"de"the default. See MOEA/D.
VAMOS 1.3.0: three real-coded mutations scale their steps by the range of each variable.
non_uniformis Michalewicz's mutation, as in jMetal: a mutated variable moves towards one of its bounds, chosen at random, byy * (1 - r ** ((1 - t / T) ** b)), whereyis the distance to that bound. The operator does not know the run's progresst / T, so it uses 0: the step isy * (1 - r), andperturbation(b) has no effect. The tuning spaces no longer offernonuniform_perturbation. In VAMOS 1.2.0 the step was(1 - r ** b)times the whole range, with a random sign, so 25% to 41% of the mutated genes left their bounds and the repair moved them onto the bound.gaussianandcauchyreadsigmaandgammaas fractions of each variable's range, as pymoo does, andgaussiandefaults tosigma = 0.1. In VAMOS 1.2.0 both were in the variables' units, so the same value was negligible on a range of 1000 and large on a range of 0.01, andgaussianhad no default. On variables with a range of 1, such as those of DTLZ and most of ZDT, they behave as before.
Choose an initial experiment¶
| Need | Starting point | Check before increasing the budget |
|---|---|---|
| General population-based Pareto search | NSGA-II tutorial | Encoding, operators and feasibility convention |
| Scalar subproblems that cooperate through neighbours | MOEA/D tutorial | Objective scales, aggregation and exact weight/population count |
| Reference-direction coverage for several objectives | NSGA-III tutorial | Exact direction/population count; unconstrained problem |
| Hypervolume-based environmental selection | SMS-EMOA | Objective count, reference point and indicator cost |
| Strength/density-based archive search | SPEA2 | Internal archive size versus separate result archive |
| Indicator-based fitness | IBEA | Indicator choice, scaling and its parameters |
| Particle-swarm search | SMPSO | Real/mixed representation and leaders archive; release notes below |
| Alternative many-objective diversity mechanisms | AGE-MOEA or RVEA | Geometry/reference vectors and explicit constraint mode |
| Constrained problems whose feasible regions are hard to reach | CCMO | Budget of at least 2 * pop_size; GA or DE variation |
| Constrained problems where infeasible regions guide the search to the feasible front | C-TAEA | Population set by its weight vectors (91 for 100 and three objectives); budget of at least that size |
| Constrained problems whose feasible regions are small or far from the unconstrained front | ToP | Real variables; budget of at least pop_size; phase 1 can take up to 90% of the budget |
| Constrained problems where the objectives and the constraints must be balanced | CMOEA-MS | Budget of at least pop_size; GA or DE variation; feasible_ratio_threshold (lambda) switches the stage |
These are starting points for a study, not objective-count cut-offs or performance rankings. Compare algorithms using explicit budgets, repeated seeds and the same problem formulation.
Results and cardinality¶
Use an explicit result mode when output cardinality matters. population returns the final population (or swarm); non_dominated selects a non-dominated result source. The latter need not have pop_size rows. NSGA-III's configuration builder defaults to population; the other builders default to non_dominated. The encoding-aware automatic setup and explicit builders need not select the same result mode, so report the resolved configuration.
VAMOS 1.2.0: without an explicit algorithm_config, optimize, studies and vamos tune run SMPSO in non_dominated mode, so its result is the leaders archive, as SMPSOConfig.default() already chose. VAMOS 1.1.0 and earlier forced population there and returned the final swarm, which is not elitist: on ZDT1 with 10 000 evaluations, 91 of its 200 rows were dominated.
For algorithms with a supported external result archive, enabling it makes that archive the default result source unless population is requested explicitly. Inspect result.data["population"] and result.data["archive"] separately. An internal SPEA2 environmental archive or SMPSO leaders archive influences search; an external result archive serves a different purpose. See stopping and archives.
VAMOS 1.3.0: an unbounded external archive returns every non-dominated solution the run found, thousands on long runs, whereas jMetal's BestSolutionsArchive and Evolver return a subset as large as the population. external_archive(capacity=None, final_selection=..., final_size=...) makes the result report such a subset when the run ends:
from vamos.algorithms import NSGAIIConfig
config = (
NSGAIIConfig.builder()
.pop_size(100)
.crossover("sbx", prob=0.9, eta=20.0)
.mutation("pm", prob="1/n", eta=20.0)
.selection("tournament", size=2)
.external_archive(capacity=None, final_selection="crowding", final_size=100)
.build()
)
final_selection is "none" (the default: the whole archive, as before), "farthest", "crowding", "hv_greedy" or "kmeans", the selections of top_k(method=...); kmeans is seeded with the archive's rng_seed, which without a value derives from the run seed (see Reproducibility). final_size defaults to the population size. result.X and result.F hold the subset, the archive stays whole in result.data["archive"] (archive_X/archive_F for NSGA-III and IBEA, external_archive for SPEA2), and result.data["archive_subset"] records the selection, the size and the indices of the selected rows in the archive. A saved run stores the subset as its result and the whole archive under archive/ (SPEA2: external_archive/, since its archive/ is the environmental archive), and its resolved specification records final_selection and final_size, so a replay selects the same subset. The subset also applies to a bounded archive larger than final_size, not with result_mode="population", and not to hypervolume termination or live callbacks, which see the whole archive during the run.
Development after 1.4.0: an unbounded external archive no longer filters itself once per generation. Once it holds feasible, finite rows, it keeps the rows each generation offers and merges them, with moocore's non-dominated filter when moocore is installed, only when something reads the archive (the result, a live callback in population_archive mode, hypervolume termination, SMPSO's leaders) or when the kept rows outnumber twice the archive. One merge gives the same rows, in the same order, as one update per generation, so results do not change; a run that reads its archive only at the end filters it once. Over the 200 000 evaluations of an NSGA-II run, the archive took 0.1 s instead of 5.0 s on CRE21 (7 000 rows), 0.16 s instead of 11.5 s on RCM08 and 0.28 s instead of 85 s on RCM25 (112 000 rows). Before the first feasible row, and after rows with non-finite feasible objectives, the archive is updated at once, as before.
NSGA-III and RVEA require a population compatible with the configured reference directions. MOEA/D requires one weight vector per population member. For a simplex lattice with p divisions and m objectives, use comb(p + m - 1, m - 1); for three objectives and 12 divisions, that is 91. Explicit incompatible cardinalities fail; they are not warning-only cases. Follow the tutorials before changing objective count or population size.
VAMOS 1.2.0: NSGA-III needs at least one individual per reference direction (N >= H) instead of exactly one, as Deb and Jain, jMetal and pymoo do; 100 individuals with 12 divisions and three objectives run with 91 directions, and fewer than 91 fail. Without divisions, NSGA-III uses the complete Das-Dennis lattice with the most directions that fit in pop_size; VAMOS 1.1.0 and earlier cut the next larger lattice to pop_size directions and lost the extreme direction of the first objective. With two objectives, NSGA-III and RVEA default to pop_size - 1 divisions, or 99 without pop_size, instead of 6. RVEA and MOEA/D still need exactly one individual per vector; RVEA then keeps one survivor per occupied vector, so its population can end smaller than pop_size (see RVEA).
VAMOS 1.2.0: optimize and study planning check each built-in algorithm's smallest population and number of objectives before the run and raise ConfigurationError (or, when planning, UnresolvedStudyTaskError with INVALID_POPULATION_SIZE or UNSUPPORTED_OBJECTIVE_COUNT) that names the minimum. NSGA-II, IBEA, AGE-MOEA, MOEA/D, NSGA-III and RVEA need pop_size >= 2 (for NSGA-II and IBEA the selection decides: a tournament needs as many individuals as its size, 2 by default, and random, Boltzmann, ranking and SUS selection one); SMS-EMOA, AGE-MOEA, NSGA-III and RVEA need at least two objectives. The table is vamos.engine.algorithm.catalog.ALGORITHM_MINIMUMS. VAMOS 1.1.0 failed later with an error from the parent tournament or from moocore, and AGE-MOEA ran a single-objective problem.
VAMOS 1.2.0: with pop_size, NSGAIIIConfig.default() uses the complete lattice with the most directions that fit in it, for any number of objectives (four divisions, 70 directions, for 100 individuals and five objectives, which used to fail with six divisions and 210 directions); RVEAConfig.default() uses the lattice of exactly pop_size vectors and otherwise fails at once naming the nearest valid sizes, such as 91 or 105 for three objectives. Without pop_size, both still use 12 divisions for three objectives and 6 for four or more.
The command line and optimize¶
A top-level vamos run and vamos.optimize build a run separately, so with the
same problem, algorithm, population, budget and seed, and no algorithm
configuration, they resolve the same configuration except for these
differences, which tests/experiment/test_cli_api_parity.py keeps listed:
- Result mode: the command line returns
non_dominatedfor AGE-MOEA, CCMO, CMOEA-MS, C-TAEA, IBEA, MOEA/D, RVEA, SMS-EMOA, SPEA2 and ToP, whereoptimizereturnspopulation. NSGA-II, NSGA-III and SMPSO agree. - NSGA-III: the command line derives the reference directions from the
population when the run starts;
optimizerecords the lattice's divisions. - MOEA/D: the command line reads the packaged weight files and records their
directory, a path inside the installation;
optimizerecords the divisions. VAMOS 1.3.0: with three or more objectives,algorithm.resolution.weight_vectorsrecords the weights each path runs: a packaged jMetal file, such asW3D_91.dat, on the command line, and the Das-Dennis lattice withoptimize. - NSGA-II's offspring size and SMS-EMOA's reference point are written out by one path and left to their defaults by the other, with the same effect.
VAMOS 1.3.0: NSGA-III's SBX has distribution index 30 on the
command line too, as in Deb and Jain (2014), pymoo and the MOEA Framework, and
as NSGAIIIConfig.default() already had (jMetal's NSGA-III examples keep its
general SBX default, 20). VAMOS 1.2.1 and earlier used 20 on the command line,
the general SBX default of VAMOS too. Command-line NSGA-III runs on
real-coded problems therefore follow a different trajectory;
--nsga3-crossover-eta 20 reproduces the earlier setting.
When the two must agree, set these options explicitly on both and compare the resolved configuration that each run records. Both paths are stable, so their defaults stay until one execution path replaces them in 2.0.
Termination criteria¶
VAMOS 1.2.0: every algorithm's run(problem, termination=...)
and initialize, and optimize(termination=..., algorithm_config=...), accept
the same three criteria:
("max_evaluations", n), the total number of evaluations;
("n_gen", g), g generations of pop_size evaluations, the initial
population included, so g * pop_size evaluations; and
("hv", {"target_value": t, "reference_point": r, "max_evaluations": n}),
which stops once the hypervolume of the result source against r reaches t,
within n evaluations. Counts must be positive integers: ("max_evaluations",
150.9) raises ValueError, while an integral float such as 1e4 is accepted.
Every result has hv_reached, whether the HV target stopped the run; NSGA-III,
SMS-EMOA and IBEA keep hv_converged as an alias until VAMOS 2.0. In VAMOS
1.1.0, AGE-MOEA and RVEA accepted n_gen but not hv, the other seven accepted
hv but not n_gen, run() truncated a fractional budget, and NSGA-III,
SMS-EMOA and IBEA reported only hv_converged, so the CLI never recorded that
their HV target was reached.
VAMOS 1.3.0: optimize(termination=("max_time", seconds))
stops a run of any built-in algorithm once seconds of wall-clock time have
passed since it started, checked after each generation (MOEA/D after each
pop_size evaluations, SMS-EMOA after each step), so a run can overrun the
limit by one generation. ("max_time", {"seconds": s, "max_evaluations": n})
also stops it after n evaluations, whichever comes first; without
max_evaluations there is no evaluation budget. Schedules that measure progress
against the budget, such as ToP's phases, CMOEA-MS's stages and the
constraint-handling techniques that relax over the run, then barely advance, so
give them max_evaluations. A live callback still receives every generation, and
its should_stop still stops the run first. result.meta["time_limit_reached"]
says whether the time limit stopped the run, and load_result restores it from
the manifest. A run limited by time is not
reproducible, on another machine or on the same one: how many evaluations
fit in the time depends on the hardware and its load. Its resolved spec records
vamos.termination:max_time@1 with {"seconds": s, "max_evaluations": n}
(null without a cap) and determinism.declared: false; its manifest's
replayability gives the reason wall_clock_termination, and
outcome.termination_reason is max_time or, when the cap stopped it,
max_evaluations. verify_run reports it as not exactly replayable and
reproduce refuses it; rerun ("max_evaluations", n) with its
outcome.evaluations for a run with the same budget. Only optimize takes this
criterion; an algorithm's own run() and initialize() do not.
VAMOS 1.2.0: all nine algorithms implement the same
step-by-step protocol: initialize(problem, termination, seed) evaluates the
initial population; repeat ask(), evaluate the returned decision vectors, and
tell(...) the objectives (and constraints) until should_terminate(); then
result() returns what run() would. With the same seed, the result equals
run()'s. tell returns True once the HV target is reached. In VAMOS 1.1.0,
NSGA-II and MOEA/D had no public initialize, should_terminate or result,
and tell of NSGA-III, SMS-EMOA and IBEA always returned False.
Changes included in 1.0.1¶
- SMPSO:
archive_sizecontrols search leaders,.external_archive(...)configures a separate result archive, and explicitpopulationmode returns the final swarm. Version 1.0.0 returned the leaders archive without honoring these independent result controls. - AGE-MOEA and RVEA: constraint-aware survival and constraint-aligned results are included when constraint handling is enabled. Version 1.0.0 did not enforce constraints in survival.
constraint_mode="none"remains an explicit opt-out. - RVEA: continue to use a numeric mutation probability such as
1.0 / problem.n_var. Its variation setup still does not resolve the"1/n"shorthand in 1.0.1. - NSGA-III: the constraint limitation above remains in 1.0.1.
These are implementation fixes under the existing stability policy. Record the package version and, for a source checkout, its commit. See the 1.0.1 release notes before comparing or replaying older experiments.
Optional baselines¶
- PyMOO NSGA-II (real and permutation), jMetalPy NSGA-II (real and permutation), PyGMO NSGA-II.
- Enabled via
--include-external; install withpython -m pip install "vamos-optimization[research]==1.1.0". These third-party integrations are Experimental, outside the stable VAMOS algorithm contract.
VAMOS 1.2.0: these baselines are removed, with --include-external, --external-problem-source and the research extra. VAMOS depends on no other optimization framework.
Backends¶
- NumPy (default): vectorized CPU kernels.
- Numba: JIT acceleration for supported kernels (set
VAMOS_USE_NUMBA_VARIATION=1for permutation/binary/integer variation). - MooCore: accelerated kernels via
moocore. Install optional backends withpython -m pip install "vamos-optimization[compute]==1.4.0"; see installation.
Backend roles¶
| Backend | Status | Best use |
|---|---|---|
numpy |
Stable | Exact reference backend and deterministic default. |
numba |
Optional backend | JIT implementations of supported kernels; includes compilation cost on first use. |
moocore |
Optional backend | Native non-dominated sorting/hypervolume operations where available; not every algorithm step is accelerated. |
VAMOS 1.2.0: the three backends follow the same trajectory for
every built-in algorithm with the same seed. The tests compare NumPy with Numba
and NumPy with MooCore.
- Tournaments: with a tournament size above two, the tournament keeps the
best rank when crowding distances are NaN or -inf, and uses fractional ranks
as given. VAMOS 1.1.0 could let a worse rank win in NumPy and truncated ranks
to integers in both NumPy and Numba.
- MooCore survival: it returns arrays the caller owns; it returned views of
buffers that the next survival overwrote. The undocumented
VAMOS_MOOCORE_HV_CONTRIB variable, which switched it to
hypervolume-contribution truncation, is removed.
Automatic engine selection¶
VAMOS 1.1.0 expands the automatic Numba preference to all nine built-in algorithms. Version 1.0.2 applied it only to NSGA-II and MOEA/D.
| Request | Effective engine |
|---|---|
Omitted / None |
NumPy, preserving the stable 1.x default |
"auto", any of the nine built-in algorithms |
Numba if its dependency and backend load and JIT is enabled; otherwise NumPy |
"auto", external/plugin/unknown algorithm |
NumPy; no compatibility claim for custom algorithms |
"numpy", "numba", "moocore" |
Exactly the requested engine; unavailable engines raise an error |
VAMOS 1.2.0: an algorithm class built directly without a
kernel, such as NSGAII(config), also uses NumPy. VAMOS 1.1.0 used Numba there
whenever Numba was installed. The backends follow the same trajectory, so only
the speed changes; pass kernel=NumbaKernel() to keep the compiled kernels.
Pass engine="auto" to optimize, engine="auto" in StudySpec, or
--engine auto on the CLI. It does not install optional packages, benchmark the
workload, choose MooCore, compile kernels during selection, or consume random
draws. Missing or incompatible optional imports fall back before optimization;
the effective engine is recorded in result metadata and the canonical resolved
specification. Diagnostics for load failures are available through VAMOS logging.
NUMBA_DISABLE_JIT=1 also selects NumPy in auto mode.
After selection, compilation or execution errors propagate; VAMOS does not restart an optimization under another engine. Retrying could repeat objective side effects or consume a different random stream. The NumPy single-pair SBX and MOEA/D optional shortcuts also tolerate unloadable Numba installations.
An explicit auto request is retained in the requested configuration. Saved
runs and created studies freeze the resolved engine: exact replay, study
resume, and retry do not rerun auto selection. If that stored engine becomes
unavailable, they fail rather than silently substitute NumPy. A newly resolved
auto configuration can select differently in another environment; pin
engine="numpy" or engine="numba" and record the environment when that matters.
Existing 1.0 artifacts and schema versions are unchanged. Expanding the
environment-dependent auto heuristic does not change the stable omitted default
or promise cross-environment bitwise reproducibility.
VAMOS 1.2.0: the NumPy engine sorts two-objective populations
into fronts in O(N log N) by a sweep over the first objective, instead of
comparing every pair of rows, with the same ranks and fronts (ties and
duplicated rows included). Sorting 1000 rows takes about 0.4 ms instead of
33 ms. Three or more objectives still compare every pair, in O(M N²); for large
populations there, prefer engine="auto" or engine="numba".
Numba is a throughput preference, not a guarantee of a faster first call.
Compare an empty JIT cache in a fresh process, a fresh process with a populated
disk cache, and repeated runs with warm JIT separately. The reproducible
benchmark harness
supports numpy, numba, and auto; see also
Measure backend performance.
Numba engine coverage¶
engine="numba" replaces selected numerical steps with compiled kernels. Each
kernel is written to reproduce the NumPy reference: the same random draws in the
same order, the same tie-breaking and the same floating-point operations. The
repository's parity tests check that the built-in algorithms follow identical
trajectories under both engines for the same seed in the same environment;
cross-backend bitwise equality nevertheless remains outside the
stability promise. Selecting an engine
never compiles problem evaluation.
| Algorithm | Compiled with engine="numba" |
Stays in NumPy/Python |
|---|---|---|
| NSGA-II | Non-dominated ranking and crowding, survival, tournament selection, SBX, polynomial mutation; the whole one-offspring steady-state step in its supported configuration (below) | Feasibility ordering, archives, steady-state front maintenance outside that configuration |
| NSGA-III | Ranking and crowding, tournament selection, SBX, polynomial mutation | Normalization, association to reference directions, niching (it shuffles with the run generator inside the loop) |
| MOEA/D | Differential-evolution children, SBX, polynomial mutation, neighbourhood replacement; the whole one-offspring step (see below) | Weight geometry; parent sampling and repair outside the compiled one-offspring step |
| SMS-EMOA | The steady-state step (VAMOS 1.2.0, see below): child variation and clipping, front insertion, two-objective hypervolume contributions, crowding, feasibility-first removal; tournament selection where configured | Parent sampling draws, hypervolume contributions for three or more objectives (MooCore when installed), archives |
| SPEA2 | SBX, polynomial mutation, lexicographic archive truncation | Strength/raw fitness and density (vectorized NumPy) |
| IBEA | Tournament selection, SBX, polynomial mutation, indicator-based removal | Indicator matrix |
| SMPSO | Turbulence mutation, leaders-archive crowding truncation | Velocity/position updates (vectorized NumPy), deduplication |
| AGE-MOEA | Non-dominated ranking, tournament selection, SBX, polynomial mutation, greedy survival scores | Front normalization and pairwise Minkowski distances |
| RVEA | SBX, polynomial mutation | Angle-penalized survival and reference-vector adaptation (vectorized NumPy) |
VAMOS 1.2.0: steady-state NSGA-II (.steady_state(), one
offspring per step) runs each step as a few compiled calls under
engine="numba": the binary tournament, SBX on the mating pair, clip repair,
polynomial mutation, the insertion of the evaluated child into the cached
fronts, crowding and the truncation back to the population size. Random values
are still drawn from the run generator in the NumPy order, and the truncated
front is still ordered with np.argsort, so the trajectory is the NumPy
engine's. This covers unconstrained runs with binary tournament selection, SBX,
polynomial mutation and the default clip repair. Constrained problems, other
selection, crossover, mutation or repair operators, genealogy tracking,
immigration, parent-selection filters and non-breeding indices keep the
NumPy/Python steady-state path, as does any step with non-finite objective
values. External archives and hypervolume termination behave the same on both
paths.
VAMOS 1.2.0: with batch_size=1 (the default), MOEA/D under
engine="numba" compiles each whole step: parent selection, DE or SBX,
polynomial mutation, the clip repair, the ideal point and the neighbourhood
replacement. Python only draws the random numbers from the run generator, in the
order of the NumPy step, and evaluates the problem, so trajectories stay
identical. The compiled step covers real-coded runs with DE or SBX crossover,
polynomial mutation and the clip repair (the defaults), every aggregation,
constraints, external archives, live callbacks and HV termination. Genealogy
tracking, batch_size > 1, other operators or repairs, other array types, and
platforms where compiled variation stays disabled (see below) keep the
per-operator path described in the table.
VAMOS 1.4.0: the compiled MOEA/D step also covers
subproblem_order="cyclic" and the augmented_tchebycheff and
inverse_weight_tchebycheff aggregations. The DE schemes other than rand/1/bin,
the random DE base, the normalization of the objectives and the inverted_pbi
aggregation keep the per-operator path, whose neighbourhood update
is compiled, so both engines give the same results (see the
MOEA/D configuration).
Compiled SBX and polynomial mutation are enabled only after a one-time check
that compiled pow matches np.power bit for bit on the platform (some NumPy
builds use vendor SIMD power). Otherwise the Numba engine keeps the NumPy
operators. Compiled ranking, survival and archive truncation fall back to NumPy
for non-finite objective values.
VAMOS 1.4.0: the compiled power takes the same shortcuts as
np.power for a scalar exponent, which a run-time probe detects: the exponent 2
as x * x (NumPy 2) and, with NumPy 2.4, the exponent 0.5 as sqrt(x) and -1
as 1 / x. With NumPy 2.4 the check failed on these exponents and the Numba
engine kept the NumPy operators; it now keeps its compiled variation, with the
same results.
VAMOS 1.2.0: under engine="numba", SMS-EMOA runs each
steady-state step (one child) in two compiled calls for the child and one for
survival, instead of per-step NumPy and Python code. Parents and every
variation draw still come from the run generator in the reference order, and
the population, the cached ranks and crowding distances and the reference point
evolve bit for bit as in the NumPy reference. The step covers real encoding
with SBX, polynomial mutation and the clip repair (repair="auto"), random or
tournament parent selection, duplicate elimination, constraints, fixed or
adaptive reference points, external archives and live callbacks.
Two-objective contributions and constraint-violation sums are compiled only
after a one-time check against the installed reference (MooCore or the NumPy
fallback, and NumPy's summation order); three or more objectives keep the
reference contribution call. Other operators and repairs, genealogy tracking,
kernels that override the ranking or contribution hooks, a platform where
compiled pow differs from np.power, and non-finite objective values keep
the reference step. VAMOS 1.1.0 ran front insertion and contributions in Python
under every engine. VAMOS 1.3.0: jMetal's reference point rule
(reference_point(rule="jmetal")) also keeps the reference step, with the
same results under every engine.
Two compiled paths depend on whether Numba is installed rather than on the
engine: the MOEA/D neighbourhood update (disable with
VAMOS_USE_NUMBA_MOEAD=0) and SBX applied to a single mating pair (MOEA/D,
SMS-EMOA, steady-state NSGA-II). Both reproduce the NumPy results, so they
change speed, not trajectories. Compare engines in an environment without
Numba when you need a pure NumPy timing reference.
Probability shorthand¶
- Operator probabilities accept either a numeric value or the string literal
"1/n". "1/n"resolves to1.0 / n_varin every algorithm's variation path. In VAMOS 1.1.0, AGE-MOEA and RVEA required the numeric equivalent; see below.- Example:
NSGAIIConfig.builder().mutation("pm", prob="1/n", eta=20.0)
VAMOS 1.2.0: every algorithm, AGE-MOEA and RVEA included,
resolves operator probabilities with one interpreter. It accepts a number in
[0, 1] or an expression "k/n", which means k / n_var capped at 1; case and
spaces do not matter ("1/N", " 2 / n "). Anything else, a number outside
[0, 1] included, raises ValueError when the algorithm builds its
operators. A mutation prob_factor sets factor / n_var and must be
positive. In VAMOS 1.1.0,
AGE-MOEA and RVEA failed on "1/n" after evaluating the initial population;
NSGA-II, IBEA and SMPSO rejected "1/N"; MOEA/D and the binary, integer and
permutation builders replaced an unreadable string such as "0,5" with
1/n and clipped numbers to [0, 1]; and prob_factor made NSGA-II fail.
VAMOS 1.2.0: the typed configurations check their values
whenever they are built (builder().build(), from_dict() or the
constructor) and raise ConfigurationError, a ValueError, before anything
is evaluated:
- operator probabilities (
prob,cr) as above,etafinite and at least 0,prob_factorandmutation_prob_factorpositive, and a tournamentsizethat is a positive integer; - population, archive, batch and partition sizes,
neighbor_size,replace_limit,k_neighborsandoffspring_sizepositive integers; - IBEA's
kappafinite and positive, MOEA/D'sdeltain [0, 1], RVEA'salphaat least 0 andadapt_freqin [0, 1], SMPSO'sinertia,c1andc2at least 0 andvmax_fractionpositive,result_modeeithernon_dominatedorpopulation, and a MOEA/D aggregation MOEA/D implements.
The MOEA/D builder also rejects a neighbor_size larger than pop_size.
MOEADConfig.default(), the CLI and the tuning space now use
min(20, pop_size) and min(neighbor_size, pop_size), which is the
neighbourhood MOEA/D already used. from_dict() rejects unknown keys with a
suggestion (pop_sise → pop_size) instead of ignoring them, and restores the
operator pairs that JSON turns into lists, so
from_dict(json.loads(cfg.to_json())) == cfg. In VAMOS 1.1.0, SBX with
probability 1.7 or eta=-5, kappa at or below 0 (which inverts IBEA's
selection) and delta=1.5 ran without warning, and a result_mode or
aggregation typo failed only after the initial population was evaluated.
VAMOS 1.3.0: mutation_prob_factor reaches every algorithm
whose configuration has it: MOEA/D, NSGA-III, SMS-EMOA, SPEA2, AGE-MOEA and
RVEA now set the mutation probability to factor / n_var (at most 1), as
NSGA-II and IBEA did. In VAMOS 1.2.0 those six ran with the mutation's own
prob. The fields that still have no effect warn; see
stable configuration.
For a measured first-call/subsequent-call example, follow Measure backend performance.
Comparative benchmarking¶
- Kernel-focused benchmarks:
python tools/benchmark_kernels.py --smoke --output artifacts/performance/kernel_smoke.json - VAMOS vs pymoo seeded comparisons:
python tools/benchmark_compare_pymoo.py --output artifacts/performance/pymoo_comparison.json --markdown artifacts/performance/pymoo_comparison.md. VAMOS 1.2.0: install pymoo yourself first (python -m pip install -c constraints/ci.txt pymooin a source checkout); no VAMOS extra installs it.
Live visualization¶
The visualization surface is Experimental. Enable --live-viz to stream Pareto fronts during runs (--live-viz-interval, --live-viz-max-points). Saves a live_pareto.png at run end.
VAMOS 1.2.0: the live window plots the current population,
dominated and infeasible solutions included, and its title says so. It rescales
its axes at every update, labels them with the plotted objectives, and samples
the populations larger than --live-viz-max-points with a seeded generator
instead of the global random state. VAMOS 1.1.0 and earlier kept the axes of
the first generation, so a converging population soon moved out of view.