Skip to content

Settings

Settings

Every solver owns a Settings dataclass at solver.settings. Mutate its fields before setup() or between solves:

import warp as wp
from cupiqp import DenseSolver

solver = DenseSolver(dtype=wp.float64)
solver.settings.verbose = True
solver.settings.max_iter = 100
solver.settings.eps_abs = 1e-6
solver.setup(P=P, c=c)
solver.solve()

You can also build a Settings object directly. The factory Settings.for_dtype(dtype) returns settings with dtype-appropriate tolerance defaults (see Precision):

import warp as wp
from cupiqp import Settings

settings = Settings.for_dtype(wp.float32)
settings.max_iter = 200

dtype is fixed at construction

Settings.dtype cannot be reassigned after the object is created. Pass dtype= to the solver constructor, or build a fresh Settings via Settings.for_dtype(dtype). Assigning settings.dtype = ... raises AttributeError.

Precision and dtype

Field Type Default Description
dtype wp.float32 | wp.float64 wp.float64 Solver arithmetic precision (fixed at construction).

float32 and float64 carry different default tolerances, since you cannot ask for float64-level accuracy in float32 arithmetic. Settings.for_dtype(wp.float32) loosens the tolerances accordingly. If you tighten a float32 tolerance below its recommended floor, the solver emits a warning that convergence may fail.

Representative defaults:

Field float64 default float32 default
eps_abs 1e-8 1e-4
eps_rel 1e-9 1e-4
eps_duality_gap_abs 1e-8 1e-4
eps_duality_gap_rel 1e-9 1e-4
reg_lower_limit 1e-10 1e-5

Convergence tolerances

Field Default (f64) Description
eps_abs 1e-8 Absolute tolerance on the primal/dual residuals.
eps_rel 1e-9 Relative tolerance on the primal/dual residuals.
check_duality_gap True Also require the duality gap to satisfy its tolerances before declaring convergence.
eps_duality_gap_abs 1e-8 Absolute duality-gap tolerance.
eps_duality_gap_rel 1e-9 Relative duality-gap tolerance.
max_iter 250 Maximum interior-point iterations before returning CUPIQP_MAX_ITER_REACHED.
infeasibility_threshold 0.9 Threshold used in the primal/dual infeasibility detection.

Proximal regularization

cuPIQP is a proximal interior-point method: it regularizes the KKT system with a primal regularization rho and a dual regularization delta, driving both down as the iterates converge.

Field Default (f64) Description
rho_init 1e-6 Initial primal proximal regularization.
delta_init 1e-4 Initial dual proximal regularization.
reg_lower_limit 1e-10 Lower limit on the proximal regularization.
reg_finetune_lower_limit 1e-13 Tighter lower limit used during fine-tuning.
reg_finetune_primal_update_threshold 7 Stagnated-primal-update count that triggers regularization fine-tuning.
reg_finetune_dual_update_threshold 7 Stagnated-dual-update count that triggers regularization fine-tuning.
tau 0.99 Fraction-to-the-boundary parameter for the interior-point step.
max_factor_retires 10 Max KKT-factorization retries (with increased regularization) before a numerical failure.

Preconditioner (Ruiz equilibration)

cuPIQP equilibrates the problem with a Ruiz preconditioner before solving.

Field Default Description
preconditioner_iter 10 Number of Ruiz equilibration sweeps. Set to 0 to disable scaling entirely.
preconditioner_scale_cost False Also scale the cost (P, c) during equilibration.
preconditioner_reuse_on_update False On update(), reuse the existing scaling instead of recomputing it.

Exact gradients

When differentiating through the solve, setting preconditioner_iter = 0 yields exact gradients (no scaling to differentiate through).

Iterative refinement

Field Default (f64) Description
iterative_refinement_always_enabled False Always run iterative refinement after each KKT solve.
iterative_refinement_eps_abs 1e-12 Absolute target residual for refinement.
iterative_refinement_eps_rel 1e-12 Relative target residual for refinement.
iterative_refinement_max_iter 10 Max refinement iterations per KKT solve.
iterative_refinement_min_improvement_rate 5.0 Required residual-improvement rate to keep refining.
iterative_refinement_static_regularization_eps 1e-8 Static regularization added to the factorized system for refinement.
iterative_refinement_static_regularization_rel ≈ε² Relative static regularization (float-eps squared).

Execution and CUDA graphs

Field Default Description
enable_cuda_graph True Record the solve as a CUDA graph on the first solve() and replay it afterwards: the whole solve, with the IPM loop running on the GPU, for the dense and multistage backends; one IPM iteration for the sparse backend. Recording does not slow the first solve, and later solves are typically several times faster for small problems. Set it to False only for debugging: every kernel is then launched from Python, so an error is reported at the kernel that caused it.
use_deterministic_mode_for_cudss False Bit-wise reproducible cuDSS factorizations (slower); sparse backend only.

Differentiation, diagnostics, and logging

Field Default Description
enable_grad False Allocate backward buffers; see Differentiation.
gradient_smoothing False Enable qpax-style relaxed-KKT gradient smoothing. Fixed at setup(). Requires enable_grad. See Differentiation.
gradient_smoothing_mu 1e-3 Target complementarity s * z = mu at the relaxed point. Larger smooths more (more bias); smaller approaches the unsmoothed gradient.
gradient_smoothing_tol 1e-5 Convergence tolerance of the inner relaxed-Newton solve (separate from the forward eps_abs).
gradient_smoothing_max_iter 5 Maximum relaxed-Newton iterations per backward (separate from the forward max_iter).
verbose False Print the banner and the per-iteration log during solve().

Validation

settings.verify_settings() returns True when every field is within its valid range (positive tolerances, 0 < tau ≤ 1, a recognized dtype, etc.). Use it as a quick sanity check after programmatically constructing settings.