Architecture

1 Layout

anneal/
  Cargo.toml          Rust crate (lib + cdylib + staticlib)
  src/                Rust source
  include/            hand-written C++ companion header
  python/anneal/      Python package (mixed maturin layout)
  pytest/             pytest suite
  docs/               this documentation

2 Crate types

The Rust crate produces three artefacts:

• rlib for downstream Rust consumers

• cdylib for Python (pyo3) and C dynamic loading

• staticlib for C/C++ static linking

3 Bindings

• *Python.

4 anneal._core is the Rust extension; the user-facing package anneal re-exports both Rust types and pure-Python helpers from a mixed-mode maturin layout.

• *C.

5 cargo-c produces anneal-core.h and libanneal_core.{a,so} with pkg-config integration via anneal-core.pc.

• *C++.

6 The hand-written include/anneal-core.hpp wraps the C ABI in namespace anneal for ergonomic C++ use.

7 The five signatures (summary)

See algebra for the full types and the mapping to the TLA+ invariants. In one sentence each:

• Obj is the only component that knows F.

• Cool is the only component that knows the schedule T(k).

• Neigh knows the scale at T.

• Move knows the proposal shape at T (this is where GLE, independence, and the classical visit distributions live).

• Accept knows the acceptance rule (and the three finite-precision channels).

8 The four laws (summary)

L1 symmetry, L2 support, L3 downhill=1, L4 monotone in T. Each is required both for the TLA+ safety invariants (TypeOK, BestMonotone, SymmetricNeighbors, MonotoneCooling) and for the “one change serves all” property.

9 Cooperative cluster population

Four replicas divide the charged-work budget across processor elements without turning the search into four unrelated restarts. Each replica owns a monotone event sequence and a local hop ledger. The coordinator admits a candidate only after a fresh quench and descriptor validation, deduplicates replayed events, and maintains per-replica plus aggregate work totals. A disconnected replica continues locally; its fallback is explicit in the trace rather than silently changing the accounting.

At a synchronization boundary, every replica submits one validated quenched representative. The final submission closes the epoch. The coordinator ranks the population by energy, descriptor novelty, exact-census scarcity, and latent-Gaussian transition uncertainty. A target-free Feynman–Kac potential converts those ranks to bounded weights. Systematic resampling then produces one immutable parent assignment with the same population size. A family cap prevents a single parent from occupying every processor element, and siblings receive distinct deterministic descriptor-space rejuvenation draws.

local hop + charged ledger (one per replica)
                  |
                  v
fresh quench -> validator -> census/catalogue coordinator
                                  |
                    all replicas reach epoch barrier
                                  |
                                  v
                 energy + novelty + scarcity + GMRF uncertainty
                                  |
                                  v
             systematic parents + family cap + rejuvenation
                                  |
                                  v
                  next local epoch on all processor elements

The shared-catalogue ensemble and an ensemble with one private catalogue per replica use identical local budgets and seeds. Their difference is therefore the communication treatment: shared validated evidence versus independent catalogues. The population barrier coordinates division of work; it does not pool unvalidated structures or let one replica spend another replica’s ledger.

This layer takes inspiration from fixed-population diffusion Monte Carlo and the walker-management architecture used by QMC codes. The correspondence is mutation, weighting, resampling, and genealogy. There is no trial wavefunction, imaginary-time Green function, fixed-node constraint, or quantum-energy estimator, so it is not a classical analogue of quantum propagation.

The transition residual field has sparse Gaussian precision equal to a graph Laplacian plus prior and observation terms. Its conditional posterior and marginal variances are Gaussian and are solved directly. This is the latent-GMRF component that an INLA construction would contain, but there is no non-Gaussian likelihood or hyperparameter integral requiring a Laplace approximation. Calling it full INLA would overstate the implementation. The inverse precision is also a screened graph Green function: diagonal terms measure local uncertainty and off-diagonal terms propagate floor evidence along observed basin paths. It is an exact solve on the bounded active graph, not a factorized mean-field closure or an imaginary-time propagator.

The Bayesian layers retain separate conditioning information: discounted Thompson allocation chooses local move arms, a cost-asymmetric screen assigns full quench work, and the GMRF supplies only the cross-replica uncertainty rank. Nested sampling also remains separate because its descending ceiling and live-point volume weights have different semantics from Feynman–Kac genealogy. It is a matched-budget comparison arm, not another weight folded into the cooperative population.

Source: src/cooperative_search.rs, src/cooperative_search/ledger.rs, src/methods/feynman_kac.rs, src/residual_field.rs, src/catalog_rpc/server.rs, and src/methods/nested.rs. The mathematical specification is in docs/derivations/descriptor_catalog_geometry.org.

10 Method Families (detailed)

10.1 Classical presets (Boltzmann, Fast, Gsa)

Slots: Cool + Neigh/Move (the three families differ only in those three slots). On a 2-D Styblinski-Tang problem all three reach the known global basin from the same QMC start in < 2000 evaluations; the only visible difference is the tail behaviour of the proposal (Gaussian vs Cauchy vs Tsallis). Payoff: the orchestrator, device kernel, and Accept are identical for all three. Source: src/variant.rs and the preset constructors in python/anneal/__init__.py.

