Struct Lu 

pub struct Lu<T: Real = f64, U: BasisUpdate<T> = ForrestTomlin<T>> { /* private fields */ }

Sparse LU factors of a basis with a basis-update policy U (Forrest–Tomlin by default): the contract’s Lu<T, U>.

Usage contract (the simplex method of Chapter 6), through LuFactor:

1. LuFactor::factorize with a ColumnSource (the basis heading and A);
2. LuFactor::ftran / LuFactor::btran any number of times;
3. to exchange the column at position r: LuFactor::ftran_for_update on the entering column a_q (this yields α_q = B⁻¹ a_q and records the spike), then LuFactor::update(r, α_q[r]);
4. when the update returns UpdateOutcome::RefactorNeeded (or an error), call LuFactor::factorize with the new heading — the factor never refactorizes by itself, since only the caller holds the columns (D-0016).

Implementations

impl<T: Real, U: BasisUpdate<T>> Lu<T, U>

pub fn new(opts: LuOptions) -> Self

An empty factor (no valid factorization yet).

pub fn set_pre_order(&mut self, pre_order: Option<PreOrder>)

The column pre-order of the bump (step L5′; Chapter 5.12): None (the default) runs Algorithm M exactly as before, bit for bit; Some(PreOrder::Colamd) eliminates the bump in the COLAMD order of its columns, choosing the row by threshold partial pivoting. Read at the next LuFactor::factorize.

(The contract has it as a field LuOptions::pre_order; a field would make LuOptions, and the simplex’s SimplexOptions that holds it, 8 bytes larger, past the 256-byte limit of clippy’s large_types_passed_by_value in the simplex and the MIP solver.)

pub fn pre_order(&self) -> Option<PreOrder>

The column pre-order in force (Lu::set_pre_order).

pub fn set_refactor_pivot_tol(&mut self, tol: Option<f64>)

The relative threshold u_R of the replay test of LuFactor::refactorize_same_pattern (step R5 of Chapter 5.12): None (the default) uses LuOptions::rel_pivot_tol, the threshold of the Markowitz search — a replayed sequence is then one Algorithm L would have accepted, (R2); Some(u_R) with 0 < u_R ≤ u accepts the recorded pivots down to u_R times the largest entry of their column, trading a little stability for fewer fallbacks when the values drift (task L1.5b, D8). Never read by LuFactor::factorize (Algorithm L is unchanged). A setter, not a field of LuOptions, for the reason of Lu::set_pre_order.

Panics

If u_R is not in (0, 1].

pub fn refactor_pivot_tol(&self) -> Option<f64>

The replay threshold in force (Lu::set_refactor_pivot_tol).

pub fn has_spike(&self) -> bool

true iff a spike is recorded and LuFactor::update may be called.

pub fn update_policy(&self) -> &U

The basis-update policy (its statistics and name).

impl<T: Real, U: BasisUpdate<T>> Lu<T, U>

pub fn expected_densities(&self) -> [f64; 3]

Expected result density of each kind of solve (policy (c)), for diagnostics: [ftran, btran, ftran_for_update].

Trait Implementations

impl<T: Clone + Real, U: Clone + BasisUpdate<T>> Clone for Lu<T, U>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Real, U: Debug + BasisUpdate<T>> Debug for Lu<T, U>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Real, U: BasisUpdate<T>> Default for Lu<T, U>

fn default() -> Self

Returns the “default value” for a type.

impl<T: Real, U: BasisUpdate<T>> LuFactor<T> for Lu<T, U>

fn factorize<C: ColumnSource<T>>(&mut self, cols: &C) -> Result<(), LuError>

Algorithm L: factorizes the m × m basis B whose columns the source gives.

fn refactorize_same_pattern<C: ColumnSource<T>>( &mut self, cols: &C, ) -> Result<(), LuError>

Algorithm R (Chapter 5.12): factorizes the m × m basis B with the pivot sequence of the last successful factorization — no search, no count lists — as long as every pivot passes the threshold test; otherwise (or without a sequence of order m) it falls back to LuFactor::factorize. Meant for new values on the same pattern; the outcome and the errors are those of factorize, and LuStats::symbolic_reuses / LuStats::symbolic_fallbacks say which path ran.

fn symbolic(&self) -> Option<&SymbolicLu>

The pivot sequence of the last successful factorization, if any.

fn ftran(&mut self, v: &mut SparseVec<T>)

v ← B⁻¹ v: row-indexed in, position-indexed out (D-0016).

fn btran(&mut self, v: &mut SparseVec<T>)

v ← B⁻ᵀ v: position-indexed in, row-indexed out.

fn ftran_for_update(&mut self, v: &mut SparseVec<T>)

LuFactor::ftran that also records the spike for the next LuFactor::update.

fn update(&mut self, r: usize, alpha_r: T) -> Result<UpdateOutcome, LuError>

Replaces the column at position r; alpha_r is entry r of the α_q returned by the last ftran_for_update. The factor never refactorizes on its own.

fn m(&self) -> usize

Dimension m of the last basis given to factorize.

fn is_valid(&self) -> bool

true iff the factor holds a valid factorization (the last factorize succeeded).

fn stats(&self) -> &LuStats

Statistics of the current factor.

fn update_stats(&self) -> &UpdateStats

Statistics of the update policy since the last factorization.

fn options(&self) -> &LuOptions

The options in force.

fn set_options(&mut self, opts: LuOptions)

Replaces the options. The factorization reads them at the next factorize, the solves and the update at their next call (e.g. a tighter LuOptions::rel_pivot_tol after numerical trouble, PLAN.md §8).

fn check_invariants(&self) -> Result<(), SparseError>

Checks invariants (F1)–(F3) of a valid factor (and of its updates).