MAPL3 migration: iterative hybrid-build strategy for porting GEOS to MAPL v3

[tclune]

Overview

This is the top-level tracking issue for the GEOS migration to MAPL v3, using an iterative hybrid-build strategy. The approach allows the migration to proceed incrementally — GEOS always builds at every step — rather than requiring a complete port before anything can be released.

An agent working on this migration should read this issue in full before starting work, then proceed to the sub-issues listed below.

---

Where to start (for implementors and agents)

Begin with GEOS-ESM/MAPL#4610. Read that issue, then implement the CMake changes (MAPL_SUPPORT_MAPL3 option + MAPL2.* target renaming) on branch feature/mapl2-support-library in the MAPL repository.

Work through Phase 1 in order: #4610 → #4611 → #4612. Do not begin Phase 2 until Phase 1 is complete and MAPL2 builds cleanly with MAPL_SUPPORT_MAPL3=ON.

---

MAPL3 architecture: key directories

Understanding the MAPL3 (release/MAPL-v3) directory layout is essential to avoid confusion:

Directory	CMake target	Role
generic3g/	MAPL.generic3g	The new MAPL3 coupling layer. This is what GEOS components will ultimately use. Fortran modules use the mapl3g_ prefix (e.g. mapl3g_Generic, generic3g).
mapl3g/	MAPL	MAPL3 top-level umbrella. Defines module MAPL and re-exports generic3g, pfio, grids, etc. This is the entry point for ported components: they use MAPL from MAPL3.
generic/	(legacy)	The old MAPL2-compatible coupling layer — being removed from MAPL3. Do not port components to this. It exists only transiently during MAPL3 development and will be deleted.

The correct porting target is mapl3g/ (MAPL CMake target, module MAPL), not generic/ or MAPL_GenericMod.

GEOS components that currently use MAPL (from MAPL2) will, after porting, use MAPL from MAPL3's mapl3g/ umbrella. The module name is the same; the source is different. The CMake dependency changes from MAPL2's MAPL target to MAPL3's MAPL target.

---

Strategy: Hybrid Dual-Mount

The key insight is that MAPL3's generic (coupling) layer is the essential prerequisite — all GEOS components must use it before MAPL3 can be released. But many MAPL2 support utilities (grids, regridders, I/O, constants, etc.) do not need to be ported first.

The solution: mepo-mount both MAPL v3 and MAPL v2 inside GEOSgcm simultaneously.

• MAPL3 (release/MAPL-v3 branch): owns the generic/coupling layer and progressively takes over support utilities
• MAPL2 (feature/mapl2-support-library branch, built with MAPL_SUPPORT_MAPL3=ON): reduced to a support library — no generic layer, targets renamed to MAPL2.*, umbrella module renamed to module MAPL2

GEOS components migrate to MAPL3's coupling layer one at a time. Each migrated component switches its CMake dependency from MAPL2.generic (gone) to MAPL3's MAPL.generic. Components still using MAPL2 support utilities link against MAPL2.base, MAPL2.pfio, etc.

---

Iterative Milestones

Phase 1 — Prepare the hybrid infrastructure (prerequisites for everything else)

• MAPL2 CMake switch — Add MAPL_SUPPORT_MAPL3 option, rename targets to MAPL2.*
  → GEOS-ESM/MAPL #4610
• MAPL2 umbrella module — Rename module MAPL to module MAPL2 in hybrid mode
  → GEOS-ESM/MAPL #4611
• MAPL2 branch and CI — Create feature/mapl2-support-library, coordinate CI
  → GEOS-ESM/MAPL #4612

Gate: MAPL2 builds cleanly with MAPL_SUPPORT_MAPL3=ON.

Phase 2 — Activate the dual-mount GEOSgcm build

• GEOSgcm dual-mount — Update components.yaml and top-level CMake for dual mepo mount
  → GEOS-ESM/GEOSgcm Hybrid MAPL build: dual mepo mount of MAPL2 (support library) and MAPL3 in GEOSgcm #1058 (this repo)

Gate: Full GEOSgcm builds with MAPL3 coupling + MAPL2 support library. CI passes.

Phase 3+ — Iterative support-layer migration (repeating)

For each MAPL2 support subsystem to be migrated to MAPL3:

1. Port / reimplement the subsystem in MAPL3
2. Update GEOS components to use MAPL3's version
3. Deactivate the subsystem in MAPL2's hybrid mode (add to MAPL_SUPPORT_MAPL3 exclusion list)
4. Verify GEOSgcm still builds and CI passes

---

Branch naming convention

Repo	Branch
GEOS-ESM/MAPL (v3)	release/MAPL-v3 (existing)
GEOS-ESM/MAPL (v2 support)	feature/mapl2-support-library (different name — same repo)
GEOS-ESM/GEOSgcm	feature/mapl3-migration
All other repos	feature/mapl3-migration

All non-MAPL repos can share the feature/mapl3-migration branch name since they are in separate GitHub repositories. MAPL must use two different branch names because MAPL2 and MAPL3 live in the same repository.

---

Key technical decisions

• CMake switch name: MAPL_SUPPORT_MAPL3 (placeholder — pending team agreement; easy to rename as it is set in one place)
• CMake target naming: When MAPL_SUPPORT_MAPL3=ON, all MAPL2 targets become MAPL2.* (e.g. MAPL2.base, MAPL2.shared)
• Fortran umbrella: module MAPL becomes module MAPL2 in hybrid mode; use MAPL in hybrid mode is a compile error (intentional)
• Fortran module conflicts: Resolved on-demand as they are encountered. When a module name conflicts between MAPL2 and MAPL3, the MAPL2 version is renamed with the mapl2g_ prefix, guarded by #ifdef MAPL_SUPPORT_MAPL3
• MAPL_cfio: Already has non-conflicting names (MAPL_cfio_r4, MAPL_cfio_r8) — no rename needed
• Profiler: Stays in both MAPL2 and MAPL3; conflicts resolved as they arise
• Context: Hybrid mode is only used when GEOSgcm is the top-level CMake project (dual mepo mount); not a standalone MAPL2 build scenario

---

Sub-issues

Issue	Repo	Phase
#4610 MAPL2 CMake switch and MAPL2.* target renaming	GEOS-ESM/MAPL	1
#4611 MAPL2 umbrella rename to module MAPL2	GEOS-ESM/MAPL	1
#4612 MAPL2 branch setup and CI coordination	GEOS-ESM/MAPL	1
#1058 GEOSgcm dual-mount of MAPL2 and MAPL3	GEOS-ESM/GEOSgcm	2

[tclune]

Phase 1 complete. All three MAPL sub-issues are done and merged:

• MAPL2 hybrid mode: add MAPL_SUPPORT_MAPL3 CMake switch and rename targets to MAPL2.* MAPL#4610 — MAPL_SUPPORT_MAPL3 CMake option + MAPL2.* target renaming ✅ (merged to develop via PR #4613)
• MAPL2 hybrid mode: rename umbrella MAPL/MAPL.F90 to 'module MAPL2' when MAPL_SUPPORT_MAPL3=ON MAPL#4611 — Umbrella module renamed to module MAPL2 when MAPL_SUPPORT_MAPL3=ON ✅ (merged to develop via PR #4613)
• MAPL2 hybrid mode: branch setup and CI coordination for feature/mapl2-support-library MAPL#4612 — Branch feature/mapl2-support-library created off develop and pushed ✅

MAPL2 builds cleanly with MAPL_SUPPORT_MAPL3=ON (all tests pass). The Phase 1 gate is satisfied. Phase 2 (porting GEOS components to the MAPL3 coupling layer) can begin.