Algorithms

1. The space must be finite. If any axis has more than 10 000 values — most notably a fine-stepped float — initialize() throws:

“GridOptimizer: search space is not finite — use TPE/SA/GA/Random instead.”

2. The space must be under 50 000 combinations. The running product is set to Infinity as soon as it crosses that line, which clears the finiteSearchSpace flag and trips the same check.

Both produce an error, not a truncated run. A partial exhaustive search that reported itself as exhaustive would be far more dangerous than a refusal.

• All parameters excluded → the product is empty and the run does zero trials. It is not an error; it simply ends immediately.
• Budget smaller than the space → the run is truncated. Grid has no stop-reason field, so no distinct reason is reported.
• A dimension with zero choices → one row is emitted with an undefined value, which fails validation. The result is 0 committed trials and 1 rejected suggestion — a run that appears to have done nothing.
• Memory is O(product length), because the product is built up front. At 50 000 rows that is fine; it is still a full materialisation.

It is a ring buffer of the last dedupeWindow signatures, oldest evicted on every push. It is not a permanent “have I seen this” set.

Membership is a linear scan over up to 1 000 strings per draw. The signature sorts the value keys and stringifies them, so it is order-independent — but it is built from raw values with no step-granularity snapping, so two float draws differing in their last bits count as distinct. (Compare the identity key used by SA, which does snap.)

The window is written at proposal time, before the trial runs — so a trial later rejected by validation has still consumed a slot.

evaluateConditions is reached from the random sampler and from NSGA-II’s proposal path. Grid, Brute, SA and GA do not consult it, and the value validator does not either.

So a Grid or Brute run over a space with conditional parameters will happily produce trials that violate the condition — they are still type- and range-checked, so the run completes and the numbers look legitimate.

With the defaults, T ← 0.95 × T reaches the floor of 1e-3 after 135 scored trials:

ceil( ln(1e-3) / ln(0.95) ) = 135

Generally: ceil( ln(minTemperature / initialTemperature) / ln(coolingRate) ). Set a softer coolingRate of 0.99 and you get roughly 1 384 trials — a tenfold budget increase from one config change.

This is a genuine gotcha: a user who sets a 1 000-trial budget on an SA run watches it stop at 135, because cooling is not skipped for rejected or failed trials.

1. The initial uniform sample is never evaluated. The seed is added to the visited set immediately, and suggest() only ever returns a neighbour of the current point. So the first trial is a neighbour of a uniform sample, and the uniform sample itself is discarded unscored. The first scored trial is accepted unconditionally, and becomes the starting current point. The file’s own header describes the seed as being evaluated — the code does not do that.

2. Acceptance is non-strict. Ties (pnl >= current.pnl) are accepted. The header comment says “strictly improving”; the comparison is >=.

3. It anneals continuously and never restarts. There is no reheat, no restart and no multi-phase logic anywhere in the implementation — a single monotonic decay.

SA is the only algorithm here with an unbounded visited set — one entry per proposal, for the life of the run, with no eviction.

On a small or integer-only space, neighbour proposals saturate: after 16 collisions SA takes a uniform global fallback instead of a local step. After 64 consecutive fallbacks it emits exactly one console warning, once per run, and then stays quiet — so a silently degraded run looks identical to a healthy one from the UI.

Every parameter becomes an integer-indexed dimension, and a candidate is an array of per-dimension indices. Booleans get two slots; categoricals get one per choice; numerics get floor((max − min) / step) + 1 slots. A dimension with a non-finite or inverted range is silently dropped, as is any parameter of an unrecognised type.

Numeric density is a Gaussian kernel density estimate with a 10 % uniform mixture, evaluated on the value scale:

kde   = (1/n) · Σ exp(−0.5·u²),  u = (x − sᵢ)/bw
uni   = 1 / max(hi − lo, 1e-12)
mixed = (1 − α)·kde + α·uni,  α = 0.1
return log(max(mixed, 1e-300))

That is a linear mixture of densities — the logarithm is taken once, after mixing, not per component.

Bandwidth is Silverman’s rule, floored:

silver = 1.06 · σ · n^(-0.2)
bw     = max(silver, (hi − lo)/50, 1e-6)

