Repository navigation
Description
Stage 3 of #56. Extend the compact flux-form Diffusion leaf to BlockForest, on the per-leaf reference path (packed GPU kernels are stage 4).
This is the stage with genuine open design questions. It should get its own design pass before implementation — the two questions below are not settled by anything that exists today, and one of them can only be answered by measurement.
Already in place
The declared transpose gather is written and tested. apply_adjoint! branches on _has_interface(g) and falls through to a bounds-masked adjoint_gather!, exercised in test/diffusion.jl and in the accumulating-gather contract cases in test/operators_abstract.jl — both construct the leaf through the inner constructor on a grid carrying Interface faces, with κ ghosts filled by hand. That hand-filling is precisely what this stage has to supply for real.
Open question 1 — how κ crosses an Interface face
Unlike a slab (stage 2), a forest has no global κ array to slice: the coefficient is already a BlockField partitioned into blocks, so this needs a real exchange. It must be coefficient-appropriate, and the existing solution exchange is wrong for it on both halves:
- same-level face copies are exact and can be reused as-is;
- coarse→fine must not use the Martin–Cartwright quadratic interpolant (
_emit_interp!, weights in_cf_normal_weights) — that is tuned for solution smoothness, not a material coefficient; - fine→coarse must not use the flux-matching restriction (
_emit_restrict!, weight2/2^(N-1)) — a volume average is what a coefficient wants.
Because κ is constant through a solve, the exchange belongs once at prepare/construction, cached, never per apply (#56 invariant, and a #54 success criterion).
Decide explicitly whether AD with respect to κ on a forest must flow through that exchange, and therefore whether it needs its own adjoint or a custom rule. Do not reuse the existing _exchange_storage! rules for κ: the weights differ, and a rule firing on a path that carries operator parameters is the exact failure mode the package forbids, because it silently zeroes coefficient gradients.
Open question 2 — one authoritative flux per coarse–fine face
#54 §3 requires that the coarse residual receive the area-weighted sum of the abutting fine-face fluxes rather than an independently evaluated coarse flux. Whether the existing coarse–fine ghost machinery already delivers that for the diffusion flux, or whether a separate flux-injection seam is needed, must be settled by a conservation test, not by reading the code: Σ V·(Lu) ≈ 0 to roundoff on a refined forest under periodic and no-flux boundaries. Write that test first; let it decide the design.
If a seam is needed, factor it as a face-flux descriptor that reuses the existing topology cache rather than adding a second schedule.
Scope
_leaf_op(D::Diffusion, i, lg)slicing κ per block (src/operators/forest.jl:53-57), plus same-forest validation at construction.- The coefficient exchange from question 1, and whatever question 2 concludes.
_prepare_tree(D::Diffusion{<:BlockField}, ::PackedBlockField)so a packed prototype packs the coefficient (src/linalg.jl:208-210).- Relax the public constructor to accept a
BlockForestand anAbstractBlockFieldcoefficient once — and only once — the ghosts are genuinely supplied.
Watch out for
isselfadjointmust keep routing through_selfadjoint_grid, which goes false on a non-uniform forest — coarse–fine interpolation is not symmetric. The gather is load-bearing there, not an optimization.- Per-leaf stencil adjoints must leave corner ghosts exactly zero (
src/transfer.jl:343-347). A compact flux stencil never reads corners, so this should hold for free — assert it rather than assume it. operator_diagonalcontinues to throw on forest leaves, matchingLaplacian; forest multigrid is out of scope regardless.- A
regrid!invalidates coefficient fields that were not passed through it, and any cached κ exchange must be invalidated on the same generation counter asPreparedForest.
Acceptance
- Forest-vs-single-grid parity: a uniform forest reconstructs the same action, adjoint, and
boundary_rhsas the equivalentCartesianGrid. Σ V·(Lu) ≈ 0to roundoff on a refined (non-uniform) forest under periodic and no-flux boundaries — the test that settles question 2.- Adjoint dot-product identity on a refined forest, and corner ghosts exactly zero after the adjoint.
- No additional halo exchange per application versus the
Laplacianbaseline.
Activity
test(amr): conservation test convicts the coarse-fine diffusion flux
docs(amr): record the conservative coarse-fine flux decision
docs(diffusion): split the Interface-face advice by grid kind
docs(design): fix the §8 scope note and one term
test(amr): conservation test convicts the coarse-fine diffusion flux
docs(amr): record the conservative coarse-fine flux decision