Struct Archive 

pub struct Archive { /* private fields */ }

CVT quality-diversity archive: capacity niches, each holding the best solution found for it.

Implementations

impl Archive

pub fn try_new( dim: usize, qd_lb: &[f64], qd_ub: &[f64], capacity: usize, samples_per_niche: usize, rng: &mut Rng, ) -> Result<Self, &'static str>

Construct a validated CVT archive.

Errors

Returns an error if dim or capacity is zero, if the descriptor bound slices are empty or of unequal length, or if any bound pair is non-finite or does not satisfy lower < upper.

pub fn new( dim: usize, qd_lb: &[f64], qd_ub: &[f64], capacity: usize, samples_per_niche: usize, rng: &mut Rng, ) -> Self

Construct a CVT archive, panicking on invalid configuration. Prefer Archive::try_new for user-supplied inputs.

Panics

Panics on any configuration Archive::try_new rejects.

pub fn dim(&self) -> usize

Number of decision variables stored for each elite.

pub fn qd_dim(&self) -> usize

Number of behavior-descriptor dimensions.

pub fn capacity(&self) -> usize

Total number of niches.

pub fn occupied(&self) -> usize

Number of niches containing an evaluated elite.

pub fn grid_layout(&self) -> Option<GridLayout>

Exact layout of a regular two-dimensional archive.

Returns None for CVT archives and descriptor dimensions other than two. Use capacity as the coverage denominator and this layout when mapping a niche index to a rendered row.

pub fn grid_shape(&self) -> Option<(usize, usize)>

Shape of a regular two-dimensional archive.

The first component is the number of columns and the second the number of rows. Returns None for CVT archives and for descriptor dimensions other than two. Non-rectangular regular grids report the maximum column count; early rows may contain one additional cell as documented by the archive’s exact-capacity construction.

pub fn seed_uniform(&mut self, lower: &[f64], upper: &[f64], rng: &mut Rng)

Seed all niche solutions with uniform random samples in [lower, upper] (never evaluated — they serve as the initial SBX/Iso parent pool, as the Python original documents).

Panics

Panics if lower.len() or upper.len() differs from the archive’s decision dimension.

pub fn index_of_niche(&self, d: &[f64]) -> usize

Index of the niche whose center is nearest the (encoded) descriptor.

Panics

Panics if d.len() differs from the archive’s descriptor dimension.

pub fn set(&mut self, i: usize, y: f64, d: &[f64], x: &[f64])

Add a solution to niche i if it improves it.

Panics

Panics if i is not below the archive capacity, or if d or x do not match the descriptor and decision dimensions.

pub fn update( &mut self, xs: &[Vec<f64>], fitness: &mut dyn QdFitness, ) -> (Vec<f64>, Vec<f64>)

Evaluate xs, add to the archive, and return (improvements, real_ys) where improvement = fitness - niche's previous fitness (negative is an improvement — the objective the Diversifier’s optimizer minimizes).

Panics

Panics if fitness returns a descriptor whose length differs from the archive’s descriptor dimension.

pub fn update_evaluated( &mut self, xs: &[Vec<f64>], evaluations: &[(f64, Vec<f64>)], ) -> Result<(Vec<f64>, Vec<f64>), &'static str>

Apply already evaluated (fitness, descriptor) values in input order. Keeping this step separate lets callers parallelize expensive objective functions without concurrently mutating the archive.

Errors

Returns an error if evaluated does not have the same length as xs.

pub fn update_batch( &mut self, xs: &[Vec<f64>], fitness: &mut dyn QdBatchFitness, ) -> Result<(Vec<f64>, Vec<f64>), &'static str>

Evaluate and apply a complete batch. Evaluation may be parallel inside fitness; archive updates are deterministic and retain input order.

Errors

Returns an error if fitness does not return exactly one (fitness, descriptor) pair per candidate.

pub fn argsort(&mut self)

Re-sort niche indices ascending by fitness.

pub fn random_xs( &self, best_n: usize, chunk: usize, rng: &mut Rng, ) -> Vec<Vec<f64>>

Sample chunk solutions from the best best_n niches (by fitness).

pub fn random_x_one(&self, best_n: usize, rng: &mut Rng) -> (Vec<f64>, f64)

A random solution from the best best_n niches (with fitness).

pub fn best_y(&self) -> f64

Lowest finite quality currently stored, or infinity for an empty archive.

pub fn qd_score(&self) -> f64

QD-score matching Python Archive.get_qd_score: for an all-positive archive, sum reciprocal fitness; otherwise sum the negated negative fitness values. Higher is better in both cases.

pub fn ys(&self) -> &[f64]

Per-niche quality values; empty niches contain infinity.

pub fn xs(&self) -> &[Vec<f64>]

Per-niche decision vectors.

pub fn descriptors(&self) -> &[Vec<f64>]

Per-niche behavior descriptors.

pub fn counts(&self) -> &[u64]

Number of evaluated candidates mapped to each niche.

pub fn occupied_data(&self) -> Vec<(Vec<f64>, f64, Vec<f64>)>

Occupied (x, y, descriptor) triples.