fcmaes-core

Optimization ecosystem · Shared solver-selection and agent guide

fcmaes-core provides fast, parallel, gradient-free optimization algorithms implemented entirely in Rust. It is the reusable optimizer core of the fcmaes-rust project and does not compile, link, load, or call the historical C++ optimizer backend.

Installation

cargo add fcmaes-core

The minimum supported Rust version is 1.88. The crate depends on crates.io crates only. To build it from source, or to use changes not yet released:

git clone https://github.com/dietmarwo/fcmaes-rust
cd fcmaes-rust
cargo test -p fcmaes-core --locked

[dependencies]
fcmaes-core = { git = "https://github.com/dietmarwo/fcmaes-rust" }

ParetoArchive2D is an exact two-objective Pareto archive with incremental hypervolume, a Rust port derived from bitehv2.h in Aleksey Vaneev’s BiteOpt repository. See PARETO_ARCHIVE.md.

Minimal example

use fcmaes_core::{De, DeParams, Fitness};

fn sphere(x: &[f64]) -> f64 {
    x.iter().map(|value| value * value).sum()
}

fn main() {
    let dim = 5;
    let lower = vec![-5.0; dim];
    let upper = vec![5.0; dim];
    let fitness = Fitness::bounded(dim, 1, &lower, &upper);
    let params = DeParams {
        max_evaluations: 20_000,
        seed: 1,
        ..Default::default()
    };
    let mut optimizer = De::new(fitness, &[], &[], None, &params);
    let result = optimizer.optimize(&sphere);

    println!(
        "value={} evaluations={} x={:?}",
        result.y, result.evaluations, result.x
    );
}

Use optimized builds for real workloads:

cargo run --release

Parallel design: retry and ask/tell

fcmaes-core uses two complementary forms of parallelism to improve the result returned within a fixed wall time:

• retry runs independent optimizer instances on separate workers and keeps the best results. Its closure can wrap fcmaes algorithms or compatible single-threaded optimizers from other crates and FFI libraries.
• ask/tell and batch APIs expose one population for concurrent evaluation. This is especially effective when objective calls are expensive simulations, training jobs, hardware tests, or remote requests.

Every population-based core optimizer has ask/tell or an equivalent batch boundary: DE, active CMA-ES, CR-FM-NES, PGPE, BiteOpt, MODE, MAP-Elites, and Diversifier. Dual Annealing is sequential and has no population ask/tell interface; use retry to parallelize independent Dual Annealing searches.

The controlled GTOP equal-wall campaign uses retry around an external serial CMA-ES implementation. On its fixed 16-core machine and four-second protocol, retry improves mean objective on all seven tested problems over 100 paired seeds per problem. This is scoped experimental evidence, not a guarantee for every workload. When combining outer retry with inner population evaluation, divide the physical cores between the two layers to avoid oversubscription.

Capabilities

• Differential Evolution, active CMA-ES, CR-FM-NES, PGPE and Dual Annealing
• BiteOpt and batched ask/tell optimization
• MODE multi-objective optimization
• exact and sampled hypervolume, IGD/IGD+, GD/GD+, epsilon, spacing, spread, non-dominated sorting, and crowding distance
• independent, coordinated and weighted multi-objective retry
• CVT MAP-Elites, quality-diversity search and the Diversifier
• native multithreading and parallel batch evaluation

API map

Every public item is documented. Module pages provide runnable examples, algorithm references, parameter semantics, stopping behavior, and execution notes. The crate rejects undocumented public additions and broken rustdoc links at compile time.

Documentation

• API reference
• Rendered user guide
• Getting started
• Choosing an optimizer
• Optimizer scope and interoperation
• Optimizer guide
• Retry guide

Avoid CPU oversubscription when combining retry-level and population-evaluation parallelism. Debug builds are not representative of optimizer performance.

License

MIT