Struct JacobianPattern 

pub struct JacobianPattern {
    pub n_unknowns: usize,
    /* private fields */
}

A topology’s Jacobian sparsity pattern plus the per-entry recipes needed to refill its values. Build once per topology via analyze; call fill every iteration.

rows/cols/entries are parallel arrays of the same length, in the exact emission order solver::build_jacobian_triplets used, so a cached symbolic factorization keyed on that order stays valid — until permute puts them in a sparse LU’s own storage order.

Fields

n_unknowns: usize

Implementations

impl JacobianPattern

pub fn analyze(buses: &[Bus], ybus: &YBusSparse) -> Self

Derives the pattern from a topology and a bus-type assignment.

Must be recomputed if either changes — a different set of branches, or any bus switching PV↔PQ (which changes n_unknowns itself). This is the same validity condition solver::PersistentSolver documents for its cached factorization, and the two are reset together.

pub fn permute(&mut self, order: &[usize])

Reorders the entries so that entry k is the one that was at order[k]: from then on fill writes, and to_triplets lists, in that order. What lu::SparseLu::adopt_storage_order returns, so the fill writes straight into the factorization’s own layout.

Panics

If order is not a permutation of 0..len().

pub fn len(&self) -> usize

Number of Jacobian nonzeros — the length of values that fill expects.

pub fn is_empty(&self) -> bool

pub fn rows(&self) -> &[u32]

pub fn cols(&self) -> &[u32]

pub fn entries(&self) -> &[Entry]

pub fn fill( &self, buses: &[Bus], p_calc: &[f64], q_calc: &[f64], values: &mut Vec<f64>, )

Writes this iteration’s Jacobian values into values, which is resized to len and otherwise fully overwritten.

Every write is independent and lands at a fixed offset — no allocation, no index arithmetic, no branching beyond the eight-way kind dispatch. That independence is what makes this portable to one thread per entry.

pub fn fill_into( &self, buses: &[Bus], p_calc: &[f64], q_calc: &[f64], values: &mut Vec<f64>, )

fill without the clear — appends this scenario’s values to values. What lets bde::BlockDiagonal concatenate B scenarios’ blocks into one flat array for a block-diagonal solve.

pub fn fill_with( &self, v: &BusVoltages, p_calc: &[f64], q_calc: &[f64], values: &mut Vec<f64>, )

fill from voltages already taken, which the Newton loop shares with the power injections.

pub fn fill_identity_into(&self, values: &mut Vec<f64>)

Appends an identity block in this pattern’s own layout: 1.0 at every stored diagonal position, 0.0 everywhere else.

This is how bde::BlockDiagonal masks a converged or diverged scenario out of a batch. Dropping its block outright would change the stacked matrix’s sparsity pattern and invalidate the cached symbolic factorization — the whole reason batching is cheap. Writing an identity into the same stored positions keeps the pattern bit-identical while making that scenario’s update exactly zero (with a zero right-hand side), and identity is perfectly conditioned so it cannot degrade the factorization.

Every diagonal position is structurally present: Hii supplies (r, r) for every angle row and Lii supplies it for every magnitude row, so no fill-in is required to write this.

pub fn to_triplets(&self, values: &[f64]) -> Vec<(usize, usize, f64)>

Convenience for callers that still want (row, col, value) triplets, which is the shape every solver::LinearSolver backend consumes.