AMM: budget-aware routing of classical solvers by online probes

AMM is a derivative-free optimizer for continuous black-box problems with a known evaluation budget and a known box. It does not run one algorithm: it spends a small, counted part of the budget on online probes (curvature, plateau, separability, kink, basin and fractal readings of the objective near the incumbent) and uses their outcomes to route the rest of the budget among quasi-Newton (SLSQP, L-BFGS-B), trust-region (COBYQA), coordinate (STEP), multistart (MLSL) and population (CMA-ES family, the ATM sampler) engines. A probe that does not fire leaves the run on a general path, so a misreading costs evaluations, not the run. Every rule reads only the dimension, the budget, the box and evaluated function values.

The method, its development protocol and its evaluation on COCO/bbob are described in the paper (citation below). The package was developed under the code name ATM; the implementation therefore lives in atm, and amm is an alias for the same objects.

Install

pip install amm-optimizer            # NumPy and SciPy only
pip install -e ".[dev]"              # from a checkout; add ",bench" for the COCO/bbob tooling

Quick start (the configuration frozen for the paper)

import numpy as np
import amm                                  # `import atm` is equivalent

def f(x):
    return float(np.sum((x - 1.0) ** 2))

result = amm.minimize(
    f,
    x0=np.zeros(10),
    budget=100 * 10,                        # maximum number of function evaluations
    seed=0,                                 # runs are deterministic given the seed
    bounds=(-5, 5),                         # required: the box (scalars or one value per coordinate)
    config=amm.presets.get("c46"),          # the frozen configuration; see docs/FREEZE_2026-10-22.md
)
print(result.x, result.fun, result.nfev)

bounds is required by this preset (it raises ValueError without it). The box is used, not enforced as a constraint: samples are folded into it before the function is called. The objective must be deterministic. Tested on noiseless, continuous, box-constrained problems with budgets of 10 to 1000 x the dimension.

Reproducing the paper. The code is that of git tag freeze-2026-10-22; the configuration hash of amm.presets.get("c46").config_hash() is 2153948ebed51150. Pre-registrations and result notes of every batch are in docs/research/batches/, and docs/FREEZE_2026-10-22.md records what was frozen and why.

Citation. See CITATION.cff (the paper's reference will be added when it is public).

Legacy ATM presets

The sections below document the original ATM sampler and the older presets (ATMConfig(), composite(), improved()); they are kept because every recorded result and test depends on them. This repository is a clean, tested re-implementation of the original ATM that reproduces its results exactly (see docs/DEVIATIONS.md).

import numpy as np
import atm

def sphere(x):
    return np.sum((x - 2) ** 2)

result = atm.minimize(sphere, x0=np.zeros(10), budget=2000, seed=0)
print(result.x, result.fun, result.nfev)

budget is the maximum number of function evaluations, and ATM uses all of them (the best point found is kept even if the budget ends mid-iteration). Pass seed= (or an rng=np.random.RandomState) for reproducible runs. A starting point where the function is NaN or infinite raises ValueError; NaN or infinite values elsewhere count as failed evaluations and never win.

The defaults reproduce the original ATM exactly (see docs/DEVIATIONS.md); ATMConfig(strict_budget=False) also restores the original's looser budget accounting.

Better results: the improved preset

If you know the search box, ATMConfig.improved() gets far more out of the same budget:

result = atm.minimize(
    sphere,
    x0=np.zeros(10),
    budget=2000,
    seed=0,
    bounds=(-5, 5),                      # scalars or one value per coordinate
    config=atm.ATMConfig.improved(),
)
print(result.fun)

The box is used, not enforced as a constraint: samples are folded back into it before the function is called, so the function only ever sees points inside. Without bounds= the preset raises ValueError. The objective must be deterministic.

This preset is a hybrid, not just ATM. It takes ATM's sampler with five improvements (success-rate control of the search width, a uniform first pool over the box, bounds folded with a 25 % corner clip, a pool sized from the budget, no re-evaluation of the incumbent) and adds local-search stages: a simplex search in up to 4 dimensions and a (1+1)-ES above, for the first part of small budgets; a learned covariance up to 10 dimensions; and, up to 10 dimensions, a simplex search over the last half of the budget. Each option is documented in docs/DEVIATIONS.md and docs/EXPERIMENTS.md.

Presets, from simplest to largest:

tests/golden/presets.json pins the exact cost traces of all of them.

What to expect from improved(), measured on COCO bbob (2021 suite) instances 96-100 that were not used to design it (docs/HOLDOUT_TIER5.md, 18,000 runs per arm, raw COCO evaluation):

• ECDF value (fraction of targets reached) improves by +.196 [95 % CI +.180, +.212] over the defaults, averaged over budgets of 30, 100 and 300 x dimension, and by +.096 [+.085, +.108] over composite().
• The gain shrinks as the dimension grows: over the defaults +.412 at D = 2, +.197 at D = 5, +.127 at D = 10, +.082 at D = 20, +.055 at D = 40; over composite() +.215 at D = 2 down to +.017 at D = 40, where the two are almost the same algorithm.
• It does not beat everything: a plain (1+1)-ES with the 1/5 rule is still ahead at 40 dimensions (-.031) and level at 20, and CMA-ES is far ahead of every ATM variant at large budgets (on the Tier 4 instances: .597 against .504 for the closest hybrid at 1000 x D).
• Only noiseless, continuous, box-constrained problems with budgets of 10 to 1000 x D were tested. The three-algorithm design means its gain should not be described as an improvement of ATM's sampler alone; use composite() if you want that.

Development

pytest -m "not slow"      # fast suite, includes golden-master and parity tests
pytest -m slow            # 400 random cases against the frozen original in reference/
python tools/record_golden.py   # re-record golden masters (only for deliberate changes)
python benchmarks/perf.py       # repeatable speed benchmark, original vs this package
python benchmarks/block_profile.py   # where the time goes, per algorithm block

CI runs on your laptop

There is deliberately no GitHub Actions CI for now (it would use Actions minutes). Run the same checks locally with the project's virtual environment:

.venv\Scripts\python tools/ci.py          # fast gate, about 2 minutes: lint, format, types, quick tests
.venv\Scripts\python tools/ci.py --full   # about 3 minutes (longer on a busy machine): all tests incl. the 400-case parity sweep, 100 % coverage gate

Both stop at the first failing step and exit non-zero (--keep-going runs everything). To run the fast gate automatically before every git push, opt in with git config core.hooksPath .githooks (undo with git config --unset core.hooksPath; skip once with git push --no-verify). It is not enabled by default.

A GitHub Actions workflow is parked, switched to manual start, in ci/github-actions-ci.yml; moving it to .github/workflows/ needs a token with the workflow scope.

Licensed under Apache-2.0.