# Five-minute walkthrough
The shortest path from a fresh project to a working optimizer.
## 1. Add heuropt to your `Cargo.toml`
```toml
[dependencies]
heuropt = "0.5"
```
The default feature set is small. Optional features:
- `parallel` — rayon-backed parallel population evaluation.
- `serde` — `Serialize` / `Deserialize` derives on the core data
types.
```toml
heuropt = { version = "0.5", features = ["parallel"] }
```
## 2. Define a problem
A problem is a struct that implements the [`Problem`] trait. You tell
heuropt what kind of decision your problem takes (`Vec<f64>`,
`Vec<bool>`, …), what objectives it has (minimize or maximize), and
how to score one decision.
```rust,no_run
use heuropt::prelude::*;
struct Sphere;
impl Problem for Sphere {
type Decision = Vec<f64>;
fn objectives(&self) -> ObjectiveSpace {
ObjectiveSpace::new(vec![Objective::minimize("f")])
}
fn evaluate(&self, x: &Vec<f64>) -> Evaluation {
let f: f64 = x.iter().map(|v| v * v).sum();
Evaluation::new(vec![f])
}
}
```
The Sphere function is a single-objective continuous problem: minimize
`f(x) = Σ xᵢ²`. The optimum is `x = 0`, `f = 0`.
## 3. Pick an algorithm and run it
For a smooth single-objective continuous problem, [`CmaEs`] is a
strong default. Configure it, build it, run it.
```rust,no_run
# use heuropt::prelude::*;
# struct Sphere;
# impl Problem for Sphere {
# type Decision = Vec<f64>;
# fn objectives(&self) -> ObjectiveSpace {
# ObjectiveSpace::new(vec![Objective::minimize("f")])
# }
# fn evaluate(&self, x: &Vec<f64>) -> Evaluation {
# Evaluation::new(vec![x.iter().map(|v| v * v).sum::<f64>()])
# }
# }
let bounds = RealBounds::new(vec![(-5.0, 5.0); 5]); // 5-dim search box
let mut opt = CmaEs::new(
CmaEsConfig {
population_size: 12,
generations: 80,
initial_sigma: 1.0,
eigen_decomposition_period: 1,
initial_mean: None,
seed: 42,
},
bounds,
);
let result = opt.run(&Sphere);
let best = result.best.expect("at least one feasible candidate");
println!("best f = {:.3e} at x = {:?}", best.evaluation.objectives[0], best.decision);
```
Run with `cargo run --release` — heuristic optimization is allergic
to debug builds. Expect output like:
```text
best f = 1.4e-29 at x = [-1.6e-15, 4.5e-16, ...]
```
CMA-ES drops to machine epsilon on the Sphere in well under 80
generations.
## 4. What just happened
- [`Problem`] is the **what** you're optimizing.
- [`CmaEs`] (or any other optimizer) is the **how**.
- [`CmaEsConfig`] is a plain public-field struct: there are no
builders, no chained setters, just public fields you set
directly.
- [`Optimizer::run`] returns an [`OptimizationResult`] containing the
full final `population`, the `pareto_front` (just the best for
single-objective), the `best` candidate, the total `evaluations`,
and the number of `generations`.
## 5. Where to go next
- **Multi-objective:** see [Defining a problem](./defining-problems.md)
for how to express two or more objectives, and
[Choosing an algorithm](./choosing-an-algorithm.md) for which
optimizer fits.
- **Want to know which algorithm to pick:** read the README's
decision tree, or jump straight to the [choosing-an-algorithm](./choosing-an-algorithm.md)
chapter for the long form.
- **Production patterns:** the [cookbook](./cookbook.md) has recipes
for parallelism, expensive evaluations, comparing algorithms, and
more.
[`Problem`]: https://docs.rs/heuropt/latest/heuropt/core/problem/trait.Problem.html
[`Optimizer::run`]: https://docs.rs/heuropt/latest/heuropt/traits/trait.Optimizer.html
[`OptimizationResult`]: https://docs.rs/heuropt/latest/heuropt/core/result/struct.OptimizationResult.html
[`CmaEs`]: https://docs.rs/heuropt/latest/heuropt/algorithms/cma_es/struct.CmaEs.html
[`CmaEsConfig`]: https://docs.rs/heuropt/latest/heuropt/algorithms/cma_es/struct.CmaEsConfig.html