Categorical and boolean density is a histogram with a +1 Laplace pseudocount on every possible value, not only the observed ones — so an unobserved choice keeps probability 1/(n + k) and stays reachable for the whole run. That is a deliberate safeguard: without it, a choice that never appeared in a good trial could never return.

const gammaN = Math.max(1, Math.floor(cfg.gamma * n))
good = indexed.slice(0, gammaN)      // top 20 %, at least one
bad  = indexed.slice(gammaN)

At the moment warm-up ends, with 20 eligible trials, that is 4 good and 16 bad.

There is also a flat-objective guard: if every eligible trial has an identical score, both groups come back empty and the proposer falls back to uniform sampling. Without it, a meaningless objective would produce a confidently meaningless model.

This is the largest divergence from textbook TPE, and it changes what the method is.

Standard TPE draws every candidate from the good distribution and ranks by log l(x) − log g(x). This implementation flips one coin per candidate: with probability ½ the candidate is a pure uniform draw across every dimension, not a perturbation of a good observation.

With nProposals = 24, roughly 12 of the 24 candidates are uniform, and they compete on equal terms with the good-perturbed ones. The surviving candidate is therefore frequently a uniform sample.

The source code acknowledges this as a deliberate hybrid. Whatever the merits, it means “TPE” here is a 50/50 blend of model-guided and blind sampling — which is part of why it behaves so much like Random on small spaces.

s += lg - Math.max(lb, lg - 50)     // accumulated per dimension

Any dimension where the “bad” density underflows contributes at most 50 to the score, so a single saturated dimension cannot give a candidate an unbounded advantage.

This clamp appears in no textbook formulation of TPE and is not in the module’s own specification comment. It is a sound engineering guard, but it is undocumented behaviour you should know about if you ever need to reason about why one dimension dominated a parameter’s importance score.

• Log-scaled dimensions. There is no log transform anywhere — no logarithm on the value axis, no scale property read, no back-transform. A repository-wide search finds only a stale comment describing log-jitter, sitting above a float branch that jitters linearly. Parameters spanning several orders of magnitude are handled on a linear scale, which is a real limitation for threshold-style strategies.
• Warm-starting from the best. Never happens.
• Exact KDE sampling. Despite a KDE being fitted, the perturbation is a fresh Box–Muller draw around one randomly chosen good observation, with the bandwidth recomputed per dimension per proposal — not an exact sample from the fitted density.

Selection — tournament, size 3. Three candidates are drawn with replacement, uniform over array positions — not proportional to fitness. The best of the three wins. Selection pressure comes entirely from the within-tournament argmax.

for (let i = 0; i < picks; i++) {
  const idx = Math.floor(rng.next() * sorted.length)
  if (best == null || sorted[idx].pnl > best.pnl) best = sorted[idx]
}

With k = 1 selection is uniform; with k = populationSize it is pure elitism.

Crossover — uniform, per gene, 50/50, discrete only.

out[p.title] = (rng.next() < 0.5) ? a[p.title] : b[p.title]

Because a value is copied wholesale rather than blended, this is type-agnostic: integers, floats, booleans and categoricals all cross without special-casing. There is no arithmetic or blending crossover. If the second tournament returns the same individual as the first, the child is a plain clone.

Mutation — per gene. Each parameter independently passes a coin at the current rate; if it passes, that single gene is perturbed by the same neighbourhood function simulated annealing uses — deliberately shared, so there is exactly one implementation of “how do I move one gene”.

When the best result has not meaningfully improved for 5 generations, the mutation rate is multiplied by 1.30, up to a cap of 0.30. A meaningful improvement decays it by 0.02 back toward the baseline.

Two details make this correct rather than merely reactive:

• The baseline is a floor, never a replacement. The rate is clamped to [mutationRate … maxMutationRate], so the configured baseline is what you get back.
• ”Meaningful” is a hybrid threshold: ε + |lastBest| · ε. A purely relative test is wrong when the fitness values are negative, because it never fires for losses — and losses are exactly when a stagnating search needs help.

It is decided before the next generation’s children are built, so every child of generation N uses the rate chosen by generation N−1. A whole generation of failures counts as stagnation.

Two independent collapse measures are computed over the evaluated population:

• Mean pairwise distance — for every pair, the mean over dimensions of the normalised difference (numerics scaled to their own [min, max]; everything else compared as Hamming distance). Floor 0.25.
• Distinct ratio — unique keys over population size. Floor 0.60.

