Ignore:
Timestamp:
2019-10-18T18:46:26+02:00 (21 months ago)
Author:
nicolasmartin
Message:

Review README for reference confgiurations

File:
1 edited

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/cfgs/README.rst

    r11723 r11734  
    33************************ 
    44 
     5.. todo:: 
     6 
     7   Lack of illustrations for ref. cfgs, and more generally in the guide. 
     8 
    59NEMO is distributed with a set of reference configurations allowing both 
    610the user to set up his own first applications and 
    711the developer to test/validate his NEMO developments (using SETTE package). 
    812 
     13.. contents:: 
     14   :local: 
     15   :depth: 1 
     16 
    917.. attention:: 
    1018 
     
    2129=========================================================== 
    2230 
    23 A user who wants to compile the ORCA2_ICE_PISCES_ reference configuration using ``makenemo`` 
    24 should use the following, by selecting among available architecture file or providing a user defined one: 
     31To compile the ORCA2_ICE_PISCES_ reference configuration using ``makenemo``, 
     32one should use the following, by selecting among available architecture file or 
     33providing a user defined one: 
    2534 
    2635.. code-block:: console 
    2736 
    28    $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my-fortran.fcm' -j '4' 
     37   $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my_arch' -j '4' 
    2938 
    3039A new ``EXP00`` folder will be created within the selected reference configurations, 
    31 namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``, 
    32 where it will be necessary to uncompress the Input & Forcing Files listed in the above table. 
     40namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``. 
     41It will be necessary to uncompress the archives listed in the above table for 
     42the given reference configuration that includes input & forcing files. 
    3343 
    3444Then it will be possible to launch the execution of the model through a runscript 
     
    3848====================== 
    3949 
    40 All forcing files listed below in the table are available from |NEMO archives URL|_ 
    41  
    42 .. |NEMO archives URL| image:: https://www.zenodo.org/badge/DOI/10.5281/zenodo.1472245.svg 
    43 .. _NEMO archives URL: https://doi.org/10.5281/zenodo.1472245 
    44  
    45 ====================== ===== ===== ===== ======== ======= ================================================ 
    46  Configuration                     Component(s)                            Input & Forcing File(s) 
    47 ---------------------- ---------------------------------- ------------------------------------------------ 
    48  Name                   OCE   SI3   TOP   PISCES   AGRIF 
    49 ====================== ===== ===== ===== ======== ======= ================================================ 
    50  AGRIF_DEMO_             X     X                     X     AGRIF_DEMO_v4.0.tar, ORCA2_ICE_v4.0.tar 
    51  AMM12_                  X                                 AMM12_v4.0.tar 
    52  C1D_PAPA_               X                                 INPUTS_C1D_PAPA_v4.0.tar 
    53  GYRE_BFM_               X           X                     *none* 
    54  GYRE_PISCES_            X           X      X              *none* 
    55  ORCA2_ICE_PISCES_       X     X     X      X              ORCA2_ICE_v4.0.tar, INPUTS_PISCES_v4.0.tar 
    56  ORCA2_OFF_PISCES_                   X      X              ORCA2_OFF_v4.0.tar, INPUTS_PISCES_v4.0.tar 
    57  ORCA2_OFF_TRC_                      X                     ORCA2_OFF_v4.0.tar 
    58  ORCA2_SAS_ICE_                X                           ORCA2_ICE_v4.0.tar, INPUTS_SAS_v4.0.tar 
    59  SPITZ12_                X     X                           SPITZ12_v4.0.tar 
    60 ====================== ===== ===== ===== ======== ======= ================================================ 
     50All forcing files listed below in the table are available from |DOI data|_ 
     51 
     52=================== === === === === === ================================== 
     53 Configuration       Component(s)        Archives (input & forcing files) 
     54------------------- ------------------- ---------------------------------- 
     55 Name                O   S   T   P   A 
     56=================== === === === === === ================================== 
     57 AGRIF_DEMO_         X   X           X   AGRIF_DEMO_v4.0.tar, 
     58                                         ORCA2_ICE_v4.0.tar 
     59 AMM12_              X                   AMM12_v4.0.tar 
     60 C1D_PAPA_           X                   INPUTS_C1D_PAPA_v4.0.tar 
     61 GYRE_BFM_           X       X           *none* 
     62 GYRE_PISCES_        X       X   X       *none* 
     63 ORCA2_ICE_PISCES_   X   X   X   X       ORCA2_ICE_v4.0.tar, 
     64                                         INPUTS_PISCES_v4.0.tar 
     65 ORCA2_OFF_PISCES_           X   X       ORCA2_OFF_v4.0.tar, 
     66                                         INPUTS_PISCES_v4.0.tar 
     67 ORCA2_OFF_TRC_              X           ORCA2_OFF_v4.0.tar 
     68 ORCA2_SAS_ICE_          X               ORCA2_ICE_v4.0.tar, 
     69                                         INPUTS_SAS_v4.0.tar 
     70 SPITZ12_            X   X               SPITZ12_v4.0.tar 
     71=================== === === === === === ================================== 
     72 
     73.. admonition:: Legend for component combination 
     74 
     75   O for OCE, S for SI\ :sup:`3`, T for TOP, P for PISCES and A for AGRIF 
    6176 
    6277AGRIF_DEMO 
     
    7287particular interest to test sea ice coupling. 
    7388 
     89.. image:: _static/AGRIF_DEMO_no_cap.jpg 
     90   :scale: 66% 
     91   :align: center 
     92 
    7493The 1:1 grid can be used alone as a benchmark to check that 
    7594the model solution is not corrupted by grid exchanges. 
    7695Note that since grids interact only at the baroclinic time level, 
    7796numerically exact results can not be achieved in the 1:1 case. 
    78 Perfect reproducibility is obtained only by switching to a fully explicit setup instead of a split explicit free surface scheme. 
     97Perfect reproducibility is obtained only by switching to a fully explicit setup instead of 
     98a split explicit free surface scheme. 
    7999 
    80100AMM12 
     
    84104a regional configuration covering the Northwest European Shelf domain on 
    85105a regular horizontal grid of ~12 km of resolution (see :cite:`ODEA2012`). 
     106 
     107.. image:: _static/AMM_domain.png 
     108   :align: center 
    86109 
    87110This configuration allows to tests several features of NEMO specifically addressed to the shelf seas. 
     
    99122-------- 
    100123 
    101 ``C1D_PAPA`` is a 1D configuration for the `PAPA station <http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml>`_ located in the northern-eastern Pacific Ocean at 50.1°N, 144.9°W. 
    102 See `Reffray et al. (2015) <http://www.geosci-model-dev.net/8/69/2015>`_ for the description of its physical and numerical turbulent-mixing behaviour. 
    103  
    104 The water column setup, called NEMO1D, is activated with the inclusion of the CPP key ``key_c1d`` and 
    105 has a horizontal domain of 3x3 grid points. 
    106  
    107 This reference configuration uses 75 vertical levels grid (1m at the surface), GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae. 
     124.. figure:: _static/Papa2015.jpg 
     125   :height: 225px 
     126   :align:  left 
     127 
     128``C1D_PAPA`` is a 1D configuration for the `PAPA station`_ located in 
     129the northern-eastern Pacific Ocean at 50.1°N, 144.9°W. 
     130See :gmd:`Reffray et al. (2015) <8/69/2015>` for the description of 
     131its physical and numerical turbulent-mixing behaviour. 
     132 
     133| The water column setup, called NEMO1D, is activated with 
     134  the inclusion of the CPP key ``key_c1d`` and 
     135  has a horizontal domain of 3x3 grid points. 
     136| This reference configuration uses 75 vertical levels grid (1m at the surface), 
     137  GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae. 
     138 
    108139Data provided with ``INPUTS_C1D_PAPA_v4.0.tar`` file account for: 
    109140 
    110 - ``forcing_PAPASTATION_1h_y201[0-1].nc`` : ECMWF operational analysis atmospheric forcing rescaled to 1h (with long and short waves flux correction) for years 2010 and 2011 
    111 - ``init_PAPASTATION_m06d15.nc`` : Initial Conditions from observed data and Levitus 2009 climatology 
    112 - ``chlorophyll_PAPASTATION.nc`` : surface chlorophyll file from Seawifs data 
     141- :file:`forcing_PAPASTATION_1h_y201[0-1].nc`: 
     142  ECMWF operational analysis atmospheric forcing rescaled to 1h 
     143  (with long and short waves flux correction) for years 2010 and 2011 
     144- :file:`init_PAPASTATION_m06d15.nc`: Initial Conditions from 
     145  observed data and Levitus 2009 climatology 
     146- :file:`chlorophyll_PAPASTATION.nc`: surface chlorophyll file from Seawifs data 
    113147 
    114148GYRE_BFM 
    115149-------- 
    116150 
    117 ``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_, but NEMO is coupled with the `BFM <http://www.bfm-community.eu/>`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``. 
     151``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_, 
     152but NEMO is coupled with the `BFM`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``. 
    118153 
    119154GYRE_PISCES 
     
    125160Analytical forcing for heat, freshwater and wind-stress fields are applied. 
    126161 
    127 This configuration acts also as demonstrator of the **user defined setup** (``ln_read_cfg = .false.``) and 
    128 grid setting are handled through the ``&namusr_def`` controls in ``namelist_cfg``: 
     162This configuration acts also as demonstrator of the **user defined setup** 
     163(``ln_read_cfg = .false.``) and grid setting are handled through 
     164the ``&namusr_def`` controls in :file:`namelist_cfg`: 
    129165 
    130166.. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_cfg 
    131167   :language: fortran 
    132    :lines: 34-42 
     168   :lines:    35-41 
    133169 
    134170Note that, the default grid size is 30x20 grid points (with ``nn_GYRE = 1``) and 
    135171vertical levels are set by ``jpkglo``. 
    136 The specific code changes can be inspected in ``./src/OCE/USR``. 
    137  
    138 **Running GYRE as a benchmark** : 
    139 this simple configuration can be used as a benchmark since it is easy to increase resolution, 
    140 with the drawback of getting results that have a very limited physical meaning. 
    141  
    142 GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE`` (integer multiplier scaling factor), as described in the following table: 
    143  
    144 =========== ========= ========== ============ =================== 
    145 ``nn_GYRE``  *jpiglo*  *jpjglo*   ``jpkglo``   **Equivalent to** 
    146 =========== ========= ========== ============ =================== 
    147  1           30        20         31           GYRE 1° 
    148  25          750       500        101          ORCA 1/2° 
    149  50          1500      1000       101          ORCA 1/4° 
    150  150         4500      3000       101          ORCA 1/12° 
    151  200         6000      4000       101          ORCA 1/16° 
    152 =========== ========= ========== ============ =================== 
    153  
    154 Note that, it is necessary to set ``ln_bench = .true.`` in ``namusr_def`` to 
    155 avoid problems in the physics computation and that 
    156 the model timestep should be adequately rescaled. 
    157  
    158 For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid, 
    159 the timestep ``rn_rdt = 1200`` should be set to 1200 seconds 
    160  
    161 Differently from previous versions of NEMO, 
    162 the code uses by default the time-splitting scheme and 
    163 internally computes the number of sub-steps. 
     172The specific code changes can be inspected in :file:`./src/OCE/USR`. 
     173 
     174.. rubric:: Running GYRE as a benchmark 
     175 
     176| This simple configuration can be used as a benchmark since it is easy to increase resolution, 
     177  with the drawback of getting results that have a very limited physical meaning. 
     178| GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE`` 
     179  (integer multiplier scaling factor), as described in the following table: 
     180 
     181=========== ============ ============ ============ =============== 
     182``nn_GYRE``  ``jpiglo``   ``jpjglo``   ``jpkglo``   Equivalent to 
     183=========== ============ ============ ============ =============== 
     184 1           30           20           31           GYRE 1° 
     185 25          750          500          101          ORCA 1/2° 
     186 50          1500         1000         101          ORCA 1/4° 
     187 150         4500         3000         101          ORCA 1/12° 
     188 200         6000         4000         101          ORCA 1/16° 
     189=========== ============ ============ ============ =============== 
     190 
     191| Note that, it is necessary to set ``ln_bench = .true.`` in ``&namusr_def`` to 
     192  avoid problems in the physics computation and that 
     193  the model timestep should be adequately rescaled. 
     194| For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid, 
     195  the timestep ``rn_rdt`` should be set to 1200 seconds 
     196  Differently from previous versions of NEMO, the code uses by default the time-splitting scheme and 
     197  internally computes the number of sub-steps. 
    164198 
    165199ORCA2_ICE_PISCES 
     
    174208the ratio of anisotropy is nearly one everywhere 
    175209 
    176 this configuration uses the three components 
    177  
    178 - |NEMO-OCE|, the ocean dynamical core 
    179 - |NEMO-ICE|, the thermodynamic-dynamic sea ice model. 
    180 - |NEMO-MBG|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015` 
     210This configuration uses the three components 
     211 
     212- |OCE|, the ocean dynamical core 
     213- |ICE|, the thermodynamic-dynamic sea ice model. 
     214- |MBG|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015` 
    181215 
    182216All components share the same grid. 
    183  
    184217The model is forced with CORE-II normal year atmospheric forcing and 
    185218it uses the NCAR bulk formulae. 
    186219 
    187 In this ``ORCA2_ICE_PISCES`` configuration, 
    188 AGRIF nesting can be activated that includes a nested grid in the Agulhas region. 
    189  
    190 To set up this configuration, after extracting NEMO: 
    191  
    192 Build your AGRIF configuration directory from ``ORCA2_ICE_PISCES``, 
    193 with the ``key_agrif`` CPP key activated: 
    194  
    195 .. code-block:: console 
    196  
    197         $ ./makenemo -r 'ORCA2_ICE_PISCES' -n 'AGRIF' add_key 'key_agrif' 
    198  
    199 By using the input files and namelists for ``ORCA2_ICE_PISCES``, 
    200 the AGRIF test configuration is ready to run. 
    201  
    202 **Ocean Physics** 
    203  
    204 - *horizontal diffusion on momentum*: the eddy viscosity coefficient depends on the geographical position. It is taken as 40000 m^2/s, reduced in the equator regions (2000 m^2/s) excepted near the western boundaries. 
    205 - *isopycnal diffusion on tracers*: the diffusion acts along the isopycnal surfaces (neutral surface) with an eddy diffusivity coefficient of 2000 m^2/s. 
    206 - *Eddy induced velocity parametrization* with a coefficient that depends on the growth rate of baroclinic instabilities (it usually varies from 15 m^2/s to 3000 m^2/s). 
    207 - *lateral boundary conditions* : zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries. 
    208 - *bottom boundary condition* : zero fluxes of heat and salt are applied through the ocean bottom. 
    209   The Beckmann [19XX] simple bottom boundary layer parameterization is applied along continental slopes. 
    210   A linear friction is applied on momentum. 
    211 - *convection*: the vertical eddy viscosity and diffusivity coefficients are increased to 1 m^2/s in case of static instability. 
    212 - *time step* is 5760sec (1h36') so that there is 15 time steps in one day. 
     220.. rubric:: Ocean Physics 
     221 
     222:horizontal diffusion on momentum: 
     223   the eddy viscosity coefficient depends on the geographical position. 
     224   It is taken as 40000 m\ :sup:`2`/s, reduced in the equator regions (2000 m\ :sup:`2`/s) 
     225   excepted near the western boundaries. 
     226:isopycnal diffusion on tracers: 
     227   the diffusion acts along the isopycnal surfaces (neutral surface) with 
     228   an eddy diffusivity coefficient of 2000 m\ :sup:`2`/s. 
     229:Eddy induced velocity parametrization: 
     230   With a coefficient that depends on the growth rate of baroclinic instabilities 
     231   (it usually varies from 15 m\ :sup:`2`/s to 3000 m\ :sup:`2`/s). 
     232:lateral boundary conditions: 
     233   Zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries. 
     234:bottom boundary condition: 
     235   Zero fluxes of heat and salt are applied through the ocean bottom. 
     236   The Beckmann [19XX] simple bottom boundary layer parameterization is applied along 
     237   continental slopes. 
     238   A linear friction is applied on momentum. 
     239:convection: 
     240   The vertical eddy viscosity and diffusivity coefficients are increased to 1 m\ :sup:`2`/s in 
     241   case of static instability. 
     242:time step: is 5760sec (1h36') so that there is 15 time steps in one day. 
    213243 
    214244ORCA2_OFF_PISCES 
     
    218248but only PISCES model is an active component of TOP. 
    219249 
    220  
    221250ORCA2_OFF_TRC 
    222251------------- 
    223252 
    224 ``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration 
    225 (see ORCA2_ICE_PISCES_ for general description) along with the tracer passive transport module (TOP), but dynamical fields are pre-calculated and read with specific time frequency. 
    226  
    227 This enables for an offline coupling of TOP components, 
    228 here specifically inorganic carbon compounds (cfc11, cfc12, sf6, c14) and water age module (age). 
    229 See ``namelist_top_cfg`` to inspect the selection of each component with the dedicated logical keys. 
     253| ``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration 
     254  (see ORCA2_ICE_PISCES_ for general description) along with 
     255  the tracer passive transport module (TOP), 
     256  but dynamical fields are pre-calculated and read with specific time frequency. 
     257| This enables for an offline coupling of TOP components, 
     258  here specifically inorganic carbon compounds (CFC11, CFC12, SF6, C14) and water age module (age). 
     259  See :file:`namelist_top_cfg` to inspect the selection of 
     260  each component with the dedicated logical keys. 
    230261 
    231262Pre-calculated dynamical fields are provided to NEMO using 
    232 the namelist ``&namdta_dyn``  in ``namelist_cfg``, 
     263the namelist ``&namdta_dyn``  in :file:`namelist_cfg`, 
    233264in this case with a 5 days frequency (120 hours): 
    234265 
    235 .. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_ref 
     266.. literalinclude:: ../../namelists/namdta_dyn 
    236267   :language: fortran 
    237    :lines: 935-960 
    238  
    239 Input dynamical fields for this configuration (``ORCA2_OFF_v4.0.tar``) comes from 
     268 
     269Input dynamical fields for this configuration (:file:`ORCA2_OFF_v4.0.tar`) comes from 
    240270a 2000 years long climatological simulation of ORCA2_ICE using ERA40 atmospheric forcing. 
    241271 
    242 Note that, this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that 
    243 model mesh is not varying in time and 
    244 it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that 
    245 requires the provision of bbl coefficients through ``sn_ubl`` and ``sn_vbl`` fields. 
    246  
    247 It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or 
    248 a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.`` 
    249 (and adaptation of ``./src/TOP/MY_TRC`` routines). 
     272| Note that, 
     273  this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that 
     274  model mesh is not varying in time and 
     275  it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that 
     276  requires the provision of BBL coefficients through ``sn_ubl`` and ``sn_vbl`` fields. 
     277| It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or 
     278  a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.`` 
     279  (and adaptation of ``./src/TOP/MY_TRC`` routines). 
    250280 
    251281In addition, the offline module (OFF) allows for the provision of further fields: 
     
    254284   by including an input datastream similarly to the following: 
    255285 
    256 .. code-block:: fortran 
    257  
    258    sn_rnf  = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', '' 
    259  
    260 2. **VVL dynamical fields**, 
    261    in the case input data were produced by a dyamical core using variable volume (``ln_linssh = .false.``) 
    262    it necessary to provide also diverce and E-P at before timestep by 
     286   .. code-block:: fortran 
     287 
     288      sn_rnf  = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', '' 
     289 
     2902. **VVL dynamical fields**, in the case input data were produced by a dyamical core using 
     291   variable volume (``ln_linssh = .false.``) 
     292   it is necessary to provide also diverce and E-P at before timestep by 
    263293   including input datastreams similarly to the following 
    264294 
    265 .. code-block:: fortran 
    266  
    267    sn_div  = 'dyna_grid_T', 120, 'e3t'      , .true., .true., 'yearly', '', '', '' 
    268    sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', '' 
    269  
     295   .. code-block:: fortran 
     296 
     297      sn_div  = 'dyna_grid_T', 120, 'e3t'      , .true., .true., 'yearly', '', '', '' 
     298      sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', '' 
    270299 
    271300More details can be found by inspecting the offline data manager in 
    272 the routine ``./src/OFF/dtadyn.F90``. 
     301the routine :file:`./src/OFF/dtadyn.F90`. 
    273302 
    274303ORCA2_SAS_ICE 
    275304------------- 
    276305 
    277 ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and 
    278 it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description). 
    279  
    280 The standalone surface module allows surface elements such as sea-ice, iceberg drift, and 
    281 surface fluxes to be run using prescribed model state fields. 
    282 It can profitably be used to compare different bulk formulae or 
    283 adjust the parameters of a given bulk formula. 
    284  
    285 More informations about SAS can be found in NEMO manual. 
     306| ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and 
     307  it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description). 
     308| The standalone surface module allows surface elements such as sea-ice, iceberg drift, and 
     309  surface fluxes to be run using prescribed model state fields. 
     310  It can profitably be used to compare different bulk formulae or 
     311  adjust the parameters of a given bulk formula. 
     312 
     313More informations about SAS can be found in :doc:`NEMO manual <cite>`. 
    286314 
    287315SPITZ12 
     
    290318``SPITZ12`` is a regional configuration around the Svalbard archipelago 
    291319at 1/12° of horizontal resolution and 75 vertical levels. 
    292 See `Rousset et al. (2015) <https://www.geosci-model-dev.net/8/2991/2015/>`_ for more details. 
     320See :gmd:`Rousset et al. (2015) <8/2991/2015>` for more details. 
    293321 
    294322This configuration references to year 2002, 
Note: See TracChangeset for help on using the changeset viewer.