A general system preconditioner: the CPRW pressure stage as a two-level method

[hnil]

Builds on #7278 — its ten commits are the first ten here, since GitHub cannot
base a pull request on a fork branch. Review from Add composable sweep steps for the system preconditioner onwards.

SystemPreconditioner runs a fixed three-stage sequence. Written out, that
sequence is

coarse pressure solve -> well solve -> reservoir smoother -> well solve

which is coarse_solver { reservoir_solver, well_solver } followed by
smoother { reservoir_smoother, well_solver }. This PR makes that structure the
configuration, and makes the pressure stage a real two-level method rather than a
hand-rolled first stage.

SystemPressureBhpTransferPolicy presents the CPRW pressure system (dimension
nCells + nWells) as a Dune level transfer policy, PressureSolverPolicy builds
its solver, and TwoLevelMethodCpr drives them with preSteps = 0,
postSteps = 1. Dune hands a smoother a single (correction, defect) pair, so
everything after the coarse correction is composed into one
SystemSweepPreconditioner that carries its own defect. Without add_wells
there is no system-wide coarse space, so the reservoir solve is an ordinary block
step and no two-level method is built.

Selected with --linear-solver=general_system_cpr / general_system_cprw. The
JSON follows cpr's shape -- coarsesolver, finesmoother, weight_type,
pre_smooth, post_smooth in the same places -- but the smoother is an ordered
list, since a coupled system has more than one block to visit:

"finesmoother": { "steps": [ { "block": "well",      "..." },
                             { "block": "reservoir", "..." },
                             { "block": "well",      "..." } ] }

so steps can be reordered, repeated or left out. coarsesolver is itself the
solver spec for the coarse pressure system and the keys beside it describe the
coarse space; leaving it out means no coarse space. That replaces an add_wells
buried in a nested preconditioner deciding whether a two-level method got built
at all, and a coarse solver reached at
coarse_solver.reservoir_solver.preconditioner.coarsesolver.

Arrays of sub-trees needed PropertyTree::get_child_list / put_child_list,
which did not exist -- get_child_items_as_vector reads scalars.

With equivalent settings it reproduces the existing preconditioner exactly.
That works because TwoLevelMethodCpr keeps the same defect bookkeeping the
sweep does -- postsmooth reduces the defect with applyscaleadd(-1, lhs, rhs),
and SystemMatrix::usmv accumulates A,C into the reservoir half and B,D into the
well half, the same operations in the same order as the fixed version's four
mmv calls.

deck	system_cprw	general_system_cprw	system_cpr	general_system_cpr
SPE1CASE1	440	440	571	571
SPE9_CP	468	468	682	682
Norne	2248	2248	4303	4253
Norne, one segment per connection	2558	2558	4839	4972

On Norne all 2831 physical summary vectors are identical for both system_cprw
pairs; TCPU is the only one that differs. The two general_system_cpr figures
that do not match are the updateForChangedWellStructure trade described below --
Norne is the only one of these decks that opens and closes wells.

One exception, which the test states explicitly: with well_transfer = full the
well half of the result is a sum of three non-zero terms, and the two associate it
differently -- ((0 + dw) + c1) + c2 against dw + ((0 + c1) + c2), because Dune
adds the coarse correction to the update and then adds the smoother's separately
accumulated correction. They agree to one rounding step and no closer. The
reservoir half has two terms and stays exact, and classic (the default) and
no_prolongation stay exact because the coarse well correction is zero there.
Removing this would mean rewriting Dune's postsmooth, which also serves the
classic CPR path.

Two incidental changes:

• TwoLevelMethodCpr::pre resizes its work vectors, and MultiTypeBlockVector
  has no resize. Since pre is a virtual override it is instantiated whether or
  not it is called, so the resize is now behind if constexpr (requires ...).
  apply assigns to both vectors, which sizes them.
• preconditioner.well_structure_update chooses what a changed well structure
  costs: rebuild (default) builds every part again, refresh creates only what
  the wells size and refreshes the rest in place. Not cosmetic -- a CPR reservoir
  solve keeps its hierarchy when refreshed and re-aggregates it when rebuilt, and
  on Norne that moves general_system_cpr between 4253 and 4303 iterations.
  refresh is what the fixed version does, and with it both variants reproduce it
  exactly. The kind of change is classified too (Values / Pattern /
  Dimension), though Pattern and Dimension are still handled alike: a
  changed sparsity invalidates the coarse pattern as surely as a changed dimension.

Cost. Full Norne, two repeats on one binary, mean wall time:

	fixed	general, rebuild	general, refresh
system_cprw	143 s / 2248	145.5 s / 2248	142.5 s / 2248
system_cpr	172 s / 4303	172.5 s / 4253	175.5 s / 4303

Run-to-run spread is 3-5%, so nothing here separates them. The first version was
a consistent 3.8% slower because each step updated both halves of the residual
whether or not anything read them again -- a full A*corr over every cell in the
smoother, which the hand-written version omits by hand. Which halves are still
read is now decided once at build time.

🤖 Generated with Claude Code

[ElyesAhmed]

maybe need a fix as SystemCprwStep is defined but never instantiated anywhere..... The CPRW pressure stage is used as the two-level coarse solver via SystemPressureBhpTransferPolicy; the sweep only ever gets ReservoirStep/WellStep. Could we either delete it, or wire it up as a block: "cprw" sweep step if the intent was to allow the pressure stage inside the sweep..?

[hnil]

Right, SystemCprwStep is only reachable as the two-level coarse solver via SystemPressureBhpTransferPolicy, never from the sweep. It is there so a config can name it as a step; if you would rather it not exist until something instantiates it, I can drop it.

[ElyesAhmed]

This extraction is shared by every cpr/cprw configuration right?, not just the new solver, so a regression here would be wide.

[hnil]

Correct - it is on the shared cpr/cprw path, so a regression would be wide. That is why the extraction is a pure refactor with the same arithmetic; worth a reviewer eye on exactly that though.

[ElyesAhmed]

as before, we have a "minor" same consistency as in #7278: the code fallback here is "full" while the generated config ships "classic", so a general_system_cprw JSON omitting well_transfer silently gets a different preconditioner than the built-in one. Consider aligning the fallback to "classic" in both PRs.

[hnil]

Fixed in both places here - the fallback is classic now.

[ElyesAhmed]

The current unit test does not exercise the parallel (MPI) path — that coverage is provided only by the deck runs mentioned in the commit message. This is acceptable for a unit test in isolation.

However, if you would like to strengthen the testing, consider adding a small 2-rank test case. This would specifically validate the copyOwnerToAll placement inside apply and catch any regressions in the parallel logic.

Not necessary maybe in this PR

[ElyesAhmed]

This PR turns the fixed three‑stage preconditioner into a true two‑level method (TwoLevelMethodCpr + SystemPressureBhpTransferPolicy coarse space, with an ordered sweep as the fine smoother), while exactly reproducing the original behaviour. The reproduction is structural, not accidental — the setupSystem* helpers are shared between both layouts, and the test proves equality with a well‑reasoned tolerance exception for well_transfer=full. One thing is related to SystemCprwStep which is dead code see comment).
Maybe a rebase on #7278 once it merged is a good step, so this diff drops to its own 9 commits.