Anneal

Start here. Bound-constrained global optimization with a single budget knob, or classical simulated-annealing presets you can swap without rewriting a driver.

Simulated-annealing components on the eindir typed primitives. One surface, many drivers: classical presets, Bayesian pilot+mixer, generalized Langevin equation (GLE) colored noise, rank-1 additive independence, quasi-Monte Carlo (QMC) polish, device/ensemble scale. All obey the same five-component algebra (Obj / Cool / Neigh / Move / Accept) and four composition laws checked at construction.

Cluster search and cooperative production

Config::recommended(n) composes surface relocations that pay one acceptance test for a whole excursion, Normal-Gamma Thompson allocation over move arms, and tabu response to a stalled walk. Config::for_cluster(n) retains the plain Wales-Doye protocol as a comparison baseline. Accuracy and efficiency claims come from sealed, evaluation-matched ensembles rather than reference energies or morphology labels supplied to the search.

Large-cluster production uses four synchronously cooperating replicas. Each replica spends an independently auditable charged-work sequence and submits a freshly validated quenched representative. The coordinator updates an exact basin census and bounded descriptor catalogue, then closes a population epoch only after all replicas submit. A target-free Feynman--Kac potential ranks energy, descriptor novelty, census scarcity, and latent-Gaussian transition uncertainty. Replayable systematic resampling assigns parents at fixed population size; family caps and distinct descriptor-space rejuvenation keep one funnel from consuming every processor element.

This population layer borrows fixed-population bookkeeping from diffusion Monte Carlo, not imaginary-time quantum propagation or fixed-node physics. The latent transition field is the Gaussian part of an INLA-style model; its Gaussian posterior is solved directly, so no Laplace approximation or R-INLA runtime is involved. Bayesian move allocation and quench screening retain their own evidence, while nested sampling remains a matched-budget comparison with separate live-point weights. Shared-catalogue and one-private-catalogue- per-replica ensembles form the causal communication comparison.

use anneal_core::methods::cluster_hopping::{optimize, Config, Ledger};

let cfg = Config::recommended(38);
let mut ledger = Ledger::new(400_000);
// supply `relax` closing over your objective; see examples/lj_cluster_search.rs

External potentials use the same optimizer driver. The molecular-cluster and slab examples share one persistent in-process profile adapter; selecting nwchemc loads libnwchemc once and serves the complete hop loop without an RPC server or a result cache. Molecular requests omit a simulation cell, while the slab driver sends the periodic cell through the same adapter.

POTENTIAL_CONFIG=/path/to/PotentialConfig.bin \
POTENTIAL_LIBRARY=/path/to/libnwchemc.so \
cargo run --locked --release --features rgpot-ex \
  --example molecular_cluster -- 6 1200 8 nwchemc

The shared adapter is examples/common/profile_engine.rs; the two consumers are examples/molecular_cluster.rs and examples/slab_adsorption.rs.

Install

pip install anneal

Full stack (pinned Rust + Python + docs):

pixi install

Start here (budget-only portfolio)

The intended stand-alone tool for most users: pass an objective, box bounds, and a work-unit budget (objective and gradient evaluations share the counter).

import numpy as np
from anneal import global_optimize

def rastrigin(x):
    return 10.0 * len(x) + np.sum(x * x - 10.0 * np.cos(2.0 * np.pi * x))

low, high = np.full(5, -5.0), np.full(5, 5.0)
out = global_optimize(rastrigin, low, high, budget=4000, seed=0)
print(out["best_val"], out["best_pos"])

Runnable copies:

• Script: examples/quickstart_portfolio.py
• Notebook: examples/notebooks/01_quickstart.ipynb
• Website quickstart + four tutorials: https://anneal.rgoswami.me

Classical presets (same driver, different slots)

from anneal import Boltzmann, Fast, Gsa, run

h = run(rastrigin, low, high, Boltzmann(t_init=5.0, sigma=0.5),
        n_epochs=40, steps_per_epoch=50, seed=1)
print(h.best_val)

Every proposal is reflected into [low, high], so obj_fn is only ever called inside the box. Pass x0= to start the walk from a known point (global_optimize and run_qmc take it too). The start costs one call: a run makes 1 + n_epochs * steps_per_epoch evaluations.

ChemFit

Gradient-free fits go through anneal.chemfit. The chain starts at the fitter's initial parameters, and every candidate stays inside the box. fit_anneal and fit_chemfit speak init / ask / tell / finish. run_benchmark also accepts evaluate / step. driver="portfolio" (the default) is the budget-only global optimizer. driver="boltzmann", "fast", and "gsa" are the classical presets.

from anneal.chemfit import run_benchmark

def run_anneal(benchmark_context):
    return run_benchmark(
        benchmark_context,
        method="portfolio",
        low=-3.0,
        high=3.0,
    )

A scalar low or high is broadcast across the flattened parameters. Bounds may also live on benchmark_context["bounds"] or fitter.bounds.

Optional arms (additive independence + QMC polish)

import numpy as np
from anneal import additive_independence, qmc_polish

def rastrigin(x):
    return 10.0 * len(x) + np.sum(x*x - 10.0 * np.cos(2.0 * np.pi * x))

def grad_rastrigin(x):
    return 2.0 * x + 20.0 * np.pi * np.sin(2.0 * np.pi * x)

low = np.full(5, -5.0)
high = np.full(5, 5.0)

# Values-only rank-1 independence (no gradient)
res = additive_independence(rastrigin, low, high, max_fevals=3000, seed=7)

# Polish with gradient
refined = qmc_polish(rastrigin, grad_rastrigin, low, high,
                     n_starts=32, max_fevals_per_start=50, seed=0, top_k=1)
print(refined["best_val"])

Full docs, tutorials (classical, Bayesian pilot+mixer, GLE, polish+device), algebra, how-tos, and reference at https://anneal.rgoswami.me .

Method catalog

Every algorithmic mechanism in the crate, with file:line references, constants, and how the pieces feed each other: docs/orgmode/methods/catalog.org. A narrative walk of one cooperative run end to end, naming each mechanism as it fires, plus a dataflow diagram: docs/orgmode/methods/composition.org.

Development

pixi install
pixi run -e python python-test
pixi run -e docs docs-export
pixi run -e docs docs-build

See pixi.toml and docs/export.el (modeled on rgpycrumbs/rsx-rs patterns).

License and citation

MIT (see LICENSE.txt). Citation: CITATION.cff or the software Zenodo DOI. Multi-author software citation lists six authors. Project history since February 2023. Reproducibility package for paper tables and figures: HaoZeke/anneal_repro (Zenodo 10.5281/zenodo.20672620).