Struct RootBatch

Source

pub struct RootBatch { /* 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::roots — all-or-nothing. Ok(Vec<f64>) only when every lane converged; otherwise Err(RootBatchFailure). Use this when a partial answer is useless, which for a per-cell thermodynamic inversion it usually is.
Self::solutions — per-lane, when the caller wants to handle failures individually (fall back to a wider bracket, flag the cell, sub-cycle).

§Units

See RootSolution.

Implementations§

Source §

impl RootBatch

Source

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

Every lane’s outcome, in problem order.

Source

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

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<RootSolution>

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, RootSolution)>

The first failing lane and its outcome, if any.

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

Source

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

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

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

Source

pub fn roots(&self) -> Result<Vec<f64>, RootBatchFailure>

All roots, or an error naming the failures — the all-or-nothing path.

§Returns

Ok(v) with v[i] the root of problem i, in the abscissa’s units, when every lane converged. Otherwise Err(RootBatchFailure) 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

RootBatchFailure when one or more lanes did not converge.

§Example

use outram_foam_basic_lib::compute::ComputeBackend;
use outram_foam_basic_lib::math::parallel::{
    solve_bracketed_batch, RootMethod, RootProblem, RootSettings, RootStatus,
};

// Lane 1's bracket does not straddle a root of x^2 - 2.
let problems = [RootProblem::new(0.0, 4.0), RootProblem::new(3.0, 4.0)];
let batch = solve_bracketed_batch(
    &problems,
    RootMethod::Brent,
    RootSettings::default(),
    ComputeBackend::Serial,
    |_, x| x * x - 2.0,
);

let err = batch.roots().expect_err("lane 1 is not bracketed");
assert_eq!(err.failure_count, 1);
assert_eq!(err.first_index, 1);
assert_eq!(err.first_status, RootStatus::NotBracketed);

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