Ignore:
Timestamp:
2018-10-09T18:46:38+02:00 (2 years ago)
Author:
nicolasmartin
Message:

Preliminary implementation of a NEMO Quick Start Guide via RST files and Sphinx installation

Location:
NEMO/trunk/doc/rst/source
Files:
1 added
1 moved

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/doc/rst/source/interfacing_options.rst

    r10182 r10186  
     1=================== 
     2Interfacing options 
     3=================== 
     4 
     5.. contents:: 
     6   :local: 
     7   :depth: 1 
     8            
     9Embedded zooms with AGRIF 
     10========================= 
     11 
     12.. contents:: 
     13   :local: 
     14 
     15-------- 
     16Overview 
     17-------- 
     18 
     19AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over 
     20rectangular regions in NEMO. 
     21Refinement factors can be odd or even (usually lower than 5 to maintain stability). 
     22Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and 
     23the child grid provides volume averages of prognostic variables once a given number of time step is completed. 
     24These pages provide guidelines how to use AGRIF in NEMO. 
     25For a more technical description of the library itself, please refer to http://agrif.imag.fr. 
     26 
     27----------- 
     28Compilation 
     29----------- 
     30 
     31Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:  
     32 
     33.. code-block:: sh 
     34 
     35   ./makenemo add_key 'key_agrif' 
     36 
     37Although this is transparent to users, the way the code is processed during compilation is different from 
     38the standard case: 
     39a preprocessing stage (the so called "conv" program) translates the actual code so that 
     40saved arrays may be switched in memory space from one domain to an other. 
     41 
     42-------------------------------- 
     43Definition of the grid hierarchy 
     44-------------------------------- 
     45 
     46An additional text file ``AGRIF_FixedGrids.in`` is required at run time. 
     47This is where the grid hierarchy is defined. 
     48An example of such a file, here taken from the ``ICEDYN`` test case, is given below:: 
     49 
     50   1 
     51   34 63 34 63 3 3 3 
     52   0 
     53 
     54The first line indicates the number of zooms (1). 
     55The second line contains the starting and ending indices in both directions on the root grid 
     56(imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3). 
     57The last line is the number of child grid nested in the refined region (0). 
     58A more complex example with telescoping grids can be found below and 
     59in the ``AGRIF_DEMO`` reference configuration directory. 
     60 
     61[Add some plots here with grid staggering and positioning ?] 
     62 
     63When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and 
     64depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and 
     65nbghostcells=3. 
     66The grid refinement is 3 and nxfin is the number of child grid points in i-direction.   
     67 
     68.. image:: _static/agrif_grid_position.jpg 
     69 
     70Note that rectangular regions must be defined so that they are connected to a single parent grid. 
     71Hence, defining overlapping grids with the same refinement ratio will not work properly, 
     72boundary data exchange and update being only performed between root and child grids. 
     73Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either. 
     74Defining for instance a circumpolar zoom in a global model is therefore not possible.  
     75 
     76------------- 
     77Preprocessing 
     78------------- 
     79 
     80Knowing the refinement factors and area, a ``NESTING`` pre-processing tool may help to create needed input files 
     81(mesh file, restart, climatological and forcing files). 
     82The key is to ensure volume matching near the child grid interface, 
     83a step done by invoking the ``Agrif_create_bathy.exe`` program. 
     84You may use the namelists provided in the ``NESTING`` directory as a guide. 
     85These correspond to the namelists used to create ``AGRIF_DEMO`` inputs. 
     86 
     87---------------- 
     88Namelist options 
     89---------------- 
     90 
     91Each child grid expects to read its own namelist so that different numerical choices can be made 
     92(these should be stored in the form ``1_namelist_cfg``, ``2_namelist_cfg``, etc... according to their rank in 
     93the grid hierarchy). 
     94Consistent time steps and number of steps with the chosen time refinement have to be provided. 
     95Specific to AGRIF is the following block: 
     96 
     97.. code-block:: fortran 
     98 
     99   !----------------------------------------------------------------------- 
     100   &namagrif      !  AGRIF zoom                                            ("key_agrif") 
     101   !----------------------------------------------------------------------- 
     102      ln_spc_dyn    = .true.  !  use 0 as special value for dynamics 
     103      rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s] 
     104      rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s] 
     105      ln_chk_bathy  = .false. !  =T  check the parent bathymetry 
     106   /              
     107 
     108where sponge layer coefficients have to be chosen according to the child grid mesh size. 
     109The sponge area is hard coded in NEMO and applies on the following grid points: 
     1102 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area)  
     111 
     112----------    
     113References 
     114---------- 
     115 
     116`Debreu, L., P. Marchesiello, P. Penven and G. Cambon, 2012: Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation. Ocean Modelling, 49-50, 1-21. <http://doi.org/10.1016/j.ocemod.2012.03.003>`_ 
     117 
     118`Penven, P., L. Debreu, P. Marchesiello and J. C. Mc Williams, 2006: Evaluation and application of the ROMS 1-way embedding procedure to the central california upwelling system. Ocean Modelling, 12, 157-187. <http://doi.org/10.1016/j.ocemod.2005.05.002>`_ 
     119 
     120`Spall, M. A. and W. R. Holland, 1991: A Nested Primitive Equation Model for Oceanic Applications. J. Phys. Ocean., 21, 205-220. <https://doi.org/10.1175/1520-0485(1991)021\<0205:ANPEMF\>2.0.CO;2>`_ 
     121 
     122---- 
     123 
     124On line biogeochemistry coarsening 
     125================================== 
     126 
     127.. contents:: 
     128   :local: 
     129 
     130.. role:: underline  
     131   :class: underline 
     132 
     133------------ 
     134Presentation 
     135------------ 
     136 
     137A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed. 
     138This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution, 
     139to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics. 
     140 
     141A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented. 
     142 
     143----------------------------------------------------- 
     144What is available and working for now in this version 
     145----------------------------------------------------- 
     146 
     147[To be completed] 
     148 
     149---------------------------------------------- 
     150Description of the successful validation tests 
     151---------------------------------------------- 
     152 
     153[To be completed] 
     154 
     155------------------------------------------------------------------ 
     156What is not working yet with on line coarsening of biogeochemistry 
     157------------------------------------------------------------------ 
     158 
     159[To be completed] 
     160 
     161''should include precise explanation on MPI decomposition problems too'' 
     162 
     163--------------------------------------------- 
     164How to set up and use on line biogeochemistry 
     165--------------------------------------------- 
     166 
     167:underline:`How to activate coarsening?` 
     168 
     169To activate the coarsening, ``key_crs`` should be added to list of CPP keys. 
     170This key will only activate the coarsening of dynamics. 
     171 
     172Some parameters are available in the namelist_cfg: 
     173 
     174.. code-block:: fortran 
     175 
     176                  !   passive tracer coarsened online simulations 
     177   !----------------------------------------------------------------------- 
     178      nn_factx    = 3         !  Reduction factor of x-direction 
     179      nn_facty    = 3         !  Reduction factor of y-direction 
     180      nn_msh_crs  = 0         !  create (=1) a mesh file or not (=0) 
     181      nn_crs_kz   = 3         ! 0, volume-weighted MEAN of KZ 
     182                              ! 1, MAX of KZ 
     183                              ! 2, MIN of KZ 
     184                              ! 3, 10^(MEAN(LOG(KZ))  
     185                              ! 4, MEDIANE of KZ  
     186      ln_crs_wn   = .false.   ! wn coarsened (T) or computed using horizontal divergence ( F ) 
     187                              !                           ! 
     188      ln_crs_top = .true.     !coarsening online for the bio 
     189   / 
     190 
     191- Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for 
     192  the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...). 
     193- ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask. 
     194- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient.  
     195- ``ln_crs_wn`` 
     196 
     197  - when ``key_vvl`` is activated, this logical has no effect; 
     198    the coarsened vertical velocities are computed using horizontal divergence. 
     199  - when ``key_vvl`` is not activated, 
     200 
     201    - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``)  
     202    - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``) 
     203- ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space; 
     204  so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``. 
     205 
     206:underline:`Choice of operator to coarsene KZ` 
     207 
     208A sensiblity test has been done with an Age tracer to compare the different operators. 
     209The 3 and 4 options seems to provide the best results. 
     210 
     211Some results can be found [xxx here] 
     212 
     213:underline:`Example of xml files to output coarsened variables with XIOS` 
     214 
     215In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and 
     216some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.   
     217To write variables on the coarsened grid, and in particular the passive tracers, 
     218a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and 
     219the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ]. 
     220 
     221:underline:`Passive tracers tracers initial conditions` 
     222 
     223When initial conditions are provided in NetCDF files, the field might be: 
     224 
     225- on the coarsened grid 
     226- or they can be on another grid and 
     227  interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_. 
     228  Example of namelist for PISCES : 
     229   
     230   .. code-block:: fortran 
     231 
     232      !----------------------------------------------------------------------- 
     233      &namtrc_dta      !    Initialisation from data input file 
     234      !----------------------------------------------------------------------- 
     235      ! 
     236         sn_trcdta(1)  = 'DIC_REG1'        ,        -12        ,  'DIC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     237         sn_trcdta(2)  = 'ALK_REG1'        ,        -12        ,  'ALK'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     238         sn_trcdta(3)  = 'O2_REG1'         ,        -1         ,  'O2'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     239         sn_trcdta(5)  = 'PO4_REG1'        ,        -1         ,  'PO4'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     240         sn_trcdta(7)  = 'Si_REG1'         ,        -1         ,  'Si'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     241         sn_trcdta(10) = 'DOC_REG1'        ,        -12        ,  'DOC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     242         sn_trcdta(14) = 'Fe_REG1'         ,        -12        ,  'Fe'      ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     243         sn_trcdta(23) = 'NO3_REG1'        ,        -1         ,  'NO3'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
     244         rn_trfac(1)   =   1.0e-06  !  multiplicative factor 
     245         rn_trfac(2)   =   1.0e-06  !  -      -      -     - 
     246         rn_trfac(3)   =  44.6e-06  !  -      -      -     - 
     247         rn_trfac(5)   = 122.0e-06  !  -      -      -     - 
     248         rn_trfac(7)   =   1.0e-06  !  -      -      -     - 
     249         rn_trfac(10)  =   1.0e-06  !  -      -      -     - 
     250         rn_trfac(14)  =   1.0e-06  !  -      -      -     - 
     251         rn_trfac(23)  =   7.6e-06  !  -      -      -     - 
     252       
     253         cn_dir        =  './'      !  root directory for the location of the data files 
     254 
     255:underline:`PISCES forcing files` 
     256 
     257They might be on the coarsened grid. 
     258 
     259:underline:`Perspectives` 
     260 
     261For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and 
     262future releases. 
     263Those will be discussed in Autumn 2018 
     264 
     265---- 
     266 
     267Coupling with other models (OASIS, SAS, ...) 
     268============================================ 
     269 
     270NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface 
     271(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_). 
     272It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), 
     273as well as to WRF (Weather Research and Forecasting Model), and to implement the coupling of 
     274two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand 
     275(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_). 
     276 
     277To enable the OASIS interface the required compilation key is ``key_oasis3``. 
     278The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``. 
     279 
     280---- 
     281 
     282With data assimilation 
     283====================== 
     284 
     285.. contents:: 
     286   :local: 
     287 
     288The assimilation interface to NEMO is split into three modules. 
     289- OBS for the observation operator 
     290- ASM for the application of increments and model bias correction (based on the assimilation increments). 
     291- TAM the tangent linear and adjoint model. 
     292 
     293Please see the `NEMO reference manual`_ for more details including information about the input file formats and 
     294the namelist settings. 
     295 
     296-------------------------------------- 
     297Observation and model comparison (OBS) 
     298-------------------------------------- 
     299 
     300The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity, 
     301sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and 
     302calculates an interpolated model equivalent value at the observation location and nearest model timestep. 
     303The resulting data are saved in a feedback file (or files). 
     304The code was originally developed for use with the NEMOVAR data assimilation code, but 
     305can be used for validation or verification of model or any other data assimilation system. 
     306This is all controlled by the namelist. 
     307To build with the OBS code active ``key_diaobs`` must be set.  
     308 
     309More details in the `NEMO reference manual`_ chapter 12. 
     310 
     311Standalone observation operator (SAO) 
     312------------------------------------- 
     313 
     314The OBS code can also be run after a model run using saved NEMO model data. 
     315This is accomplished using the standalone observation operator (SAO) 
     316(previously known the offline observation operator). 
     317 
     318To build the SAO use makenemo. 
     319This means compiling NEMO once (in the normal way) for the chosen configuration. 
     320Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file. 
     321Then recompile with the replacement main program in ``./src/SAO``. 
     322This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and 
     323observations and runs the OBS code. 
     324See section 12.4 of the `NEMO reference manual`_. 
     325 
     326----------------------------------- 
     327Apply assimilation increments (ASM) 
     328----------------------------------- 
     329 
     330The ASM code adds the functionality to apply increments to the model variables: 
     331temperature, salinity, sea surface height, velocity and sea ice concentration. 
     332These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 
     333The code can also output model background fields which are used as an input to data assimilation code. 
     334This is all controlled by the namelist nam_asminc. 
     335To build the ASM code ``key asminc`` must be set. 
     336 
     337More details in the `NEMO reference manual`_ chapter 13. 
     338 
     339-------------------------------- 
     340Tangent linear and adjoint (TAM) 
     341-------------------------------- 
     342 
     343This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation. 
     344 
     345---- 
     346 
     347Inputs-Outputs (using XIOS) 
     348=========================== 
     349 
     350.. contents:: 
     351   :local: 
     352 
     353| Output of diagnostics in NEMO is usually done using XIOS. 
     354  This is an efficient way of writing diagnostics because the time averaging, file writing and even 
     355  some simple arithmetic or regridding is carried out in parallel to the NEMO model run. 
     356| This page gives a basic introduction to using XIOS with NEMO. 
     357  Much more information is available from the XIOS homepage above and from the `NEMO reference manual`_. 
     358 
     359Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. 
     360The default version of XIOS is the 2.0 release.  
     361 
     362------------------------------ 
     363Extracting and installing XIOS 
     364------------------------------ 
     365 
     3661. Install the NetCDF4 library. 
     367   If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO. 
     3682. Download the version of XIOS that you wish to use. 
     369   The recommended version is now XIOS 2.0: 
     370    
     371   .. code-block:: console 
     372 
     373      $ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0 
     374 
     375   and follow the instructions in `XIOS documentation`_ to compile it. 
     376   If you find problems at this stage, support can be found by subscribing to the `XIOS users mailing list`_ and 
     377   sending a mail message to it.  
     378 
     379--------- 
     380Namelists 
     381--------- 
     382 
     383XIOS is controlled using xml input files that should be copied to your model run directory before 
     384running the model. 
     385The exact setup differs slightly between 1.0 and 2.0 releases. 
     386 
     387An ``iodef.xml`` file is still required in the run directory. 
     388For XIOS 2.0 the ``field_def.xml`` file has been further split into ``field_def-oce.xml`` (for physics), 
     389``field_def-ice.xml`` (for ice) and ``field_def-bgc.xml`` (for biogeochemistry). 
     390Also the definition of the output files has been moved from the ``iodef.xml`` file into 
     391separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file. 
     392Note that the ``domain_def.xml`` file is also different for XIOS 2.0. 
     393 
     394----- 
     395Modes 
     396----- 
     397 
     398Detached Mode 
     399------------- 
     400 
     401In detached mode the XIOS executable is executed on separate cores from the NEMO model. 
     402This is the recommended method for using XIOS for realistic model runs. 
     403To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file: 
     404 
     405.. code-block:: xml 
     406 
     407   <variable id="using_server" type="boolean">true</variable> 
     408 
     409Make sure there is a copy (or link to) your XIOS executable in the working directory and 
     410in your job submission script allocate processors to XIOS. 
     411 
     412Attached Mode 
     413------------- 
     414 
     415In attached mode XIOS runs on each of the cores used by NEMO. 
     416This method is less efficient than the detached mode but can be more convenient for testing or 
     417with small configurations. 
     418To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file 
     419 
     420.. code-block:: xml 
     421 
     422   <variable id="using_server" type="boolean">false</variable> 
     423 
     424and don't allocate any cores to XIOS. 
     425Note that due to the different domain decompositions between XIOS and NEMO if 
     426the total number of cores is larger than the number of grid points in the j direction then the model run will fail. 
     427 
     428------------------------------ 
     429Adding new diagnostics to NEMO 
     430------------------------------ 
     431 
     432If you want to add a NEMO diagnostic to the NEMO code you will need to do the following: 
     433 
     4341. Add any necessary code to calculate you new diagnostic in NEMO 
     4352. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for 
     436   your new diagnostics and variable is the fortran variable containing the data. 
     437   This should be called at every model timestep regardless of how often you want to output the field. 
     438   No time averaging should be done in the model code.  
     4393. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to 
     440   determine if it is requested in the current model run. For example, 
     441    
     442   .. code-block:: fortran 
     443 
     444      IF iom_use('field_id') THEN 
     445         !Some expensive computation 
     446         !... 
     447         !... 
     448         iom_put('field_id', variable) 
     449      ENDIF 
     450 
     4514. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file 
     4525. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file. 
     453 
     454.. _NEMO reference manual:   http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO 
     455.. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation 
     456.. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users 
Note: See TracChangeset for help on using the changeset viewer.