MOM NUOPC Cap
 All Classes Files Functions Variables Pages
MOM NUOPC Cap

Table of Contents

Author
Fei Liu (fei.l.nosp@m.iu@g.nosp@m.mail..nosp@m.com)
Date
1/12/17 Original documentation

Overview

This MOM cap has been tested with MOM5 and MOM6.

This document describes the MOM "cap", which is a small software layer that is required when the MOM ocean model is used in National Unified Operation Prediction Capability (NUOPC) coupled systems. The NUOPC Layer is a software layer built on top of the Earth System Modeling Framework (ESMF). ESMF is a high-performance modeling framework that provides data structures, interfaces, and operations suited for building coupled models from a set of components. NUOPC refines the capabilities of ESMF by providing a more precise definition of what it means for a model to be a component and how components should interact and share data in a coupled system. The NUOPC Layer software is designed to work with typical high-performance models in the Earth sciences domain, most of which are written in Fortran and are based on a distributed memory model of parallelism (MPI). A NUOPC "cap" is a Fortran module that serves as the interface to a model when it's used in a NUOPC-based coupled system. The term "cap" is used because it is a small software layer that sits on top of model code, making calls into it and exposing model data structures in a standard way. For more information about creating NUOPC caps in general, please see the Building a NUOPC Model how-to document.

The MOM cap package includes the cap itself (mom_cap.F90, a Fortran module), a set of time utilities (time_utils.F90) for converting between ESMF and FMS time types, and two makefiles. Also included are self-describing dependency makefile fragments (mom5.mk and mom5.mk.template), although these can be generated by the makefiles for specific installations of the MOM cap.

Cap Subroutines

The MOM cap Fortran module contains a set of subroutines that are required by NUOPC. These subroutines are called by the NUOPC infrastructure according to a predefined calling sequence. Some subroutines are called during initialization of the coupled system, some during the run of the coupled system, and some during finalization of the coupled system. The initialization sequence is the most complex and is governed by the NUOPC technical rules. Details about the initialization sequence can be found in the NUOPC Reference Manual.

A particularly important part of the NUOPC intialization sequence is to establish field connections between models. Simply put, a field connection is established when a field output by one model can be consumed by another. As an example, the MOM model is able to accept a precipitation rate when coupled to an atmosphere model. In this case a field connection will be established between the precipitation rate exported from the atmosphere and the precipitation rate imported into the MOM model. Because models may uses different variable names for physical quantities, NUOPC relies on a set of standard names and a built-in, extensible standard name dictionary to match fields between models. More information about the use of standard names can be found in the NUOPC Reference Manual.

Two key initialization phases that appear in every NUOPC cap, including this MOM cap are the field "advertise" and field "realize" phases. Advertise is a special NUOPC term that refers to a model participating in a coupled system providing a list of standard names of required import fields and available export fields. In other words, each model will advertise to the other models which physical fields it needs and which fields it can provide when coupled. NUOPC compares all of the advertised standard names and creates a set of unidirectional links, each from one export field in a model to one import field in another model. When these connections have been established, all models in the coupled system need to provide a description of their geographic grid (e.g., lat-lon, tri-polar, cubed sphere, etc.) and allocate their connected fields on that grid. In NUOPC terms, this is refered to as realizing a set of fields. NUOPC relies on ESMF data types for this, such as the ESMF_Grid type, which describes logically rectangular grids and the ESMF_Field type, which wraps a models data arrays and provides basic metadata. Because ESMF supports interpolation between different grids (sometimes called "regridding" or "grid remapping"), it is not necessary that models share a grid. As you will see below the advertise and realize phases each have a subroutine in the HYCOM cap.

The following table summarizes the NUOPC-required subroutines that appear in the MOM cap. The "Phase" column says whether the subroutine is called during the initialization, run, or finalize part of the coupled system run.

Phase MOM Cap Subroutine Description
Init InitializeP0 Sets the Initialize Phase Definition (IPD) version to use
Init InitializeAdvertise Advertises standard names of import and export fields
Init InitializeRealize Creates an ESMF_Grid for the MOM grid as well as ESMF_Fields for import and export fields
Init SetClock Ensures stability timestep constraint is met
Run ModelAdvance Advances the model by a timestep
Final Finalize Cleans up

Underlying Model Interfaces

Domain Creation

