ultra::search_stats< I, F > Class Template Reference

#include <search_stats.h>

Classes
struct	run_summary
	Summary information for a single run. More...

Public Member Functions
void	update (const I &, const model_measurements< F > &, std::chrono::milliseconds)
std::size_t	best_run () const noexcept
const I &	best_individual () const noexcept
std::set< std::size_t >	good_runs (const model_measurements< F > &) const
const model_measurements< F > &	best_measurements () const noexcept
std::size_t	runs () const noexcept
double	success_rate (const model_measurements< F > &) const noexcept
std::span< const run_summary >	elite_runs (double=0.05) const noexcept

Public Attributes
distribution< F >	fitness_distribution {}
std::chrono::milliseconds	elapsed {0}

Detailed Description

template<Individual I, Fitness F>
class ultra::search_stats< I, F >

Collects statistics across multiple independent search runs.

Template Parameters

I	individual type
F	fitness type

The class stores per-run summaries ordered by best performance, tracks the distribution of fitness values and records runs that satisfy a user-defined success threshold.

Member Function Documentation

best_individual()

template<Individual I, Fitness F>

const I & search_stats::best_individual ( ) const

nodiscardnoexcept

Returns the best individual observed across all runs.

Precondition

runs() > 0

best_measurements()

template<Individual I, Fitness F>

const model_measurements< F > & search_stats::best_measurements ( ) const

nodiscardnoexcept

Returns the measurements associated with the best run.

Precondition

runs() > 0

best_run()

template<Individual I, Fitness F>

std::size_t search_stats::best_run ( ) const

nodiscardnoexcept

Returns the identifier of the best run.

Precondition

runs() > 0

The best run is the one whose measurements compare highest according to model_measurements<F> ordering.

elite_runs()

template<Individual I, Fitness F>

std::span< const typename search_stats< I, F >::run_summary > search_stats::elite_runs ( double perc = 0.05 ) const

nodiscardnoexcept

Returns a view of the top-performing runs.

Parameters

[in]

perc

fraction of runs to include in the elite set (0.0 <= perc <= 1.0)

Returns

span referencing the elite run summaries

The returned span contains the best runs according to model_measurements<F> ordering. Runs are sorted from best to worst, therefore the elite set corresponds to a prefix of the internal run summaries.

The number of runs returned is ceil(runs() * perc). If no runs have been recorded or perc is zero, an empty span is returned.

Note

The returned span remains valid only as long as the object is not modified.

good_runs()

template<Individual I, Fitness F>

std::set< std::size_t > search_stats::good_runs ( const model_measurements< F > & threshold ) const

nodiscard

Returns the identifiers of runs that satisfy the given threshold.

Parameters

[in]

threshold

measurements threshold used to identify successful runs

Returns

set of run identifiers

A run is considered successful when its best measurements compare greater-or-equal to threshold (i.e. best_measurements >= threshold).

If threshold is empty (no criteria set), the returned set is empty.

runs()

template<Individual I, Fitness F>

std::size_t search_stats::runs ( ) const

nodiscardnoexcept

Returns the number of completed runs.

success_rate()

template<Individual I, Fitness F>

double search_stats::success_rate ( const model_measurements< F > & threshold ) const

nodiscardnoexcept

Returns the fraction of runs that satisfy the given threshold.

Parameters

[in]

threshold

measurements threshold used to identify successful runs

Returns

0 when no runs have been recorded; otherwise the fraction of runs whose best measurements satisfy threshold

If threshold is empty (no criteria set), the success rate is 0.

update()

template<Individual I, Fitness F>

void search_stats::update	(	const I &	lr_best_prg,
		const model_measurements< F > &	lr_measurements,
		std::chrono::milliseconds	lr_elapsed )

Updates statistics with the results of a completed run.

Parameters

[in]	lr_best_prg	best individual produced by the completed run
[in]	lr_measurements	measurements associated with the best individual
[in]	lr_elapsed	duration of the completed run

Precondition

lr_measurements.fitness.has_value()

Completed runs are stored in descending lexicographic order of their best measurements:

• higher fitness ranks first;
• when fitness is equal, higher accuracy ranks first;
• for equal fitness, a present accuracy value ranks before std::nullopt.

This ordering is used only to rank completed runs inside stats_; it does not rely on the general ordering semantics of model_measurements<F> (which may, for example, be based on Pareto dominance).

Member Data Documentation

elapsed

template<Individual I, Fitness F>

std::chrono::milliseconds ultra::search_stats< I, F >::elapsed {0}

Total elapsed time across all runs.

This is the sum of the durations passed to update().

fitness_distribution

template<Individual I, Fitness F>

distribution<F> ultra::search_stats< I, F >::fitness_distribution {}

Distribution of finite fitness values observed across runs.

Only runs with finite fitness values contribute to the distribution.

---

The documentation for this class was generated from the following files:

• search_stats.h
• search_stats.tcc