docs: Wave E alignment — authority map, style-guide de-drift, changelog, value-first call-site sweep (WE-01..03,05,06,08,09,10) by lmoresi · Pull Request #338 · underworldcode/underworld3

lmoresi · 2026-07-06T17:52:04Z

Wave E of the July 2026 quality campaign: bring documentation, the style guide, and legacy call sites into line with the merged Waves A/C and the UW3 Style Charter. Implements the Wave E rows of docs/reviews/2026-07/REMEDIATION-WORKLIST.md, with evidence in docs/reviews/2026-07/DOCS-STANDARDS-COHERENCE.md (DOC-01..08).

Per-item summary

Item	Finding	Status	Commit
WE-01	DOC-04	Authority map adopted: CLAUDE.md Data Access pointer repointed to `subsystems/data-access.md`; Charter §10 authority table recorded in `docs/developer/index.md`; Charter added to the Getting Started toctree	`c31972b`
WE-02	DOC-01, SWARM-13	Style Guide de-drifted: NumPy/RST docstring section (replaces Markdown-for-pdoc), MyST `.md` (replaces Quarto `.qmd`), real runnable coordinate examples (`mesh.X.coords`, `mesh.deform()`, `swarm.coords` setter — the old "Preferred" `swarm.data += …` raises AttributeError), Quarto front matter dropped, Charter declared normative	`d412cfb`
WE-03	DOC-02	`review_queue.md` + `inventory.json` regenerated over all of `src/`; DOC-02 cross-validation passes (solve/SNES_Scalar no longer flagged; June API present, 13 mentions; DOC-05 targets flagged). Three parser bugs in `scripts/docstring_sweep.py` fixed to make the queue truthful (blank-line-eating indent regex, multi-line signatures, `r"""` docstrings). Sweep added to the release checklist	`89aaaf6`
WE-05	DOC-03	Changelog backfilled May – early July 2026: 14 grouped entries (new Q3 section + extended Q2), including the quality-campaign PRs #309–#313, #317, #322–#326, #329, #334 as grouped entries; every entry backed by a merged commit (`git log --first-parent aed517f6..3184a406`). Changelog sweep added to the release checklist	`bee8d7a`
WE-06	DOC-07	Status headers stamped on the 13 unmarked design docs (re-derived count; the audit's ~16 over-counted) + corrected the stale "Design Phase" marker on MATHEMATICAL_MIXIN_DESIGN.md. Every stamp verified against `git log --follow` and the current source before writing	`2988ded`
WE-08	API-12	`units.py`: 18 public docstrings converted Google → NumPy (docstring-only; `dimensionalise` was already NumPy; privates untouched)	`857fd0a`
WE-09	API-01/02 sweep	74 call sites of `add_nitsche_bc` / `add_rotated_freeslip_bc` / `add_constraint_bc` migrated to canonical value-first `(conds, boundary, ...)`: tests/ 63 (12 files), docs/ 7, .claude/skills/ 3, CLAUDE.md 1. `test_0641_wave_c_api_shims.py` untouched (its legacy calls are the deprecation contract); legacy-trio sites untouched per D2	`ef04f22`
WE-10	LE-23	Already resolved upstream — Wave A #325 (`51e7b0e`) rewrote the exact `disk_snapshot.py` "Phase 1 (this commit)" header; verified no stale text remains. No action	—

Deferred: WE-04, WE-07 (Wave B file overlap), WE-11 (swarm-design-doc agent).

Bug found (reported, not fixed — Charter §9)

The WE-09 sweep exposed a Wave C shim bug: add_rotated_freeslip_bc(0.0, boundary) — the canonical form its own deprecation message recommends — raises NotImplementedError because the zero-datum guard uses structural sympy comparison (sympy.sympify(0.0) != 0 is True). Filed as #336 with a TODO(BUG) marker at the guard (comment-only). Swept call sites use the working conds=0 integer form.

Gates

pytest -m "level_1 and tier_a" — pre (development tip, working tree stashed): 369 passed, 10 skipped, 2 xfailed, 1 xpassed, 0 failed (95 warnings). Post: 369 passed, 10 skipped, 2 xfailed, 1 xpassed, 0 failed (39 warnings — the drop is the sweep no longer exercising the Wave C deprecation shims).
Every WE-09-touched test file run in full, zero DeprecationWarning: serial — test_1017/1060/1065×2 (15 passed), test_1018 (14 passed), test_1061+1062 (16 passed), test_1064 spherical response (passed); parallel at np2 — test_1062+1063 (4 passed), test_1064+1017 (12 passed). Residual warnings are pre-existing UserWarnings (monolithic-LU diagnostic), not deprecations.
Docs build (pixi run -e amr-dev docs-build): succeeded, 36 warnings vs 37 baseline — one warning removed (Charter now in a toctree), zero new.
WE-05/WE-06 factual accuracy: every changelog entry and status stamp cites a merged commit/PR verified in git log (per-doc verification recorded in the WE-06 commit message).
No lockfile/dependency changes; src touches limited to units.py docstrings (WE-08) and the sanctioned comment-only TODO(BUG) marker (Wave B overlap checked: feature/wave-b-migration does not touch disk_snapshot.py or these files).

Underworld development team with AI support from Claude Code

Repoint CLAUDE.md's Data Access 'Authoritative Reference' from the stale UW3_Style_and_Patterns_Guide.md to subsystems/data-access.md (the guide it crowned teaches patterns the code deprecates at runtime — DOC-04), and record the Style Charter §10 authority table in docs/developer/index.md as the master authority index. The Charter is added to the Getting Started toctree (removes a baseline 'not included in any toctree' warning). Finding: DOC-04 (docs/reviews/2026-07/DOCS-STANDARDS-COHERENCE.md). Underworld development team with AI support from Claude Code

Rewrites the sections DOC-01 verified as contradicting the settled standards: - Docstring format: the 'Markdown Docstrings for pdoc/pdoc3' section is replaced by the NumPy/Sphinx RST standard (worked example with :math: and Parameters/Returns/Examples/Notes; conversion tracked in docs/plans/docstring-conversion-plan.md), per Style Charter section 6. - Doc file format: Quarto .qmd prescription (zero .qmd files exist in the repo) replaced by MyST .md/Sphinx guidance matching CLAUDE.md; migration table row updated. - Data access examples: 'Preferred' coordinate examples now use the real, runnable API — mesh.X.coords (read), mesh.deform() (coordinate changes), and the swarm.coords getter/setter for particle positions. The previous 'Preferred' example swarm.data += displacement raises AttributeError (getter-only property — SWARM-13 evidence); mesh.data warns at runtime. The private-attribute migration advice (swarm._particle_coordinates, mesh._deform_mesh presented as the NEW pattern) is deleted. - Front matter: the 21-line Quarto YAML header is replaced by a minimal MyST title block, and the guide now states that the UW3 Style Charter is the normative contract and wins on conflict. All replacement examples verified against current source: Swarm.coords setter (swarm.py), Mesh.deform (discretisation_mesh.py:3133), uw.synchronised_array_update / NDArray_With_Callback.delay_callbacks_global. Findings: DOC-01, SWARM-13 (style-guide part). Underworld development team with AI support from Claude Code

…the release checklist The queue (last generated 2026-01-13, cdf5bb2) misrepresented the codebase both ways: it flagged now-complete items (solve, SNES_Scalar) as missing and contained zero entries for the June 2026 API (DOC-02). Regenerated over src/underworld3/**/*.py + **/*.pyx at the current tip. Two bugs in scripts/docstring_sweep.py's regex-based Cython parser made the regenerated queue lie about .pyx docstrings and are fixed as part of making the regeneration meaningful: - the indent group '(\s*)' with re.MULTILINE consumed preceding blank lines, shifting the computed definition line so the docstring search started ON the def/class line and always missed; - the docstring search started at the definition line rather than after the (possibly multi-line) signature, so long signatures hid their docstrings; - raw-string docstrings (r""", the norm in the solver .pyx) were not recognised. DOC-02 cross-validation on the regenerated queue now passes: solve / SNES_Scalar in the solver pyx are no longer flagged 'none'; the queue contains the June API (add_nitsche_bc, add_rotated_freeslip_bc, boundary_flux, set_custom_fmg, consistent_jacobian: 13 mentions) and flags the DOC-05 targets (Swarm.advection x2, read_timestep, write_proxy) as undocumented. Also adds the sweep to the quarterly release checklist (guides/release-process.md) so the queue cannot go stale unnoticed again. Findings: DOC-02 (docs/reviews/2026-07/DOCS-STANDARDS-COHERENCE.md). Underworld development team with AI support from Claude Code

…e changelog sweep to the release checklist The changelog (the quarterly CIG/stakeholder record) ended in April 2026 while ~117 first-parent commits landed May through early July (DOC-03). Backfilled at the existing conceptual granularity — 14 grouped entries, grouped by subsystem rather than by PR, matching the established format (### Title (Month Year), bold lead sentence, hyphen bullets, inline PR references): - New '2026 Q3 (July - September)' section: the July 2026 quality campaign (#309-#313, #317, #322-#326, #329, #334 as grouped entries), rotated strong free-slip / boundary traction / dynamic topography (#293, #294, #298, #306), generalized geometric multigrid via custom prolongation (#290, #297), consistent Jacobian tangent (#258), swarm correctness (#216, #313, #323, #329), numpy 2 support (#301, #305). - Extended '2026 Q2' section with the May-June entries: mesh adaptation movers (#190, #209, #213, #228, #259, #264, #266), moving-mesh field transfer / deform() (#246, #249, #251), semi-Lagrangian accuracy controls (#164, #183, #185-#189, #208, #220), snapshot/checkpoint toolkit (#146, #195, #196, #198), Stokes_Constrained (#224, #229, #240, #265), local-h Nitsche + boundary-slip surfaces (#225, #241, #275), units interoperability (#277, #278, #283, #284), memory/evaluation/solver infrastructure (#161, #177-#179, #181, #182, #222, #237, #250, ...). Every entry is backed by a merged commit on development (verified against git log --first-parent aed517f..3184a40). Also adds a quarterly-changelog sweep step beside the docstring sweep in the release checklist (guides/release-process.md) per DOC-03's proposed fix. Findings: DOC-03 (docs/reviews/2026-07/DOCS-STANDARDS-COHERENCE.md). Underworld development team with AI support from Claude Code

…verification) Adds one-to-three-line Status markers to the 13 design docs that lacked one, following the directory's existing conventions (**Status**: line under the title; status: key inside existing YAML frontmatter for the three frontmatter-only docs), and corrects the stale 'Design Phase' marker on MATHEMATICAL_MIXIN_DESIGN.md (the mixin ships in utilities/mathematical_mixin.py). Every stamp was verified against git history (git log --follow dates) and the current source tree before writing: - Implemented: jacobian-consistent-tangent (PR #258, c63cd70), fmg-checkpoint-hierarchy (3cd73cd), petsc-dmplex-checkpoint-reload-plan (PR #146, write_timestep(petsc_reload=True) in tree), fault-refinement-simplification (smooth_mesh_interior / metric_density_from_gradient / fault_comb_metric all in tree), MATHEMATICAL_MIXIN_DESIGN. - Current reference/contract: mesh-adaptation-formulation, ND_UNITS_BOUNDARY_CONTRACT (PR #278, e0ece9a). - Investigation records (preserved via PR #245, 34a9dd4; production geometric-MG is custom prolongation, PR #290): snesfas-feasibility, snesfas-vanka-feasibility-study. - Design notes / prototypes with honest gaps: in_memory_checkpoint_design (not implemented, per its own trailing Status section), submesh-solver-architecture (extract_region/extract_surface exist; coarsened_companion does not). - Historical: ARCHITECTURE_ANALYSIS (persistence.py layout superseded), COORDINATE_MIGRATION_GUIDE (transition shipped), WHY_UNITS_NOT_DIMENSIONALITY (decision record). The audit's ~16 estimate over-counted: re-derived at this tip, 13 docs were unmarked plus one marked-but-stale (DOC-07). Findings: DOC-07 (docs/reviews/2026-07/DOCS-STANDARDS-COHERENCE.md). Underworld development team with AI support from Claude Code

Docstring-only conversion of the 18 public module-level functions that carried Google-style Args:/Returns:/Raises:/Examples: labels (check_units_consistency, get_dimensionality, get_units, non_dimensionalise, show_nondimensional_form, simplify_units, create_quantity, convert_units, to_base_units, to_reduced_units, to_compact, get_scaling_coefficients, set_scaling_coefficients, validate_expression_units, assert_dimensionality, validate_coordinates_dimensionality, enforce_units_consistency, require_units_if_active, convert_angle_to_degrees) to the NumPy/Sphinx standard (Style Charter section 6). dimensionalise was already NumPy style; one-line docstrings and private helpers are untouched. No code, signature, or behaviour changes (verified: every diff hunk is inside a docstring; ast.parse clean). Finding: API-12 (docs/reviews/2026-07/API-CONSISTENCY-REVIEW.md). Underworld development team with AI support from Claude Code

…(conds, boundary, ...) order Wave C (#334) made the ORIGINAL value-first order canonical for add_nitsche_bc / add_rotated_freeslip_bc / add_constraint_bc (maintainer decisions D2/D3; Style Charter section 6) with deprecation shims for the legacy boundary-first and g= spellings. This sweep updates every call site of those THREE methods to the canonical order so nothing in the repository exercises the shims — 74 sites total: - tests/: 63 call sites across 12 files (test_1017, test_1018, test_1060, test_1061, test_1062, test_1064, test_1065 x2 serial; parallel test_1017, test_1062, test_1063, test_1064). tests/test_0641_wave_c_api_shims.py is deliberately untouched — its legacy-order calls ARE the deprecation contract. - docs/: 7 sites (curved-boundary-conditions.md x4, CONSTRAINED_FREESLIP_MULTIPLIER.md call + signature line, examples/submesh_investigation/test_region_ds_nitsche.py). - .claude/skills/: 3 sites (adapt-on-top-faults x2, free-surface-convection x1). - CLAUDE.md: 1 signature reference (free-slip BC preference section). The ~1,370 legacy-trio (add_dirichlet_bc/add_natural_bc/add_essential_bc) sites already conform and are untouched per the D2 decision. The audit review documents under docs/reviews/2026-07/ record the pre-decision state as evidence and are not swept. Discovered while verifying the swept tests run warning-free: the Wave C zero-datum guard in add_rotated_freeslip_bc rejects FLOAT zero (sympy.sympify(0.0) != 0 is structurally True), so the canonical add_rotated_freeslip_bc(0.0, boundary) raises NotImplementedError while conds=0 works. Filed as issue #336 with a TODO(BUG) marker at the guard (comment-only src touch); the swept call sites use the working integer form add_rotated_freeslip_bc(0, boundary). No fix applied here (Charter section 9 scope discipline). Findings: API-01/API-02 sweep (WE-09, REMEDIATION-WORKLIST.md). Underworld development team with AI support from Claude Code

Copilot

Pull request overview

This PR is Wave E of the July 2026 quality campaign, aligning documentation and legacy call sites with the UW3 Style Charter and prior Waves (A/C). It updates docs authority/format guidance, refreshes release-process checklists, fixes docstring-sweep parsing so the review queue is accurate, and migrates remaining BC call sites to the canonical value-first (conds, boundary, ...) order.

Changes:

Migrate many add_nitsche_bc / add_constraint_bc / add_rotated_freeslip_bc call sites (tests, docs, skills) to canonical value-first ordering.
De-drift documentation: authority map in developer index, Style Guide updates (NumPy/RST docstrings + MyST docs), design-doc status headers, and changelog backfill.
Fix scripts/docstring_sweep.py parsing bugs (indent regex, multi-line signatures, r""" docstrings) and add docstring/changelog sweeps to the release checklist.

Reviewed changes

Copilot reviewed 39 out of 41 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_1065_rotation_gauge_freeslip.py	Update constrained BC calls to value-first signature.
tests/test_1065_nitsche_local_h.py	Update Nitsche BC calls to value-first signature.
tests/test_1064_constrained_spherical_shell_response.py	Update Nitsche/constraint BC calls to value-first signature.
tests/test_1062_constrained_solcx.py	Update constraint BC calls to value-first signature.
tests/test_1061_constrained_freeslip.py	Update constraint BC calls (including error-path test) to value-first signature.
tests/test_1060_nitsche_freeslip.py	Update Nitsche BC calls to value-first signature.
tests/test_1018_rotated_freeslip.py	Update rotated free-slip BC calls to value-first signature (using `conds=0`).
tests/test_1017_custom_mg_stokes.py	Update constraint BC calls to value-first signature.
tests/parallel/test_1064_rotated_freeslip_parallel.py	Update rotated free-slip BC calls to value-first signature (MPI diagnostics).
tests/parallel/test_1063_constrained_freeslip_parallel.py	Update constraint BC calls to value-first signature (MPI diagnostics).
tests/parallel/test_1062_constrained_stratum_guard_parallel.py	Update constraint BC calls to value-first signature (MPI guard test).
tests/parallel/test_1017_custom_mg_parallel_mpi.py	Update constraint BC calls to value-first signature (MPI test).
src/underworld3/units.py	Docstring-only conversion of public API docs to NumPy/RST style.
src/underworld3/cython/petsc_generic_snes_solvers.pyx	Add comment-only `TODO(BUG)` marker documenting rotated-free-slip float-zero guard issue (#336).
scripts/docstring_sweep.py	Fix Cython docstring parsing (indent regex, multi-line signatures, prefixed docstrings).
docs/examples/submesh_investigation/test_region_ds_nitsche.py	Update example Nitsche BC call to value-first signature.
docs/developer/UW3_Style_and_Patterns_Guide.md	De-drift style guidance to Charter (NumPy/RST docstrings, MyST docs, coordinate access patterns).
docs/developer/index.md	Add Charter authority-map table and include Charter in toctree.
docs/developer/guides/release-process.md	Add docstring-queue + changelog freshness sweeps to release checklist.
docs/developer/design/WHY_UNITS_NOT_DIMENSIONALITY.md	Stamp status header.
docs/developer/design/submesh-solver-architecture.md	Stamp status header.
docs/developer/design/snesfas-vanka-feasibility-study.md	Stamp status in front matter.
docs/developer/design/snesfas-feasibility.md	Stamp status in front matter.
docs/developer/design/petsc-dmplex-checkpoint-reload-plan.md	Stamp status header.
docs/developer/design/ND_UNITS_BOUNDARY_CONTRACT.md	Stamp status header.
docs/developer/design/mesh-adaptation-formulation.md	Stamp status header.
docs/developer/design/MATHEMATICAL_MIXIN_DESIGN.md	Correct status to implemented design record.
docs/developer/design/jacobian-consistent-tangent.md	Stamp status header.
docs/developer/design/in_memory_checkpoint_design.md	Stamp status header.
docs/developer/design/fmg-checkpoint-hierarchy.md	Stamp status in front matter.
docs/developer/design/fault-refinement-simplification.md	Stamp status header.
docs/developer/design/COORDINATE_MIGRATION_GUIDE.md	Stamp status header.
docs/developer/design/CONSTRAINED_FREESLIP_MULTIPLIER.md	Update constraint-BC signature reference to value-first.
docs/developer/design/ARCHITECTURE_ANALYSIS.md	Stamp status header and clarify it is historical/superseded in parts.
docs/developer/CHANGELOG.md	Backfill May–early July 2026 entries (Q2/Q3), grouped by subsystem/campaign work.
docs/advanced/curved-boundary-conditions.md	Update Nitsche BC examples to value-first signature.
CLAUDE.md	Update authoritative pointers (data-access doc) and rotated-free-slip signature guidance.
.claude/skills/free-surface-convection/SKILL.md	Update Nitsche call in skill doc to value-first signature.
.claude/skills/adapt-on-top-faults/SKILL.md	Update rotated-free-slip calls in skill doc to value-first signature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

lmoresi added 7 commits July 6, 2026 16:54

CopilotAI review requested due to automatic review settings July 6, 2026 17:52

Copilotstarted reviewing on behalf of lmoresi July 6, 2026 17:52 View session

CopilotAI reviewed Jul 6, 2026
View reviewed changes

lmoresi mentioned this pull request Jul 6, 2026
fix(bc): rotated free-slip zero-datum guard compares by value (#336) #339
Merged

lmoresi merged commit fb6fa5b into developmentJul 6, 2026
2 checks passed

Navigation Menu

Uh oh!

docs: Wave E alignment — authority map, style-guide de-drift, changelog, value-first call-site sweep (WE-01..03,05,06,08,09,10) - #338

docs: Wave E alignment — authority map, style-guide de-drift, changelog, value-first call-site sweep (WE-01..03,05,06,08,09,10)#338
lmoresi merged 7 commits into
developmentfrom
feature/wave-e-docs

lmoresi commented Jul 6, 2026

Uh oh!

CopilotAI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

lmoresi commented Jul 6, 2026

Per-item summary

Bug found (reported, not fixed — Charter §9)

Gates

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants