pub struct MinSolution { /* private fields */ }Expand description
The outcome of a single lane: its status, its located abscissa, the objective value there, the final bracket width and the work it took.
The fields are private on purpose. The only way to get a number claimed to be
an extremum is Self::extremum, which returns Option<f64> and hands back
Some only for a converged lane. The raw iterate is available from
Self::last_iterate, whose name is chosen so that using it as an answer is
a visible decision in the calling code rather than an accident.
Abscissa versus value. Self::extremum is the argument x* — the
argmin (or argmax). Self::extremal_value is the objective value f(x*)
there. Mixing those two up is the classic minimisation bug, so they are named
apart rather than both being called “the minimum”.
Copy, so it can be read out of a MinBatch without cloning.
§Units
Self::extremum, Self::last_iterate and Self::bracket_width are in
the abscissa’s units; Self::extremal_value and Self::last_value are in
the objective’s units; Self::iterations is a dimensionless count.
Implementations§
Source§impl MinSolution
impl MinSolution
Sourcepub fn extremum(&self) -> Option<f64>
pub fn extremum(&self) -> Option<f64>
The located extremum’s abscissa x*, if this lane converged.
None for every failure status. This is the accessor to reach for; the
Option is the point.
§Returns
Some(x) in the abscissa’s units when Self::status is
MinStatus::Converged, otherwise None. The value returned is the
midpoint of the final bracket, so the worst-case distance to the true
extremum of a unimodal objective is half of Self::bracket_width — but
read the module-level accuracy section before believing a bracket width
below sqrt(eps) * |x|.
Sourcepub fn extremal_value(&self) -> Option<f64>
pub fn extremal_value(&self) -> Option<f64>
The objective value f(x*) at the located extremum, if this lane
converged.
None for every failure status. In the objective’s units, with the
caller’s own sign — nothing is negated for Sense::Maximise.
Sourcepub fn last_iterate(&self) -> f64
pub fn last_iterate(&self) -> f64
The last abscissa the solver held, converged or not.
An extremum only when Self::status is MinStatus::Converged.
For MinStatus::MaxIterations this is the midpoint of the bracket the
lane ran out of iterations on, offered for diagnosis — for deciding
whether the lane was close or wildly off — not as an answer. For
MinStatus::InvalidBracket it is NaN, because there is no honest
number to report.
Sourcepub fn last_value(&self) -> f64
pub fn last_value(&self) -> f64
The objective value at Self::last_iterate, in the objective’s units.
NaN when no meaningful evaluation was reached; for
MinStatus::NotFinite it is the offending non-finite value itself,
which tells you whether the objective overflowed or produced a NaN.
Sourcepub fn bracket_width(&self) -> f64
pub fn bracket_width(&self) -> f64
Width of the final bracket, in the abscissa’s units.
NaN when the lane never established a bracket. For a converged lane this
bounds the abscissa error at half its value for a unimodal objective;
it says nothing at all if the objective was multimodal.
Sourcepub fn iterations(&self) -> u32
pub fn iterations(&self) -> u32
Iterations performed on this lane, dimensionless.
One iteration contracts the bracket by exactly GOLDEN_RATIO and costs
one objective evaluation, on top of the two interior probes every lane
pays up front and the one final evaluation at the returned midpoint. So a
lane reporting k iterations called the objective k + 3 times, unless
it stopped early on a non-finite value.