Changes between Version 15 and Version 16 of Working Groups/TOP/TOP-User Quick Guide


Ignore:
Timestamp:
2018-01-17T12:02:04+01:00 (3 years ago)
Author:
lovato
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Working Groups/TOP/TOP-User Quick Guide

    v15 v16  
    152152'''1. TOP tracers initialization''' : sn_tracer (namtrc) 
    153153 
    154 Beside providing name and metadata for tracers, here are also defined the use of initial (sn_tracer%llinit) and boundary (sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc) conditions. 
     154Beside providing name and metadata for tracers, here are also defined the use of initial (sn_tracer%llinit) and boundary (sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc) conditions. 
    155155 
    156156In the following, an example of the full structure definition is given for two idealized tracer both with initial conditions given and the first with surface boundary forcing prescribes, while the second has surface and coastal forcing: 
     
    173173sn_tracer(2)%llcbc = .true. 
    174174}}} 
    175 The data structure is internally initialized by code with dummy names and all initialization/forcing logical fields set to .false. . 
     175The data structure is internally initialized by code with dummy names and all initialization/forcing logical fields set to .false. . 
    176176 
    177177'''2. SBC structure to read input fields''' : sn_trcdta (namtrc_dta), sn_trcsbc/sn_trccbc/sn_trcobc (namtrc_bc) 
     
    191191 
    192192=== namelist_trc === 
    193 Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14.  
    194  
    195 |||| &namcfc     !   CFC || 
     193Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14. 
     194 
     195|||| &'''namcfc'''     !   CFC || 
    196196|| ndate_beg || datedeb1 || 
    197197|| nyear_res || iannee1 || 
    198 || clname || Name of formatted file with annual hemisperic CFCs concentration in the atmosphere (ppt) || 
    199 |||| &namc14_typ     !  C14 - type of C14 tracer, default values of C14/C and pco2 || 
     198|| '''clname''' || Name of formatted file with annual hemisperic CFCs concentration in the atmosphere (ppt) || 
     199|||| &namc14_typ     !  C14 - type of C14 tracer, default values of C14/C and pco2 || 
    200200|| kc14typ || Type of C14 tracer (0=equilibrium; 1=bomb transient; 2=past transient) || 
    201201|| rc14at || Default value for atmospheric C14/C (used for equil run) || 
    202202|| pco2at || Default value for atmospheric pcO2 [atm] (used for equil run) || 
    203203|| rc14init || Default value for initialization of ocean C14/C (when no restart) || 
    204 |||| &namc14_sbc     !  C14 - surface BC || 
     204|||| &'''namc14_sbc'''     !  C14 - surface BC || 
    205205|| ln_chemh || Use (T) or not (F) Chemical enhancement in piston velocity || 
    206206|| xkwind || Coefficient for gas exchange velocity || 
    207207|| xdicsur || Reference DIC surface concentration (mol/m3) || 
    208 |||| &namc14_fcg     !  files & dates || 
     208|||| &'''namc14_fcg'''     !  files & dates || 
    209209|| cfileco2 || Name of formatted file with atmospheric co2 - Bomb || 
    210210|| cfilec14 || Name of formatted file with atmospheric c14 - Bomb || 
    211211|| tyrc14_beg || starting year of experiment - Bomb || 
     212 
     213 
     214 
     215== Generalized coupling interface for external BGC models == 
     216The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between NEMO and any external BGC model. 
     217 
     218The call to MY_TRC is activated by setting ln_my_trc = .true. (in namtrc) 
     219 
     220The following 6 fortran files are available in MY_TRC with the specific purposes here described. 
     221 
     222par_my_trc.F90 
     223 
     224This module allows to define additional arrays and public variables to be used within the MY_TRC interface 
     225 
     226trcini_my_trc.F90 
     227 
     228Here are initialized user defined namelists and the call to the external BGC model initialization procedures to populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to system metrics that could be needed by the BGC model. 
     229 
     230trcnam_my_trc.F90 
     231 
     232This routine is called at the beginning of trcini_my_trc and should contain the initialization of additional namelists for the BGC model or user-defined code.  
     233 
     234trcsms_my_trc.F90 
     235 
     236The routine performs the call to Boundary Conditions and its main purpose is to contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model. Be aware that lateral boundary conditions are applied in trcnxt routine. IMPORTANT: the routines to compute the light penetration along the water column and the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in the code.  
     237 
     238trcice_my_trc.F90 
     239 
     240Here it is possible to prescribe the tracers concentrations in the seaice that will be used as boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice). See e.g. the correspondent PISCES subroutine. 
     241 
     242trcwri_my_trc.F90 
     243 
     244This routine performs the output of the model tracers (only those defined in namtrc) using IOM module (see Manual Chapter “Output and Diagnostics”). It is possible to place here the output of additional variables produced by the model, if not done elsewhere in the code, using the call to iom_put. 
     245 
     246== Coupling with an external BGC model == 
     247The coupling with an external BGC model through the NEMO compilation framework can be achieved in different ways according to the degree of coding complexity (e.g., code is only in one file or it has multiple modules and interfaces) of the BGC model itself. 
     248 
     249Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named “MYBGC” made of a rather essential coding structure, likely few Fortran files. 
     250 
     251The best solution is to have a single folder containing the modified MY_TRC routines and the BGC model ones and use the makenemo external addressing of MY_SRC folder. 
     252 
     253The configuration listed in cfg.txt will look like 
     254 
     255NEMO_MYBGC OPA_SRC TOP_SRC 
     256 
     257and the related cpp_MYBGC.fcm content will be  
     258 
     259bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top 
     260 
     261For compilation it will be then used the following syntax 
     262 
     263makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH> 
     264 
     265The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with a user defined external one. 
     266 
     267In the case of more complex and articulated BGC model code infrastructure, like in the case of BFM (!http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf), the compilation requires some additional features. 
     268 
     269As before, let’s assume that we have a coupled configuration name NEMO_MYBGC, but in this case the BGC model repository has 3 different subfolders for biogeochemistry, named initialization, pelagic, and benthic, and a separate one named nemo_coupling that contains the modified MY_SRC routines. 
     270 
     271The latter folder containing the modified NEMO coupling interface will be still linked using the makenemo “-e” option. 
     272 
     273To include the BGC model subfolders in the compilation of NEMO code it will be necessary to extend the configuration cpp_NEMO_MYBGC.fcm file (see previous case), as in the following example  
     274 
     275bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top 
     276 
     277src::MYBGC::initialization           <MYBGCPATH>/initialization 
     278 
     279src::MYBGC::pelagic         <MYBGCPATH>/pelagic 
     280 
     281src::MYBGC::benthic             <MYBGCPATH>/benthic 
     282 
     283bld::pp::MYBGC      1 
     284 
     285bld::tool::fppflags::MYBGC %FPPFLAGS 
     286 
     287bld::tool::fppkeys  %bld::tool::fppkeys MYBGC_MACROS 
     288 
     289where MYBGC_MACROS is the space delimited list of macros used in MYBGC model for selecting/excluding specific parts of the code. 
     290 
     291The BGC model code will be preprocessed in the configuration BLD folder as for NEMO, but with an independent path, like NEMO_MYBGC/BLD/MYBGC/<subforlders>. 
     292 
     293The compilation will be performed as in the previous case with the following  
     294 
     295makenemo -n NEMO_MYBGC -m <arch_my_machine> -j 8 -e <MYBGCPATH> 
     296 
     297Note that, the additional lines of previous example, can be written into a separate file, e.g. named MYBGC.fcm, and then simply included in the cpp_NEMO_MYBGC.fcm as follow 
     298 
     299bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top key_my_trc 
     300 
     301inc <MYBGCPATH>/MYBGC.fcm 
     302 
     303This will enable a more portable compilation structure for all MYBGC related configurations. 
     304 
     305Finally, the coupling interface contained in nemo_coupling cannot be added using the FCM syntax, as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines. 
     306 
     307All modifications illustrated above, can be easily implemented using shell or python scripting to edit the NEMO configuration cpp.fcm file and to create the BGC model specific FCM compilation file with code paths.