Collapse is either floor firing, checked independently.

When it fires, 8 % of the child slots are replaced with fresh uniform draws — 3 of 28 by default. The quota is computed before the evolutionary fill so immigrants genuinely occupy slots rather than topping up a short population. Elites are never displaced: they were already committed before the quota is applied.

Off by default. The default was chosen specifically so that existing users’ trial counts do not silently change.

When enabled, a fraction of the budget (30 % by default) is reserved for an exhaustive grid over a ±2-step neighbourhood of the best parameters found. Only the numeric bounds of integer and float parameters are narrowed; the step, the type, and every categorical and boolean parameter pass through unchanged.

The radius shrinks deterministically until the combination count fits the budget, and the grid is enumerated with the same function Grid uses — so it hits the same limits and the same failure mode.

The exact skip threshold, with the defaults:

skip ⟺ B − floor(0.30·B) < 50  ⟺  B ≤ 70

At a budget of 71 trials refinement switches on (21 grid, 50 evolutionary). At 70 it is skipped. A budget of 100 gives 30 grid and 70 evolutionary.

The top individuals are carried into the next generation unchanged and never re-run — deliberately, because re-evaluating a known individual would violate the de-duplication contract and waste a full backtest.

One visible consequence: a generation emits populationSize − elitism new trials, not populationSize. At the defaults that is 28 new trials per generation, not 30 — so a 50-generation run costs fewer trials than 30 × 50.

const key = paramsKey(values, parameters)
const slot = pending.find(p => p.key === key) ?? null

Results are matched back to their slot by parameter key, never by position. That is precisely what allows a batched run to report results out of order and still attribute them correctly.

Two more guarantees: a failed or non-finite result is written as −Infinity, so it can never be selected as a parent; and the best result is monotonic and independent of the slot match — a late report from a previous generation still updates the best, even though its fitness is lost to that generation.

Earlier versions of this page recorded a defect here: the run stopped at generation > generations while the stop reason was reported at >= — so the loop and the reason disagreed by one generation about what the run actually did.

That is fixed. Both GA and NSGA-II now use >=, and a regression test asserts generation === generations for several generation budgets across both algorithms.

It is kept here because the interesting part is why it mattered: the off-by-one was a GA pattern that NSGA-II copied, and the two algorithms are now measured against each other precisely so a silent divergence like that cannot come back.

resolveConfig() reads flat keys — opts.populationSize, falling back to OPTIMIZER_DEFAULTS.nsga2.populationSize — not an nsga2.-prefixed block. So populationSize genuinely controls the population; immigrantRate is GA-only and NSGA-II never reads it.

The defaults are notably larger than GA’s 30 / 50. The reasoning is in config.js: Deb’s own NSGA-II experiments use 100 for 2–3 objectives, which is where crowding distance beats tournament selection. The side effect is that 100 × 40 = 4000 exceeds a typical 1000-trial budget, so a standard run usually stops on budget around generation 10 — well short of the cap. The Pareto panel is therefore a snapshot, not a finished front.

The worker pool finishes a batch in whatever order the workers happen to complete it. So NSGA-II matches each result back to its slot by paramsKey, never by array position — the same rule GA uses.

Each slot carries an emitted flag, and a slot counts as available only when that flag is not strictly true. The strict test is deliberate: a slot built without the field is still treated as available, so adding a new construction site elsewhere cannot silently mark a whole generation as already emitted and starve the batch.

What makes a seeded run reproducible is therefore not a return order — there isn’t one — but the combination of key matching and the rule that a batch must never span a generation boundary.

chooseMethod() ends in method: ‘tpe’ with a tightened budget. Random is reached only through the explicit sub-50-trial branch at the top.

That distinction matters: TPE is the one method that keeps learning from a larger budget, so it is the safer fallback when the space does not fit a finite search. Random would simply spend the same budget without improving.

Auto keeps your requested method displayed and substitutes the one it actually chose. The method that executed is recorded in the run context.

That is deliberate: silently relabelling the method would make a saved run irreproducible-looking, and would hide the fact that a different algorithm produced the numbers. The discrepancy is visible rather than hidden — but it does mean the algorithm name on screen is not always the algorithm that ran. The run context is authoritative.