The MOM tripolar grid is represented as a 2D ESMF_Grid and coupling fields are placed on this grid. Calls related to creating the grid are located in the InitializeRealize subroutine, which is called by the NUOPC infrastructure during the intialization sequence.

The cap determines parameters for setting up the grid by calling subroutines in the mpp_domains_mod module. The global domain size is determined by calling mpp_get_global_domain(). A check is in place to ensure that there is only a single tile in the domain (the cap is currently limited to one tile; multi-tile mosaics are not supported). The decomposition across processors is determined via calls to mpp_get_compute_domains() (to retrieve decomposition block indices) and mpp_get_pelist() (to determine how blocks are assigned to processors).

The grid is created in several steps:

Masks, areas, center (tlat, tlon), and corner (ulat, ulon) coordinates are then added to the ESMF_Grid by retrieving those fields from MOM with calls to ocean_model_data_get().

Initialization

During the InitializeAdvertise phase, calls are made to MOM's native initialization subroutines, including fms_init(), constants_init(), field_manager_init(), diag_manager_init(), and set_calendar_type(). The MPI communicator is pulled in through the ESMF VM object for the MOM component. The dt and start time are set from parameters from the incoming ESMF clock with calls to set_time() and set_date().

Run

The ModelAdvance subroutine is called by the NUOPC infrastructure when it's time for MOM to advance in time. During this subroutine, there is a call into the MOM update routine: 

 call update_ocean_model(Ice_ocean_boundary, Ocean_state, Ocean_sfc, Time, Time_step_coupled)

Prior to this call, the cap performs a few steps:

After the call to update_ocean_model(), the cap performs these steps:

Vector Rotations

Vector rotations are applied to incoming momentum fluxes (from regular lat-lon to tripolar grid) and outgoing ocean currents (from tripolar to regular lat-lon). The rotation angles are provided from the native MOM grid by a call to get_ocean_grid(Ocean_grid). The cosine and sine of the rotation angle are: 

Ocean_grid%cos_rot(i,j)
Ocean_grid%sin_rot(i,j)

The rotation of momentum flux from regular lat-lon to tripolar is:

\[ \begin{bmatrix} \tau_x' \ \tau_y' \end{bmatrix} = \begin{bmatrix} cos \theta & sin \theta \ -sin \theta & cos \theta \end{bmatrix} * \begin{bmatrix} \tau_x \ \tau_y \end{bmatrix} \]

The rotation of ocean current from tripolar to regular lat-lon is:

\[ \begin{bmatrix} u' \ v' \end{bmatrix} = \begin{bmatrix} cos \theta & -sin \theta \ sin \theta & cos \theta \end{bmatrix} * \begin{bmatrix} u \ v \end{bmatrix} \]

Finalization

NUOPC infrastructure calls ocean_model_finalize at the end of the run. This subroutine is a hook to call into MOM's native shutdown procedures: 

call ocean_model_end (Ocean_sfc, Ocean_State, Time)
call diag_manager_end(Time )
call field_manager_end
call fms_io_exit
call fms_end

Model Fields

The following tables list the import and export fields currently set up in the MOM cap.

Import Fields

Standard Name Units Model Variable Description Notes
inst_pres_height_surface Pa p pressure of overlying sea ice and atmosphere
mass_of_overlying_sea_ice kg mi mass of overlying sea ice
mean_calving_heat_flx W m-2 calving_hflx heat flux, relative to 0C, of frozen land water into ocean
mean_calving_rate kg m-2 s-1 calving mass flux of frozen runoff
mean_evap_rate kg m-2 s-1 q_flux specific humidity flux sign reversed (- evap)
mean_fprec_rate kg m-2 s-1 fprec mass flux of frozen precip
mean_merid_moment_flx Pa v_flux j-directed wind stress into ocean vector rotation applied - lat-lon to tripolar
mean_net_lw_flx W m-2 lw_flux long wave radiation
mean_net_sw_ir_dif_flx W m-2 sw_flux_nir_dif diffuse near IR shortwave radiation
mean_net_sw_ir_dir_flx W m-2 sw_flux_nir_dir direct near IR shortwave radiation
mean_net_sw_vis_dif_flx W m-2 sw_flux_vis_dif diffuse visible shortware radiation
mean_net_sw_vis_dir_flx W m-2 sw_flux_vis_dir direct visible shortware radiation
mean_prec_rate kg m-2 s-1 lprec mass flux of liquid precip
mean_runoff_heat_flx W m-2 runoff_hflx heat flux, relative to 0C, of liquid land water into ocean
mean_runoff_rate kg m-2 s-1 runoff mass flux of liquid runoff
mean_salt_rate kg m-2 s-1 salt_flux salt flux
mean_sensi_heat_flx W m-2 t_flux sensible heat flux into ocean sign reversed (- sensi)
mean_zonal_moment_flx Pa u_flux j-directed wind stress into ocean vector rotation applied - lat-lon to tripolar

Export Fields

Export fields are populated from the ocean_sfc parameter (type ocean_public_type) after the call to update_ocean_model().

Standard Name Units Model Variable Description Notes
freezing_melting_potential W m-2 frazil accumulated heating from frazil formation cap converts model units (J m-2) to (W m-2) for export
ocean_mask ocean mask
ocn_current_merid m s-1 v_surf j-directed surface velocity on u-cell vector rotation applied - tripolar to lat-lon
ocn_current_zonal m s-1 u_surf i-directed surface velocity on u-cell vector rotation applied - tripolar to lat-lon
s_surf psu s_surf sea surface salinity on t-cell
sea_lev m sea_lev sea level model computation is eta_t + patm/(rho0*grav) - eta_geoid - eta_tide
sea_surface_temperature K t_surf sea surface temperature on t-cell

Memory Management

The MOM cap has an internal state type with pointers to three types defined by MOM. There is also a small wrapper derived type required to associate an internal state instance with the ESMF/NUOPC component: 

type ocean_internalstate_type
   type(ocean_public_type),       pointer :: ocean_public_type_ptr
   type(ocean_state_type),        pointer :: ocean_state_type_ptr
   type(ice_ocean_boundary_type), pointer :: ice_ocean_boundary_type_ptr
end type

type ocean_internalstate_wrapper
   type(ocean_internalstate_type), pointer :: ptr
end type

The member of type ocean_public_type stores ocean surface fields used during the coupling. The member of type ocean_state_type is required by the ocean driver, although its internals are private (not to be used by the coupling directly). This type is passed to the ocean init and update routines so that it can maintain state there if desired. The member of type ice_ocean_boundary_type is populated by this cap with incoming coupling fields from other components. These three derived types are allocated during the InitializeAdvertise phase. Also during that phase, the ice_ocean_boundary type members are all allocated using bounds retrieved from mpp_get_compute_domain().

During the InitializeRealize phase, ESMF_Fields are created for each of the coupling fields in the ice_ocean_boundary and ocean_public_type members of the internal state. These fields directly reference into the members of the ice_ocean_boundary and ocean_public_type so that memory-to-memory copies are not required to move data from the cap's import and export states to the memory areas used internally by MOM.

I/O

The cap can optionally output coupling fields for diagnostic purposes if the ESMF attribute "DumpFields" has been set to "true". In this case the cap will write out NetCDF files with names "field_ocn_import_<fieldname>.nc" and "field_ocn_export_<fieldname>.nc". Additionally, calls will be made to the cap subroutine dumpMomInternal to write out model internal fields to files named "field_ocn_internal_<fieldname>.nc". In all cases these NetCDF files will contain a time series of field data.

Building and Installing

There are two makefiles included with the MOM cap, makefile and makefile.nuopc. The makefile.nuopc file is intended to be used within another build system, such as the NEMSAppBuilder. The regular makefile can be used generally for building and installing the cap. Two variables must be customized at the top:

To install run: $ make install

A makefile fragment, mom5.mk, will also be copied into the directory. The fragment defines several variables that can be used by another build system to include the MOM cap and its dependencies.

Dependencies

The MOM cap is dependent on the MOM library itself (lib_ocean.a) and the FMS library (lib_FMS.a).

Runtime Configuration

At runtime, the MOM cap can be configured with several options provided as ESMF attributes. Attributes can be set in the cap by the NUOPC Driver above this cap, or in some systems (e.g., NEMS) attributes are set by reading in from a configuration file. The available attributes are:

Repository

The MOM NUOPC cap is maintained in a GitHub repository: https://github.com/feiliuesmf/nems_mom_cap

References

Generated by   doxygen 1.8.5