Struct PsiGramTensor 

pub struct PsiGramTensor { /* private fields */ }

Certified Chebyshev-in-ψ expansion of a design-moving Gram (#1033b).

Holds the one-time Chebyshev sufficient-statistic series; every per-trial accessor is O(Dk²) or cheaper and never touches n rows again.

Implementations

impl PsiGramTensor

pub fn build( eval_design: impl FnMut(f64) -> Result<Array2<f64>, String>, weights: ArrayView1<'_, f64>, z: ArrayView1<'_, f64>, psi_lo: f64, psi_hi: f64, ) -> Result<Self, String>

Build and certify the tensor over psi ∈ [psi_lo, psi_hi].

eval_design(psi) must return the EXACT n×k design at psi (the same builder the per-trial path uses — exactness of the expansion is judged against it). weights are the fixed observation weights, z the fixed weighted-response target (e.g. y − offset). Returns None when the window is degenerate, any evaluation fails/has non-finite entries, or no ladder rung certifies — callers then keep the exact per-trial path.

pub fn reduced_basis_equal(&self, psi_ref: f64, psi_new: f64) -> bool

True when the realized reduced basis the design-revision fast path freezes at the pinning psi_ref is still valid at psi_new — the genuine reduced-basis-equality witness the skip requires (#1264, #1216 item 3).

The fast path keeps the reference surface (its conditioned frame and its RRQR-reduced / null-space basis) frozen at psi_ref while re-keying only the Gram XᵀWX(ψ) and penalty S(ψ) to psi_new. That is exact iff the reduced basis — the range / null split of the conditioned data Gram — is unchanged. A conditioning-ratio or RRQR rank/permutation gate only bounds NECESSARY conditions; the reduced SUBSPACE can still rotate while rank and pivot order look tame, which is exactly the ~7.8e-2 β̂ regression a cluster run found. This witness compares the orthogonal RANGE PROJECTORS of the conditioned Gram at psi_ref and psi_new (both assembled n-free from the tensor): the skip is sound only when the numerical ranks match AND the projectors agree to proj_atol in max-norm — i.e. the two reduced bases span the SAME subspace. The projector identity is gauge-invariant, so it certifies subspace equality directly rather than a particular basis choice.

psi_ref == psi_new (a repeat trial at the same ψ) is trivially sound. Off-window ψ’s, a non-finite / rank-degenerate Gram, or any eigendecomp failure return false (refuse the skip → caller takes the slow path).

ROTATION WALL (#1033). On production spatial geometry the conditioned data-Gram range subspace can ROTATE with ψ at fixed rank — the wall on which the earlier RRQR-pivot / entrywise-projector gates kept refusing the skip. The fix is the SUBSPACE-DISTANCE certificate below: the skip is sound exactly when the two equal-rank ranges coincide as SUBSPACES, measured by the spectral norm of the projector difference (the principal angle), which is invariant to any orthonormal-basis rotation WITHIN the range. So a pure gauge rotation that left the entrywise max-abs above tolerance — and therefore used to be refused — now certifies, letting the n-free skip fire across the rotation. A genuine subspace MOVE (different rank, or a real principal-angle separation) still refuses; refusing is the SOUND fallback (the caller takes the exact slow path). Do not weaken PSI_GRAM_SKIP_PROJ_ATOL / PSI_GRAM_SKIP_RANK_RTOL: the spectral gate is already the tightest correct subspace metric, and loosening it past a true principal-angle separation reintroduces the ~7.8e-2 β̂ regression this witness exists to prevent.

pub fn contains(&self, psi: f64) -> bool

True when psi lies inside the certified window.

pub fn contains_for_gradient(&self, psi: f64) -> bool

True when psi lies inside the certified gradient window where the analytic ψ-derivative is bit-tight against the exact design derivative (#1033b). The n-free kappa outer loop is armed only when this covers the full optimizer bounds.

pub fn gram_at(&self, psi: f64) -> Array2<f64>

XᵀWX(ψ) assembled n-free in O(Dk²) from the direct Gram series.

pub fn rhs_at(&self, psi: f64) -> Array1<f64>

XᵀWz(ψ) assembled n-free in O(Dk).

pub fn dgram_dpsi(&self, psi: f64) -> Array2<f64>

Exact ∂(XᵀWX)/∂ψ from the SAME representation as the value — the structural cure for the objective↔gradient desync class on this channel. n-free, O(Dk²) from the direct Gram series.

pub fn drhs_dpsi(&self, psi: f64) -> Array1<f64>

Exact ∂(XᵀWz)/∂ψ, n-free.

pub fn d2gram_dpsi2(&self, psi: f64) -> Array2<f64>

Exact ∂²(XᵀWX)/∂ψ² from the SAME representation as the value/gradient — the n-free curvature that lets the outer Newton/ARC step read the τ-τ Hessian’s design-moving block without re-streaming an O(n) slab Gram (#1033, Gaussian-identity single-ψ Hessian channel). O(Dk²) from the direct Gram series.

XᵀWX(ψ) = Σ_d T_d(x) G_d with x = mapped(ψ), so by the chain rule d²/dψ² = T_d″(x) · (dx/dψ)².

pub fn d2rhs_dpsi2(&self, psi: f64) -> Array1<f64>

Exact ∂²(XᵀWz)/∂ψ², n-free. T_d″·(dx/dψ)² against the rhs slabs.

pub fn gaussian_fixed_cache_at(&self, psi: f64) -> GaussianFixedCache

Assemble the Gaussian-identity sufficient-statistic cache at psi without touching a single data row — the bridge from this tensor into the inner PLS solver’s fast path (#1033b → GaussianFixedCache).

(XᵀWX, XᵀWz, zᵀWz) is everything the Gaussian penalized solve needs at any λ, so a ψ-trial that holds a certified tensor can hand the inner solver this cache instead of realizing the n×k design. The caller is responsible for contains(psi) (off-window trials fall back to the exact realizer path). Dense-path bridge only: the sparse scatter cache stays None.