feat(problems): binary and combinatorial problems, batch 12, each with its own example

AGENTS.md

@@ -136,7 +136,7 @@ Stops: `Stop::target(score)` (at least as good), `generations(n)`, `evaluations(
 - Maximize is the default; use `.minimize()`, don't negate.
 - `None`, `Fitness::invalid()` and NaN are invalid: worse than everything.
 - **Constraints:** return `(score, violation)`, 0 when feasible, adding up `constraint::at_most(value, limit)`, `at_least`, `equal(value, target, tolerance)`. Deb's rules: feasible beats infeasible, then score or violation decides. Select with `Tournament` or `Rank`: roulette and SUS give infeasible solutions no weight. `Penalty::new(weight)?.fitness(objective, score, violation)` is a static penalty instead.
-- **Test problems:** `problems::{Sphere, AxisParallelEllipsoid, Schwefel1_2, Rastrigin, Rosenbrock, Ackley, Griewank, Schwefel2_26, Levy, Zakharov, StyblinskiTang, Michalewicz, Schwefel2_21, Schwefel2_22, DixonPrice, Trid, Powell, SumOfDifferentPowers, Step, Quartic, Penalized1, Penalized2, HighConditionedElliptic, BentCigar, Discus, DifferentPowers, BucheRastrigin, NonContinuousRastrigin, Weierstrass, Katsuura, HappyCat, HgBat, SchafferF7, RotatedHyperEllipsoid}::new(n)` (`Powell` takes a multiple of 4; `Quartic::noisy(n)` adds noise drawn from the genome) and `problems::{Himmelblau, Branin, GoldsteinPrice, SixHumpCamel, Hartmann3, Hartmann6, Shekel5, Shekel7, Shekel10, Easom, Eggholder, SchafferF6, Beale, Booth, Matyas, Bohachevsky1, Bohachevsky2, Bohachevsky3, ThreeHumpCamel, Langermann, ShekelFoxholes, Kowalik}` are fitness functions for `Engine::new(algorithm, problem)`, all minimized. The `problems::Problem` trait gives `representation()` (the bounds), `optimum()` (`value()`, `solutions()`), `reference()`; `problems::all()` lists them as `Box<dyn DynProblem>`. `problems::Shifted::new(problem, seed)` and `problems::Rotated::new(problem, seed)` make CEC/BBOB-style instances of any of them (e.g. CEC 2005's F10: `Rotated::new(Shifted::new(Rastrigin::new(n), seed), seed)`), keeping the optimum's value and what the wrapped problem provides: its gradient (by the chain rule through the rotation), constraint values and their Jacobian. Constrained, with fitness `(score, violation)` and `constraints(&x)` (`g <= 0`, then `h = 0`): `problems::cec2006::{G01, …, G24}` (equalities met within `EQUALITY_TOLERANCE` = 1e-4; `with_tolerance(δ)` for the problems with equalities, e.g. `G03::with_tolerance(δ)`), and `problems::engineering::{WeldedBeam, WeldedBeamRagsdell, PressureVessel, TensionCompressionSpring, SpeedReducer, ThreeBarTruss, CantileverBeam, CarSideImpact}`. `PressureVessel` and `SpeedReducer` round their discrete genes when evaluated; `design(&x)` gives the rounded design. `engineering::GearTrain` has an `Integer` genome and isn't in `all()`. `Optimum::is_proven()` is false for a best known value.
+- **Test problems:** `problems::{Sphere, AxisParallelEllipsoid, Schwefel1_2, Rastrigin, Rosenbrock, Ackley, Griewank, Schwefel2_26, Levy, Zakharov, StyblinskiTang, Michalewicz, Schwefel2_21, Schwefel2_22, DixonPrice, Trid, Powell, SumOfDifferentPowers, Step, Quartic, Penalized1, Penalized2, HighConditionedElliptic, BentCigar, Discus, DifferentPowers, BucheRastrigin, NonContinuousRastrigin, Weierstrass, Katsuura, HappyCat, HgBat, SchafferF7, RotatedHyperEllipsoid}::new(n)` (`Powell` takes a multiple of 4; `Quartic::noisy(n)` adds noise drawn from the genome) and `problems::{Himmelblau, Branin, GoldsteinPrice, SixHumpCamel, Hartmann3, Hartmann6, Shekel5, Shekel7, Shekel10, Easom, Eggholder, SchafferF6, Beale, Booth, Matyas, Bohachevsky1, Bohachevsky2, Bohachevsky3, ThreeHumpCamel, Langermann, ShekelFoxholes, Kowalik}` are fitness functions for `Engine::new(algorithm, problem)`, all minimized. The `problems::Problem` trait gives `representation()` (the bounds), `optimum()` (`value()`, `solutions()`), `reference()`; `problems::all()` lists them as `Box<dyn DynProblem>`. `problems::Shifted::new(problem, seed)` and `problems::Rotated::new(problem, seed)` make CEC/BBOB-style instances of any of them (e.g. CEC 2005's F10: `Rotated::new(Shifted::new(Rastrigin::new(n), seed), seed)`), keeping the optimum's value and what the wrapped problem provides: its gradient (by the chain rule through the rotation), constraint values and their Jacobian. Constrained, with fitness `(score, violation)` and `constraints(&x)` (`g <= 0`, then `h = 0`): `problems::cec2006::{G01, …, G24}` (equalities met within `EQUALITY_TOLERANCE` = 1e-4; `with_tolerance(δ)` for the problems with equalities, e.g. `G03::with_tolerance(δ)`), and `problems::engineering::{WeldedBeam, WeldedBeamRagsdell, PressureVessel, TensionCompressionSpring, SpeedReducer, ThreeBarTruss, CantileverBeam, CarSideImpact}`. `PressureVessel` and `SpeedReducer` round their discrete genes when evaluated; `design(&x)` gives the rounded design. `engineering::GearTrain` has an `Integer` genome and isn't in `all()`. `Optimum::is_proven()` is false for a best known value. On bit strings (`Binary` genomes, `Bits`), maximized, not in `all()`: `problems::binary::{OneMax, LeadingOnes}::new(n)`, `Trap::new(blocks, k)` (Deb and Goldberg's trap: a = k − 1, b = k, z = k − 1; `with_values(blocks, k, a, b, z)?`), `RoyalRoad::{r1, r2}()` (`new(blocks, size)`, `hierarchical(blocks, size)`), `NkLandscape::new(n, k, Neighborhood::{Adjacent, Random}, seed)?` and the 0/1 knapsack, `Knapsack::generator(KnapsackClass::..., items).seed(s).generate()?` (Pisinger's classes, fitness `(profit, violation)`; `Knapsack::new(weights, profits, capacity)?` for given items); the NK landscapes' and knapsacks' `optimum()` is computed exactly (dynamic programming, or every string of a small NK landscape), `None` when too large. Python: `gx.problems.binary`.
 - **Extras:** return `Evaluated::new(value, info)` (`value` any of the above, `info` any `Send + Sync + 'static` type, e.g. a struct with a penalty's terms) to keep what the fitness function computed. Read it by type: `outcome.best_info::<T>()`, `snapshot.info::<T>(genome)` and `snapshot.best_info::<T>()` in `.on_generation`, `hall_of_fame.info::<T>(genome)`, and in `MultiEngine` `snapshot.info` and `outcome.info(genome)` for the front; `None` for another type. Never used by the search. Kept by genome for the population, the discarded and the best (copies share it); not in checkpoints.
 - **Gradients:** `Differentiable(|x: &Reals, gradient: &mut [f64]| value)`, for gradient-based methods; see [Gradients](#gradients-supplying-them).
 - **Constraint values:** `Constrained::new(m, |x: &Reals, g: &mut [f64]| score)` writes the values of m constraints `gᵢ(x) <= 0`; `Constrained::differentiable(m, |x, gradient, g, jacobian| score)` also the gradient and the Jacobian (`jacobian[i * n + j]` = ∂gᵢ/∂xⱼ). Either is `(score, Σ max(0, gᵢ))` for any algorithm, and gives the values one by one to those that use them (`Mma`). The CEC 2006 problems with inequalities only and the engineering problems give their values (`problem.provides().inequalities`), shifted or rotated too, not their gradients.

docs/features.md

@@ -74,6 +74,7 @@ What genoxide has on main; [docs.rs](https://docs.rs/genoxide) documents the lat
   - **Integer genomes:** the genes rounded inside the kernel (Garrido-Merchán and Hernández-Lobato 2020), the acquisition maximized on the lattice by a hill climb (every point of a small lattice at once), the run finished once the lattice is evaluated.
 - **Gaussian processes** (`model::gp`, unstable for one release): regression with a constant mean, an ARD Matérn 5/2 or squared exponential kernel, no noise by default (the model interpolates a deterministic function) or learned noise, inputs scaled to the unit cube and outputs standardized; hyperparameters by maximum marginal likelihood (Rasmussen and Williams, eq. 2.30 and 5.9) with genoxide's L-BFGS-B from fixed and seeded random starts; the posterior mean and variance with their gradients; Cholesky factorizations with a growing jitter. In Python as `gx.model.gp`.
 - **Test problems** (`problems`): Sphere, the axis-parallel ellipsoid, Schwefel 1.2 and 2.26, Rastrigin, Rosenbrock, Ackley, Griewank, Levy, Zakharov, Styblinski-Tang, Michalewicz, Himmelblau, Branin, Goldstein-Price, the six-hump camel, Hartmann's functions in 3 and 6 dimensions, Shekel's with 5, 7 and 10 wells, Easom, the eggholder, Schaffer's F6, Schwefel 2.21 and 2.22, Dixon-Price, Trid, Powell's singular function, Beale, Booth, Matyas, Bohachevsky's three functions, the three-hump camel, Langermann, Shekel's foxholes, Kowalik, the sum of different powers, the step function, the quartic (with or without noise), Yao, Liu and Lin's two penalized functions, the high-conditioned elliptic, the bent cigar, the discus, BBOB's different powers, Büche-Rastrigin, the non-continuous Rastrigin, Weierstrass, Katsuura, HappyCat, HGBat, Schaffer's F7 and the rotated hyper-ellipsoid, each with its bounds, known optimum (or best known, for those found numerically) and reference, in Rust and Python, and the analytic gradient of all but seven (the eggholder, Schwefel 2.21 and 2.22, the step function, the non-continuous Rastrigin, Katsuura and the noisy quartic, whose derivative is undefined or 0 on sets of positive measure); and shift and rotation wrappers, generated from a seed, for CEC- and BBOB-style instances of any of them, which pass on the wrapped problem's gradient (by the chain rule), constraint values and Jacobian.
+- **Binary and combinatorial test problems** (`problems::binary`), maximized, on bit strings: OneMax and LeadingOnes (Droste, Jansen and Wegener), Deb and Goldberg's deceptive trap in blocks of any size, with any slopes (Ackley's included), Mitchell, Forrest and Holland's royal roads R1 and R2 and their forms of any size, Kauffman and Weinberger's NK landscapes with adjacent or random neighbors, and the 0/1 knapsack with Pisinger's eleven generated instance classes (uncorrelated, weakly, strongly, inverse strongly and almost strongly correlated, subset sum, similar weights, spanner, multiple strongly correlated, profit ceiling and circle) or given items. NK landscapes and knapsack instances are drawn from a seed with the portable random numbers, the same on every platform, and their optimum is computed exactly: by dynamic programming (the knapsack, and NK landscapes with adjacent neighbors) or by evaluating every string in Gray code order (small NK landscapes). In Rust and Python.
 - **Constrained test problems:** CEC 2006's g01-g24 (`problems::cec2006`), and the engineering design problems (`problems::engineering`): the welded beam in two forms, the pressure vessel, the tension/compression spring, the speed reducer, the gear train (integer), the three-bar truss, the cantilever beam and the car side impact, each with its optimum or best known solution and references, in Rust and Python. Those with inequalities only give their constraints' values one by one to the algorithms that use them.
 
 ## Multi-objective
@@ -120,7 +121,12 @@ Each example in [examples/](../examples/) is a folder with the same program in R
 
 ```text
 cargo run --release --example one_max             # binary genome, GA
-cargo run --release --example knapsack            # a constraint with Deb's feasibility rules
+cargo run --release --example leading_ones        # the (1+1) evolutionary algorithm, Θ(n²) steps
+cargo run --release --example deceptive_trap      # fully deceptive blocks, solved by two-point crossover
+cargo run --release --example royal_road_r1       # hill climbing beats a GA on the royal road R1
+cargo run --release --example royal_road_r2       # the hierarchical royal road R2, a GA
+cargo run --release --example nk_landscape        # an NK landscape, iterated local search against exhaustive search
+cargo run --release --example knapsack            # Pisinger's knapsack instances, Deb's rules and dynamic programming
 cargo run --release --example n_queens            # permutation, (μ+λ)
 cargo run --release --example tsp_berlin52        # TSPLIB berlin52, simulated annealing with 2-opt moves
 cargo run --release --example jobshop_ft06        # job shop ft06, permutation with repetition