Skip to content

Fix AMR code by applying error estimator from Larson 2001 - #349

Merged
jorgensd merged 1 commit into
mainfrom
dokken/amr-fixes
Nov 4, 2026
Merged

jorgensd merged 1 commit into
mainfrom
dokken/amr-fixes

Conversation

@jorgensd

@jorgensd jorgensd commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Fix the error indicator and parallel marking in the adaptive refinement demo

The adaptive mesh refinement demo (chapter2/amr.py) solves the Laplace
eigenvalue problem, but mark_cells used the error indicator for the Poisson problem
$-\Delta u = 1$, and the indicator was summed incorrectly in parallel. This PR fixes the residual,
weights the facet term as in Larson (2000), and fixes the parallel marking, the formula in the text
and the termination check.

What was wrong

Before After
Cell residual f + div(grad(uh_r)) with f = 1; lam unused lam_h * uh_r + div(grad(uh_r))
Formula in the text Jump written as $[\nabla\cdot\mathbf n_E]$; facet term had ds but no $\int_E$ Larson's per-cell definition: $h_K\int_{\partial K\setminus\partial\Omega}\vert[\nabla u_h\cdot\mathbf n]/2\vert^2$, plus the global $\eta^2$
Facet weight per cell $h_K/2$ times the squared jump $h_K/4$ times the squared jump (half the jump, squared), as in Larson (3.6) and (5.2)
Assembly of $\eta_K^2$ in parallel Facet contributions to ghost cells never reached the owning process scatter_reverse(InsertMode.add) after assembly
Marked cells Ghost entries included, using partial values Owned cells only
Termination (lam - exact) / abs(exact) < 1e-5, which passes as soon as lam < exact abs(lam - exact) / abs(exact)
Sign of uh_r in the GIF np.sign(min), so round-off on the boundary could flip the frame Sign of the value with the largest magnitude

The residual bug comes from the upstream
ngsPETSc demo this
tutorial was ported from. There, the Poisson estimator from the ngsPETSc paper was kept when the
loop was changed to solve an eigenvalue problem. Refinement still concentrated at the re-entrant
corner, because the facet jumps dominate there, so the GIF looked right. Away from the corner, a
different set of cells was marked.

Changes

mark_cells

  • Uses the eigenvalue residual $\lambda_h u_h + \Delta u_h$. $\lambda_h$ is a Constant, so the
    form isn't recompiled at every iteration.
  • Replaces the two one-sided facet terms, h("±") / 2 * flux_jump**2 against w("±"), with a single
    term, inner((flux_jump / 2) ** 2, 2 * avg(h * w)) * dS. Each cell now gets $h_K/4$ times the
    squared jump over each of its interior facets, as in Larson (2000), Equation 5.2.
  • After assemble_vector, calls eta_squared.x.scatter_reverse(dolfinx.la.InsertMode.add). With
    GhostMode.shared_facet, each facet on a process boundary is integrated on one process only, so
    without this, owned cells next to the boundary lost the facet contributions from their
    neighbours.
  • Marks only owned cells. eta_max is computed with an allreduce that also works on a process
    with no cells.
  • Maps between cells and DG0 dofs through W.dofmap.list, instead of assuming that dof i belongs
    to cell i.
  • Compares the NumPy array directly, instead of interpolating a ufl.conditional through an
    Expression. This also removes the version check for interpolation_points.

Text

  • The indicator is now written per cell, following Larson (2000), Equations 3.5-3.7: the facet part
    is half the jump of the normal derivative, integrated over $\partial K\setminus\partial\Omega$ and
    weighted by $h_K$.
  • A note explains why this definition becomes inner((flux_jump / 2) ** 2, 2 * avg(h * w)) * dS in
    UFL. Each interior facet contributes to both of its cells, and $h^+w^+ + h^-w^- = 2,\mathrm{avg}(hw)$.
    The note also says that Larson bounds the error by $\Vert h(R_i+R_e)\Vert$, which differs from
    $\eta$ by at most a factor 2.
  • A sentence describes the marking strategy ($\eta_K &gt; \theta,\eta_{\max}$, $\theta = 0.5$) and the
    reverse scatter.
  • Citations to Larson (2000) and Durán, Padra and Rodríguez (2003) were added to
    references.bib, with a per-page {bibliography} block using keyprefix: amr-,
    following chapter4/mixed_poisson.py.

Loop and plotting

  • The termination check uses the absolute relative error. With a curved approximation of the
    domain, $\lambda_h \ge \lambda$ is not guaranteed.
  • write_frame takes the sign of the eigenfunction from the value with the largest magnitude. It
    uses min(initial=...) and max(initial=...) so that a process with no dofs doesn't raise.

chapter2/amr.ipynb was regenerated with jupytext --sync.

Testing

NetGen is not available in the environment where this was developed, so the full demo was not run.
Instead, the final mark_cells was copied verbatim from the tutorial and tested on a P3 function on
the unit square, using a 12×12 mesh with GhostMode.shared_facet for the parallel tests.

Parallel:

Test Result
Marked cells (by original cell index), 1 vs 3 vs 4 processes Identical (34 cells)
Facet contributions per cell, 4 processes, with the reverse scatter Matches serial (relative difference ≈ 1e-13)
Same, without the reverse scatter (the old code) 24 of 288 cells wrong, by up to 2.7% of $\eta_{\max}$

Facet term against Larson's definition, on a graded 9×7 mesh where neighbouring cells have
different diameters. $J = [\nabla u_h\cdot\mathbf n]$ is the jump of the normal derivative.

Test Result
Larson (5.2) computed directly: $\int_{\partial K\setminus\partial\Omega}J^2$ assembled per cell, then multiplied by $h_K/4$ Reference
The tutorial's inner((flux_jump / 2) ** 2, 2 * avg(h * w)) * dS Matches the reference in every cell (relative difference ≈ 2e-16)

ruff check and ruff format --check pass.

Not yet checked:

  • The demo itself, with NetGen, and the new {bibliography} block. The Jupyter Book build in CI
    executes the demo in serial and renders the page.
  • The demo in parallel. CI does not run amr.py with mpirun, so the parallel fixes are only
    covered by the test above. A suggested check is mpirun -n 2 python3 amr.py.
  • The GIF. amr.gif is generated by the book build. A different set of cells is now marked, so the
    refinement pattern in the GIF will change.

🤖 Generated with Claude Code

@jorgensd
jorgensd merged commit 024c2f9 into main Nov 4, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant