3. Developer Guide

Important

Everything in the Developer Guide assumes familiarity with ESMF and the NUOPC Layer. The mediator is built entirely on ESMF/NUOPC data types and conventions — in particular ESMF States, Fields, FieldBundles and RouteHandles, and the NUOPC concepts of components, caps, connectors and the run sequence. If these are unfamiliar, start with the ESMF reference manual and the NUOPC reference manual before continuing.

Understanding this part is a prerequisite for any CMEPS customization or modification. It covers the code organization in depth, the phase lifecycle, how fields are declared and exchanged for each host (addfld / addmap / addmrg), the mapping, merging and fraction machinery, atmosphere/ocean flux and albedo calculation, diagnostics/history/restart, and a walkthrough for adding a new coupled field. It also develops the full conservation, area-correction and accumulation derivations summarized in Core concepts.

Unlike the User Guide, the Developer Guide is not host-specific: it describes the shared mediator code that serves all host applications. Where behavior differs by host, it is in the esmFldsExchange_<host> exchange modules and the fd_<host>.yaml dictionaries, which are called out where relevant.

• 3.1. Code organization
  • 3.1.1. The mediator/ directory
  • 3.1.2. The mediator component
  • 3.1.3. The internal state
• 3.2. Field exchange
  • 3.2.1. Advertise and realize
  • 3.2.2. The field-exchange module
  • 3.2.3. When esmFldsExchange runs
  • 3.2.4. addfld — advertise fields
  • 3.2.5. addmap — map a source field to a destination
  • 3.2.6. addmrg — merge mapped fields into a destination
  • 3.2.7. How it fits together
• 3.3. Conservation, area corrections and accumulation
  • 3.3.1. Conservative mapping weights
  • 3.3.2. Fraction-weighted normalized mapping
  • 3.3.3. Merging with fractions
  • 3.3.4. Area corrections
  • 3.3.5. Accumulation and averaging
• 3.4. The phase lifecycle
  • 3.4.1. Initialization phases
  • 3.4.2. Run phases
  • 3.4.3. Finalization phases
• 3.5. Mapping
  • 3.5.1. Routehandles
  • 3.5.2. Map types
  • 3.5.3. Fractional normalization
  • 3.5.4. Packed mapping
  • 3.5.5. Vector mapping
• 3.6. Merging
  • 3.6.1. Automatic merging
  • 3.6.2. The merge operations
  • 3.6.3. Multi-source (surface) merges
  • 3.6.4. Merging and conservation
• 3.7. Surface fractions
  • 3.7.1. Key assumptions
  • 3.7.2. The fraction fields
  • 3.7.3. How the fractions are set
  • 3.7.4. Where the fractions are used
• 3.8. Atmosphere/ocean fluxes
  • 3.8.1. Interface versus algorithm
  • 3.8.2. The run phase
  • 3.8.3. The flux calculation grid
• 3.9. Ocean albedo
  • 3.9.1. What is computed
  • 3.9.2. The run phase
  • 3.9.3. Options
• 3.10. Water and energy budgets
  • 3.10.1. Sign convention
  • 3.10.2. The budget phases
  • 3.10.3. Reading a budget table
  • 3.10.4. Enabling the budgets
• 3.11. History output
  • 3.11.1. Instantaneous and time-averaged streams
  • 3.11.2. The write phases
  • 3.11.3. File names
  • 3.11.4. Auxiliary history (histaux) files
• 3.12. Restarts
  • 3.12.1. Timing profile
• 3.13. Adding a coupled field
  • 3.13.1. What you will touch
  • 3.13.2. Step 1 — add the field to the dictionary
  • 3.13.3. Step 2 — advertise, map and merge it
  • 3.13.4. Step 3 — advertise the field in the component caps
  • 3.13.5. Checklist