Struct ArrowSolveOptions 

pub struct ArrowSolveOptions {
    pub mode: ArrowSolverMode,
    pub gpu_policy: GpuPolicy,
    pub pcg: ArrowPcgOptions,
    pub trust_region: ArrowTrustRegionOptions,
    pub streaming_chunk_size: Option<usize>,
    pub riemannian_trust_region: bool,
    pub gpu_matvec: Option<GpuSchurMatvec>,
    pub evidence_policy: ArrowEvidencePolicy,
    pub solve_precision: ArrowSolvePrecisionPolicy,
    pub newton_schur_tikhonov_rel_floor: Option<f64>,
    pub sae_resident_frame: Option<Arc<dyn SaeResidentFrame + Send + Sync>>,
}

Complete BA Schur solve options.

Use ArrowSolveOptions::automatic for normal latent-coordinate fits; use ArrowSolveOptions::sqrt_ba when the assembler has single-precision row blocks or an ill-conditioned gauge; use ArrowSolveOptions::inexact_pcg for SAE-manifold scale K.

Fields

mode: ArrowSolverMode

gpu_policy: GpuPolicy

Backend policy owned by this solve. Keeping it in the immutable solve request prevents one fit from changing another fit’s device routing.

pcg: ArrowPcgOptions

trust_region: ArrowTrustRegionOptions

streaming_chunk_size: Option<usize>

Row chunk size for streaming direct/Square-Root Schur assembly.

riemannian_trust_region: bool

Use the Riemannian latent projection before the Schur reduction. The reduced Steihaug solve itself remains in Euclidean β coordinates.

gpu_matvec: Option<GpuSchurMatvec>

Optional GPU-backed Schur matvec for CPU-driven InexactPCG at K ≥ 5000.

When set, run_pcg_with_preconditioner delegates each S·p call to this closure instead of the CPU schur_matvec. Constructed by crate::gpu_kernels::arrow_schur::gpu_schur_matvec_backend when cuda_selected() and the system has dense per-row H_tβ slabs. None means CPU-only PCG.

evidence_policy: ArrowEvidencePolicy

Conditioning contract for the separately-built undamped evidence cache.

solve_precision: ArrowSolvePrecisionPolicy

Arrow solve precision policy. Default is f64-only.

newton_schur_tikhonov_rel_floor: Option<f64>

Optional spectral positive-definiteness floor on the reduced Schur complement S = H_ββ + ridge_β·I − Σ_i H_tβ^(i)ᵀ (H_tt^(i))⁻¹ H_tβ^(i), as a relative fraction of S’s largest eigenvalue.

None (default) keeps the strict contract: a non-PD S errors as ArrowSchurError::SchurFactorFailed so the LM outer loop lifts ridge_beta globally and re-forms S.

Some(floor) engages the #1026 SAE co-collapse cure on the SOLVE path: when the reduced Schur Cholesky refuses (collapsed atoms drive a per-row H_tt near-singular, so the accumulated (H_tt)⁻¹ over-subtracts S into an INDEFINITE matrix), instead of rejecting and over-damping every β direction with a global ridge, symmetric-eigendecompose S and clamp every eigenvalue UP to floor·max(λ). This is Levenberg–Marquardt restricted to exactly the indefinite/collapsed subspace: the well-conditioned β directions (λ ≫ floor·max λ) are untouched and the step in those directions is the exact Newton step, while only the collapsed directions receive the minimal damping needed for a PD solve. The inner Newton then makes a real descent step rather than crawling behind an inflated global ridge. Mirrors the per-row spectral floor the evidence path uses for #1377/#1117/#1118 ([super::factorization::factor_spectral_deflated_criterion_row]); the difference is the floored value — a small positive floor·max λ (Tikhonov) for the solve, vs unit stiffness +1 (log 1 = 0) for the evidence log-det.

Only consulted by the dense Direct / SqrtBA reduced solve (the only caller of [super::reduced_solve::solve_dense_reduced_system]); the InexactPCG path is unaffected.

sae_resident_frame: Option<Arc<dyn SaeResidentFrame + Send + Sync>>

#1017 device-resident framed SAE frame for the LM ridge ladder.

When set (by super::newton_step::solve_with_lm_escalation_inner on a device-admitted matrix-free SAE system), both the Direct SAE-PCG seam ([super::newton_step::try_device_arrow_direct_sae_pcg]) and the native large-border InexactPCG branch recompute only the ridge-dependent per-row ainv per ladder trial and reuse the resident ridge-independent operand buffers, instead of re-marshalling and re-uploading every operand through flatten_device_sae_frame_data on each trial. The solve is bit-identical; only the redundant per-trial upload is removed. None (default) keeps the per-trial re-flatten path. A trait object (like GpuSchurMatvec) keeps the CUDA-only device buffers out of these cfg-independent options.

Implementations

impl ArrowSolveOptions

pub fn automatic(k: usize) -> Self

Select Direct for K <= 2000 and InexactPCG above, following BA RCS practice for dense-vs-iterative reduced systems.

pub fn direct() -> Self

Force dense reduced-camera-system Cholesky, the classic BA direct solve for small K.

pub fn sqrt_ba() -> Self

Force Square-Root BA Schur assembly for the direct reduced solve.

pub fn inexact_pcg() -> Self

Force inexact BA Schur PCG with Jacobi preconditioning.

pub fn with_streaming_chunk_size(self, chunk_size: Option<usize>) -> Self

pub fn with_gpu_policy(self, gpu_policy: GpuPolicy) -> Self

Route every device probe made by this solve under one per-request policy. In particular, Off returns to the exact CPU implementation before touching a possibly broken CUDA installation.

pub fn with_positive_definite_evidence(self) -> Self

Build an undamped evidence cache that accepts positive-definite factors regardless of their Newton-step condition-number gate.

pub fn with_evidence_unit_deflation(self, relative_floor: f64) -> Self

Build the undamped evidence β-Schur with original-coordinate unit deflation at relative_floor.

pub fn with_newton_schur_tikhonov(self, relative_floor: f64) -> Self

Enable Newton-only spectral Tikhonov damping on collapsed reduced-Schur directions. This never changes the evidence value or inverse.

pub fn with_solve_precision_policy( self, policy: ArrowSolvePrecisionPolicy, ) -> Self

pub fn with_streaming_solve_precision_default(&self) -> Self

Turn certified mixed precision ON for the streaming/residency reduced solve unless the caller already pinned an explicit policy (#1014).

Only F64Only (the inherited default) is upgraded to CertifiedMixed; a caller that deliberately set a policy keeps it. The reduced-Schur f64 factor and every evidence log-determinant are unaffected — see [mixed_precision_reduced_beta].

Trait Implementations

impl Clone for ArrowSolveOptions

fn clone(&self) -> ArrowSolveOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ArrowSolveOptions

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

Formats the value using the given formatter.