Function range_reduce_sqrt

Source

fn range_reduce_sqrt<T>(y: T) -> (T, u32)where
    T: FixedPointNumber + Copy + PartialOrd,
    T::Inner: From<u8> + Shr<u32, Output = T::Inner> + TryInto<i128> + Copy,

Expand description

Reduces a fixed-point value y toward 1 by repeatedly taking its square root, returning the reduced value and the number of reductions applied.

§Purpose

Series expansions for ln(y) converge fastest when y is close to 1. This function brings y into the band [0.5, 1.5] where ln_near_one is both accurate and efficient.

§Algorithm

Each iteration replaces y with sqrt(y), halving the distance to 1 in logarithmic space. After k reductions:

y_original = y_reduced ^ (2^k)
ln(y_original) = 2^k * ln(y_reduced)

The caller uses k to undo the reduction after computing ln(y_reduced).

§Stopping Conditions

Iteration stops when any of the following occur:

|y - 1| <= 0.5 - y is in [0.5, 1.5], close enough for ln_near_one
ny == y - Newton-Raphson stagnated, no further reduction is possible
ny == 0 - degenerate input at fixed-point boundaries; result will be approximate
MAX_ITERATIONS reached - hard cap to guarantee termination

§Arguments

y - A positive fixed-point value to reduce. Behaviour for y <= 0 is undefined - caller is responsible for domain validation.

§Returns

A tuple (y_reduced, k) where:

y_reduced is in [0.5, 1.5] (or as close as the stopping conditions allow)
k is the number of square root reductions applied