Skip to content

Add MAPL3 vs MAPL2 differences documentation#4555

Draft
tclune wants to merge 16 commits intorelease/MAPL-v3from
feature/#4554-mapl3-vs-mapl2-docs
Draft

Add MAPL3 vs MAPL2 differences documentation#4555
tclune wants to merge 16 commits intorelease/MAPL-v3from
feature/#4554-mapl3-vs-mapl2-docs

Conversation

@tclune
Copy link
Copy Markdown
Collaborator

@tclune tclune commented Mar 24, 2026 •
edited
Loading

Types of change(s)

  • Trivial change (affects only documentation)

Description

Adds docs/mapl3/diffs-from-mapl2.md — a comprehensive migration and reference document describing the architectural and user-facing differences between MAPL3 and MAPL2. This is a required deliverable for the MAPL v3.0.0 alpha release.

A ### Documentation entry has been added to the [v3.0.0 - Development] section of CHANGELOG.md, pointing to this document in lieu of a large number of individual changelog entries for the v3 release.

Sections covered

  • Component structure (OuterMetaComponent, framework-driven init, DSO/shared-library composition)
  • Connections (automatic regridding, precision/unit conversion)
  • Variable/field specs (extended state item types, ACG .rc → .acg format change)
  • Resource files (ESMF Config → HConfig/YAML, child isolation rules)
  • Cap and time loop (cap.yaml reference example, time advance now after History)
  • History3G
  • ExtData
  • Statistics component (new in MAPL3)
  • Clocks (per-component clocks, perpetual clocks)
  • Build system (always shared library, ESMF 8.8.0+, FLAP removed, new profiling switches)
  • Grid classes: tripolar is subsumed into xy in MAPL3 (no separate class: tripolar; use class: xy with n_peri_dim: 1 — see issue feat(geom): add n_peri_dim support to XYGeomSpec/XYGeomFactory for tripolar grids #4691)

Outstanding items requiring peer review

  • @atrayano — Section 3: Please verify the description of the MAPL2 "friendly" mechanism and document how SERVICE/SERVICE_PROVIDER/SERVICE_SUBSCRIBER replace it in MAPL3.
  • @bena-nasa — Section 6: Please provide a reference History3G YAML config example and document any breaking changes from HISTORY.rc.
  • @bena-nasa — Section 7: Please document any breaking changes in the ExtData YAML config between MAPL2 and MAPL3.

Related Issue

Closes #4554
Related: #4691
@tclune
Add MAPL3 vs MAPL2 differences documentation
e22a9e9 
Adds docs/mapl3/diffs-from-mapl2.md as the primary migration reference
for developers moving from MAPL2 to MAPL3. Adds a Documentation section
to the v3.0.0 CHANGELOG entry pointing to this document.

Closes #4554
@tclune tclune requested a review from a team as a code owner March 24, 2026 14:33
@tclune tclune added 0 Diff The changes in this pull request have verified to be zero-diff with the target branch. 📈 MAPL3 MAPL 3 Related Changelog Skip Skips the Changelog Enforcer labels Mar 24, 2026
tclune
tclune commented Mar 24, 2026
View reviewed changes
Comment thread CHANGELOG.md Outdated
tclune added 3 commits March 24, 2026 10:48
@tclune
Address PR review: rename release section, triage items
82a0d8d 
- Rename [v3.0.0 - Development] to [v3.0.0-alpha-0]
- Remove low-level changelog items from CHANGELOG.md
- Append raw changelog items to diffs-from-mapl2.md Section 12
  for peer review and triage
- Use GitHub IDs (@atrayano, @bena-nasa) in review table
@tclune
Fix changelog section header to ### Added
60b5b26
@tclune
Integrate triaged changelog items into diffs doc
8cff897 
- Add per-component scheduling (timestep, reference_time, offset)
- Add generic3g / mapl3g_ prefix / ESMF_CONTEXT_PARENT_VM detail
- Expand unit conversion description in Connections section
- Add ACG3 new columns table (ALIAS, add2export, RESTART enum)
- Expand HConfig section with MAPL_GetResource detail
- Expand History3G with time accumulation, vertical/ungridded dims,
  wildcard specs, and expression field extraction
- Remove Section 12 (triage complete)
@tclune tclune marked this pull request as draft March 24, 2026 15:55
tclune
tclune commented Mar 24, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@tclune tclune left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should document a difference in how pFlogger is used.

In MAPL2, each user gridcomp had a logger that is identified by the "full" name of the component in the hierarchy. E.g., 'GCM.AGCM.PHYS.CHEM.GOCART2G.DU'. In MAPL3 we just use the "final" name 'DU'. This simplifies the resource file for logging, but makes it more difficult to change debug level for an entire hierarchy.
tclune added 2 commits March 24, 2026 12:49
@tclune
docs: add api-changes.md and cross-reference it from diffs-from-mapl2…
fb20919 
….md [skip ci]

- Add docs/mapl3/api-changes.md: procedure-level reference of core framework
  API changes between MAPL2 and MAPL3 (stubbed V2 APIs, new framework entry
  points, lifecycle/child/field-spec/connectivity/resource/timer replacements)
- Add See Also section and ToC cross-reference in diffs-from-mapl2.md
- Update CHANGELOG [v3.0.0-alpha-0] entry to include api-changes.md
@tclune
docs: add pFlogger logger-naming section to diffs-from-mapl2 [skip ci]
b145e03 
MAPL2 uses full hierarchical logger names (e.g. GCM.AGCM.PHYS.DU);
MAPL3 uses only the short component name (e.g. DU).  Documents the
trade-offs and migration note for logging.yaml resource files.
tclune
tclune commented Mar 25, 2026
View reviewed changes
Comment thread docs/mapl3/diffs-from-mapl2.md
Comment on lines +164 to +167
In MAPL2, connections are generally only supported between state items
that share the same grid, precision, and units. Mismatched items
cannot be automatically connected; the user is responsible for
ensuring compatibility.
Copy link
Copy Markdown
Collaborator Author

@tclune tclune Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

V2 ignores units, so it is in not so much that they cannot be automatically connected as the results will be wrong for mismatched units. Users beware.

V2 also does not have any notion of requiring that an export provide certain user-defined attributes that make be required by an import. E.g., some children of GOCART2G require a "radius" attribute that is expected to come from the export. V3 provides a mechanism to specify and enforce such required attributes.
@tclune
docs: expand mapl: section description with geometry/children schema …
c4523cb 
…and examples [skip ci]

Replace the brief 'Shared Libraries' paragraph with a full treatment of
the mapl: config section as the primary declarative composition mechanism.
Covers geometry kinds, children/DSO schema, states/connections asides,
and three worked examples (DYN, GOCART, AGCM).  Update cross-references
in the Resource Files caveat and the cap.yaml footnote.
tclune
tclune commented Mar 25, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@tclune tclune left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another V3 difference is that V3 provides a "universal" executable GEOS.x. Through the use of command line, ESMF config, and DSO's, GEOS.x should be able to run any GEOS configuration. So we no longer need separate executables elsewhere such as GEOSgcm.x etc.
@tclune
docs: add GEOS.x universal executable section to Cap chapter [skip ci]
a4b48e0 
Documents that GEOS.x replaces model-specific executables, its single
cap.yaml argument, the four top-level config sections that drive a run,
and how cap.mapl.children DSO entries make it configuration-universal.
Adds REVIEW NEEDED marker for MAPL_Component_Driver.x deprecation.
@tclune tclune mentioned this pull request Mar 25, 2026
Open
5 tasks
tclune added 6 commits March 25, 2026 15:25
@tclune
docs: optimistically reflect elimination of MAPL_Component_Driver.x (…
a9463be 
…see #4566) [skip ci]

GEOS.x now serves as the single universal executable for all MAPL3
applications. MAPL_Component_Driver.x and DriverCap.F90 are removed
as part of issue #4566.
@tclune
docs: add Grid and Geometry Access section (Section 12) [skip ci]
395cc03 
Documents MAPL3's discouragement of global resolution parameters
(IM_WORLD, JM_WORLD) in favour of geometry-based accessors
(GeomGet/GridGet area). Notes planned min/max spacing/area accessors
with reference to tracking issue #4570.
@tclune
Fix MAPL_ESMF_InfoKeys.F90 include (was still Exceptions.h)
e5732d7
@tclune
Revert "Fix MAPL_ESMF_InfoKeys.F90 include (was still Exceptions.h)"
87df62b 
This reverts commit e5732d7.
@tclune
docs: add MAPL3 GridComp template with ACG and CMake reference [skip ci]
df41143 
Add docs/mapl3/gridcomp-template.md — a minimal Fortran template for a
MAPL3 gridded component covering:
- Fortran module structure with implicit none(type,external) and free
  setServices DSO wrapper
- ACG spec file format (pipe-delimited table, all supported columns)
- mapl_acg() CMake integration

Also link the new file from the See Also section of diffs-from-mapl2.md,
and fix a missing hconfig declaration in the Fortran template.
@tclune
Add tripolar-into-xy note to diffs-from-mapl2
e1d2ed4
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. Changelog Skip Skips the Changelog Enforcer 📈 MAPL3 MAPL 3 Related

1 participant

@tclune