heuropt 0.11.0

A practical Rust toolkit for heuristic single-, multi-, and many-objective optimization.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# Stability and SemVer

heuropt is pre-1.0. The public API may change between minor versions.
This page sets explicit expectations.

## What "public API" means in heuropt

The crate's public surface is everything re-exported from
[`heuropt::prelude`] plus the items reachable from `heuropt::core`,
`heuropt::traits`, `heuropt::operators`, `heuropt::algorithms`,
`heuropt::pareto`, `heuropt::metrics`, and `heuropt::selection`.

Items in `heuropt::internal` (e.g. the Cholesky / eigendecomposition
helpers) are **not** public API. They may change between any two
versions — use them at your own risk.

## SemVer in heuropt 0.x

While we are pre-1.0:

- **Minor bumps (`0.10 → 0.11`) may break the public API.** The
  CHANGELOG calls out everything that changed, and a **migration
  guide** in this book documents the move.
- **Patch bumps (`0.10.0 → 0.10.1`) only contain bug fixes,
  performance improvements, and additive non-breaking features.**
  No deprecations, no removals.

## What's actually likely to change before 1.0

In rough order of likelihood:

1. **Algorithm config structs may gain fields.** All current configs
   are public-field structs; adding a non-`Default` field is a
   breaking change. We may switch to builder patterns to avoid this
   class of break, or we may add `#[non_exhaustive]`.
2. **Some operators may move between `operators` and `pareto`** as
   the boundary between "things that produce candidates" and "Pareto
   utilities" gets clearer.

What is **not** likely to change:

- The `Problem` trait shape.
- The `AsyncProblem` / `AsyncPartialProblem` trait shapes.
- The `Variation` / `Initializer` / `Repair` traits.
- The `Optimizer<P>` trait — single `run` method, no callbacks.
- The `Evaluation` / `Candidate` / `Population` / `OptimizationResult`
  data types.
- The seeded determinism property.

## What "bit-identical" means for stability

heuropt promises that a given algorithm + seed + config produces the
same numeric output on the same minor version of heuropt.

Across minor versions, output may change if an algorithm's
implementation changes (e.g. a perf rewrite that reorders
floating-point operations, or a new feature that changes the
RNG-consumption pattern). The CHANGELOG calls this out explicitly
when it happens. As of v0.8, the entire history of perf
optimizations has been bit-identical against the v0.3.0 reference.

## MSRV (minimum supported Rust version)

heuropt's MSRV is **1.85** as of v0.10. This is tested in CI against
every PR.

MSRV bumps are treated as patch-bump-eligible (they don't break the
public API). When the MSRV is bumped, the CHANGELOG entry for that
release will note the new MSRV.

## Feature-flag stability

The current optional features:

- `serde` — adds `Serialize` / `Deserialize` derives on the core data
  types.
- `parallel` — rayon-backed parallel population evaluation.
- `async` — `AsyncProblem` + `AsyncPartialProblem` traits, plus a
  `run_async` method on every algorithm in the catalog, for
  IO-bound evaluations.

Features added in 0.x can be renamed or removed in any minor bump
that documents the change. Removing a feature is treated like a
breaking API change.

## How to track changes

- **CHANGELOG.md** — the canonical record of changes per release.
- **Migration guides** — per-release, in this book at
  [migration](./migration.md).
- **GitHub releases** — each tag has release notes.
- **Watch the repo** — https://github.com/swaits/heuropt — to be
  notified of new releases.

[`heuropt::prelude`]: https://docs.rs/heuropt/latest/heuropt/prelude/index.html