FMS Usage in Global Workflow Infrastructure - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

FMS Usage in Global Workflow Infrastructure

Date: May 4, 2026
Analysis Method: MCP-RAG tool-assisted investigation (AgentCore Runtime v5, Neptune graph + OpenSearch vector)
Companion: FMS-Analysis-MCP-Tool-Effectiveness-Report

Executive Summary

The Flexible Modeling System (FMS) is a foundational software framework developed by GFDL (Geophysical Fluid Dynamics Laboratory) that provides core infrastructure services to the UFS Weather Model and its component models within the Global Workflow. FMS is not a single executable — it is a library of Fortran modules that provides message passing (MPI), I/O, diagnostics, domain decomposition, time management, and physical constants to every model component in the coupled system.

FMS permeates the Global Workflow at multiple levels:

Layer FMS Role Scope
UFS Model Core Runtime initialization/finalization (fms_init/fms_end) 188 callers / 316 callers
Atmosphere (FV3) Domain decomposition, namelist I/O, climate nudging FV3 dynamical core
Ocean (MOM6) Diagnostic output, I/O infrastructure, domain management MOM6 via FMS2 interface
Sea Ice (CICE) History file conversion (cice_hist2fms) CICE ↔ FMS format bridge
Data Assimilation (JEDI/GDAS) FMS namelist management, cube-sphere increments, state conversion fv3-jedi, SOCA
Diagnostics diag_manager controls all ATM and MOM6 output via diag_table Runtime output control
Build System FMS compiled as shared library, linked by all UFS components sorc/ufs_model.fd/

1. FMS Source Location

FMS lives within the UFS model submodule tree. The Global Workflow does not contain FMS source directly — it is pulled in transitively through the UFS model:

global-workflow/
└── sorc/
    └── ufs_model.fd/           ← UFS Weather Model (git submodule)
        ├── FMS/                 ← FMS library source (GFDL)
        └── MOM6-interface/
            └── MOM6/
                └── config_src/
                    └── infra/
                        ├── FMS1/   ← MOM6 FMS1 compatibility layer
                        └── FMS2/   ← MOM6 FMS2 interface (current)

MOM6 maintains its own FMS infrastructure adapters (FMS1/ and FMS2/) that abstract the FMS version differences, plus an FMS_cap/ driver for standalone MOM6 runs.

2. Core FMS Modules and Their Usage

2.1 fms_init — Framework Initialization (188 callers)

The fms_init subroutine is the entry point for the entire FMS framework. It initializes MPI communication, sets up the domain decomposition, and prepares the I/O and diagnostic subsystems. 188 Fortran subroutines across the codebase call fms_init, making it one of the most widely-used symbols in the Global Workflow.

Key callers include:

  • initialize — UFS model top-level initialization
  • create, setup_domain — Domain setup routines
  • set_and_fill_geometry_fields — Grid geometry initialization
  • pedges2pmidlayer, getVerticalCoord — Vertical coordinate setup
  • get_data, get_num_nodes_and_elements — Data access routines

2.2 fms_end — Framework Finalization (316 callers)

Even more widely referenced than fms_init, fms_end is called by 316 Fortran subroutines. This includes MPI communication routines, domain management, halo updates, and broadcast operations — all of which need access to the FMS finalization path for clean shutdown:

  • mp_assign_gid, mp_start, mp_stop, mp_barrier — MPI management
  • domain_decomp, broadcast_domains, switch_current_domain — Domain operations
  • start_var_group_update_2d/3d/4d — Halo exchange operations
  • complete_group_halo_update — Halo completion
  • switch_current_Atm — Atmosphere grid switching

2.3 fms_mod — Core Module

The fms_mod Fortran module provides the primary FMS API. It is used by:

  • fv_climate_nudge_nlm_mod — FV3 climate nudging
  • fv_climate_nudge_init, fv_climate_nudge, fv_climate_nudge_end — Nudging lifecycle
  • var_state_init, var_state_assignment, var_state_del — Variable state management
  • prt_minmax_2d, prt_minmax_3d — Diagnostic print routines
  • remap_coef, remap_xy_3d, remap_xy_2d, remap_ps, remap_3d — Remapping operations

