Add boundary integral support (BdIntegral) with PETSc ghost facet fix

.gitignore

@@ -250,6 +250,9 @@ debug_*.py
 
 # Visualization output files (generated during notebook execution)
 docs/beginner/tutorials/html5/*.html
-petsc-custom/petsc/
+# Pixi environment (directory in main repo, symlink in worktrees)
+.pixi
 .pixi-env
+# PETSc build (directory in main repo, symlink in worktrees)
+petsc-custom/petsc
 Untitled*.ipynb

CHANGES.md

@@ -1,5 +1,19 @@
 # CHANGES: Underworld3
 
+## 2026-03-13
+
+  - New `uw.maths.BdIntegral` for boundary and surface integrals:
+    - Wraps PETSc `DMPlexComputeBdIntegral` with MPI Allreduce and units support
+    - Works on external boundaries, internal boundaries (`AnnulusInternalBoundary`, etc.)
+    - Integrand can reference outward unit normal via `mesh.Gamma` / `mesh.Gamma_N`
+    - Handles PETSc API change in v3.22.0 (function pointer signature)
+  - PETSc patch for internal boundary assembly in parallel (`plexfem-internal-boundary-ownership-fix.patch`):
+    - Ghost facet filtering in boundary integral, residual, and Jacobian paths
+    - Part-consistent assembly (`support[key.part]`) with support-size guards
+    - Fixes rank-dependent L2 norms for internal boundary natural BCs (issue #77)
+  - MPI regression test: `tests/parallel/test_0765_internal_boundary_integral_mpi.py`
+  - Boundary integral tests: `tests/test_0502_boundary_integrals.py`
+
 ## 2025-12-21
 
   - PETSc 3.24 compatibility verified (conda-forge petsc 3.24.2 works correctly)

CLAUDE.md

@@ -198,16 +198,20 @@ worktree changes, the worktree edits will not be active. Always:
 2. `./uw build`
 3. Run your code / tests from there
 
-### AI-Assisted Commit Attribution
-When committing code developed with AI assistance, end the commit message with:
+### AI-Assisted Attribution (Commits and PRs)
+When committing code or creating pull requests with AI assistance, end the
+message/body with:
 
 ```
-Underworld development team with AI support from Claude Code
+Underworld development team with AI support from [Claude Code](https://claude.com/claude-code)
 ```
 
+(In commit messages, use the plain-text form without the markdown link.)
+
 **Do NOT use**:
 - `Co-Authored-By:` with a noreply email (useless for soliciting responses)
 - Generic AI attribution without team context
+- Emoji in PR descriptions
 
 ---
 
@@ -220,11 +224,20 @@ Underworld development team with AI support from Claude Code
 - Requires complete rebuild (~1 hour) if relocated
 
 ### Rebuild After Source Changes
-**After modifying source files, always run `pixi run underworld-build`!**
+**After modifying source files, always run `./uw build`!**
 - Underworld3 is installed as a package in the pixi environment
 - Changes go to `.pixi/envs/default/lib/python3.12/site-packages/underworld3/`
 - Verify with `uw.model.__file__`
 
+**⚠️ STALE BUILD CACHE**: If `./uw build` succeeds but Python still uses old code
+(e.g. a new parameter is "unknown"), pip's wheel cache is stale. Fix with:
+```bash
+rm -rf build/lib.* build/bdist.*
+pixi run -e default pip install --no-build-isolation --force-reinstall --no-deps .
+```
+This is the most common build issue — `./uw build` reuses cached wheels when the
+version number hasn't changed. Always verify changes are installed before debugging.
+
 ### Test Quality Principles
 **New tests must be validated before making code changes to fix them!**
 - Validate test correctness before changing main code
@@ -534,10 +547,10 @@ When working on specific subsystems, these documents provide detailed guidance.
 
 ## Quick Reference
 
-### Pixi Commands
+### Build & Test Commands
 ```bash
-pixi run underworld-build    # Rebuild after source changes
-pixi run underworld-test     # Run test suite
+./uw build                   # Rebuild after source changes (preferred)
+./uw test                    # Run test suite
 pixi run -e default python   # Run Python in environment
 ```
 

docs/advanced/parallel-computing.md

@@ -18,6 +18,56 @@ Underworld3 uses PETSc for parallel operations, which means **you rarely need to
 
 The main use of `uw.mpi.rank` is for conditional output/visualization.
 
+## MPI + Thread Pools (Oversubscription)
+
+When running with MPI, each rank can also spawn BLAS/OpenMP worker threads.
+If this is not controlled, total runnable threads can explode and performance
+can degrade severely.
+
+Example: `mpirun -np 8` with OpenBLAS default `10` threads can create up to
+`80` compute threads, often slower than expected.
+
+### Default Underworld3 Policy
+
+Underworld3 now applies MPI-safe defaults (thread pool size `1`) unless users
+explicitly set their own values:
+
+- `OMP_NUM_THREADS`
+- `OPENBLAS_NUM_THREADS`
+- `MKL_NUM_THREADS`
+- `VECLIB_MAXIMUM_THREADS`
+- `NUMEXPR_NUM_THREADS`
+
+This happens in two places:
+
+1. `./uw` launcher: sets defaults before Python starts.
+2. `underworld3` import path: applies the same defaults for MPI runs if unset.
+
+### Runtime Warning
+
+If running with MPI and any of the thread variables above are explicitly set
+to values greater than `1`, Underworld3 prints a rank-0 warning about possible
+oversubscription.
+
+### User Controls
+
+- Disable automatic thread caps:
+
+```bash
+export UW_DISABLE_THREAD_CAPS=1
+```
+
+- Suppress warning (keep your explicit thread settings):
+
+```bash
+export UW_SUPPRESS_THREAD_WARNING=1
+```
+
+### Recommended Practice
+
+For most MPI benchmark and production jobs, keep `1` thread per rank unless
+you are intentionally tuning hybrid MPI+threads.
+
 ## Parallel-Safe Output
 
 ### The Problem with Rank Conditionals
@@ -468,4 +518,4 @@ These operations require **ALL ranks** to participate:
 4. **Collective operations must run on ALL ranks** - never inside rank conditionals
 5. **Test with `mpirun -np N`** to catch issues early
 
-The parallel safety system makes parallel programming in Underworld3 safer and more intuitive - collective operations are evaluated on all ranks automatically, preventing common deadlock scenarios!
+The parallel safety system makes parallel programming in Underworld3 safer and more intuitive - collective operations are evaluated on all ranks automatically, preventing common deadlock scenarios!