Bindings

1 Python (maturin)

The Python package anneal ships from PyPI as a maturin-built wheel. The Rust extension is exposed as the submodule anneal._core. The package source lives at python/anneal/ in the repo and is installed via maturin develop --features python during development.

2 C and C++ (cargo-c)

The Rust crate produces a cdylib, staticlib, generated header anneal-core.h, and pkg-config metadata anneal-core.pc via cargo-c.

cargo cinstall --release --prefix /usr/local
pkg-config --cflags --libs anneal-core

A hand-written companion header anneal-core.hpp wraps the C declarations in namespace anneal for ergonomic C++ usage.

3 Build-system glue

3.1 Meson

anneal_core_dep = dependency('anneal-core')
executable('myprog', 'main.cpp', dependencies: anneal_core_dep)

3.2 CMake

find_package(PkgConfig REQUIRED)
pkg_check_modules(ANNEAL_CORE REQUIRED IMPORTED_TARGET anneal-core)
target_link_libraries(myprog PRIVATE PkgConfig::ANNEAL_CORE)

3.3 Tiny C example (preset + run)

#include <anneal-core.h>
#include <stdio.h>

static double rosen(const double *x, void *user) {
    (void)user;
    return (1.0 - x[0])*(1.0 - x[0]) + 100.0*(x[1] - x[0]*x[0])*(x[1] - x[0]*x[0]);
}

int main(void) {
    double low[2] = {-5.0, -5.0};
    double high[2] = {5.0, 5.0};
    AnnealHandle *h = anneal_boltzmann(rosen, NULL, low, high, 2, 5.0, 0.5);
    anneal_run(h, 20, 80, 42);
    double best[2];
    double val = anneal_best(h, best, 2);
    printf("best val %.6f at (%.4f, %.4f)\n", val, best[0], best[1]);
    anneal_free(h);
    return 0;
}

3.4 Tiny C++ example (using the hand-written header)

#include <anneal-core.hpp>
#include <iostream>

double rosen(const double* x, void*) {
    return (1.0 - x[0])*(1.0 - x[0]) + 100.0*(x[1]-x[0]*x[0])*(x[1]-x[0]*x[0]);
}

int main() {
    std::array<double,2> lo{-5, -5}, hi{5, 5};
    auto h = anneal::make_boltzmann(rosen, nullptr, lo.data(), hi.data(), 2, 5.0, 0.5);
    h.run(20, 80, 42);
    auto [pos, val] = h.best();
    std::cout << "best " << val << " at " << pos[0] << "," << pos[1] << "\n";
}