Skip to content

Replace the agent docs with a short map and agent guide; propagate add_incs errors - #446

Merged
pchakraborty merged 3 commits into
release/MAPL-v3from
feature/pchakrab/fvdycore-agent-docs
Nov 12, 2026
Merged

pchakraborty merged 3 commits into
release/MAPL-v3from
feature/pchakrab/fvdycore-agent-docs

Conversation

@pchakraborty

@pchakraborty pchakraborty commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Description

  • docs/ARCHITECTURE.md is now a short repository map in the style of matklad's ARCHITECTURE.md (about 70 lines instead of about 410): bird's-eye view (the dynamics state lives in MAPL's internal state and is copied into FV3 before each step and back after it; tracers stay with their owners and are lent through TRADV), codemap, how DYN and ADV are put together (placement under Superdyn, grid, state, run, run_add_incs, FV_Run and tracer packing, ADV and its DYCORE settings), contracts (imports, exports; DYN and ADV both provide TRADV and subscribe to no service), invariants, cross-cutting concerns. It names modules and routines, describes only what changes rarely, and has no status or to-dos.
  • AGENTS.md keeps what changes and what to do: rules (bugs and questions go to issues; do not edit generated *___.h; MAPL3 error macros; porting follows the GEOSgcm_GridComp AGENTS.md), status and to-dos, known traps (each phrased as what goes wrong), build and test. Verified against 4d7c4a3.
  • Removed docs/decisions.md (the reasons were inferred, not recorded decisions).
  • The old documents predated adv-sa (Add adv-sa regression test for standalone AdvCore #437) and the current geometry: keys, and pointed one directory too high for Superdyn's documents; the new ones are checked against the code.
  • regression/README.md brought up to date: where the regression data comes from (LOCAL_REGRESSION_DATA_DIR, S3 sync), how checkpoints are compared, the logging.yaml setup, and what each case runs; removed the section on cmpchk.py scripts that do not exist, and dyn-sa is no longer called Held-Suarez (CASE_ID: 1 is the Jablonowski-Williamson steady state).
  • Bug fix in DynCore_GridCompMod.F90: run and run_add_incs called ADD_INCS without rc, and add_incs passed rc=rc to its eight PULL_Q calls without checking it, so errors there went unreported. These calls now use _RC. Error handling only; no change to results.

The open questions and observations from the removed documents are not in this PR; they are collected separately to be filed as issues. Same approach as GEOS-ESM/GOCART#503, GEOS-ESM/GEOSgcm_GridComp#1577 and GEOS-ESM/GEOSradiation_GridComp#117; the PRs are independent.

Testing

Built in the GEOSgcm fixture; ctest -L REGRESSION passes, including adv-dyn, adv-sa and dyn-sa.

run and run_add_incs called ADD_INCS without rc, and add_incs passed rc=rc to PULL_Q without checking it, so a failure there (for example a missing water tracer) went unreported. All of these calls now use _RC.
docs/ARCHITECTURE.md is now a short map (codemap, how DYN and ADV are put together, contracts, invariants, cross-cutting concerns); AGENTS.md keeps rules, status, known traps and build and test. Remove docs/decisions.md. Covers the adv-sa case and the current geometry keys, and fixes the parent-document paths.
@pchakraborty pchakraborty added documentation Improvements or additions to documentation 0 diff The changes in this pull request have verified to be zero-diff with the target branch. MAPL3 MAPL 3 Related labels Nov 11, 2026
Describe where the regression data comes from, how the checkpoints are compared, the logging setup and what each case runs; remove the section on cmpchk.py scripts that do not exist and the Held-Suarez description of dyn-sa (CASE_ID 1 is the Jablonowski-Williamson steady state). Drop the corresponding status item from AGENTS.md.
@pchakraborty
pchakraborty marked this pull request as ready for review November 11, 2026 15:13
@pchakraborty
pchakraborty requested a review from a team as a code owner November 11, 2026 15:13
@pchakraborty
pchakraborty merged commit c86df56 into release/MAPL-v3 Nov 12, 2026
18 of 19 checks passed
@pchakraborty
pchakraborty deleted the feature/pchakrab/fvdycore-agent-docs branch November 12, 2026 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

0 diff The changes in this pull request have verified to be zero-diff with the target branch. documentation Improvements or additions to documentation MAPL3 MAPL 3 Related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants