Anneal

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.
Docs https://anneal.rgoswami.me
License MIT
Software DOI https://zenodo.org/doi/10.5281/zenodo.10672746
Paper reproducibility https://github.com/HaoZeke/anneal_repro — Zenodo 10.5281/zenodo.20672620
History Continuous development since 2023-02 (see git log); multi-author CITATION.cff

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:

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)

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 .

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).

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rgoswami from gravatar.com rgoswami

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Rohit Goswami

Maintainer: Rohit Goswami

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

cutest gpu plotter testing

Tags

optimization algorithms simulated-annealing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

anneal-0.9.0.tar.gz (4.0 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

anneal-0.9.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

anneal-0.9.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

anneal-0.9.0-cp310-abi3-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

anneal-0.9.0-cp310-abi3-macosx_10_12_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file anneal-0.9.0.tar.gz.

File metadata

  • Download URL: anneal-0.9.0.tar.gz
  • Upload date:
  • Size: 4.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for anneal-0.9.0.tar.gz
Algorithm Hash digest
SHA256 a7f550a57883aea603e14b464d457ace069e5cabd5e9daaf48a37f61d8bc5487
MD5 2d20807f094b43324f644109e338e739
BLAKE2b-256 53007e77ad40e5a04850046f1c846c9068929091b0bb0cb86e5a42ccc0d36a2c

See more details on using hashes here.

Provenance

The following attestation bundles were made for anneal-0.9.0.tar.gz:

Publisher: release.yml on HaoZeke/anneal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file anneal-0.9.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for anneal-0.9.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f388e943b77a4f740f26bb2c5f8f913caa1bc8410305aa27edfd1720d6451ea8
MD5 8c5d20f89a8b12ecaf85808f02e8316b
BLAKE2b-256 74d9e1b4ec0c24c04095d0d638a8e70913a5795653a8ebe829cd40b254b18a4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for anneal-0.9.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on HaoZeke/anneal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file anneal-0.9.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for anneal-0.9.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ce43977e8175389ae6b71c2e99d784786e6bd8c684a8f30e5f1b754845ebd919
MD5 c18e5216aaaf0c56c633885764302904
BLAKE2b-256 8d3b5eec807dc686930cc19142c599b434207b228fc6f988cbd92dff4babd7ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for anneal-0.9.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on HaoZeke/anneal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file anneal-0.9.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for anneal-0.9.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8599036326fdc72014d5a36b9bd2ee577c7926e14831db841f0fe65c1df91910
MD5 9613e2a3b9cfab436a77583d94536a02
BLAKE2b-256 456448918ab0e5e0ea30628e7c27ff260fc9dd1306dc645fd4d46238f814c466

See more details on using hashes here.

Provenance

The following attestation bundles were made for anneal-0.9.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on HaoZeke/anneal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file anneal-0.9.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for anneal-0.9.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6fea8850390dc5b4e8fc71db9b5b27c95d217ff3fbac82067d1624e4619e5822
MD5 75a85dc9c7b6b8b90cfd013b5b9a0aef
BLAKE2b-256 053b89e91711d0e72c763f1c83fa396cf7682e761053b25fb5a84e4912c20e46

See more details on using hashes here.

Provenance

The following attestation bundles were made for anneal-0.9.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on HaoZeke/anneal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page