feat: v0.5.0 — comprehensive documentation release
Theme: documentation and project polish. No public-API changes; this is the v0.5 release that elevates heuropt's docs/onboarding/governance to bar-setting status. Adds: - mdbook user guide at docs/book/ with intro, getting-started, defining-problems, choosing-an-algorithm, cookbook (7 recipes), comparison vs other libraries, stability/SemVer, migration guides. Deploys to https://swaits.github.io/heuropt/ via .github/workflows/ docs.yml. - Runnable rustdoc examples on every algorithm (35 of them), all exercised by cargo test --doc. - Three real-world examples: portfolio.rs (multi-obj with budget constraint), hyperparam_tuning.rs (BO + TPE), scheduling.rs (permutation via SA + SwapMutation against Smith's-rule oracle). - Governance: CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md (adopting builderscode.org's Builder's Code of Conduct), GitHub issue templates, PR template. Polishes: - README hero with badges + user-guide link. - lib.rs crate-level docs. - CHANGELOG entry for 0.5.0. Bumps Cargo.toml to 0.5.0.
This commit is contained in:
@@ -0,0 +1,108 @@
|
||||
# Comparison with other libraries
|
||||
|
||||
heuropt is one of many heuristic-optimization libraries. This chapter
|
||||
is an honest, opinionated comparison to help you choose.
|
||||
|
||||
The columns:
|
||||
|
||||
- **Lang** — primary implementation language.
|
||||
- **Algorithms** — rough catalog count.
|
||||
- **Multi-obj** — built-in support for Pareto-based multi-objective
|
||||
optimization.
|
||||
- **Surrogates** — built-in Bayesian / TPE / multi-fidelity.
|
||||
- **Determinism** — seeded reproducibility as a first-class property.
|
||||
- **Async / async-eval** — first-class async runtime support.
|
||||
|
||||
| Library | Lang | Algorithms | Multi-obj | Surrogates | Determinism | Async |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **heuropt 0.5** | Rust | 35 | ✅ NSGA-II/III, SPEA2, IBEA, MOEA/D, MOPSO, SMS-EMOA, HypE, AGE-MOEA, GrEA, KnEA, RVEA, PESA-II, ε-MOEA, PAES | ✅ BO, TPE, Hyperband | ✅ bit-identical seeded | ⏳ planned |
|
||||
| pymoo | Python | ~25 | ✅ extensive | partial (BO via plug-ins) | ✅ | ❌ |
|
||||
| DEAP | Python | flexible toolbox | ✅ | ❌ | ✅ | ❌ |
|
||||
| hyperopt | Python | TPE-focused | ❌ | ✅ TPE | partial | partial |
|
||||
| optuna | Python | TPE / CMA-ES / NSGA-II | ✅ | ✅ TPE, BoTorch via plug-in | ✅ | ✅ |
|
||||
| MOEA Framework | Java | ~40 | ✅ very extensive | ❌ | ✅ | ❌ |
|
||||
| metaheuristics-rs | Rust | ~10 | partial | ❌ | ✅ | ❌ |
|
||||
| argmin | Rust | line-search / quasi-Newton | ❌ | ❌ | ✅ | ❌ |
|
||||
|
||||
## When to pick heuropt
|
||||
|
||||
- You're working in **Rust** and want a single, dependency-light crate
|
||||
for evolutionary / metaheuristic optimization.
|
||||
- You need **multi-objective or many-objective** algorithms (12+
|
||||
Pareto-aware methods in the catalog) AND you don't want to glue
|
||||
Python into your Rust pipeline.
|
||||
- You want **bit-identical determinism**: same seed produces same
|
||||
output, on every machine, across releases unless explicitly noted
|
||||
otherwise.
|
||||
- You want a **small, readable codebase** — every algorithm is
|
||||
written for clarity, no trait-object plumbing, no GATs in user-
|
||||
facing APIs. Reading `RandomSearch` should be enough to write a
|
||||
new optimizer.
|
||||
|
||||
## When *not* to pick heuropt
|
||||
|
||||
- You need **first-class async / await** for evaluations that talk to
|
||||
HTTP services or spawn subprocesses. heuropt is sync; that's on
|
||||
the roadmap but not shipping yet.
|
||||
- You need **gradient-based** optimization. Use `argmin` (Rust) or
|
||||
`scipy.optimize` (Python) — heuropt is gradient-free by design.
|
||||
- You need **GPU-accelerated** evaluations. heuropt's `evaluate`
|
||||
function runs on CPU; use Python (jax/torch) or roll your own
|
||||
GPU pipeline.
|
||||
- You need **distributed multi-machine** evaluation. heuropt
|
||||
parallelizes within one process via rayon. Distribution is up to
|
||||
you (split the seeds across machines, aggregate).
|
||||
- You're comfortable in Python and pymoo / optuna already cover
|
||||
your problem. heuropt's value-add over pymoo is mostly that it's
|
||||
Rust — if that doesn't matter to you, the Python ecosystem has more
|
||||
battle-tested integrations.
|
||||
|
||||
## Algorithm coverage at a glance
|
||||
|
||||
heuropt covers the same major Pareto MOEAs as pymoo and MOEA Framework:
|
||||
NSGA-II/III, SPEA2, IBEA, MOEA/D, MOPSO, SMS-EMOA, HypE, AGE-MOEA,
|
||||
GrEA, KnEA, RVEA, PESA-II, ε-MOEA, PAES.
|
||||
|
||||
The expensive-evaluation regime: BayesianOpt + TPE + Hyperband. This
|
||||
is comparable to optuna's coverage but in pure Rust.
|
||||
|
||||
The single-objective continuous catalog (CMA-ES, IPOP-CMA-ES, sNES,
|
||||
DE, PSO, GA, TLBO, (1+1)-ES, NelderMead, RandomSearch, HillClimber,
|
||||
SimulatedAnnealing) covers the canonical baselines and several modern
|
||||
variants.
|
||||
|
||||
What heuropt does **not** ship that some libraries do:
|
||||
|
||||
- **Re-themed metaphor metaheuristics** (Whale Optimization, Grey
|
||||
Wolf, Bat, Firefly, Harris Hawks, etc.). These are cut from the
|
||||
catalog deliberately — they are mostly DE/PSO with new names. If
|
||||
you specifically need one, please open an issue with citations.
|
||||
- **Non-evolutionary global optimizers** like dual annealing or
|
||||
basin-hopping (use `scipy.optimize` for those).
|
||||
- **A web UI / dashboard** like optuna's. heuropt is library-only.
|
||||
|
||||
## Speed
|
||||
|
||||
heuropt's hot paths (Pareto utilities, hypervolume, key inner loops)
|
||||
are heavily optimized — see the perf entry in the v0.4.0 CHANGELOG.
|
||||
On the comparison harness in `examples/compare.rs` (10-seed mean,
|
||||
30 000 evaluations on DTLZ2), the total wall-clock time across 12
|
||||
algorithms is ~5 seconds. Per-algorithm timings are in
|
||||
[`examples/compare-results.md`](https://github.com/swaits/heuropt/blob/main/examples/compare-results.md).
|
||||
|
||||
For comparison-shopping speed against Python libraries, the gap is
|
||||
typically 10×–100× in heuropt's favor for compute-bound
|
||||
`evaluate` functions, because Rust skips the Python-loop overhead. If
|
||||
your `evaluate` calls into NumPy/PyTorch and those are the bottleneck,
|
||||
the gap shrinks substantially.
|
||||
|
||||
## Honest weakness: ecosystem
|
||||
|
||||
The biggest thing pymoo / optuna / DEAP have that heuropt doesn't:
|
||||
**community + plug-ins + tutorials**. They've been around longer and
|
||||
have rich third-party integrations (visualization, MLflow,
|
||||
Hyperband+BO hybrids, distributed runners). heuropt is younger; the
|
||||
core is solid but the ecosystem is small.
|
||||
|
||||
If you adopt heuropt and miss a thing, the project is small enough
|
||||
that contributions land fast. See [CONTRIBUTING.md](https://github.com/swaits/heuropt/blob/main/CONTRIBUTING.md).
|
||||
Reference in New Issue
Block a user