2.4 fms2_io_mod — Modern I/O Interface

The FMS2 I/O module provides the current-generation file I/O interface. It is used by:

  • fv_control_init — FV3 control initialization
  • set_namelist_pointers — Namelist configuration
  • read_namelist_* — Multiple namelist readers (nest, fv_nest, fv_grid, fv_core, test_case)
  • setup_update_regions — Update region configuration
  • fv_end — FV3 finalization
  • fv3jedi_fv3_control_mod — JEDI FV3 interface
  • set_eta, set_external_eta — Vertical coordinate setup
  • var_les, var_gfs — Variable configuration

2.5 mpp_mod — Message Passing Primitives

The FMS message passing module (mpp_mod) wraps MPI and provides domain-aware communication. Used by the same broad set of FV3 routines as fms_mod, it is the backbone of all parallel communication in the UFS model.

2.6 constants_mod — Physical Constants

FMS provides standardized physical constants used across all model components:

  • med_kind_mod, ufs_const_mod — UFS mediator constants
  • med_diag_mod, med_diag_init — Mediator diagnostics
  • med_phases_diag_accum, med_phases_diag_atm, med_phases_diag_lnd — Component diagnostics
  • diag_atm_recv, diag_atm_send — Atmosphere diagnostic exchange
  • diag_lnd, diag_rof — Land and river diagnostics

2.7 diag_manager_mod — Diagnostic Output Manager

The FMS diagnostic manager controls all model output. It is configured at runtime via the diag_table file and manages output for both the ATM (FV3) and ocean (MOM6) components.

Configuration files:

  • diag_table — Defines output fields, files, sampling intervals, and reduction methods
  • diag_manager_nml — Namelist controlling diagnostic manager behavior (max files, fields, CMOR mode)
  • field_table — Tracer registration and management

Output controlled by FMS diag_manager:

  • atmos_4xdaily.tile[1-6].nc — 4× daily atmospheric diagnostics
  • atmos_static.tile[1-6].nc — Static atmospheric fields
  • atmfHHH.nc — Atmospheric forecast files
  • sfcfHHH.nc — Surface forecast files
  • grid_spec.tile[1-6].nc — Grid specification

The diag_table field format specifies: module_name, field_name, output_name, file_name, time_sampling, reduction_method, regional_section, and packing precision.

3. FMS in the Data Assimilation System (GDAS/JEDI)

FMS plays a critical role in the data assimilation pipeline through the FV3-JEDI interface:

3.1 FMS Namelist Management

  • fv3jedi_fmsnamelist_mod.f90 — Manages FMS namelists for JEDI
  • fmsmpp.nml — FMS MPI configuration for JEDI tests

3.2 State Format Conversion

FMS defines the "non-restart" file format used by FV3. JEDI needs to convert between FMS and restart formats:

  • convertstate_gfs_restart2fms_nonrestart.yaml — Restart → FMS format
  • convertstate_gfs_fms_nonrestart2restart.yaml — FMS → Restart format
  • fv3jediGeosToFms.f90 — GEOS to FMS format converter

3.3 Cube-Sphere Increments

  • _add_fms_cube_sphere_increments (Python function) — Adds DA increments in FMS cube-sphere format
  • Called by finalize → to_fv3time → add_increments chain
  • JCB templates: atmosphere_final_increment_fms_nonrestart.yaml.j2, atmosphere_output_ensemble_increments_fms_nonrestart.yaml.j2

3.4 Ocean DA (SOCA)

  • FmsInput.h / FmsInput.cc — C++ FMS input interface for SOCA geometry
  • cice_hist2fms — Converts CICE history files to FMS format for ocean DA

3.5 Snow and Soil DA

  • snow_final_increment_fms.yaml.j2 — Snow increment in FMS format
  • soil_final_increment_fms.yaml.j2 — Soil increment in FMS format

4. FMS in MOM6 (Ocean Model)

MOM6 has the deepest FMS integration of any component:

4.1 I/O Infrastructure

  • MOM_io_infra.F90 — MOM6 I/O layer built on FMS (io_infra_init, io_infra_end)
  • MOM_diag_manager_infra.F90 — MOM6 diagnostic manager wrapper around FMS diag_manager
  • fms_diag_id — Every MOM6 diagnostic field has an underlying FMS diagnostic ID

