Nested Fitting — Worked Examples

Note

The HPO module ships fifteen end-to-end examples that build up gradually: 01 is the smallest viable config, each subsequent one introduces one or two new features. Between them they exercise the optimiser libraries and the INIT, STRATEGY, EXPLORE, RESTART, and INNER blocks. Each example is a self-contained directory with one config.hpo and one README.md; all share a small Ta training/validation bundle in examples/common/ and the shared common/run.sh driver (two examples ship their own run.sh to bootstrap a seed first).

To keep a single source of truth the canonical content for each example lives in the HPO source tree. The links below point at the GitLab tree so the README, configuration, and any helper scripts you read here are byte-identical to the files you check out.

How to run one example

After cloning the HPO repository alongside your Tadah!MLIP build (see Installation), run:

cd HPO/examples/01_minimal
bash ../common/run.sh

How to run them all

bash HPO/examples/run_all.sh

prints a one-line summary per example (best loss, eval count, status).

Index

#	Example	What it exercises	Knobs
01	01_minimal	Smallest viable config: one OPTIM knob optimised with DLIB:BFGS. With no INIT block, iter 0 is the implicit CONFIG point. Use as a baseline for the elaborate configs.	TYPE PLAIN, DLIB:BFGS
02	02_random_search	Uniform random sampling inside the bounds via LIB TADAH, ALGO RANDOM — a baseline against any smarter optimiser.	TADAH:RANDOM, SEED
03	03_nlopt_local	Derivative-free local search (LN_SBPLX, a Subplex variant of Nelder-Mead). Robust when finite-difference gradients are noisy.	NLOPT:LN_SBPLX, STEP
04	04_skip_bad_pots	PC_ERMSE --skip-above / --skip-rel early-reject filter: fail-score obviously-broken potentials before LAMMPS is invoked.	PC_ERMSE, --skip-above, --skip-rel
05	05_extra_observables	PC_LAMMPS --invar injects LAMMPS variables; --outvar captures extra per-iter observables from a parametric script.	PC_LAMMPS, --invar, --outvar
06	06_init_random	Introduces the INIT block: an explicit, reproducible random starting point (STRATEGY RANDOM + SEED).	INIT.RANDOM, SEED
07	07_init_lhs_multistart	Latin-hypercube INIT seeds combined with the MULTISTART policy — one local optimiser run per seed.	INIT.LHS, MULTISTART
08	08_init_sobol_gfs	Sobol low-discrepancy INIT seeds feeding DLIB:GFS, the multi-seed global consumer.	INIT.SOBOL, DLIB:GFS
09	09_init_warm	Warm restart: STRATEGY WARM reloads a previous best plus its hot-variable warmstart cache. Ideal for incremental retunes.	INIT.WARM, WARM_ON_MISMATCH
10	10_init_chain	Chained INIT — WARM then LHS — feeding DLIB:GFS; the chain runs in written order, so WARM seeds iter 0.	chained INIT
11	11_grid_sweep	Exhaustive Cartesian grid sweep (LIB TADAH, ALGO GRID) — a deterministic survey of a low-dimensional search box.	TADAH:GRID, STEP
12	12_prestage	TYPE PRESTAGE: a global EXPLORE stage harvests the TOPK candidates that the outer optimiser then refines.	TYPE PRESTAGE, EXPLORE, TOPK
13	13_restart	The RESTART decorator relaunches the optimiser from a fresh seed after AFTER_STAGNATION stalled evals, up to MAX times.	RESTART, AFTER_STAGNATION
14	14_mlsl_inner	NLopt MLSL global driver with a mandatory INNER local optimiser (LN_BOBYQA).	NLOPT:G_MLSL_LDS, INNER
15	15_simulated_annealing	Classic Kirkpatrick/Metropolis simulated annealing (LIB TADAH, ALGO ANNEAL) with an auto-calibrated initial temperature.	TADAH:ANNEAL, PARAM