Struct ScaledSumSqAccumulator 

pub struct ScaledSumSqAccumulator<SumSqAcc>
where
    SumSqAcc: SumAccumulator<Input: RealScalar>,
{ /* private fields */ }

Accumulator for computing scaled sum-of-squares: scale² × Σ(xᵢ/scale)².

This accumulator is used internally for computing vector norms (especially L2), but is general enough for any algorithm that needs to sum squared non-negative values while maintaining numerical stability through dynamic scaling.

The key invariant is that scale tracks the running maximum absolute value, preventing overflow and underflow. When a larger value is encountered, previous accumulated terms are rescaled by (old_scale / new_scale)².

Type parameter SumSqAcc

The accumulation strategy for the scaled sum-of-squares term:

• NaiveSum: plain +=, fastest
• NeumaierSum: compensated summation for better accuracy

Input contract

The Input type is NonNegativeRealScalar<ScalarType::RealType>, which explicitly encodes that all pushed values must be non-negative. Callers must validate and wrap values with NonNegativeRealScalar before pushing.

Example

use num_valid::algorithms::accumulators::*;
use num_valid::scalars::NonNegativeRealScalar;

let mut acc = ScaledSumSqAccumulator::<NaiveSum<f64>>::new();
acc.push(NonNegativeRealScalar::new(3.0));  // validated non-negative
acc.push(NonNegativeRealScalar::new(4.0));
let result = acc.result();  // 3² + 4² = 25

Implementations

impl<SumSqAcc> ScaledSumSqAccumulator<SumSqAcc>

where SumSqAcc: SumAccumulator<Input: RealScalar>,

pub fn result_sqrt(self) -> NonNegativeRealScalar<SumSqAcc::Input>

pub fn new_sequential<I>(values: I) -> Self

where I: IntoIterator<Item = NonNegativeRealScalar<SumSqAcc::Input>>,

Build a new accumulator by sequentially pushing non-negative values.

This is the basic constructor for building from validated non-negative inputs. For building from arbitrary scalars (which need abs()), use new_sequential_from_scalars.

pub fn new_sequential_from_scalars<I>(values: I) -> Self

where I: IntoIterator<Item: FpScalar<RealType = SumSqAcc::Input>>,

Build a new accumulator by sequentially processing scalars, automatically taking abs().

This is a convenience method for L2 norm computation, where scalar values (real or complex) are automatically converted to their absolute value (modulus for complex scalars) before accumulation.

Example

use num_valid::algorithms::accumulators::*;

let values = [3.0_f64, -4.0, 5.0];
let mut acc = ScaledSumSqAccumulator::<NaiveSum<f64>>::new_sequential_from_scalars(values);
// Accumulates |3| = 3, |-4| = 4, |5| = 5
// Result: √(9 + 16 + 25) = √50

pub fn new_parallel_from_scalars<I>(values: I) -> Self

where Self: Send, I: IntoParallelIterator<Item: FpScalar<RealType = SumSqAcc::Input>>,

Build a new accumulator in parallel, automatically taking abs() of each scalar.

Distributes work across threads using rayon. Each thread accumulates its chunk independently, then results are merged via Accumulator::combine.

Trait Implementations

impl<SumSqAcc> Accumulator for ScaledSumSqAccumulator<SumSqAcc>

where SumSqAcc: SumAccumulator<Input: RealScalar>,

type Input = NonNegativeRealScalar<<SumSqAcc as Accumulator>::Input>

Input must be already validated as non-negative

fn push(&mut self, value: Self::Input)

Adds a non-negative value to the accumulator. The input must already be validated as non-negative via NonNegativeRealScalar.

fn combine(&mut self, other: Self)

Merges another accumulator, rescaling as needed when scales differ. Handles all permutations of scale relationships (>, <, ==) and empty accumulators.

fn result(self) -> Self::Output

Returns the squared result: scale² × sumsq.

type Output = NonNegativeRealScalar<<SumSqAcc as Accumulator>::Input>

The type of the final result produced by result.

fn new() -> Self

Creates a new, empty accumulator (the identity for combine).

fn new_sequential<I>(values: I) -> Self

where I: IntoIterator<Item = Self::Input>,

Creates a new accumulator by sequentially adding all values from values.

fn new_parallel<I>(values: I) -> Self

where Self: Send, I: IntoParallelIterator<Item = Self::Input>,

Builds an accumulator by processing a parallel iterator.