Skip to content

Add generic Ferrite assembly driver for per-quadrature-point kernels - #5

Merged
xtalax-droid merged 3 commits into
forge/m1-2-kernelsfrom
forge/m1-3-assembly
Oct 26, 2026
Merged

xtalax-droid merged 3 commits into
forge/m1-2-kernelsfrom
forge/m1-3-assembly

Conversation

@xtalax-droid

@xtalax-droid xtalax-droid commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

PR 3 of 4 for milestone M1 (spec §11.1): the generic Ferrite assembly driver. Stacked on #4 (emit_kernels, base forge/m1-2-kernels), which is stacked on #1.

What

This adds an internal, unexported driver that assembles the per-quadrature-point kernels from emit_kernels, f(U, G, Ud, V, W, X, T, N, P), with Ferrite.

  • AssemblyContext(dh, fields, cv, fv, pieces) holds the DofHandler, the field order (which is also the equation index), the shared CellValues and FacetValues, and a map from boundary piece to facet set. A facet set can be given as a grid facet-set name or as a set of FacetIndex.
  • assemble_linear(ctx, kernels, p; t, ch) returns (; M, K, F).
    • M comes from the :mass kernels, evaluated with a unit trial function in Ud.
    • K comes from the :bilinear kernels, evaluated with a unit trial function in U and G.
    • F is −∫source.
    • All three share one sparsity pattern from allocate_matrix(dh[, ch]). An in-place assemble_linear! is also provided.
  • assemble_nonlinear(ctx, kernels, u, p; t, ch) returns (; r, J). It assembles the :nonlinear kernels and their tangents ∂I/∂[U; G] in one pass. An in-place assemble_nonlinear! is also provided.
  • The driver makes one pass over the mesh, with a single Ferrite.reinit! per cell. Kernels are iterated as a tuple behind a function barrier, so each kernel's loop is type-stable. Multi-field problems use field-major slots and dof_range element blocks.
  • Facet kernels are assembled only on their own piece, using FacetIndex membership. The number of facets assembled per piece is asserted to equal the size of its set.

The residual convention is M u̇ + K u − F + r(u) = 0. Constraints and DAE lowering are not in this PR; they belong to M2. m2's FEMSpace (#2) maps onto AssemblyContext without changes to either side.

Why

This covers spec §6.5 (the kernel slot-in rules: Ferrite.reinit!, FacetIndex membership, the facet-count assertion), §6.6 (function barrier, concrete kernel types, nonlinear r and J in one pass, shared pattern) and the traps in Appendix C. It consumes the kernels from stage f of §5.1.

Tests

The tests are in a new Assembly group, test/Assembly/assembly.jl, with 22 tests.

  • End to end: case (i) goes through the stand-in analyse, then weak_form, then emit_kernels, then this driver. K, M and F agree with a hand-written Ferrite loop to relative error ≤ 1e-14.
  • Case (i) with hand-built kernels, on generate_grid(Triangle, (20, 20)) with a source, a Neumann piece and a Robin piece: K, M and F agree to ≤ 1e-14, and M and K share one pattern.
  • Facet terms are non-vanishing: sum(F) with and without the Neumann datum differs by k·h·|Γ|.
  • Error paths: the facet-count assertion fires on invalid facet entries, and an unknown facet-set name or an unknown piece raises an error.
  • Two fields with cross-diffusion, linear coupling, a nonlinear ±u²w reaction and per-equation Neumann data: K, M, F and r agree with hand-written blocks to ≤ 1e-14, and J agrees with central differences to ≤ 1e-9.
  • Case (iii), k(u) = 1 + u² with a nonlinear Neumann facet term: r agrees with a hand-written residual at a random state to ≤ 1e-14, and J agrees with central differences to ≤ 1e-9.

GROUP=Assembly passes 22/22. Runic is clean. Codex review approved it with no findings.

Branches covered: linear assembly (mass, bilinear, source; volume and facet), nonlinear residual and Jacobian, single-field and two-field, Neumann, Robin, nonlinear natural conditions, and the facet-set error paths.

Performance

On the 100×100 P1 case (i), with the real emit_kernels kernels, compared with the hand-written loop from the prototype:

  • Volume terms take 1.25× as long, or 1.09× when assembling in place.
  • With the Neumann and Robin facets, they take 1.78× as long.
  • The in-place pass allocates 4–12 kB per call. Allocating a single matrix allocates 3.9 MB.

For comparison, the prototype's naive driver measured 68× and its function-barrier variant 5.3×.

Reviewer notes

  • Facet membership costs one Set lookup per local facet per piece on every cell. That is cheap at 3 pieces, but it scales with the number of pieces.
  • Unit-trial evaluation assumes the :mass and :bilinear kernels are exactly linear in their slots. classify (Add weak_form and classify (strong-to-weak stage e) #1) guarantees this.
  • The code reads dh.grid directly because Ferrite.get_grid is not public.

Follow-up commit

80b9c41 renames the element state vector ue to u_elem, because the Typos spell check flagged it. Codex review approved it with no findings. The branch has since been rebased onto #4's head; git range-diff shows every patch unchanged.


🤖 Posted by an AI agent · harness: Claude Code 2.1.310 · model: claude-opus-5-5
Review: unreviewed
Session: d6252e53-ed42-4149-9811-233262edb2ef

xtalax and others added 3 commits October 26, 2026 16:18
Implements spec §6.5/§6.6 for M1: one pass per operator set over the cells with a shared Ferrite.reinit!, kernels iterated as a tuple through a function barrier, facet kernels by piece with FacetIndex membership and a facet-count assertion, linear M/K/F on one sparsity pattern and nonlinear r/J in one pass. Defines KernelSpec per the M1 contract (deduplicated against PR 1 at rebase).

Agent-Harness: Claude Code 2.1.310
Agent-Model: claude-opus-5-5
Agent-Session: d6252e53-ed42-4149-9811-233262edb2ef
Agent-Review: unreviewed
Co-authored-by: Claude Code <agent@noreply.juliahub.com>
…tests to Assembly group

Drops the duplicate src/kernelspec.jl now that src/weakform.jl defines KernelSpec with the same fields. Adds a case (i) check from seam analysis through weak_form and emit_kernels to the driver against the hand-written reference, and moves the driver tests to test/Assembly/ with an [Assembly] entry in test_groups.toml.

Agent-Harness: Claude Code 2.1.310
Agent-Model: claude-opus-5-5
Agent-Session: d6252e53-ed42-4149-9811-233262edb2ef
Agent-Review: unreviewed
Co-authored-by: Claude Code <agent@noreply.juliahub.com>
CI's typos check reads the identifier ue as a misspelling of use/due.

Agent-Harness: Claude Code 2.1.310
Agent-Model: claude-opus-5-5
Agent-Session: d6252e53-ed42-4149-9811-233262edb2ef
Agent-Review: unreviewed
Co-authored-by: Claude Code <agent@noreply.juliahub.com>
@xtalax-droid
xtalax-droid merged commit ba4bfd6 into forge/m1-2-kernels Oct 26, 2026
5 checks passed
xtalax-droid added a commit that referenced this pull request Oct 27, 2026
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.

2 participants