Struct DeviceResidentArrowWorkspace 

pub struct DeviceResidentArrowWorkspace { /* private fields */ }

Upload-once workspace for the SAE data-fit Arrow-Schur inner iteration.

Implementations

impl DeviceResidentArrowWorkspace

pub fn new( shape: DeviceResidentArrowShape, target_x: Vec<f64>, basis_values: Vec<f64>, gate_activations: Vec<f64>, slabs: DeviceResidentArrowSlabs, ) -> Result<Self, DeviceResidentArrowError>

pub const fn shape(&self) -> DeviceResidentArrowShape

pub fn device_resident(&self) -> bool

pub fn resident_device_bytes(&self) -> usize

pub fn host_shadow_bytes(&self) -> usize

pub fn one_inner_iteration( &self, ridge_t: f64, ridge_beta: f64, ) -> Result<DeviceResidentArrowStep, DeviceResidentArrowError>

Run one device-side Newton sequence. No CPU fallback is attempted here: callers that want a reference path must call Self::cpu_reference_step.

pub fn cpu_reference_step( &self, ridge_t: f64, ridge_beta: f64, ) -> Result<DeviceResidentArrowStep, DeviceResidentArrowError>

CPU reference for parity harnesses. This path is explicit and is never called from Self::one_inner_iteration.

pub fn inner_iteration_for_production( &self, mode: GpuPolicy, ridge_t: f64, ridge_beta: f64, ) -> Result<DeviceResidentArrowStep, DeviceResidentArrowError>

Production seam (#1017 Phase 3): one SAE data-fit inner Newton step under the process-wide gam_gpu::GpuPolicy residency contract the caller passes (gam_gpu::global_policy()). This is the entry a production inner Newton loop calls per iterate; it does NOT touch the fitting loop itself — the caller wires it (see the #1017 seam report).

Break-even admission (“shapes clear the device threshold”) is already carried by Self::device_resident: the resident buffers upload only when gam_gpu::linalg_dispatch::route_through_gpu admits the qwen-scale row-block workload, so a below-break-even shape is simply not device-resident. This method adds the mode lever and the typed fallback:

• gam_gpu::GpuPolicy::Off — the dense CPU reference step; no device contact.
• gam_gpu::GpuPolicy::Auto — the resident device step when the workspace is device-resident, else the CPU reference; on a device-solve fault the fallback to the CPU reference is taken and logged ONCE per process (never a silent CPU downgrade). The resident step is a single frame-build + solve (no tile loop), so there is no unbounded async backlog to stall on silently — the #2227 “never silent” discipline here is the one-shot engagement warn plus the typed fault surface, not a per-tile heartbeat.
• gam_gpu::GpuPolicy::Required — the resident device step, or a typed DeviceResidentArrowError when the workspace is not device-resident or the solve faults (fails closed; never degrades to CPU).

pub fn to_arrow_system(&self) -> ArrowSchurSystem

pub fn device_fit( &self, opts: &DeviceResidentInnerOptions, ) -> Result<DeviceResidentInnerOutcome, DeviceResidentArrowError>

Run the full device-resident inner Newton loop. Routes the per-iteration arrow solve through the GPU path; returns Unavailable when CUDA did not admit the resident workload (callers wanting a CPU path use Self::cpu_reference_fit).

pub fn device_reupload_fit( &self, opts: &DeviceResidentInnerOptions, ) -> Result<DeviceResidentInnerOutcome, DeviceResidentArrowError>

The #1017 residency baseline: run the SAME inner Newton loop but compute each per-iterate arrow step through solve_arrow_newton_step, which re-packs/re-uploads D/B/g and re-runs the per-row POTRF + border Schur factor on EVERY iterate. This is the “current re-uploading path”; the bench divides Self::device_fit (resident) against it to isolate the across-iteration residency speedup on one device, holding the host control flow and the GPU factor kernels fixed.

pub fn cpu_reference_fit( &self, opts: &DeviceResidentInnerOptions, ) -> Result<DeviceResidentInnerOutcome, DeviceResidentArrowError>

CPU dense-reference inner loop. Bit-for-bit the same host arithmetic as Self::device_fit except the per-iteration arrow solve uses the dense reference factorisation; the parity harness asserts the two agree.

This is a correctness ORACLE, not a speed baseline: it factors the full dense (n·d+k) × (n·d+k) joint Hessian, which is what makes it an independent check of the arrow algebra, and also what makes its wall clock meaningless as a CPU competitor. Use Self::cpu_arrow_fit for the timing baseline.

pub fn cpu_arrow_fit( &self, opts: &DeviceResidentInnerOptions, ) -> Result<DeviceResidentInnerOutcome, DeviceResidentArrowError>

The honest CPU competitor: the SAME inner Newton loop with the per-iterate step taken by the PRODUCTION structured Arrow-Schur solve on the host (device policy off). This is what a CPU-only production host runs, so it — not the dense oracle — is what a device speedup must be divided against.

log_det_hessian is reported as NaN for this mode: the production solve entry returns the step and its PCG diagnostics, not the joint log determinant, and fabricating one from a second factorisation would put work in the baseline that the production path does not do.

pub fn device_fit_outer_sequence( &self, base_gradient_overrides: &[(Vec<f64>, Vec<f64>)], opts: &DeviceResidentInnerOptions, ) -> Result<OuterSequenceOutcome, DeviceResidentArrowError>

Run a sequence of outer evaluations that SHARE one resident frame when the Hessian operator is unchanged across outers (#1017 deliverable 3).

Each entry of base_gradient_overrides is one outer evaluation’s base gradient (g_t rows: n·d, g_β: p) — the only part of the bordered quadratic that moves across outers at a frozen gate/basis frame. The constant Hessian blocks ride the resident frame, which is built ONCE and reused for every outer (frame builds are counted and returned so a caller can assert the across-outer amortization actually fired: exactly one frame build for an unchanged operator, regardless of how many outers run).

Returns one DeviceResidentInnerOutcome per outer plus the number of resident-frame builds performed across the whole sweep. On a CPU-only host returns Unavailable (callers wanting a host path use Self::cpu_reference_outer_sequence).

pub fn cpu_reference_outer_sequence( &self, base_gradient_overrides: &[(Vec<f64>, Vec<f64>)], opts: &DeviceResidentInnerOptions, ) -> Result<OuterSequenceOutcome, DeviceResidentArrowError>

CPU-reference outer sequence: same host control flow as Self::device_fit_outer_sequence but the per-iterate arrow solve uses the dense reference factorisation. The parity harness asserts the device across-outer sweep agrees with this per-outer-independent reference.