|
HYCOM NUOPC Cap
|
|
HYCOM NUOPC Cap
|
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.
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 |
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:
ESMF_VMAllGatherESMF_DistGrid is created over the global index space. If the "Regional" attribute is set to "true", then no periodic boundaries are set. Otherwise, for a global grid, connections are set up so that the index space is periodic in the first dimension and has a fold at the top for the bipole. In either case, the decompostion blocks are passed into the call to ESMF_DistGridCreateESMF_Arrays, with appropriate halo widths set to nbdy: plon, plat (center coordinates), ip (mask), scp2 (area)ESMF_Grid is then created by passing in the above ESMF_DistGridplot and plat arraysulon and ulat arraysThe 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 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} \]](form_0.png)
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} \]](form_1.png)
The Finalize NUOPC phase deallocates internal state memory. There is no call to any native HYCOM finalization subroutine.
The following tables list the import and export fields currently set up in the HYCOM cap.
| Standard Name | Units | Model Variable | Description | Notes |
|---|---|---|---|---|
| downward_sea_ice_basal_solar_heat_flux | W m-2 | fswice | solar heat flux thru ice to ocean | imported 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 |
| 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 |
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.
The following runtime options are set with ESMF Attributes:
Restart - when set to "true", HYCOM will be asked ot read atmospheric forcing data during its initializationAtm_init - ?DumpFields - when set to "true", diagnostic NetCDF files will be written during the advance phase, one per import/export fieldRegional - when set to "true", HYCOM is set up in regional mode with a regional gridThe HYCOM NUOPC cap is maintained in a GitHub repository: https://github.com/feiliuesmf/hycom_cesm
1.8.5