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 reduced_basis_subspace_distance( &self, psi_ref: f64, psi_new: f64, ) -> Option<f64>

The gauge-invariant subspace distance ‖P(ψ_ref) − P(ψ_new)‖₂ = sin θ_max between the two conditioned-Gram range subspaces — the exact quantity Self::reduced_basis_equal thresholds against PSI_GRAM_SKIP_PROJ_ATOL. Exposed for #1033 frontier instrumentation so a refused n-free skip can be attributed to a genuine in-window basis ROTATION (this distance exceeds the tolerance at equal rank) versus a rank change. Returns None for an off-window ψ, an equal-ψ pair, a rank mismatch, or an eigendecomp failure. Purely k-space (O(k³)) — independent of n.

pub fn gram_numerical_rank(&self, psi: f64) -> Option<usize>

Numerical rank of the conditioned Gram XᵀWX(ψ) at psi, under the same relative cutoff (PSI_GRAM_SKIP_RANK_RTOL·λ_max) the design-revision skip’s reduced_basis_equal witness uses. Returns None for an off-window / non-finite / all-zero Gram. Purely k-space (O(k³)) — independent of n.

pub fn rank_stable_psi_floor(&self, psi_anchor: f64) -> Option<f64>

Lower edge of the contiguous ψ-band, ANCHORED at psi_anchor, over which the conditioned Gram XᵀWX(ψ) holds the SAME numerical rank it has at the anchor — i.e. the ψ-floor below which the design-revision skip’s reduced_basis_equal witness must (soundly) refuse, because the range subspace collapses as the longest-length-scale radial mode drops under the rank cutoff. Lifting the κ-optimizer’s lower bound to this floor keeps every in-window trial on the n-free fast path and is inherently n-INDEPENDENT: the rank is a property of the k×k tensor, not of the sample size (#1033).

Anchoring at psi_anchor (the optimizer’s ψ seed) is essential: the conditioned Gram is rank-deficient at BOTH window ends on production radial geometry — at small ψ the longest-scale mode collapses into the polynomial nullspace, and at very large ψ every radial column goes collinear with it. The maximal-rank region is therefore a middle BAND, and the κ-optimum lives inside it. We walk DOWN from the anchor on a fixed k-space grid and return the lowest ψ still at the anchor’s rank (stopping at the first node that differs). Purely O(nodes·k³) — no row access.

Returns None when the band already reaches psi_lo (no lift needed), when the anchor is off-window / rank-indeterminate, or when the window is empty.

pub fn rank_stable_psi_ceiling(&self, psi_anchor: f64) -> Option<f64>

Upper edge of the contiguous maximal-rank ψ-band, the symmetric twin of Self::rank_stable_psi_floor (#1033). The conditioned Gram XᵀWX(ψ) is rank-deficient at BOTH window ends — at small ψ the longest-length-scale radial mode collapses into the polynomial nullspace, and at very large ψ every radial column goes collinear with the low-frequency mode, so the maximal-rank region is a middle BAND. The optimizer’s line search can OVERSHOOT above that band (e.g. ψ≈1.0 on production Duchon geometry), where the design-realization skip’s reduced_basis_equal witness must soundly refuse (the range subspace dropped a dimension) → an O(n) reset_surface, AND the pinning ψ recorded at that reset is itself rank-deficient, so the NEXT in-band trial mismatches its reference and resets a SECOND time. Both resets vanish once the optimizer’s UPPER bound is clamped down to this n-free k-space ceiling, keeping every trial inside the maximal-rank band.

Walks UP from the anchor on the same fixed k-space grid as the floor and returns the highest ψ still at the window’s maximal numerical rank (stopping at the first node above that differs). Purely O(nodes·k³) — no row access, inherently n-INDEPENDENT (rank is a property of the k×k tensor).

Returns None when the band already reaches psi_hi (no clamp needed), when the anchor is off-window / rank-indeterminate, or when the window is empty.

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

True when psi lies inside the certified window.

pub fn psi_window(&self) -> (f64, f64)

The certified value window [psi_lo, psi_hi] (#1033 instrumentation).

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.