NUOPC Cap UFS: Difference between revisions
From WikiROMS
Jump to navigationJump to search
| (12 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
<div class="title">ROMS ESMF/NUOPC Cap for the UFS</div> | <div class="title">ROMS Stand-Alone ESMF/NUOPC Cap for the UFS</div> | ||
__TOC__ | __TOC__ | ||
| Line 7: | Line 7: | ||
A '''NUOPC''' <span class="red">cap</span> is a Fortran module that serves as the interface to a model when it's used in a '''NUOPC'''-based coupled system. The term <span class="red">cap</span> is used because it is a lightweight software layer that sits on top of model code, making calls to it and exposing model data structures in a standard way. | A '''NUOPC''' <span class="red">cap</span> is a Fortran module that serves as the interface to a model when it's used in a '''NUOPC'''-based coupled system. The term <span class="red">cap</span> is used because it is a lightweight software layer that sits on top of model code, making calls to it and exposing model data structures in a standard way. | ||
== | ==Implementation== | ||
The <span class="blue">cmeps_roms.F</span> module | The <span class="blue">cmeps_roms.F</span> module declares several derived-type structures to facilitate the management of all internal objects and variables: | ||
* ESM coupling time managing variables and ESMF objects. <div class=" | * '''ESM''' coupling time managing variables and '''ESMF''' objects. <div class="code"> <span class="darkTurquoise">TYPE</span>, <span class="darkTurquoise">PRIVATE</span> :: <span class="forestGreen">ESM_Clock</span><br /><br /> <span class="darkTurquoise">logical</span> :: <span class="red">Restarted</span><br /><br /> <span class="darkTurquoise">integer</span> (<span class="red">i8b</span>) :: <span class="red">AdvanceCount</span> <span class="twilightBlue">! advance counter</span><br /><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Current_Time</span> <span class="twilightBlue">! seconds</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Time_Reference</span> <span class="twilightBlue">! seconds</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Time_Restart</span> <span class="twilightBlue">! seconds</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Time_Start</span> <span class="twilightBlue">! seconds</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Time_Stop</span> <span class="twilightBlue">! seconds</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Time_Step</span> <span class="twilightBlue">! seconds</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">Name</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">CalendarString</span> <span class="twilightBlue">! 360_day, gregorian</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">Time_ReferenceString</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">Time_RestartString</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">Time_StartString</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">Time_StopString</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Calendar</span>) :: <span class="red">Calendar</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Clock</span>) :: <span class="red">Clock</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Direction_flag</span>) :: <span class="red">Direction</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Time</span>) :: <span class="red">CurrentTime</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Time</span>) :: <span class="red">ReferenceTime</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Time</span>) :: <span class="red">RestartTime</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Time</span>) :: <span class="red">StartTime</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Time</span>) :: <span class="red">StopTime</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_TimeInterval</span>) :: <span class="red">TimeStep</span><br /><br /> <span class="darkTurquoise">END TYPE</span> <span class="forestGreen">ESM_Clock</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_Clock</span>), <span class="darkTurquoise">allocatable</span>, <span class="darkTurquoise">target</span> :: <span class="red">ClockInfo(:)</span></div> | ||
* ESM coupled state sets. If appropriate, it includes the logic for connecting nested grids. <div class=" | * '''ESM''' coupled state sets. If appropriate, it includes the logic for connecting nested grids. <div class="code"> <span class="darkTurquoise">TYPE</span>, <span class="darkTurquoise">PRIVATE</span> :: <span class="forestGreen">ESM_CplSet</span><br /><br /> <span class="darkTurquoise">logical</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">LinkedGrid(:,:)</span> <span class="twilightBlue">! connected grid</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=100), <span class="darkTurquoise">allocatable</span> :: <span class="red">SetLabel(:)</span> <span class="twilightBlue">! set label</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=100), <span class="darkTurquoise">allocatable</span> :: <span class="red">ExpLabel(:)</span> <span class="twilightBlue">! export label</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=100), <span class="darkTurquoise">allocatable</span> :: <span class="red">ImpLabel(:)</span> ! <span class="twilightBlue">import label</span><br /><br /> <span class="darkTurquoise">END TYPE</span> <span class="forestGreen">ESM_CplSet</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_CplSet</span>), <span class="darkTurquoise">allocatable</span>, <span class="darkTurquoise">target</span> :: <span class="red">COUPLED(:)</span></div> | ||
* Import and export fields metadata information. <div class=" | * Import and export fields metadata information. <div class="code"> <span class="darkTurquoise">TYPE</span>, <span class="darkTurquoise">PRIVATE</span> :: <span class="forestGreen">ESM_Field</span><br /><br /> <span class="darkTurquoise">logical</span> :: <span class="red">connected</span> <span class="twilightBlue">! connected to coupler</span><br /> <span class="darkTurquoise">logical</span> :: <span class="red">debug_write</span> <span class="twilightBlue">! write exchanged field</span><br /><br /> <span class="darkTurquoise">integer</span> :: <span class="red">gtype</span> ! <span class="twilightBlue">field grid mesh type</span><br /> <span class="darkTurquoise">integer</span> :: <span class="red">Tindex</span> <span class="twilightBlue">! rolling two-time indices</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">short_name</span> <span class="twilightBlue">! short name</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">standard_name</span> <span class="twilightBlue">! standard name</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">long_name</span> <span class="twilightBlue">! long name</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">dst_gtype</span> <span class="twilightBlue">! DST grid type</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">dst_units</span> <span class="twilightBlue">! DST units</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">src_gtype</span> <span class="twilightBlue">! SRC grid type</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">src_units</span> <span class="twilightBlue">! SRC units</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">nc_vname</span> <span class="twilightBlue">! DATA Vname</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">nc_tname</span> <span class="twilightBlue">! DATA Tname</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">map_norm</span> <span class="twilightBlue">! mapping norm</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">map_type</span> <span class="twilightBlue">! regrid method</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=22) :: <span class="red">DateString(2)</span> <span class="twilightBlue">! snapshots date</span><br /><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">scale_factor</span> <span class="twilightBlue">! field scale factor</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">add_offset</span> <span class="twilightBlue">! field add offset value</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Tmin</span> <span class="twilightBlue">! DATA time minimum value</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Tmax</span> <span class="twilightBlue">! DATA time maximum value</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Tstr</span> <span class="twilightBlue">! DATA lower time-snapshot</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Tend</span> <span class="twilightBlue">! DATA upper time-snapshot</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Tintrp(2)</span> <span class="twilightBlue">! interpolation time (day)</span><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>) :: <span class="red">Vtime(2)</span> <span class="twilightBlue">! latest two-time values</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_RouteHandle</span>) :: <span class="red">rhandle</span> ! <span class="twilightBlue">field RouteHandle</span><br /><br /> <span class="darkTurquoise">END TYPE</span> <span class="forestGreen">ESM_Field</span></div> | ||
* Import and export fields mesh data. <div class=" | * Import and export fields mesh data. <div class="code"> <span class="darkTurquoise">TYPE</span>, <span class="darkTurquoise">PRIVATE</span> :: <span class="forestGreen">ESM_Mesh</span><br /><br /> <span class="darkTurquoise">integer</span> :: <span class="red">gid</span> <span class="twilightBlue">! grid ID</span><br /> <span class="darkTurquoise">integer</span> :: <span class="red">gtype</span> <span class="twilightBlue">! grid mesh type</span><br /><br /> <span class="darkTurquoise">integer</span> (<span class="red">i4b</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">mask(:,:)</span> <span class="twilightBlue">! grid land/sea mask</span><br /><br /> <span class="darkTurquoise">real</span> (<span class="red">r8</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">lon(:,:)</span> <span class="twilightBlue">! grid longitude</span><br /> <span class="red">real</span> (<span class="red">r8</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">lat(:,:)</span> <span class="twilightBlue">! grid latitude</span><br /> <span class="darkTurquoise">real</span> (<span class="red">r8</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">area(:,:)</span> <span class="twilightBlue">! grid area</span><br /><br /> <span class="darkTurquoise">END TYPE</span> <span class="forestGreen">ESM_Mesh</span></div> | ||
* Coupled models high-level object, [<span class="red">Nmodels=1</span>]. <div class=" | * Coupled models high-level object, [<span class="red">Nmodels=1</span>]. <div class="code"> <span class="darkTurquoise">TYPE</span>, <span class="darkTurquoise">PRIVATE</span> :: <span class="forestGreen">ESM_Model</span><br /><br /> <span class="darkTurquoise">logical</span> :: <span class="red">IsActive</span> <span class="twilightBlue">! active for coupling</span><br /><br /> <span class="darkTurquoise">integer</span> (<span class="red">i4b</span>) :: <span class="red">LandValue</span> <span class="twilightBlue">! land mask value</span><br /> <span class="darkTurquoise">integer</span> (<span class="red">i4b</span>) :: <span class="red">SeaValue</span> <span class="twilightBlue">! sea mask value</span><br /><br /> <span class="darkTurquoise">integer</span> :: <span class="red">Ngrids</span> <span class="twilightBlue">! number nested grids</span><br /><br /> <span class="darkTurquoise">integer</span> :: <span class="red">ExportCalls</span> <span class="twilightBlue">! export CALL counter</span><br /> <span class="darkTurquoise">integer</span> :: <span class="red">ImportCalls</span> <span class="twilightBlue">! import CALL counter</span><br /><br /> <span class="darkTurquoise">integer</span> :: <span class="red">nPETs</span> <span class="twilightBlue">! number model PETs</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">PETlist(:)</span> <span class="twilightBlue">! component PETs list</span><br /><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">TimeFrac(:,:)</span> <span class="twilightBlue">! driver time fraction</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">name</span> <span class="twilightBlue">! component name</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_Grid</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">grid(:)</span> <span class="twilightBlue">! grid object</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_Mesh</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">mesh(:)</span> <span class="twilightBlue">! mesh</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_Field</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">ImportField(:)</span> <span class="twilightBlue">! import fields</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_Field</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">ExportField(:)</span> <span class="twilightBlue">! export fields</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_State</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">ImportState(:)</span> <span class="twilightBlue">! import state</span><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESMF_State</span>), <span class="darkTurquoise">allocatable</span> :: <span class="red">ExportState(:)</span> <span class="twilightBlue">! export state</span><br /><br /> <span class="darkTurquoise">END TYPE</span> <span class="forestGreen">ESM_Model</span><br /><br /> <span class="darkTurquoise">TYPE</span> (<span class="forestGreen">ESM_Model</span>), <span class="darkTurquoise">allocatable</span>, <span class="darkTurquoise">target</span> :: <span class="red">MODELS(:)</span></div> | ||
* '''Internal module parameters and variables:''' | |||
** Switch to trace/track run sequence during debugging. All information is written to Fortran unit trac. For now, it uses the standard output unit. <div class="code"> <span class="darkTurquoise">logical</span> :: <span class="red">ESM_track</span> = <span class="red">.TRUE.</span> <span class="twilightBlue">! trace/track CALL sequence switch</span></div> | |||
** Number of coupled '''ESM''' gridded components and identification index. <div class="code"> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Nmodels</span> = <span class="red">1</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Idriver</span> = <span class="red">0</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Iroms</span> = <span class="red">1</span></div> | |||
** Number of ROMS export and import fields per component. <div class="code"> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">Nexport(:)</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">Nimport(:)</span></div> | |||
** Model coupling type: [<span class="red">1</span>] Explicit, [<span class="red">otherwise</span>] Semi-Implicit. In <span class="red">explicit coupling</span>, exchange fields at the next time-step are defined using known values from the time-step before it. Explicit methods require less computational effort and are accurate for small coupling time-steps. In <span class="red">implicit coupling</span>, exchange fields at the next time-step are defined by including values at the next time-step. Implicit methods are stable and allow longer coupling time-steps but are more computationally expensive. In <span class="red">semi-implicit coupling</span>, '''ROMS -> ATM''' is explicit, '''ATM -> ROMS''' is implicit. <div class="code"> <span class="darkTurquoise">integer</span> :: <span class="red">CouplingType</span> = <span class="red">1</span></div> | |||
** Linked/coupled ROMS nested grid number. <div class="code"> <span class="darkTurquoise">integer</span> :: <span class="red">linked_grid</span></div> | |||
** Distributed-memory communicator handle for each component, rank of each PET, and PET layout (sequential or concurrent). <div class="code"> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">allocatable</span> :: <span class="red">ESMcomm(:)</span><br /> <span class="darkTurquoise">integer</span> :: <span class="red">PETrank</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=10), <span class="darkTurquoise">allocatable</span> :: <span class="red">PETlayoutOption(:)</span></div> | |||
** Coupling debugging flag: [<span class="red">0</span>] no debugging, [<span class="red">1</span>] reports informative messages, or [<span class="red">2</span>] <span class="red">'1'</span> plus writes grid information in '''VTK''' format, [<span class="red">3</span>] <span class="red">'2'</span> plus writes exchage fields into '''NetCDF''' files. <div class="code"> <span class="darkTurquoise">integer</span> :: <span class="red">DebugLevel</span> = <span class="red">0</span></div> | |||
** Execution tracing level flag: [<span class="red">0</span>] no tracing, [<span class="red">1</span>] reports sequence of coupling subroutine calls, or [<span class="red">2</span>] <<span class="red">1</span>> plus writes voluminous '''ESMF''' library tracing information which slowdown performace, and creates large log file. <div class="code"> <span class="darkTurquoise">integer</span> :: <span class="red">TraceLevel</span> = <span class="red">0</span></div> | |||
** Standard output units. <div class="code"> <span class="darkTurquoise">integer</span> :: <span class="red">cplout</span> = <span class="red">77</span> <span class="twilightBlue">! coupling driver</span><br /> <span class="darkTurquoise">integer</span> :: <span class="red">trac</span> = <span class="red">6</span> <span class="twilightBlue">! trace/track CALL sequence unit</span></div> | |||
** Coupled model staggered grid-cell type indices. <div class="code"> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Inan</span> = <span class="red">0</span> <span class="twilightBlue">! unstaggered, cell center</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Icenter</span> = <span class="red">1</span> <span class="twilightBlue">! cell center</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Icorner</span> = <span class="red">2</span> <span class="twilightBlue">! cell corners</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Iupoint</span> = <span class="red">3</span> <span class="twilightBlue">! right and left cell faces</span><br /> <span class="darkTurquoise">integer</span>, <span class="darkTurquoise">parameter</span> :: <span class="red">Ivpoint</span> = <span class="red">4</span> <span class="twilightBlue">! upper and lower cell faces</span><br /><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=6), <span class="darkTurquoise">dimension</span>(0:4) :: <span class="red">GridType</span> = &<br /> & (/ '<span class="red">N/A</span> ', &<br /> & '<span class="red">Center</span>', &<br /> & '<span class="red">Corner</span>', &<br /> & '<span class="red">U</span> ', &<br /> & '<span class="red">V</span> ' /)</div> | |||
** Standard input filename for each coupled model, [<span class="red">Nmodels</span>]. <div class="code"> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=256), <span class="darkTurquoise">allocatable</span> :: <span class="red">INPname(:)</span></div> | |||
** ROMS coupling '''YAML''' configuration filename. <div class="code"> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">CPLname</span></div> | |||
** '''ESM''' strings. <div class="code"> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">CoupledSet</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">ExportStateName</span><br /> <span class="darkTurquoise">character</span> (<span class="darkTurquoise">len</span>=:), <span class="darkTurquoise">allocatable</span> :: <span class="red">ImportStateName</span></div> | |||
** '''ESM''' single and double precision constants. <div class="code"> <span class="darkTurquoise">integer</span> (<span class="red">i4b</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">MAPPED_MASK</span> = <span class="red">99_i4b</span><br /> <span class="darkTurquoise">integer</span> (<span class="red">i4b</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">UNMAPPED_MASK</span> = <span class="red">98_i4b</span><br /><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">MISSING_dp</span> = <span class="red">1.0E20_dp</span><br /> <span class="darkTurquoise">real</span> (<span class="red">r4</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">MISSING_r4</span> = <span class="red">1.0E20_r4</span><br /> <span class="darkTurquoise">real</span> (<span class="red">r8</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">MISSING_r8</span> = <span class="red">1.0E20_r8</span><br /><br /> <span class="darkTurquoise">real</span> (<span class="red">dp</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">TOL_dp</span> = <span class="red">0.5E20_dp</span><br /> <span class="darkTurquoise">real</span> (<span class="red">r4</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">TOL_r4</span> = <span class="red">0.5E20_r4</span><br /> <span class="darkTurquoise">real</span> (<span class="red">r8</span>), <span class="darkTurquoise">parameter</span> :: <span class="red">TOL_r8</span> = <span class="red">0.5E20_r8</span></div> | |||
==UFS Interface== | |||
The '''NUOPC''' <span class="red">cap</span> file is connected to the <span class="blue">UFS.F90</span> and <span class="blue">EARTH_GRID_COMP.F90</span> with '''C'''-preprocessing option <span class="mediumOrchid">FRONT_ROMS</span> as follows: | |||
<div class="code"> <span class="darkTurquoise">MODULE</span> <span class="blue">module_EARTH_GRID_COMP</span><br /><br /> ...<br /><br /><span class="mediumOrchid">#ifdef FRONT_ROMS</span><br /> <span class="darkTurquoise">USE</span> <span class="blue">cmeps_roms_mod</span>, <span class="darkTurquoise">ONLY</span> : <span class="blue">ROMS_SS</span> => <span class="blue">ROMS_SetServices</span><br /><span class="mediumOrchid">#endif</span><br /><br /> ...<br /><br /> <span class="darkTurquoise">END MODULE</span> <span class="blue">module_EARTH_GRID_COMP</span></div> | |||
==Module Subroutines== | ==Module Subroutines== | ||
The ROMS <span class="red">cap</span> 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 the initialization of the coupled system, some during the run of the coupled system, and some during the finalization of the coupled system. | The ROMS <span class="red">cap</span> 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 the initialization of the coupled system, some during the run of the coupled system, and some during the 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. The ROMS <span class="red">cap</span> requires '''ESMF version 8 or higher'''. | 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. The ROMS <span class="red">cap</span> requires '''ESMF version 8 or higher'''. | ||
{| border="1" cellspacing="0" cellpadding="5" width="1000" | {| border="1" cellspacing="0" cellpadding="5" width="1000" | ||
|valign="top"|<span class="blue">ROMS_SetServices</span> | |valign="top"|<span class="blue">ROMS_SetServices</span> | ||
|Entry point to the ROMS <span class="red">cap</span> and the only <span class="red">public</span> routine. It sets the ROMS component shared-object entry points for using NUOPC generic methods for '''initialize''', '''run''', and '''finalize'''. | |Entry point to the ROMS <span class="red">cap</span> and the only <span class="red">public</span> routine. It sets the ROMS component shared-object entry points for using '''NUOPC''' generic methods for '''initialize''', '''run''', and '''finalize'''. | ||
|- | |- | ||
|valign="top"|<span class="blue">ROMS_Create</span> | |valign="top"|<span class="blue">ROMS_Create</span> | ||
|Allocates module internal structures and | |Allocates module internal structures and processes configuration from '''YAML''' file: [[roms_cmeps.yaml]]. | ||
|- | |- | ||
|valign="top"|<span class="blue">ROMS_SetInitializeP1</span> | |valign="top"|<span class="blue">ROMS_SetInitializeP1</span> | ||
| Line 69: | Line 90: | ||
|valign="top"|<span class="blue">ROMS_Export</span> | |valign="top"|<span class="blue">ROMS_Export</span> | ||
|Exports ROMS fields to other gridded components. | |Exports ROMS fields to other gridded components. | ||
|- | |||
|valign="top"|<span class="blue">ROMS_Rotate</span> | |||
|Rotates vector components from computational grid to geographical '''EAST''' and '''NORTH''' directions or vice versa. | |||
|- | |- | ||
|valign="top"|<span class="blue">Report_TimeStamp</span> | |valign="top"|<span class="blue">Report_TimeStamp</span> | ||
|Reports coupling time-stamp. | |Reports coupling time-stamp. | ||
|- | |- | ||
|} | |||
==Import and Export Fields== | |||
The <span class="red">export</span> and <span class="red">import</span> fields are configured and specified in the '''YAML''' file [[roms_cmeps.yaml]]. Check the following [[roms_cmeps.yaml|wikiROMS]] page for detailed information. The user has full control of the coupling exchange fields metadata. | |||
Currently, '''CMEPS''' does not support coupling of nested grids. The '''ESMF/NUOPC''' library version '''8.0.0''' or higher supports native nesting capabilities. The '''NUOPC''' layer now allows coupling sets in the <span class="red">import</span> and <span class="red">export</span> states of the '''ESM''' components. A nested grid is represented as another '''ESMF_Grid''' object so that a coupled model can have a set of telescoping meshes of decreasing spatial resolution. The '''NUOPC''' connector can recognize the different grids and exchange fields to a connected '''ESM''' component. Various types of connections are possible, like nest-to-nest, fine-to-coarse, or coarse-to-fine. The user decides which nested grids to connect. The <span class="blue">NUOPC_AddNestedState</span> routine is used to advertise the nested couple sets. | |||
For example, the '''NOUPC''' cap module routines <span class="blue">ROMS_SetInitializeP1</span> can be modified easily to add the coupled sets to the <span class="red">ImportState</span> and <span class="red">ExportState</span> as shown below in the green blocks of code. | |||
{|cellpadding="3" | |||
|- | |||
|[[Image:ImportCoupledStates.png]] | |||
|[[Image:ExportCoupledStates.png]] | |||
|} | |} | ||
Latest revision as of 21:18, 26 June 2022
ROMS Stand-Alone ESMF/NUOPC Cap for the UFS
Overview
This document describes the stand-alone ROMS ESMF/NUOPC cap module to be used by third-party coupling frameworks, like the Unified Forecast System (UFS). It is a lightweight software layer on top of ROMS that can be used by NUOPC-based packages (CMEPS/CDEPS, NEMS, and others) to couple to other Earth System Models (ESMs). Detailed information about ESMF/NUOPC and its implementation in ROMS can be found on the Earth System Modeling Framework WikiROMS page.
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 lightweight software layer that sits on top of model code, making calls to it and exposing model data structures in a standard way.
Implementation
The cmeps_roms.F module declares several derived-type structures to facilitate the management of all internal objects and variables:
- ESM coupling time managing variables and ESMF objects. TYPE, PRIVATE :: ESM_Clock
logical :: Restarted
integer (i8b) :: AdvanceCount ! advance counter
real (dp) :: Current_Time ! seconds
real (dp) :: Time_Reference ! seconds
real (dp) :: Time_Restart ! seconds
real (dp) :: Time_Start ! seconds
real (dp) :: Time_Stop ! seconds
real (dp) :: Time_Step ! seconds
character (len=22) :: Name
character (len=22) :: CalendarString ! 360_day, gregorian
character (len=22) :: Time_ReferenceString
character (len=22) :: Time_RestartString
character (len=22) :: Time_StartString
character (len=22) :: Time_StopString
TYPE (ESMF_Calendar) :: Calendar
TYPE (ESMF_Clock) :: Clock
TYPE (ESMF_Direction_flag) :: Direction
TYPE (ESMF_Time) :: CurrentTime
TYPE (ESMF_Time) :: ReferenceTime
TYPE (ESMF_Time) :: RestartTime
TYPE (ESMF_Time) :: StartTime
TYPE (ESMF_Time) :: StopTime
TYPE (ESMF_TimeInterval) :: TimeStep
END TYPE ESM_Clock
TYPE (ESM_Clock), allocatable, target :: ClockInfo(:)
- ESM coupled state sets. If appropriate, it includes the logic for connecting nested grids. TYPE, PRIVATE :: ESM_CplSet
logical, allocatable :: LinkedGrid(:,:) ! connected grid
character (len=100), allocatable :: SetLabel(:) ! set label
character (len=100), allocatable :: ExpLabel(:) ! export label
character (len=100), allocatable :: ImpLabel(:) ! import label
END TYPE ESM_CplSet
TYPE (ESM_CplSet), allocatable, target :: COUPLED(:)
- Import and export fields metadata information. TYPE, PRIVATE :: ESM_Field
logical :: connected ! connected to coupler
logical :: debug_write ! write exchanged field
integer :: gtype ! field grid mesh type
integer :: Tindex ! rolling two-time indices
character (len=:), allocatable :: short_name ! short name
character (len=:), allocatable :: standard_name ! standard name
character (len=:), allocatable :: long_name ! long name
character (len=:), allocatable :: dst_gtype ! DST grid type
character (len=:), allocatable :: dst_units ! DST units
character (len=:), allocatable :: src_gtype ! SRC grid type
character (len=:), allocatable :: src_units ! SRC units
character (len=:), allocatable :: nc_vname ! DATA Vname
character (len=:), allocatable :: nc_tname ! DATA Tname
character (len=:), allocatable :: map_norm ! mapping norm
character (len=:), allocatable :: map_type ! regrid method
character (len=22) :: DateString(2) ! snapshots date
real (dp) :: scale_factor ! field scale factor
real (dp) :: add_offset ! field add offset value
real (dp) :: Tmin ! DATA time minimum value
real (dp) :: Tmax ! DATA time maximum value
real (dp) :: Tstr ! DATA lower time-snapshot
real (dp) :: Tend ! DATA upper time-snapshot
real (dp) :: Tintrp(2) ! interpolation time (day)
real (dp) :: Vtime(2) ! latest two-time values
TYPE (ESMF_RouteHandle) :: rhandle ! field RouteHandle
END TYPE ESM_Field
- Import and export fields mesh data. TYPE, PRIVATE :: ESM_Mesh
integer :: gid ! grid ID
integer :: gtype ! grid mesh type
integer (i4b), allocatable :: mask(:,:) ! grid land/sea mask
real (r8), allocatable :: lon(:,:) ! grid longitude
real (r8), allocatable :: lat(:,:) ! grid latitude
real (r8), allocatable :: area(:,:) ! grid area
END TYPE ESM_Mesh
- Coupled models high-level object, [Nmodels=1]. TYPE, PRIVATE :: ESM_Model
logical :: IsActive ! active for coupling
integer (i4b) :: LandValue ! land mask value
integer (i4b) :: SeaValue ! sea mask value
integer :: Ngrids ! number nested grids
integer :: ExportCalls ! export CALL counter
integer :: ImportCalls ! import CALL counter
integer :: nPETs ! number model PETs
integer, allocatable :: PETlist(:) ! component PETs list
integer, allocatable :: TimeFrac(:,:) ! driver time fraction
character (len=:), allocatable :: name ! component name
TYPE (ESMF_Grid), allocatable :: grid(:) ! grid object
TYPE (ESM_Mesh), allocatable :: mesh(:) ! mesh
TYPE (ESM_Field), allocatable :: ImportField(:) ! import fields
TYPE (ESM_Field), allocatable :: ExportField(:) ! export fields
TYPE (ESMF_State), allocatable :: ImportState(:) ! import state
TYPE (ESMF_State), allocatable :: ExportState(:) ! export state
END TYPE ESM_Model
TYPE (ESM_Model), allocatable, target :: MODELS(:)
- Internal module parameters and variables:
- Switch to trace/track run sequence during debugging. All information is written to Fortran unit trac. For now, it uses the standard output unit. logical :: ESM_track = .TRUE. ! trace/track CALL sequence switch
- Number of coupled ESM gridded components and identification index. integer, parameter :: Nmodels = 1
integer, parameter :: Idriver = 0
integer, parameter :: Iroms = 1 - Number of ROMS export and import fields per component. integer, allocatable :: Nexport(:)
integer, allocatable :: Nimport(:) - Model coupling type: [1] Explicit, [otherwise] Semi-Implicit. In explicit coupling, exchange fields at the next time-step are defined using known values from the time-step before it. Explicit methods require less computational effort and are accurate for small coupling time-steps. In implicit coupling, exchange fields at the next time-step are defined by including values at the next time-step. Implicit methods are stable and allow longer coupling time-steps but are more computationally expensive. In semi-implicit coupling, ROMS -> ATM is explicit, ATM -> ROMS is implicit. integer :: CouplingType = 1
- Linked/coupled ROMS nested grid number. integer :: linked_grid
- Distributed-memory communicator handle for each component, rank of each PET, and PET layout (sequential or concurrent). integer, allocatable :: ESMcomm(:)
integer :: PETrank
character (len=10), allocatable :: PETlayoutOption(:) - Coupling debugging flag: [0] no debugging, [1] reports informative messages, or [2] '1' plus writes grid information in VTK format, [3] '2' plus writes exchage fields into NetCDF files. integer :: DebugLevel = 0
- Execution tracing level flag: [0] no tracing, [1] reports sequence of coupling subroutine calls, or [2] <1> plus writes voluminous ESMF library tracing information which slowdown performace, and creates large log file. integer :: TraceLevel = 0
- Standard output units. integer :: cplout = 77 ! coupling driver
integer :: trac = 6 ! trace/track CALL sequence unit - Coupled model staggered grid-cell type indices. integer, parameter :: Inan = 0 ! unstaggered, cell center
integer, parameter :: Icenter = 1 ! cell center
integer, parameter :: Icorner = 2 ! cell corners
integer, parameter :: Iupoint = 3 ! right and left cell faces
integer, parameter :: Ivpoint = 4 ! upper and lower cell faces
character (len=6), dimension(0:4) :: GridType = &
& (/ 'N/A ', &
& 'Center', &
& 'Corner', &
& 'U ', &
& 'V ' /) - Standard input filename for each coupled model, [Nmodels]. character (len=256), allocatable :: INPname(:)
- ROMS coupling YAML configuration filename. character (len=:), allocatable :: CPLname
- ESM strings. character (len=:), allocatable :: CoupledSet
character (len=:), allocatable :: ExportStateName
character (len=:), allocatable :: ImportStateName - ESM single and double precision constants. integer (i4b), parameter :: MAPPED_MASK = 99_i4b
integer (i4b), parameter :: UNMAPPED_MASK = 98_i4b
real (dp), parameter :: MISSING_dp = 1.0E20_dp
real (r4), parameter :: MISSING_r4 = 1.0E20_r4
real (r8), parameter :: MISSING_r8 = 1.0E20_r8
real (dp), parameter :: TOL_dp = 0.5E20_dp
real (r4), parameter :: TOL_r4 = 0.5E20_r4
real (r8), parameter :: TOL_r8 = 0.5E20_r8
- Switch to trace/track run sequence during debugging. All information is written to Fortran unit trac. For now, it uses the standard output unit.
UFS Interface
The NUOPC cap file is connected to the UFS.F90 and EARTH_GRID_COMP.F90 with C-preprocessing option FRONT_ROMS as follows:
MODULE module_EARTH_GRID_COMP
...
#ifdef FRONT_ROMS
USE cmeps_roms_mod, ONLY : ROMS_SS => ROMS_SetServices
#endif
...
END MODULE module_EARTH_GRID_COMP
...
#ifdef FRONT_ROMS
USE cmeps_roms_mod, ONLY : ROMS_SS => ROMS_SetServices
#endif
...
END MODULE module_EARTH_GRID_COMP
Module Subroutines
The ROMS cap 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 the initialization of the coupled system, some during the run of the coupled system, and some during the 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. The ROMS cap requires ESMF version 8 or higher.
| ROMS_SetServices | Entry point to the ROMS cap and the only public routine. It sets the ROMS component shared-object entry points for using NUOPC generic methods for initialize, run, and finalize. |
| ROMS_Create | Allocates module internal structures and processes configuration from YAML file: roms_cmeps.yaml. |
| ROMS_SetInitializeP1 | ROMS component phase 1 initialization which sets import and export fields long and short names into its respective state. |
| ROMS_SetInitializeP2 | ROMS component phase 2 initialization which initializes the ROMS component (ROMS_Initialize), sets component grid (ROMS_SetGridArrays), and adds fields into import and export into respective states. |
| ROMS_DataInit | Exports ROMS component fields during initialization or restart. |
| ROMS_SetClock | Sets ROMS component date calendar, start and stop times, and coupling interval. |
| ROMS_SetRunClock | Sets ROMS run clock manually to avoid getting zero time stamps at the first regridding call. |
| ROMS_CheckImport | Checks if ROMS component import field is at the correct time. |
| ROMS_SetGridArrays | Sets ROMS component staggered, horizontal grid arrays, grid area, and land/sea mask if any. |
| ROMS_SetStates | Adds ROMS component export and import fields into its respective state. |
| ROMS_ModelAdvance | Advances ROMS component for a coupling interval. It calls ROMS_Import and ROMS_Export routines. |
| ROMS_SetFinalize | Finalizes ROMS component execution. |
| ROMS_Import | Loads import fields into ROMS internal kernel arrays. |
| ROMS_Export | Exports ROMS fields to other gridded components. |
| ROMS_Rotate | Rotates vector components from computational grid to geographical EAST and NORTH directions or vice versa. |
| Report_TimeStamp | Reports coupling time-stamp. |
Import and Export Fields
The export and import fields are configured and specified in the YAML file roms_cmeps.yaml. Check the following wikiROMS page for detailed information. The user has full control of the coupling exchange fields metadata.
Currently, CMEPS does not support coupling of nested grids. The ESMF/NUOPC library version 8.0.0 or higher supports native nesting capabilities. The NUOPC layer now allows coupling sets in the import and export states of the ESM components. A nested grid is represented as another ESMF_Grid object so that a coupled model can have a set of telescoping meshes of decreasing spatial resolution. The NUOPC connector can recognize the different grids and exchange fields to a connected ESM component. Various types of connections are possible, like nest-to-nest, fine-to-coarse, or coarse-to-fine. The user decides which nested grids to connect. The NUOPC_AddNestedState routine is used to advertise the nested couple sets.
For example, the NOUPC cap module routines ROMS_SetInitializeP1 can be modified easily to add the coupled sets to the ImportState and ExportState as shown below in the green blocks of code.
|
|
