Add a compatible relaxation CF splitting (-pc_air_cf_splitting_type cr)

[stevendargaville]

Adds a compatible relaxation (CR) CF splitting as a new splitting type, CF_CR / -pc_air_cf_splitting_type cr.

What it does

Classic from-scratch CR coarsening (Brandt / Brannick–Falgout form): all points start as F, and each pass promotes an independent set of the F rows where the relaxed error remains largest (the hypre candidate measure), until one application of the F-point smoothing contracts a random error on Aff by the target rate carried in -pc_air_strong_threshold (~0.1 recommended). It never forms a strength matrix or S+S^T — the independent set uses PMISR with the implicit transpose, and all heavy numerics are stock PETSc Mat/Vec ops, so aijkokkos runs the setup on device with no new Kokkos kernels.

Design points

• The CR relaxation mirrors the PCAIR Aff inverse settings (-pc_air_inverse_type, -pc_air_poly_order, -pc_air_inverse_sparsity_order, -pc_air_diag_scale_polys), passed through new optional arguments on compute_cf_splitting (standalone C/Python API unchanged; defaults match a default-configured PCAIR).
• One relaxation application per pass (nu=1), always assembled. AIR applies its F-solve once per smoothing step, so the one-application contraction ||I - M Aff|| is what gates convergence — multi-sweep asymptotic rates look good for any splitting on near-triangular advective Aff and hide growing iteration counts. Similarly the ideal restrictor is always built from the assembled sparsified inverse even with -pc_air_matrix_free_polys, making it the binding constraint: certifying with the matrix-free polynomial under-coarsens and iterations grow (16/21/27 over 100^2-400^2), while certifying with the assembled inverse stays flat and the matrix-free smoother simply does better than predicted.
• Row-scaling robust with -pc_air_diag_scale_polys (the relaxation operator p(D^-1 Aff) D^-1 Aff is row-scaling invariant); tested on the poorly scaled SUPG problem.

Results (steady upwind FD advection, -pc_air_inverse_type power, target 0.1)

n	100^2	200^2	400^2	800^2	400^2 (4 ranks)
AIRG iterations	9	10	11	12	11
grid / op complexity	1.91 / 3.7	2.00 / 4.4	1.93 / 4.3	1.99 / 4.8	—

For reference pmisr_ddc is 6 iterations flat at operator complexity ~14 — the CR hierarchies are ~3x cheaper per cycle. DG advection: 14 -> 18 over refine 2 -> 3.

Also included

• Fix for a latent segfault in calculate_and_build_approximate_inverse: present(x) .AND. associated(x) in one expression — Fortran does not short-circuit, so any caller omitting the optional dereferenced a null descriptor.
• New tests: serial + parallel cr runs of adv_diff_fd and adv_dg_upwind, the poorly scaled SUPG problem with diagonal scaling, and a CF_CR block in ex6_cf_splitting. All pass on CPU, aijkokkos, and under PFLARE_KOKKOS_DEBUG=1; make check and make tests_short pass.
• Docs updated (new_methods.md, options.md, faq.md, man pages) and a CHANGELOG entry.

🤖 Generated with Claude Code