Date:

2026

anneal Documentation

Overview

anneal is a library of simulated-annealing drivers built on the five typed components (Obj, Cool, Neigh, Move, Accept) and four composition laws (L1 symmetry of neighbors, L2 support of the proposal, L3 downhill moves accepted with probability 1, L4 monotone cooling) defined in the INFORMS Journal on Computing paper (IISE manuscript). Every driver (Boltzmann, Fast, Gsa, GLE-Langevin, additive independence, Bayesian pilot+mixer, parallel tempering, QMC polish, …) is a different filling of those five slots; a change to any shared implementation (e.g. the noise-aware Accept or the batched device kernel) therefore appears in all of them.

Use anneal when the problem is bounded, expensive, derivative-free or partly derivative-aware, and the search policy needs to be swapped without changing the objective wrapper. The public API keeps the driver choice explicit: classical schedules, GLE proposals, Bayesian pilot allocation, QMC starts, surrogate independence proposals, and device batches all pass through the same sampler surface.

Key Features

Classical presets (Boltzmann, Fast, Gsa)

Logarithmic, reciprocal, and Tsallis families.

Identical call site via run; only the component objects differ.

Bayesian pilot + mixer (bGSA auto)

QMC pilot draws for (T0, sigma, q_v), short chains, three-term posterior (prior + 0.234 target + improvement), per-chain Beta(4,1) on “produced new global best”, Thompson sampling every step with 0.05 incumbent guard.

This spends early evaluations on chains that are both accepting and improving, instead of committing the full budget to one schedule before seeing the landscape. One max_proposals knob controls the total budget.

GLE colored-noise Langevin

Optimal-sampling drift matrix from eindir fits the Move slot; BAB propagator + stationary reseed flattens efficiency across a wide frequency band.

On objectives with gradients, this gives larger coherent moves than white-noise Langevin without changing the accept law.

Rank-1 additive independence

Separable Chebyshev surrogate fitted on values only; O(d) per proposal via product of 1D tempered marginals + Metropolis correction.

The surrogate proposes from a cheap approximation and the Metropolis correction keeps the target objective authoritative.

QMC / shifted-QMC polish

Projected-gradient Armijo backtracking on low-discrepancy (or shifted-replicate) starts.

This turns a stochastic incumbent into a reproducible local finish when the objective exposes enough smoothness.

Device, ensemble, reuse

run_device (NumPy or CuPy) and run_ensemble (batched) execute the identical transition kernel.

The reuse table (dimension scale, rank-1 independence, GLE drift, batched device, noise-aware Accept, QMC polish) is the concrete payoff of the factoring: one implementation change serves every preset and advanced driver.

See the architecture page for the five signatures and L1-L4, and the algebra explanation (T4) for the TLA+ invariants they enable.

What to Read First

• Quickstart shows the smallest Python workflow.

• Choose a driver maps landscape symptoms to driver families.

• Presets and advanced drivers gives the parameter surface.

• The generated Rust API starts at Rust API Reference and follows the anneal-core crate modules.

• Used by links the reproducibility harness that regenerates the CUTEst tables and figures.

Getting started

• Quickstart
• Classical Presets
• Cluster Search
• Bayesian Pilot and Mixer
• GLE Colored-Noise Langevin
• Prerequisites
• Step 1: Define obj + grad
• Step 2: Call gle_langevin (the exposed driver)
• Step 3: The thermostat inside (what the algebra buys)
• Why this works
• Polish, Device, and Scale

How-to Guides

• Installation
• Decision Tree
• Three Channels
• How do I pick between the presets?
• What is the Bayesian mixer and when does it help?
• Do I need to supply a gradient?
• Precision and float16/float32 policy?
• Reproducibility guarantees?
• FAQ

Explanation

• Architecture
• The five components (signatures)
• The four laws (plain English)
• Reuse table (the concrete payoff)
• How every advanced driver is still just the algebra
• Bayesian Pilot and Mixer Details
• GLE Mechanics

Reference

• Specification
• Rust API Reference
• Rust API (anneal-core)
• Glossary
• Classical (values only)
• Pilot and low-discrepancy
• Polish
• Advanced drivers
• Device and ensemble (same kernel)
• Hamiltonian Monte Carlo (HMC) / quasi-Monte Carlo (QMC) variants (also exposed)
• Bindings
• Device backend, ensembles, and noise-aware acceptance
• Changelog
• Used By

Development

• Contributing
• Best Practices for anneal
• Code of Conduct

Background

anneal is implemented in Rust (anneal-core) with Python bindings (anneal) and a C ABI. It rests on eindir for the Objective trait, Bounds clipping, low-discrepancy generators, GLE thermostat matrices, and surrogate primitives. All drivers are expressed through the same Sampler trait surface; the IISE paper supplies the mechanized proofs and the TLA+ Workflow specification.

The reproducibility package anneal_repro regenerates every number, CUTEst profile, and figure from the paper sources (see used_by).