Changeset 11824


Ignore:
Timestamp:
2019-10-29T14:13:45+01:00 (11 months ago)
Author:
acc
Message:

ranch 2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps. Updates to top level rst files to align with trunk changes between 10721 and 11740. This commit brings this branch up-to-date with the trunk at revision 11740 with the exception of the doc directory which has not been touched on this branch.

Location:
NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/CONTRIBUTING.rst

    r10594 r11824  
    33************ 
    44 
     5.. todo:: 
     6 
     7 
     8 
    59.. contents:: 
    6    :local: 
     10   :local: 
    711 
    812Sending feedbacks 
     
    1721- You have a question: create a topic in the appropriate :forge:`discussion <forum>` 
    1822- You would like to raise and issue: open a new ticket of the right type depending of its severity 
    19    
     23 
    2024  - "Unavoidable" :forge:`newticket?type=Bug       <bug>` 
    21      
     25 
    2226  - "Workable"    :forge:`newticket?type=Defect <defect>` 
    2327 
     
    2731=============== 
    2832 
    29 You have build a development relevant for NEMO shared reference: an addition of the source code,   
     33You have build a development relevant for NEMO shared reference: an addition of the source code, 
    3034a full fork of the reference, ... 
    3135 
     
    3438 
    3539The proposals for developments to be included in the shared NEMO reference are first examined by NEMO Developers 
    36 Committee / Scientific Advisory Board.  
     40Committee / Scientific Advisory Board. 
    3741The implementation of a new development requires some additionnal work from the intial developer. 
    3842These tasks will need to be scheduled with NEMO System Team. 
     
    4246---- 
    4347 
    44 You only would like to inform NEMO community about your developments.  
     48You only would like to inform NEMO community about your developments. 
    4549You can promote your work on NEMO forum gathering  the contributions fromof the community by creating 
    46 a specific topic here :forge:`discussion/forum/5 <dedicated forum>`  
     50a specific topic here :forge:`discussion/forum/5 <dedicated forum>` 
    4751 
    4852 
     
    5559  routines to the ticket, to highlight the proposed changes by adding to the ticket the output of ``svn diff`` 
    5660  or ``svn patch`` from your working copy. 
    57    
     61 
    5862| Your development seems relevant for addition into the future release of NEMO shared reference. 
    5963  Implementing it into NEMO shared reference following the usual quality control will require some additionnal work 
     
    6165  your suggestion should be send as a proposed enhancement here :forge:`newticket?type=Enhancement <enhancement>` 
    6266  including description of the development, its implementation, and the existing validations. 
    63    
    64   The proposed enhancement will be examined  by NEMO Developers Committee / Scientific Advisory Board.  
     67 
     68  The proposed enhancement will be examined  by NEMO Developers Committee / Scientific Advisory Board. 
    6569  Once approved by the  Committee, the assicated development task can be scheduled in NEMO development work plan, 
    6670  and tasks distributed between you as initial developer and PI of this development action, and the NEMO System Team. 
    67    
     71 
    6872  Once sucessful (meeting the usual quality control steps) this action will allow the merge of these developments with 
    6973  other developments of the year, building the future NEMO. 
  • NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/INSTALL.rst

    r10604 r11824  
    33******************* 
    44 
     5.. todo:: 
     6 
     7 
     8 
    59.. contents:: 
    610   :local: 
     
    1014 
    1115| The NEMO source code is written in *Fortran 95* and 
    12   some of its prerequisite tools and libraries are already included in the ``./ext`` subdirectory. 
     16  some of its prerequisite tools and libraries are already included in the download. 
    1317| It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and 
    1418  the IOIPSL_ library for parts of the output. 
     
    2327- *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...), 
    2428- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_). 
    25 - |NetCDF|_ library with its underlying |HDF|_  
     29- |NetCDF|_ library with its underlying |HDF|_ 
    2630 
    2731**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.** 
     
    4044   This will limit MPI features to those defined within the MPI-2 standard 
    4145   (but will lose some performance benefits). 
    42  
    43 Specifics for NetCDF and HDF 
    44 ---------------------------- 
    45  
    46 NetCDF and HDF versions from . 
    47 However access to all the options available with the XIOS IO-server will require 
    48 the parallel IO support of these libraries which can be unavailable. 
    49  
    50 | **To satisfy these requirements, it is common to have to compile from source 
    51   in this order HDF (C library) then NetCDF (C and Fortran libraries)** 
    52 | It is also necessary to compile these libraries with the same version of the MPI implementation that 
    53   both NEMO and XIOS (see below) are compiled and linked with. 
    54  
    55 .. hint:: 
    56  
    57    | It is difficult to define the options for the compilation as 
    58      they differ from one architecture to another according to 
    59      the hardware used and the software installed. 
    60    | The following is provided without any warranty 
    61  
    62    .. code-block:: console 
    63  
    64       $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ... 
    65  
    66    It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check`` 
    67  
    68 Particular versions of these libraries may have their own restrictions. 
    69 State the following requirements for netCDF-4 support: 
    70  
    71 .. caution:: 
    72  
    73    | When building NetCDF-C library versions older than 4.4.1, use only HDF5 1.8.x versions. 
    74    | Combining older NetCDF-C versions with newer HDF5 1.10 versions will create superblock 3 files 
    75      that are not readable by lots of older software. 
    76     
    77 Extract and install XIOS 
    78 ======================== 
    79  
    80 With the sole exception of running NEMO in mono-processor mode 
    81 (in which case output options are limited to those supported by the ``IOIPSL`` library), 
    82 diagnostic outputs from NEMO are handled by the third party ``XIOS`` library. 
    83 This can be used in two different modes: 
    84  
    85 - *attached* - Every NEMO process also acts as a XIOS server 
    86 - *detached* - Every NEMO process runs as a XIOS client. 
    87   Output is collected and collated by external, stand-alone XIOS server processors. 
    88  
    89 .. important:: 
    90  
    91    In either case, XIOS needs to be compiled before NEMO, 
    92    since the libraries are needed to successfully create the NEMO executable. 
    93  
    94 Instructions on how to obtain and install the software can be found on the :xios:`XIOS wiki<wiki>`. 
    95  
    96 .. hint:: 
    97  
    98    It is recommended to use XIOS version 2.5. 
    99    This version should be more stable (in terms of future code changes) than the XIOS trunk. 
    100    It is also the version used by the NEMO system team when testing all developments and new releases. 
    101     
    102    This particular version has its own branch and can be checked out and downloaded with: 
    103  
    104    .. code:: console 
    105  
    106       $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
    107  
    108 Download the NEMO source code 
    109 ============================= 
    110  
    111 .. code:: console 
    112  
    113    $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk 
    114  
    115 Description of directory tree 
    116 ----------------------------- 
    117  
    118 +-----------+------------------------------------------------------------+ 
    119 | Folder    | Purpose                                                    | 
    120 +===========+============================================================+ 
    121 | ``arch``  | Settings (per architecture-compiler pair)                  | 
    122 +-----------+------------------------------------------------------------+ 
    123 | ``cfgs``  | :doc:`Reference configurations <configurations>`           | 
    124 +-----------+------------------------------------------------------------+ 
    125 | ``doc``   | - ``latex``    : LaTex source code for ref. manuals        | 
    126 |           | - ``namelists``: k start guide                             | 
    127 |           | - ``rst``      : ReST files for quick start guide          | 
    128 +-----------+------------------------------------------------------------+ 
    129 | ``ext``   | Dependencies included (``AGRIF``, ``FCM`` & ``IOIPSL``)    | 
    130 +-----------+------------------------------------------------------------+ 
    131 | ``mk``    | Building  routines                                         | 
    132 +-----------+------------------------------------------------------------+ 
    133 | ``src``   | Modelling routines                                         | 
    134 |           |                                                            | 
    135 |           | - ``ICE``: |SI3| for sea ice                               | 
    136 |           | - ``NST``: AGRIF for embedded zooms                        | 
    137 |           | - ``OCE``: |OPA| for ocean dynamics                        | 
    138 |           | - ``TOP``: |TOP| for tracers                               | 
    139 +-----------+------------------------------------------------------------+ 
    140 | ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               | 
    141 +-----------+------------------------------------------------------------+ 
    142 | ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         | 
    143 +-----------+------------------------------------------------------------+ 
    144  
    145 Setup your architecture configuration file 
    146 ========================================== 
    147  
    148 All compiler options in NEMO are controlled using files in 
    149 trunk/arch/arch-'my_arch'.fcm where 'my_arch' is the name of the computing 
    150 architecture.  It is recommended to copy and rename an configuration file from 
    151 an architecture similar to your owns. You will need to set appropriate values 
    152 for all of the variables in the file. In particular the FCM variables: 
    153 ``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to the 
    154 installation directories used for XIOS installation. 
    155  
    156 .. code-block:: sh 
    157  
    158         %NCDF_HOME           /opt/local 
    159         %HDF5_HOME           /opt/local 
    160         %XIOS_HOME           /Users/$( whoami )/xios-2.5 
    161         %OASIS_HOME          /not/defined 
    162  
    163 Compile and create NEMO executable 
    164 ================================== 
    165  
    166 The main script to compile and create executable is called makenemo and located in the CONFIG directory, it is used to identify the routines you need from the source code, to build the makefile and run it. 
    167 As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration: 
    168  
    169 .. code-block:: sh 
    170  
    171    ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' 
    172  
    173 The image below shows the structure and some content of "MY_CONFIG" directory from the launching of the configuration creation (directories and fundamental files created by makenemo). 
    174  
    175 +------------+----------------------------------------------------+ 
    176 | Folder     | Purpose                                            | 
    177 +============+====================================================+ 
    178 | ``BLD``    |                                                    | 
    179 +------------+----------------------------------------------------+ 
    180 | ``EXP00``  |                                                    | 
    181 +------------+----------------------------------------------------+ 
    182 | ``EXPREF`` |                                                    | 
    183 +------------+----------------------------------------------------+ 
    184 | ``MY_SRC`` |                                                    | 
    185 +------------+----------------------------------------------------+ 
    186 | ``WORK``   |                                                    | 
    187 +------------+----------------------------------------------------+ 
    188  
    189 Folder with the symbolic links to all unpreprocessed routines considered in the configuration 
    190 Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …) 
    191 Computation folder for running the model (namelists, xml, executables and inputs-outputs) 
    192 Folder intended to contain your customised routines (modified from initial ones or new entire routines) 
    193  
    194 After successful execution of makenemo command, the executable called opa is created in the EXP00 directory (in the example above, the executable is created in CONFIG/MY_GYRE/EXP00). 
    195  
    196 More makenemo options 
    197 --------------------- 
    198  
    199 ``makenemo`` has several other options that can control which source files are selected and 
    200 the operation of the build process itself. 
    201 These are:: 
    202  
    203    Optional: 
    204       -d  Set of new sub-components (space separated list from ./src directory) 
    205       -e  Path for alternative patch  location (default: 'MY_SRC' in configuration folder) 
    206       -h  Print this help 
    207       -j  Number of processes to compile (0: no build) 
    208       -n  Name for new configuration 
    209       -s  Path for alternative source location (default: 'src' root directory) 
    210       -t  Path for alternative build  location (default: 'BLD' in configuration folder) 
    211       -v  Level of verbosity ([0-3]) 
    212  
    213 These options can be useful for maintaining several code versions with only minor differences but 
    214 they should be used sparingly. 
    215 Note however the ``-j`` option which should be used more routinely to speed up the build process. 
    216 For example: 
    217  
    218 .. code-block:: sh 
    219  
    220         ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8 
    221  
    222 which will compile up to 8 modules simultaneously. 
    223  
    224  
    225 Default behaviour 
    226 ----------------- 
    227  
    228 At the first use, you need the -m option to specify the architecture 
    229 configuration file (compiler and its options, routines and libraries to 
    230 include), then for next compilation, it is assumed you will be using the 
    231 same compiler.  If the –n option is not specified the last compiled configuration 
    232 will be used. 
    233  
    234 Tools used during the process 
    235 ----------------------------- 
    236  
    237 *   functions.sh : bash functions used by makenemo, for instance to create the WORK directory 
    238 *   cfg.txt : text list of configurations and source directories 
    239 *   bld.cfg : FCM rules to compile  
    240  
    241 Examples 
    242 -------- 
    243  
    244 .. code-block:: sh 
    245  
    246         echo "Example to install a new configuration MY_CONFIG"; 
    247         echo "with OPA_SRC and LIM_SRC_2 "; 
    248         echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\""; 
    249         echo ""; 
    250         echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt; 
    251         echo ""; 
    252         echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt; 
    253         echo ""; 
    254         echo "Example to remove bad configuration "; 
    255         echo "./makenemo -n MY_CONFIG clean_config"; 
    256         echo ""; 
    257         echo "Example to clean "; 
    258         echo "./makenemo clean"; 
    259         echo ""; 
    260         echo "Example to list the available keys of a CONFIG "; 
    261         echo "./makenemo list_key"; 
    262         echo ""; 
    263         echo "Example to add and remove keys"; 
    264         echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" "; 
    265         echo ""; 
    266         echo "Example to add and remove keys for a new configuration, and do not compile"; 
    267         echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" "; 
    268  
    269 Running the model 
    270 ================= 
    271  
    272 Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00`` 
    273 For the reference configurations, the EXP00 folder also contains the initial input files (namelists, \*xml files for the IOs…). If the configuration also needs NetCDF input files, this should be downloaded here from the corresponding tar file, see Users/Reference Configurations 
    274  
    275 .. code-block:: sh 
    276  
    277         cd 'MY_CONFIG'/EXP00 
    278         mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper 
    279  
    280  
    281 Viewing and changing list of active CPP keys 
    282 ============================================ 
    283  
    284 For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in: 
    285  
    286 .. code-block:: sh 
    287  
    288         trunk/cfgs/'MYCONFIG'/cpp_'MY_CONFIG'.fcm 
    289  
    290  
    291 This text file can be edited to change the list of active CPP keys. Once changed, one needs to recompile opa executable using makenemo command in order for this change to be taken in account. 
    292 Note that most NEMO configurations will need to specify the following CPP keys: 
    293 ``key_iomput`` and ``key_mpp_mpi`` 
    294  
    295 .. Links and substitutions 
    29646 
    29747.. |OpenMPI| replace:: *OpenMPI* 
     
    30050.. _MPICH:   https://www.mpich.org 
    30151.. |NetCDF|  replace:: *Network Common Data Form (NetCDF)* 
    302 .. _NetCDF:  https://www.unidata.ucar.edu/downloads/netcdf 
     52.. _NetCDF:  https://www.unidata.ucar.edu 
    30353.. |HDF|     replace:: *Hierarchical Data Form (HDF)* 
    304 .. _HDF:     https://www.hdfgroup.org/downloads 
     54.. _HDF:     https://www.hdfgroup.org 
     55 
     56Specifics for NetCDF and HDF 
     57---------------------------- 
     58 
     59NetCDF and HDF versions from official repositories may have not been compiled with MPI support. 
     60However access to all the options available with the XIOS IO-server will require 
     61the parallelism of these libraries. 
     62 
     63| **To satisfy these requirements, it is common to have to compile from source 
     64  in this order HDF (C library) then NetCDF (C and Fortran libraries)** 
     65| It is also necessary to compile these libraries with the same version of the MPI implementation that 
     66  both NEMO and XIOS (see below) have been compiled and linked with. 
     67 
     68.. hint:: 
     69 
     70   | It is difficult to define the options for the compilation as 
     71     they differ from one architecture to another according to 
     72     the hardware used and the software installed. 
     73   | The following is provided without any warranty 
     74 
     75   .. code-block:: console 
     76 
     77      $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ... 
     78 
     79   It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check`` 
     80 
     81Particular versions of these libraries may have their own restrictions. 
     82State the following requirements for netCDF-4 support: 
     83 
     84.. caution:: 
     85 
     86   | When building NetCDF-C library versions older than 4.4.1, use only HDF5 1.8.x versions. 
     87   | Combining older NetCDF-C versions with newer HDF5 1.10 versions will create superblock 3 files 
     88     that are not readable by lots of older software. 
     89 
     90Extract and install XIOS 
     91======================== 
     92 
     93With the sole exception of running NEMO in mono-processor mode 
     94(in which case output options are limited to those supported by the ``IOIPSL`` library), 
     95diagnostic outputs from NEMO are handled by the third party ``XIOS`` library. 
     96It can be used in two different modes: 
     97 
     98:*attached*:  Every NEMO process also acts as a XIOS server 
     99:*detached*:  Every NEMO process runs as a XIOS client. 
     100  Output is collected and collated by external, stand-alone XIOS server processors. 
     101 
     102Instructions on how to install XIOS can be found on its :xios:`wiki<>`. 
     103 
     104.. hint:: 
     105 
     106   It is recommended to use XIOS 2.5 release. 
     107   This version should be more stable (in terms of future code changes) than the XIOS trunk. 
     108   It is also the one used by the NEMO system team when testing all developments and new releases. 
     109 
     110   This particular version has its own branch and can be checked out with: 
     111 
     112   .. code:: console 
     113 
     114      $ svn co https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
     115 
     116Download and install the NEMO code 
     117================================== 
     118 
     119Checkout the NEMO sources 
     120------------------------- 
     121 
     122.. code:: console 
     123 
     124   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk 
     125 
     126Description of 1\ :sup:`st` level tree structure 
     127------------------------------------------------ 
     128 
     129+---------------+----------------------------------------+ 
     130| :file:`arch`  | Compilation settings                   | 
     131+---------------+----------------------------------------+ 
     132| :file:`cfgs`  | :doc:`Reference configurations <cfgs>` | 
     133+---------------+----------------------------------------+ 
     134| :file:`doc`   | :doc:`Documentation <doc>`             | 
     135+---------------+----------------------------------------+ 
     136| :file:`ext`   | Dependencies included                  | 
     137|               | (``AGRIF``, ``FCM`` & ``IOIPSL``)      | 
     138+---------------+----------------------------------------+ 
     139| :file:`mk`    | Compilation scripts                    | 
     140+---------------+----------------------------------------+ 
     141| :file:`src`   | :doc:`Modelling routines <src>`        | 
     142+---------------+----------------------------------------+ 
     143| :file:`tests` | :doc:`Test cases <tests>`              | 
     144|               | (unsupported)                          | 
     145+---------------+----------------------------------------+ 
     146| :file:`tools` | :doc:`Utilities <tools>`               | 
     147|               | to {pre,post}process data              | 
     148+---------------+----------------------------------------+ 
     149 
     150Setup your architecture configuration file 
     151------------------------------------------ 
     152 
     153All compiler options in NEMO are controlled using files in :file:`./arch/arch-'my_arch'.fcm` where 
     154``my_arch`` is the name of the computing architecture 
     155(generally following the pattern ``HPCC-compiler`` or ``OS-compiler``). 
     156It is recommended to copy and rename an configuration file from an architecture similar to your owns. 
     157You will need to set appropriate values for all of the variables in the file. 
     158In particular the FCM variables: 
     159``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to 
     160the installation directories used for XIOS installation 
     161 
     162.. code-block:: sh 
     163 
     164   %NCDF_HOME    /usr/local/path/to/netcdf 
     165   %HDF5_HOME    /usr/local/path/to/hdf5 
     166   %XIOS_HOME    /home/$( whoami )/path/to/xios-2.5 
     167   %OASIS_HOME   /home/$( whoami )/path/to/oasis 
     168 
     169Create and compile a new configuration 
     170====================================== 
     171 
     172The main script to {re}compile and create executable is called :file:`makenemo` located at 
     173the root of the working copy. 
     174It is used to identify the routines you need from the source code, to build the makefile and run it. 
     175As an example, compile a :file:`MY_GYRE` configuration from GYRE with 'my_arch': 
     176 
     177.. code-block:: sh 
     178 
     179   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' 
     180 
     181Then at the end of the configuration compilation, 
     182:file:`MY_GYRE` directory will have the following structure. 
     183 
     184+------------+----------------------------------------------------------------------------+ 
     185| Directory  | Purpose                                                                    | 
     186+============+============================================================================+ 
     187| ``BLD``    | BuiLD folder: target executable, headers, libs, preprocessed routines, ... | 
     188+------------+----------------------------------------------------------------------------+ 
     189| ``EXP00``  | Run   folder: link to executable, namelists, ``*.xml`` and IOs             | 
     190+------------+----------------------------------------------------------------------------+ 
     191| ``EXPREF`` | Files under version control only for :doc:`official configurations <cfgs>` | 
     192+------------+----------------------------------------------------------------------------+ 
     193| ``MY_SRC`` | New routines or modified copies of NEMO sources                            | 
     194+------------+----------------------------------------------------------------------------+ 
     195| ``WORK``   | Links to all raw routines from :file:`./src` considered                    | 
     196+------------+----------------------------------------------------------------------------+ 
     197 
     198After successful execution of :file:`makenemo` command, 
     199the executable called `nemo` is available in the :file:`EXP00` directory 
     200 
     201More :file:`makenemo` options 
     202----------------------------- 
     203 
     204``makenemo`` has several other options that can control which source files are selected and 
     205the operation of the build process itself. 
     206 
     207.. literalinclude:: ../../../makenemo 
     208   :language: text 
     209   :lines: 119-143 
     210   :caption: Output of ``makenemo -h`` 
     211 
     212These options can be useful for maintaining several code versions with only minor differences but 
     213they should be used sparingly. 
     214Note however the ``-j`` option which should be used more routinely to speed up the build process. 
     215For example: 
     216 
     217.. code-block:: sh 
     218 
     219        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8 
     220 
     221will compile up to 8 processes simultaneously. 
     222 
     223Default behaviour 
     224----------------- 
     225 
     226At the first use, 
     227you need the ``-m`` option to specify the architecture configuration file 
     228(compiler and its options, routines and libraries to include), 
     229then for next compilation, it is assumed you will be using the same compiler. 
     230If the ``-n`` option is not specified the last compiled configuration will be used. 
     231 
     232Tools used during the process 
     233----------------------------- 
     234 
     235* :file:`functions.sh`: bash functions used by ``makenemo``, for instance to create the WORK directory 
     236* :file:`cfg.txt`     : text list of configurations and source directories 
     237* :file:`bld.cfg`     : FCM rules for compilation 
     238 
     239Examples 
     240-------- 
     241 
     242.. literalinclude:: ../../../makenemo 
     243   :language: text 
     244   :lines: 146-153 
     245 
     246Running the model 
     247================= 
     248 
     249Once :file:`makenemo` has run successfully, 
     250the ``nemo`` executable is available in :file:`./cfgs/MY_CONFIG/EXP00`. 
     251For the reference configurations, the :file:`EXP00` folder also contains the initial input files 
     252(namelists, ``*.xml`` files for the IOs, ...). 
     253If the configuration needs other input files, they have to be placed here. 
     254 
     255.. code-block:: sh 
     256 
     257   cd 'MY_CONFIG'/EXP00 
     258   mpirun -n $NPROCS ./nemo   # $NPROCS is the number of processes 
     259                              # mpirun is your MPI wrapper 
     260 
     261Viewing and changing list of active CPP keys 
     262============================================ 
     263 
     264For a given configuration (here called ``MY_CONFIG``), 
     265the list of active CPP keys can be found in :file:`./cfgs/'MYCONFIG'/cpp_MY_CONFIG.fcm` 
     266 
     267This text file can be edited by hand or with :file:`makenemo` to change the list of active CPP keys. 
     268Once changed, one needs to recompile ``nemo`` in order for this change to be taken in account. 
     269Note that most NEMO configurations will need to specify the following CPP keys: 
     270``key_iomput`` for IOs and ``key_mpp_mpi`` for parallelism. 
  • NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/README.rst

    r10638 r11824  
    1 :Release: |version| 
    2 :Date:    |today| 
     1.. todo:: 
    32 
    4 NEMO_ for **Nucleus for European Modelling of the Ocean** is a state-of-the-art modelling framework for 
     3 
     4 
     5NEMO_ for *Nucleus for European Modelling of the Ocean* is a state-of-the-art modelling framework for 
    56research activities and forecasting services in ocean and climate sciences, 
    67developed in a sustainable way by a European consortium since 2008. 
     
    1415The NEMO ocean model has 3 major components: 
    1516 
    16 - |OPA| models the ocean {thermo}dynamics and solves the primitive equations 
    17   (``./src/OCE``) 
    18 - |SI3| simulates seaice {thermo}dynamics, brine inclusions and subgrid-scale thickness variations 
    19   (``./src/ICE``) 
    20 - |TOP| models the {on,off}line oceanic tracers transport and biogeochemical processes 
    21   (``./src/TOP``) 
     17- |OCE| models the ocean {thermo}dynamics and solves the primitive equations 
     18  (:file:`./src/OCE`) 
     19- |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and 
     20  subgrid-scale thickness variations (:file:`./src/ICE`) 
     21- |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes 
     22  (:file:`./src/TOP`) 
    2223 
    23 These physical core engines are described in their respective `references`_ that 
    24 must be cited for any work related to their use. 
     24These physical core engines are described in 
     25their respective `reference publications <#project-documentation>`_ that 
     26must be cited for any work related to their use (see :doc:`cite`). 
    2527 
    2628Assets and solutions 
     
    3234- Create :doc:`embedded zooms<zooms>` seamlessly thanks to 2-way nesting package AGRIF_. 
    3335- Opportunity to integrate an :doc:`external biogeochemistry model<tracers>` 
    34 - Versatile :doc:`data assimilation<data_assimilation>` 
    35 - Generation of :doc:`diagnostics<diagnostics>` through effective XIOS_ system 
    36 - Roll-out Earth system modeling with :doc:`coupling interface<coupling>` based on OASIS_ 
     36- Versatile :doc:`data assimilation<da>` 
     37- Generation of :doc:`diagnostics<diags>` through effective XIOS_ system 
     38- Roll-out Earth system modeling with :doc:`coupling interface<cplg>` based on OASIS_ 
    3739 
    38 Several :doc:`built-in configurations<configurations>` are provided to 
     40Several :doc:`built-in configurations<cfgs>` are provided to 
    3941evaluate the skills and performances of the model which 
    40 can be used as templates for setting up a new configurations (``./cfgs``). 
     42can be used as templates for setting up a new configurations (:file:`./cfgs`). 
    4143 
    42 The user can also checkout available :doc:`idealized test cases<test_cases>` that 
    43 address specific physical processes(``./tests``). 
     44The user can also checkout available :doc:`idealized test cases<tests>` that 
     45address specific physical processes (:file:`./tests`). 
    4446 
    45 A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (``./tools``). 
     47A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (:file:`./tools`). 
    4648 
    4749Project documentation 
     
    4951 
    5052A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO 
    51 (``./INSTALL.rst``) .  
     53(:file:`./INSTALL.rst`). 
    5254 
    5355Reference manuals and quick start guide can be build from source and 
    54 exported to HTML or PDF formats (``./doc``) or 
    55 downloaded directly from the :website:`website<bibliography/documentation>`. 
     56exported to HTML or PDF formats (:file:`./doc`) or 
     57downloaded directly from the :forge:`development platform<wiki/Documentations>`. 
    5658 
    57 =========== ===================== =============== 
    58  Component   Reference Manual      Quick start 
    59 =========== ===================== =============== 
    60  |OPA|       |NEMO manual|_        |NEMO guide| 
    61              :cite:`NEMO_manual` 
    62  |SI3|       |SI3 manual| 
    63              :cite:`SI3_manual` 
    64  |TOP|       |TOP manual| 
    65              :cite:`TOP_manual` 
    66 =========== ===================== =============== 
     59============ ================== =================== 
     60 Component    Reference Manual   Quick Start Guide 
     61============ ================== =================== 
     62 |NEMO-OCE|   |DOI man OCE|_     |DOI qsg| 
     63 |NEMO-ICE|   |DOI man ICE| 
     64 |NEMO-MBG|   |DOI man MBG| 
     65============ ================== =================== 
    6766 
    6867Since 2014 the project has a `Special Issue`_ in the open-access journal 
    69 Geoscientific Model Development (GMD) from the European Geosciences Union (EGU). 
     68Geoscientific Model Development (GMD) from the European Geosciences Union (EGU_). 
    7069The main scope is to collect relevant manuscripts covering various topics and 
    7170to provide a single portal to assess the model potential and evolution. 
     
    7877================= 
    7978 
    80 The NEMO Consortium pulling together 5 European institutes (CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_) 
    81 plans the sustainable development in order to keep a reliable evolving framework since 2008. 
     79The NEMO Consortium pulling together 5 European institutes 
     80(CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_) plans the sustainable development in order to 
     81keep a reliable evolving framework since 2008. 
    8282 
    83 It defines the |NEMO strategy|_ that is implemented by the System Team on a yearly basis in order to 
    84 release a new version almost every four years. 
     83It defines the |DOI dev stgy|_ that is implemented by the System Team on a yearly basis 
     84in order to release a new version almost every four years. 
    8585 
    8686When the need arises, :forge:`working groups<wiki/WorkingGroups>` are created or resumed to 
    8787gather the community expertise for advising on the development activities. 
    8888 
     89.. |DOI dev stgy| replace:: multi-year development strategy 
    8990 
    90 .. Substitutions / Links 
     91Disclaimer 
     92========== 
    9193 
    92 .. |NEMO manual| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg 
    93 .. |NEMO guide|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg 
    94 .. |SI3 manual|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg 
    95 .. |TOP manual|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg 
     94The NEMO source code is freely available and distributed under 
     95:download:`CeCILL v2.0 license <../../../LICENSE>` (GNU GPL compatible). 
    9696 
    97 .. |NEMO strategy| replace:: multi-year development strategy 
    98  
    99 .. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html 
     97You can use, modify and/or redistribute the software under its terms, 
     98but users are provided only with a limited warranty and the software's authors and 
     99the successive licensor's have only limited liability. 
  • NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/REFERENCES.bib

    r10627 r11824  
    1 @manual{NEMO_manual, 
    2    title={NEMO ocean engine}, 
    3    author={Madec Gurvan and NEMO System Team}, 
    4    organization={NEMO Consortium}, 
    5    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    6    number={27}, 
    7    publisher={Zenodo}, 
    8    abstract={The ocean engine of NEMO is a primitive equation model adapted to regional and 
    9    global ocean circulation problems. 
    10    It is intended to be a flexible tool for studying the ocean and its interactions with 
    11    the others components of the earth climate system over a wide range of space and time scales.}, 
    12    doi={10.5281/zenodo.1464816}, 
    13    edition={}, 
    14    year={} 
     1@manual{NEMO_man, 
     2   title="NEMO ocean engine", 
     3   author="NEMO System Team", 
     4   series="Scientific Notes of Climate Modelling Center", 
     5   number="27", 
     6   institution="Institut Pierre-Simon Laplace (IPSL)", 
     7   publisher="Zenodo", 
     8   doi="10.5281/zenodo.1464816", 
    159} 
     10%   edition="", 
     11%   year="" 
    1612 
    17 @manual{SI3_manual, 
    18    title={SI³ – Sea Ice modelling Integrated Initiative – The NEMO Sea Ice engine}, 
    19    author={NEMO Sea Ice Working Group}, 
    20    organization={NEMO Consortium}, 
    21    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    22    number={31}, 
    23    publisher={Zenodo}, 
    24    abstract={SI³ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO 
    25    (Nucleus for European Modelling of the Ocean). 
    26    SI³ is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework, 
    27    combining the ice thickness distribution framework, the conservation of horizontal momentum, 
    28    an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics. 
    29    SI³ is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with 
    30    several atmospheric general circulation models. 
    31    It also supports two-way grid embedding via the AGRIF software.}, 
    32    doi={10.5281/zenodo.1471689}, 
    33    edition={}, 
    34    year={} 
     13@manual{SI3_man, 
     14   title="Sea Ice modelling Integrated Initiative (SI$^3$) -- The NEMO Sea Ice engine", 
     15   author="NEMO Sea Ice Working Group", 
     16   series="Scientific Notes of Climate Modelling Center", 
     17   number="31", 
     18   institution="Institut Pierre-Simon Laplace (IPSL)", 
     19   publisher="Zenodo", 
     20   doi="10.5281/zenodo.1471689", 
    3521} 
     22%   edition="", 
     23%   year="" 
    3624 
    37 @manual{TOP_manual, 
    38    title={TOP – Tracers in Ocean Paradigm – The NEMO Tracers engine}, 
    39    author={NEMO TOP Working Group}, 
    40    organization={NEMO Consortium}, 
    41    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    42    number={28}, 
    43    publisher={Zenodo}, 
    44    abstract={}, 
    45    doi={10.5281/zenodo.1471700}, 
    46    edition={}, 
    47    year={} 
     25@manual{TOP_man, 
     26   title="Tracers in Ocean Paradigm (TOP) -- The NEMO Tracers engine", 
     27   author="NEMO TOP Working Group", 
     28   series="Scientific Notes of Climate Modelling Center", 
     29   number="28", 
     30   institution="Institut Pierre-Simon Laplace (IPSL)", 
     31   publisher="Zenodo", 
     32   doi="10.5281/zenodo.1471700", 
    4833} 
     34%   edition="", 
     35%   year="" 
    4936 
    50 @Article{gmd-8-1245-2015, 
    51    author = {Vidard, A. and Bouttier, P.-A. and Vigilant, F.}, 
    52    title = {{NEMOTAM}: {T}angent and {A}djoint {M}odels for the ocean modelling platform {NEMO}}, 
    53    journal = {Geoscientific Model Development}, 
    54    volume = {8}, 
    55    year = {2015}, 
    56    number = {4}, 
    57    pages = {1245--1257}, 
    58    doi = {10.5194/gmd-8-1245-2015} 
     37@article{TAM_pub, 
     38   author = "Vidard, A. and Bouttier, P.-A. and Vigilant, F.", 
     39   title = "NEMOTAM: Tangent and Adjoint Models for the ocean modelling platform NEMO", 
     40   journal = "Geoscientific Model Development", 
     41   volume = "8", 
     42   year = "2015", 
     43   number = "4", 
     44   pages = "1245--1257", 
     45   doi = "10.5194/gmd-8-1245-2015" 
    5946} 
Note: See TracChangeset for help on using the changeset viewer.