hyperevolution

hyperevolution is the exact-aware search and proposal layer for the Hyper ecosystem. It defines candidate IDs, genomes, populations, replay policy, exact fitness reports, lexicographic and Pareto comparisons, archives, and policy records for common stochastic and local-search operators.

The crate does not own domain truth. It gives optimizers a shared way to keep proposals, fitness, replay status, and acceptance evidence together.

Hyper Ecosystem

hyperevolution is useful when a domain crate can generate candidates cheaply but needs exact replay before accepting them.

• hyperreal: exact scalar genome and fitness values.
• hyperlimit: exact predicate decisions for candidate validation.
• hypersolve: residual replay and constraint certification.
• hypercurve, hyperpath, hyperdrc, hypercircuit, and hyperphysics: domain crates that can certify accepted candidates.

Typical Search Problems

Evolutionary and black-box optimizers often accept candidates because a sampled float objective improved, even when constraints, geometry, or manufacturing rules were evaluated by approximate surrogates. That makes accepted results hard to audit, hard to reproduce, and easy to confuse with proof.

hyperevolution separates exploration from acceptance. A stochastic policy may propose or rank candidates, but archive promotion can depend on exact fitness comparison and domain replay status.

Main Types

• CandidateId, Genome, Candidate, and Population describe search state.
• FitnessValue, FitnessReport, FitnessDirection, FitnessComparison, and ParetoRelation describe exact scalar, lexicographic, interval, and Pareto ordering.
• ReplayPolicy and ReplayStatus capture how exact acceptance is gated.
• Archive stores candidates with replay-aware acceptance status.
• SelectionPolicy, MutationPolicy, CrossoverPolicy, HillClimbPolicy, HillClimbReport, and SimulatedAnnealingPolicy record proposal settings and exact local-search outcomes without implementing every optimizer family.

Precision Model

Genome values and fitness values use Real. Comparison helpers avoid collapsing exact fitness to primitive floats before ordering. Interval fitness uses exact lower and upper endpoints and reports overlap or invalid bounds explicitly rather than ranking by a lossy midpoint. Replay status is explicit, so a candidate that is promising under a sampled or approximate proposal can remain pending or unknown until the domain crate certifies it.

Performance Model

The crate is intentionally light. It stores policies, reports, and archive state without forcing a single optimizer loop. That lets domain crates run fast approximate proposal engines while retaining deterministic seeds, compact records, and exact comparison only where promotion or audit requires it.

Future performance work should focus on batch replay scheduling, archive pruning, and domain-specific caching rather than hiding approximations in the shared types.

Current Status

Implemented today:

• exact candidate IDs, genomes, populations, and replay policy records;
• scalar, lexicographic, interval, and Pareto fitness reports over Real values;
• replay-gated archive records;
• deterministic first/best-improvement hill climbing over exact Real genomes;
• simulated-annealing acceptance classification that keeps worse-move probability handling as an explicit proposal stage;
• deterministic exact-best and explicit-index tournament selection plus exact additive mutation and one-point crossover for Real genomes;
• exact structural diversity reports based on genome equality and arity;
• typed Real GP expression genomes with arity, depth, node-budget, and structurally-zero-division validation before exact evaluation;
• black-box objective and surrogate-screening reports carrying fitness, cost, cache keys, construction dependencies, replay hooks, and promotion status;
• domain replay manifests and reports that name the Hyper crate responsible for certifying a memetic candidate;
• policy carriers for selection, mutation, crossover, hill climbing, and simulated annealing.

Known limits: large optimizer families are not implemented here yet. The crate is the typed boundary those algorithms should use.

Installation

[dependencies]
hyperevolution = "0.2.0"

For sibling checkouts:

[dependencies]
hyperevolution = { path = "../hyperevolution" }

Usage

Use proposal helpers for search mechanics, then require exact replay for promotion:

use hyperevolution::{
    Candidate, CandidateId, FitnessDirection, FitnessReport, FitnessValue, Genome,
    MutationPolicy, ReplayPolicy, ReplayStatus, mutate_exact_delta,
};
use hyperreal::Real;

let candidate = Candidate {
    id: CandidateId::new("seed-0")?,
    genome: Genome { genes: vec![Real::from(2), Real::from(3)] },
    replay_policy: ReplayPolicy { seed: 42, require_exact_replay: true },
};

let mutated = mutate_exact_delta(
    &candidate.genome,
    &MutationPolicy::ExactDelta { gene: 0, delta: Box::new(Real::from(1)) },
)?;

let before = FitnessValue::Scalar(Box::new(Real::from(10)));
let after = FitnessValue::Scalar(Box::new(Real::from(8)));
assert_eq!(after.compare_total(&before, FitnessDirection::Minimize).is_better(), true);

let report = FitnessReport {
    candidate: candidate.id,
    value: after,
    replay: ReplayStatus::Accepted,
    evidence: vec!["domain replay accepted".into()],
};

For multi-objective work, use FitnessValue::Pareto and Archive; for symbolic or memetic search, use GpRealExpr, surrogate-screen reports, and DomainReplayManifest to keep the certifying crate named.

Development

Useful local checks:

cargo test
cargo bench --bench fitness