Skip to content

feat(amr): compact diffusion leaf on BlockForest, with conservative coarse-fine flux #58

Closed

Description

@kylebeggs

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!, weight 2/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 BlockForest and an AbstractBlockField coefficient once — and only once — the ghosts are genuinely supplied.

Watch out for

  • isselfadjoint must 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_diagonal continues to throw on forest leaves, matching Laplacian; 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 as PreparedForest.

Acceptance

  • Forest-vs-single-grid parity: a uniform forest reconstructs the same action, adjoint, and boundary_rhs as the equivalent CartesianGrid.
  • Σ V·(Lu) ≈ 0 to 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 Laplacian baseline.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions