All Classes Files Functions Variables Pages

Table of Contents

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


The HYCOM cap has been tested with versions 2.2.35 and 2.2.98 of HYCOM.

This document describes the HYCOM "cap", which is a small software layer that is required when the HYCOM 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.

Cap Subroutines

The HYCOM 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 HYCOM 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 HYCOM 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 HYCOM 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 HYCOM cap. The "Phase" column says whether the subroutine is called during the initialization, run, or finalize part of the coupled system run.

Phase HYCOM 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 HYCOM grid as well as ESMF_Fields for import and export fields
Run ModelAdvance Advances the model by a timestep
Final Finalize Cleans up

Underlying Model Interfaces

Domain Creation

The ESMF representation of the HYCOM tripolar grid is created in the subroutine HYCOM_GlueInitialize, which is called during the InitializeRealize NUOPC phase.

The grid is created in several steps:


The call to the native HYCOM_Init() subroutine occurs in the InitializeRealize NUOPC phase. The main parameters passed are the start time and stop time (the incoming ESMF clock is translated into seconds), and the MPI communicator, which is retrieved via a call to ESMF_VMGet(). If the "Restart" attribute is not "true" then the start time is negated, which indicates to HYCOM that it is a cold start initialization.


The NUOPC phase responsible for advancing the model is ModelAdvance. Before calling into the native advance subroutine, a call is made to HYCOM_GlueFieldsDataImport() which copies coupling fields from the import state into HYCOM native arrays. Some incoming fields have two time levels that are copied over and some unit conversions are also applied (see Import Fields table for details on which fields are impacted.)

After import fields have been copied to native arrays, a call is made to HYCOM_Run() passing in an end time parameter based on the incoming ESMF clock. This is called is a loop until end_of_run or end_of_run_cpl is true (these are set internally by HYCOM).

After the run, a call is made to HYCOM_GlueFieldsDataExport() which copies internal fields to ESMF fields in the export state.

Vector Rotations

Vector rotations are applied to incoming wind stresses (from regular lat-lon to tripolar grid) and outgoing ocean currents (from tripolar to regular lat-lon). The rotation angles are provided in the native HYCOM array pang.

The rotation of wind stress from regular lat-lon to tripolar happens in HYCOM_GlueFieldsImport():

\[ \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 happens in HYCOM_Run() in the file mod_hycom.F:

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


The Finalize NUOPC phase deallocates internal state memory. There is no call to any native HYCOM finalization subroutine.

Model Fields

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

Import Fields

Standard Name Units Model Variable Description Notes
downward_sea_ice_basal_solar_heat_flux W m-2 fswice solar heat flux thru ice to oceanimported to intermediate array siqs_import
downward_sea_ice_basal_water_flux kg m-2 s-1 sflice ice net water flux imported to intermediate array sifw_import
downward_x_stress_at_sea_ice_base Pa si_tx sea ice x stress imported to intermediate array sitx_import
downward_y_stress_at_sea_ice_base Pa si_ty sea ice y stress imported to intermediate array sity_import
friction_speed m s-1 ustar friction speed imported to intermediate array imp_ustara
frozen_water_flux_into_sea_water kg m-2 s-1 riv_input ice runoff imported to intermediate array imp_irivers; unit conversion kg m-2 s-1 -> m s-1
ice_fraction 1 covice,si_c sea ice concentration imported to intermediate array sic_import
inst_spec_humid_height2m 1 vpmx specific humidity imported to intermediate array imp_vapmix
inst_temp_height2m K airt air temperature imported to intermediate array imp_airtmp; unit conversion K -> C
mean_down_lw_flux W m-2 radfl longwave downward flux imported to intermediate array imp_lwdflx
mean_lat_flx W m-2 evap latent heat flux imported to intermediate array imp_latflx; sign reversed to comply with HYCOM convention
mean_net_lw_flx W m-2 radfl longwave net flux imported to intermediate array imp_lwflx
mean_net_sw_flx W m-2 swfl, radfl shortwave net flux imported to intermediate array imp_swflx
mean_prec_rate kg m-2 s-1 prcp precipitation imported to intermediate array imp_precip; unit conversion kg m-2 s-1 -> m s-1
mean_salt_rate flxice ice freezing/melting salt flux imported to intermediate array sifs_import
mean_sens_flx W m-2 snsibl sensible heat flux imported to intermediate array imp_sensflx; sign reversed to comply with HYCOM convention
mean_up_lw_flux W m-2 radfl longwave upward flux imported to intermediate array imp_lwuflx
sea_ice_temperature K temice, si_t sea ice temperature imported to intermediate array sit_import
sea_ice_thickness m thkice sea ice thickness imported to intermediate array sih_import
sea_ice_x_velocity m s-1 si_u sea ice x velocity imported to intermediate array siu_import
sea_ice_y_velocity m s-1 si_v sea ice y velocity imported to intermediate array siv_import
sea_surface_temperature K tdif sea surface temperature imported to intermediate array imp_surtmp; unit conversion K -> C
surface_downward_eastward_stress Pa surtx, surty eastward stress imported to imp_taue and rotated to internal grid (imp_taux and imp_tauy)
surface_downward_northward_stress Pa surtx, surty northward stress imported to imp_taun and rotated to internal grid (imp_taux and imp_tauy)
water_flux_into_sea_water kg m-2 s-1 riv_input ocean runoff imported to intermediate array imp_orivers; unit conversion kg m-2 s-1 -> m s-1
wind_speed_height10m m s-1 wind wind speed imported to intermediate array imp_wndspd

Export Fields

Standard Name Units Model Variable Description Notes
freezing_melting_potential W m-2 frzh freezing potential flux custom computation in cap
mixed_layer_depth m dpbl turbulent boundary layer depth unit conversion Pa -> m
ocean_mask ip mask sea points when ip != 0
ocn_current_merid m s-1 vmxl northward v velocity
ocn_current_zonal m s-1 umxl eastward u velocity
s_surf sml average salinity over coupling interval
sea_lev m sshm average sea surface height over coupling interval sshm converted to meters
sea_surface_slope_merid m dhde eastward slope vector rotation applied to dhdx and dhdy
sea_surface_slope_zonal m dhdn northward slope vector rotation applied to dhdx and dhdy
sea_surface_temperature K temp temperature unit conversion C -> K
upward_sea_ice_basal_available_heat_flux W m-2 (multiple) computed in cap from surface layer thickness, temperature, and salinity

Memory Management

During the InitializeRealize phase, ESMF allocates its own memory for the import and export fields. There are memory-to-memory copies required to move this data to and from native HYCOM arrays.


The cap is capable of writing out diagnostic files for each of the import and export coupling fields. To enable this feature, the "DumpFields" attribute must be set to "true". In this case, prior to the internal call to HYCOM_Run() NetCDF files named field_ocn_import_<fieldname>.nc will be written, and after the call to HYCOM_Run(), files named field_ocn_export_<fieldname>.nc will be written. These files are time series and will contain one slice of data for each time cap advance subroutine is called.

Building and Installing


Runtime Configuration

The following runtime options are set with ESMF Attributes:


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