Harden BdIntegral boundary label resolution across mesh label layouts

[Copilot]

Architectural Review Submission

Review Type: Code Implementation
Priority: MEDIUM
Review Period: 2026-03

---

📄 Review Document

• File: docs/reviews/2026-03/bdintegral-label-resolution-REVIEW.md
• Tracking Index: docs/reviews/2026-03/REVIEW-TRACKING-INDEX.md

📋 Executive Summary

uw.maths.BdIntegral previously assumed a per-boundary DM label existed and could fail on meshes that only expose the consolidated UW_Boundaries label.
This update makes boundary label resolution robust by falling back to UW_Boundaries and adding a collective missing-label guard with a clear error message.

• What changed
  • Label resolution hardening
    • Try mesh.dm.getLabel(self.boundary) first.
    • Fallback to mesh.dm.getLabel("UW_Boundaries") when per-boundary label is absent.
  • Collective validation
    • Add MPI-collective check so we only raise when labels are absent globally, avoiding per-rank ambiguity.
  • Diagnostics
    • Error now includes requested boundary and mesh name for fast triage in multi-mesh workflows.

c_label = mesh.dm.getLabel(self.boundary)
if c_label is None:
    c_label = mesh.dm.getLabel("UW_Boundaries")
if underworld3.mpi.comm.allreduce(1 if c_label else 0) == 0:
    raise ValueError(
        f"Boundary '{self.boundary}' was requested on mesh '{mesh_name}', "
        f"but neither '{self.boundary}' nor 'UW_Boundaries' exists on this mesh."
    )

🎯 Scope

Systems Affected:

• Core solvers (Stokes, Poisson, Advection-Diffusion)
• Variable system (Mesh/Swarm variables, arrays)
• Units & non-dimensionalization
• Parallel operations (MPI, collective operations)
• Testing infrastructure
• Documentation & examples
• Other: Boundary integration API (uw.maths.BdIntegral)

Files Changed:

• New files: 0
• Modified files: 1
• Total LOC: ~12

✅ Testing Status

• All tests passing: pixi run underworld-test
• New tests added: 0 tests
• Test coverage: N/A
• Regression tests validated
• Performance benchmarks run (if applicable)

Test Results:

# Command used
N/A (no new test execution added in this follow-up change)

# Results summary
N/A

📊 Key Metrics & Impact

Performance:

• Before: Boundary integral could fail for meshes exposing only consolidated boundary labels.
• After: Same boundary integral path works across both label layouts.
• Improvement: Reliability increase; no algorithmic/runtime change intended.

Quality:

• Test coverage: unchanged
• Code complexity: slight increase (defensive label resolution + collective guard)
• Documentation: unchanged

🔍 Review Checklist (for Reviewers)

Design & Architecture:

• Design rationale is clear and well-justified
• Trade-offs are documented with alternatives considered
• System architecture is comprehensible
• Integration points are identified

Implementation:

• Implementation matches documented design
• Code quality meets project standards
• Breaking changes are identified and justified
• Backward compatibility is addressed

Testing & Validation:

• Testing strategy is adequate
• Test coverage is sufficient
• Edge cases are covered
• Performance impact is assessed

Documentation:

• Known limitations are clearly documented
• Benefits are quantified
• User-facing changes are documented
• Migration guide provided (if needed)

⚠️ Known Limitations

1. This change only hardens label lookup and missing-label behavior; it does not alter PETSc boundary integration semantics.
2. Meshes with inconsistent boundary labeling remain invalid and will now fail earlier with explicit diagnostics.

🔗 Dependencies & Related Work

Depends on:

• Review #XXX (must be approved first)

Blocks:

• Review #YYY (waiting on this review)

Related:

• Discussion: [Link to GitHub Discussion]
• Prior art: [Links to related reviews]

---

🖊️ Sign-Off

This PR merge represents formal approval of the architectural review.

Reviewers: Please review the full document at docs/reviews/YYYY-MM/[NAME]-REVIEW.md and approve this PR only when satisfied with the design, implementation, and documentation.

Role	GitHub Handle	Sign-Off Date	Status
Author	@copilot	2026-03-06	✅ Submitted
Primary Reviewer	@reviewer1		⏳ Pending
Secondary Reviewer	@reviewer2		⏳ Pending
Project Lead	@lead		⏳ Pending

---

📝 Additional Context

This is a focused follow-up to review feedback: no API expansion, no behavior change for meshes already carrying per-boundary labels, and no new dependencies.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[lmoresi]

Closing — this was generated from the original review comment, but the issue was already addressed in commit 220fd1c with a different (and more correct) approach: the C wrapper now handles NULL labels gracefully by participating in the MPI reduction with a zero contribution, and the Cython layer passes NULL instead of segfaulting. The UW_Boundaries fallback proposed here doesn't match how UW3 mesh labels actually work.