10.2 Bayesian pilot (bayesian_pilot.rs)

Slots: only ever writes Cool/Neigh/Move hyperparameters. Prior draws (logN on T0/sigma, truncated on q_v), short chains, three-term Laplace posterior (prior + Roberts-Rosenthal 0.234 on logit scale + improvement term), MAP + warm-start. q_vis the continuous model-selection axis between BSA (q_v=1), FSA (q_v=2), and heavy-tail. On a 5-D quadratic the pilot with 20 short chains typically returns a (T0, sigma, q_v) triple that lets a 100-epoch production run beat a hand-tuned classical baseline. Source: src/methods/bayesian_pilot.rs.

10.3 Bayesian mixer / bGSA auto (bayesian_mixing.rs)

Slots: orthogonal lift over any inner Sampler. Single max_proposals knob, auto n_chains= min(budget/64, sqrt(dim)) clamped 2-4, QMC starts via eindir when bounds present, per-chain Beta(4/1,4) on “produced new global best”, Thompson sample every step with 0.05 incumbent guard. The 6-step trace in the Bayesian tutorial shows the alpha/beta updates and the guard in action. Payoff: the user never chooses n_chainsor per-chain schedules; the same mixer works around a classical preset or a GLE inner. Source: src/methods/bayesian_mixing.rs and the Python re-implementation in experiments/scripts/demo_bgsa.py.

10.4 GLE-Langevin (gle_langevin.rs+ eindir gle.rs)

Slots: Move (the GLE object). White-noise Langevin critically damps one frequency; GLE uses ns auxiliary momenta + optimal_{samplingdrift}matrix A so the noise spectrum flattens efficiency across [omega0, 100*omega0]. BAB propagator, stationary reseed per epoch, exact matrix_exp+ ldl_sqrt. On a 5-D Rastrigin the colored-noise version with the fitted drift reaches lower values in the same budget than a plain Langevin at the same omega0. Payoff: the same fitted drift matrix from eindir is dropped into the Move slot of any gradient-capable driver; no per-preset GLE code exists. Source: src/methods/gle_langevin.rs.

10.5 Additive / rank-1 tensor independence (additive_{independence.rs})

Slots: Obj (surrogate for fitting), Move (product of 1-D tempered marginals), Accept (Metropolis on true F), Cool (by tempering). Pilot fits separable Chebyshev surrogate on true Obj, then per-epoch draws full coordinate vector from the product, O(d) per proposal. On a separable 20-D problem the acceptance floor stays high while classical methods collapse. Payoff: one fitted object serves four slots; dimension-free behaviour appears automatically for any separable objective. Source: src/methods/additive_independence.rs.

10.6 Local / QMC / shifted-QMC polish (local_polish.rs)

Slots: Cool (deterministic schedule to zero), Move (projected-gradient backtracking Armijo on a bounded box), Accept (Armijo test). QMC version screens low-discrepancy starts (or shifted replicates), sends top-k to polish. Exposed as the deterministic last mile after any stochastic driver. On the output of a short Bayesian mixer run the polish typically recovers another 1-2 digits. Payoff: the same Armijo logic and low-discrepancy generator are used whether you call polish, qmc_polish, or shifted_qmc_polish. Source: src/methods/local_polish.rs and python/anneal/__init__.py wrappers.

10.7 Observed-cloud SOAP/ACE residual hop (soap.rs)

Slots: Move proposes an ambient analytic-Jacobian pullback of the stacked SOAP plus ACE nu=3 leftover and scales it to the caller’s Cartesian cap. Atomic packing systems use the fivefold residual instead. For molecular and surface systems, every declared movable molecule is retracted by its nearest finite proper rigid motion after scaling; ungrouped atoms keep the ambient step and frozen atoms remain pinned. The Kabsch objective is solved through Horn’s quaternion eigenproblem so planar molecules do not require an invertible covariance. The retraction preserves all intragroup distances while retaining the translation and rotation requested by the descriptor direction. Source: src/soap.rs and docs/derivations/descriptor_catalog_geometry.org, D21a.

10.8 Residual archive search (archive_search.rs)

Slots: the molecular hop on a clone of the caller’s config. Turns on return_screen and symmetrise_on_stall on the clone; never writes Config::recommended. CLI token ras / pair (not FFS archive). At cap > 50000=, N > 70= is one hop that polishes every returning trial (return_polish = R/4, return_polish_after = 0); smaller N is 30 percent skip-return then polish from the same start. Under cap < 50000 the molecular and slab examples keep their own walks. Paired 400000 x 8 on HaoZeke/anneal 0937483: LJ75 1/8 vs rec 0/8 (seed 4 Marks at 234437), LJ38 6/8 both, LJ55 8/8 with mean hit 72022 against rec 77364. Source: src/methods/archive_search.rs.

10.9 Parallel tempering and mcmc_sa

PT is an orthogonal lift (any inner Sampler + geometric ladder (Cool) + swap). mcmc_sais the Gelman-Rubin termination variant of the fixed-K loop. Both still obey the same five signatures and L1-L4. Source: src/methods/parallel_tempering.rs and src/methods/mcmc_sa.rs.

11 Layout (implementation)

(The original crate layout section continues below; the family descriptions above are the “deep” content required by the maximal docs design.)