Struct MinBatch

Source

pub struct MinBatch { /* private fields */ }

Expand description

A batch of N lane outcomes, in the same order as the problems handed in.

Lane i of the result corresponds to problems[i], always — the parallel path preserves order, so no index bookkeeping is needed.

§Getting numbers out

Self::extrema — all-or-nothing abscissae. Ok(Vec<f64>) only when every lane converged; otherwise Err(MinBatchFailure).
Self::extremal_values — the same, for the objective values.
Self::solutions — per-lane, when the caller wants to handle failures individually (widen the bracket, flag the cell, fall back to a scan).

§Units

See MinSolution.

Implementations§

Source §

impl MinBatch

Source

pub fn solutions(&self) -> &[MinSolution]

Every lane’s outcome, in problem order.

Source

pub fn into_solutions(self) -> Vec<MinSolution>

Consume the batch and take the outcomes.

Source

pub fn len(&self) -> usize

Number of lanes, dimensionless.

Source

pub fn is_empty(&self) -> bool

Whether the batch has no lanes.

Source

pub fn get(&self, i: usize) -> Option<MinSolution>

Lane i’s outcome, or None if i is out of range.

Source

pub fn all_converged(&self) -> bool

Whether every lane converged. Vacuously true for an empty batch.

Source

pub fn failure_count(&self) -> usize

How many lanes failed to converge, dimensionless.

Source

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

The first failing lane and its outcome, if any.

The natural thing to print when a batch fails: it names the lane to look at rather than just the count.

Source

pub fn failures(&self) -> Vec<(usize, MinSolution)>

Every failing lane, as (index, outcome) pairs.

Allocates, so prefer Self::first_failure or Self::failure_count on a hot path.

Source

pub fn extrema(&self) -> Result<Vec<f64>, MinBatchFailure>

The located abscissae, or an error naming the failures — the all-or-nothing path.

§Returns

Ok(v) with v[i] the extremum of problem i, in the abscissa’s units, when every lane converged. Otherwise Err(MinBatchFailure) carrying the failure count and the first failing lane. No Vec of plausible-looking numbers is ever returned for a batch that contained a failure.

An empty batch returns Ok(vec![]).

§Errors

MinBatchFailure when one or more lanes did not converge.

§Example

use outram_foam_basic_lib::compute::ComputeBackend;
use outram_foam_basic_lib::math::minimise::{
    golden_section_batch, MinProblem, MinSettings, MinStatus, Sense,
};

// Lane 1's objective is non-finite on its bracket.
let problems = [MinProblem::new(-1.0, 1.0), MinProblem::new(-1.0, 1.0)];
let batch = golden_section_batch(
    &problems,
    Sense::Minimise,
    MinSettings::default(),
    ComputeBackend::Serial,
    |i, x| if i == 1 { f64::NAN } else { x * x },
);

let err = batch.extrema().expect_err("lane 1 is not finite");
assert_eq!(err.failure_count, 1);
assert_eq!(err.first_index, 1);
assert_eq!(err.first_status, MinStatus::NotFinite);

// The converged lane is still individually readable.
assert!(batch.solutions()[0].extremum().is_some());
assert!(batch.solutions()[1].extremum().is_none());