Skip to content

Add assemble_lumped_mass! primitive#306

Merged
cmhamel merged 1 commit into
mainfrom
feature/assemble-lumped-mass
Jun 6, 2026
Merged

Add assemble_lumped_mass! primitive#306
cmhamel merged 1 commit into
mainfrom
feature/assemble-lumped-mass

Conversation

@lxmota

@lxmota lxmota commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds assemble_lumped_mass! — a partition-of-unity row-sum lumped mass primitive computed directly via per-element scatter of density * N[a] * JxW * I_NDIM, into the assembler's full-DOF residual storage, with free-DOF unknowns extracted for non-condensed mode.

This is distinct from the existing assembly primitives:

  • assemble_mass! builds the full sparse consistent mass matrix.
  • assemble_diagonal!(asm, mass, ...) extracts the diagonal of the consistent mass (rho * integral N_a^2 dV), which is not partition of unity.
  • assemble_matrix_action!(asm, mass, U_zeros, ones_free, p) silently under-counts contributions from constrained columns and breaks partition of unity at free DOFs adjacent to Dirichlet boundaries.

Why this primitive

This is the right primitive for:

  • Explicit central-difference dynamics (a = M^-1 f), where partition of unity (total mass = density × volume) is required to recover correct wave speeds at free DOFs adjacent to a Dirichlet boundary.
  • Mass-diagonal Jacobi preconditioning, for the same SPD reason.

The row-sum-of-reduced-M approach used previously by some downstream code (Carina.jl) under-counts mass at boundary-adjacent DOFs because M_red * 1_free misses the M_{free,BC} cross terms.

Implementation notes

Reuses the existing assemble_vector! scatter machinery via the AssembledVector return type, so GPU support is inherited automatically (fec_atomic_add! over an H1Field on the target backend, no CPU detour).

Exports:

  • assemble_lumped_mass!(assembler, func, Uu, p) — assembly entry point, mirrors the assemble_diagonal! calling convention.
  • lumped_mass(asm) — accessor returning free-DOF unknowns (non-condensed) or full-DOF (condensed).

Compute the partition-of-unity row-sum lumped mass directly via
per-element scatter (density * N[a] * JxW * I_NDIM), into the
assembler's full-DOF residual storage; extract free-DOF unknowns
for non-condensed mode.

Distinct from:
  - assemble_mass! (full sparse consistent mass)
  - assemble_diagonal!(asm, mass, ...) (diagonal of consistent mass,
    rho * integral N_a^2 dV, NOT partition of unity)
  - assemble_matrix_action!(asm, mass, U_zeros, ones_free, p) which
    silently under-counts contributions from constrained columns and
    breaks partition of unity at free DOFs adjacent to Dirichlet
    boundaries.

This is the right primitive for explicit central difference dynamics
(a = M^-1 f) and for mass-diagonal Jacobi preconditioning, because it
preserves partition of unity (total mass = density * volume) by
construction.

Reuses the existing assemble_vector! scatter machinery via the
AssembledVector return type, so GPU support is inherited automatically
(fec_atomic_add! over an H1Field on the target backend, no CPU detour).

Test mirrors the existing AssemblerHelperMechanics setup and validates
three invariants: (a) on a fully-free DOF space the result equals the
row sums of the consistent mass matrix; (b) on a BC-restricted space
the result equals (a) restricted to free DOFs; (c) the result
disagrees with the legacy M_red * 1_free approach at free DOFs near
the boundary (regression marker for the under-count bug).
@lxmota lxmota requested a review from cmhamel June 6, 2026 23:06
@codecov

codecov Bot commented Jun 6, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 65.59%. Comparing base (fd5f098) to head (a957563).
⚠️ Report is 11 commits behind head on main.

Files with missing lines Patch % Lines
src/assemblers/LumpedMass.jl 95.23% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #306      +/-   ##
==========================================
- Coverage   66.33%   65.59%   -0.75%     
==========================================
  Files          55       56       +1     
  Lines        4848     4868      +20     
==========================================
- Hits         3216     3193      -23     
- Misses       1632     1675      +43     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@cmhamel cmhamel merged commit 56270a8 into main Jun 6, 2026
3 of 13 checks passed
@cmhamel cmhamel deleted the feature/assemble-lumped-mass branch June 6, 2026 23:35
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