2018-10-09T18:46:38+02:00 (2 years ago)

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

1 added
1 moved


  • NEMO/trunk/doc/rst/source/interfacing_options.rst

    r10182 r10186  
     2Interfacing options 
     5.. contents:: 
     6   :local: 
     7   :depth: 1 
     9Embedded zooms with AGRIF 
     12.. contents:: 
     13   :local: 
     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. 
     31Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:  
     33.. code-block:: sh 
     35   ./makenemo add_key 'key_agrif' 
     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. 
     43Definition of the grid hierarchy 
     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:: 
     50   1 
     51   34 63 34 63 3 3 3 
     52   0 
     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. 
     61[Add some plots here with grid staggering and positioning ?] 
     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 
     66The grid refinement is 3 and nxfin is the number of child grid points in i-direction.   
     68.. image:: _static/agrif_grid_position.jpg 
     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.  
     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. 
     88Namelist options 
     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: 
     97.. code-block:: fortran 
     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   /              
     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)  
     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>`_ 
     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>`_ 
     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>`_ 
     124On line biogeochemistry coarsening 
     127.. contents:: 
     128   :local: 
     130.. role:: underline  
     131   :class: underline 
     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. 
     141A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented. 
     144What is available and working for now in this version 
     147[To be completed] 
     150Description of the successful validation tests 
     153[To be completed] 
     156What is not working yet with on line coarsening of biogeochemistry 
     159[To be completed] 
     161''should include precise explanation on MPI decomposition problems too'' 
     164How to set up and use on line biogeochemistry 
     167:underline:`How to activate coarsening?` 
     169To activate the coarsening, ``key_crs`` should be added to list of CPP keys. 
     170This key will only activate the coarsening of dynamics. 
     172Some parameters are available in the namelist_cfg: 
     174.. code-block:: fortran 
     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   / 
     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`` 
     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, 
     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``. 
     206:underline:`Choice of operator to coarsene KZ` 
     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. 
     211Some results can be found [xxx here] 
     213:underline:`Example of xml files to output coarsened variables with XIOS` 
     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 ]. 
     221:underline:`Passive tracers tracers initial conditions` 
     223When initial conditions are provided in NetCDF files, the field might be: 
     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 : 
     230   .. code-block:: fortran 
     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  !  -      -      -     - 
     253         cn_dir        =  './'      !  root directory for the location of the data files 
     255:underline:`PISCES forcing files` 
     257They might be on the coarsened grid. 
     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 
     267Coupling with other models (OASIS, SAS, ...) 
     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>`_). 
     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``. 
     282With data assimilation 
     285.. contents:: 
     286   :local: 
     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. 
     293Please see the `NEMO reference manual`_ for more details including information about the input file formats and 
     294the namelist settings. 
     297Observation and model comparison (OBS) 
     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.  
     309More details in the `NEMO reference manual`_ chapter 12. 
     311Standalone observation operator (SAO) 
     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). 
     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`_. 
     327Apply assimilation increments (ASM) 
     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. 
     337More details in the `NEMO reference manual`_ chapter 13. 
     340Tangent linear and adjoint (TAM) 
     343This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation. 
     347Inputs-Outputs (using XIOS) 
     350.. contents:: 
     351   :local: 
     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`_. 
     359Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. 
     360The default version of XIOS is the 2.0 release.  
     363Extracting and installing XIOS 
     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: 
     371   .. code-block:: console 
     373      $ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0 
     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.  
     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. 
     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. 
     398Detached Mode 
     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: 
     405.. code-block:: xml 
     407   <variable id="using_server" type="boolean">true</variable> 
     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. 
     412Attached Mode 
     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 
     420.. code-block:: xml 
     422   <variable id="using_server" type="boolean">false</variable> 
     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. 
     429Adding new diagnostics to NEMO 
     432If you want to add a NEMO diagnostic to the NEMO code you will need to do the following: 
     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, 
     442   .. code-block:: fortran 
     444      IF iom_use('field_id') THEN 
     445         !Some expensive computation 
     446         !... 
     447         !... 
     448         iom_put('field_id', variable) 
     449      ENDIF 
     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. 
     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.