4.2 FMS Version Compatibility

MOM6 maintains two FMS interface layers:

  • config_src/infra/FMS1/ — Legacy FMS1 compatibility
  • config_src/infra/FMS2/ — Current FMS2 interface (active in Global Workflow)

4.3 FMS Driver

  • config_src/drivers/FMS_cap/ — FMS-based MOM6 driver for standalone runs

4.4 Diagnostics

MOM6 diagnostics are entirely managed through FMS:

  • The diag_table controls MOM6 output fields
  • mom_is_diag_mediator provides wrappers to FMS diag_manager interfaces
  • 2D/3D axes, masks, and conversion factors are all managed through FMS diagnostic types

5. FMS Utilities (gfs_utils.fd)

The Global Workflow includes a standalone FMS utility:

  • rdbfmsua.fd/rdbfmsua.f — Reads FMS upper-air data files
  • Platform-specific modulefiles: rdbfmsua_hera.intel.lua, rdbfmsua_orion.intel.lua, rdbfmsua_wcoss2.intel.lua
  • Located in sorc/gfs_utils.fd/src/rdbfmsua.fd/

6. FMS in the Build System

FMS is compiled as a shared library during the UFS model build process. The CMake build system in sorc/ufs_model.fd/ compiles FMS first, then links it into:

  • FV3 atmospheric dynamical core
  • MOM6 ocean model
  • CICE sea ice model
  • CMEPS mediator
  • All JEDI/DA components that interface with FV3

The MOM6 autoconf build system also has FMS-specific configuration:

  • configure.fms.ac — FMS autoconf configuration
  • Makefile.fms.in — FMS Makefile template

7. Summary: FMS Dependency Map

                    ┌─────────────────────────────────┐
                    │         FMS Library             │
                    │  (fms_mod, mpp_mod, fms2_io,    │
                    │   diag_manager, constants_mod)  │
                    └──────────┬──────────────────────┘
                               │
          ┌────────────────────┼─────────────────────┐
          │                    │                     │
          ▼                    ▼                     ▼
   ┌──────────────┐   ┌──────────────┐       ┌──────────────┐
   │  FV3 (ATM)   │   │  MOM6 (OCN)  │       │  CICE (ICE)  │
   │  fms_init:   │   │  FMS2 infra  │       │  hist2fms    │
   │  188 callers │   │  diag_mgr    │       │  format conv │
   │  fms_end:    │   │  io_infra    │       └──────────────┘
   │  316 callers │   │  FMS_cap     │
   └──────┬───────┘   └──────┬───────┘
          │                  │
          ▼                  ▼
   ┌──────────────┐   ┌──────────────┐
   │  JEDI/GDAS   │   │  CMEPS       │
   │  fv3-jedi    │   │  Mediator    │
   │  fms nml mgr │   │  constants   │
   │  cube-sphere │   │  diagnostics │
   │  increments  │   └──────────────┘
   └──────────────┘
          │
          ▼
   ┌──────────────┐
   │  SOCA (OCN   │
   │  DA)         │
   │  FmsInput    │
   │  cice_hist2  │
   │  fms         │
   └──────────────┘

8. Key Takeaways

  1. FMS is ubiquitous — With fms_init called by 188 subroutines and fms_end by 316, FMS is the most widely-used infrastructure library in the UFS model
  2. FMS controls all diagnostics — The diag_table / diag_manager system is the sole mechanism for ATM and MOM6 output file generation
  3. FMS bridges DA and forecast — The FMS file format (non-restart) is the interchange format between JEDI data assimilation and the FV3 forecast model
  4. MOM6 is deeply coupled to FMS — MOM6 maintains its own FMS1/FMS2 compatibility layers and uses FMS for all I/O and diagnostics
  5. FMS is a build dependency — It must be compiled first and is linked by every UFS component

Analysis performed using MDC MCP-RAG AgentCore Runtime v5 (51 tools, Neptune 148K nodes, OpenSearch 206K docs).
See FMS-Analysis-MCP-Tool-Effectiveness-Report for tool-by-tool effectiveness assessment.