Fixed-point API

JAX-native acceleration for expensive contractive fixed-point maps.

class solvax.fixed_point.FixedPointSolution(x, residual_norm, iterations, converged, relaxation)

Result of a fixed-point solve.

Parameters:
x: Array

Alias for field number 0

residual_norm: Array

Alias for field number 1

iterations: Array

Alias for field number 2

converged: Array

Alias for field number 3

relaxation: Array

Alias for field number 4

solvax.fixed_point.aitken_relaxation(previous_residual, residual, previous_relaxation=1.0, *, min_relaxation=0.05, max_relaxation=100.0)

Return one safeguarded vector Aitken relaxation update.

Parameters:
Return type:

Array

solvax.fixed_point.anderson_weights(residuals, *, regularization=1e-08, condition_limit=None)

Return safeguarded affine weights for an Anderson residual history.

The leading axis indexes history. Reuse the returned one-dimensional weights with tensordot to mix mapped histories whose trailing shapes differ, such as coupled fields and conservative flux state.

Parameters:
Return type:

Array

solvax.fixed_point.anderson_mixing(iterates, residuals, *, regularization=1e-08, damping=1.0, condition_limit=None)

Return a regularized Anderson update from a bounded fixed-point history.

residuals[i] must equal mapping(iterates[i]) - iterates[i]. The result is a residual-minimizing affine combination of the mapped points. Keeping map evaluation and stopping outside this primitive lets applications retain their own expensive subsystem solves and physical convergence gates.

Parameters:
Return type:

Array

solvax.fixed_point.affine_fixed_point_gmres(mapping, x0, *, precond=None, inner_product=None, restart=30, rtol=1e-08, atol=0.0, max_restarts=50)

Solve an affine fixed-point map with matrix-free FGMRES.

For G(x) = L x + c, this solves (I - L) delta = G(x0) - x0 and returns x0 + delta. Each Krylov operator application evaluates mapping once; no explicit matrix or Jacobian is formed. The mapping must be affine over the trial space. Use root_solve() with a nonlinear primal solver for a genuinely nonlinear map.

Parameters:
Return type:

KrylovSolution

solvax.fixed_point.aitken_fixed_point(mapping, x0, *, rtol=1e-08, atol=0.0, max_steps=100, min_relaxation=0.05, max_relaxation=100.0)

Solve mapping(x) = x with safeguarded vector Aitken acceleration.

The scalar relaxation is updated from successive fixed-point residuals and clipped to a caller-declared interval. The implementation uses jax.lax.while_loop(), so it is compatible with jit and vmap. For derivatives of a converged root, wrap this primal solver with solvax.root_solve() instead of differentiating through its stopping iterations.

Parameters:
Return type:

FixedPointSolution