New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 10604 for NEMO – NEMO

Changeset 10604 for NEMO


Ignore:
Timestamp:
2019-01-29T15:48:21+01:00 (5 years ago)
Author:
nicolasmartin
Message:

Review partly INSTALL.rst + implement 2 features for the future

Location:
NEMO/trunk
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/INSTALL.rst

    r10596 r10604  
    1 ***************************** 
    2 Obtaining and installing NEMO 
    3 ***************************** 
     1******************* 
     2Build the framework 
     3******************* 
    44 
    55.. contents:: 
    6    :local: 
    7        
     6   :local: 
     7 
    88Prerequisites 
    99============= 
    1010 
    11 - The NEMO source code is written in Fortran 95 and some of its prerequisite 
    12   tools and libraries are already included in the (``./ext``) subdirectory. These 
    13   include: the AGRIF preprocessing program "conv"; the FCM build system and the  
    14   IOIPSL library for parts of the output. 
    15 - Other requirements that your system needs to provide include: a Perl 5 interpreter; a modern 
    16   Fortran compiler (ifort, gfortran, pgfortran, ...) and (in most cases) a MPI library 
    17   (e.g. OpenMPI or MPICH). The latter is not strictly essential since it is possible 
    18   to compile and run NEMO on a single processor. However most realistic configurations 
    19   will require the parallel capabilities of NEMO and these use the Message Passing 
    20   Interface (MPI) library. NEMO v4.0, by default, uses some MPI features introduced 
    21   into the MPI-3 standard. On older systems, that do not support these features,  
    22   the key_mpi2 preprocessor key should be used at compile time. This will limit MPI 
    23   features to those defined within the MPI-2 standard (but will lose some performance 
    24   benefits). 
    25  
    26 The following prerequisites may already be installed or be available from the 
    27 official repositories of your Linux distribution. However access to all the 
    28 options available with the XIOS IO-server will require the parallel form of the 
    29 netcdf4 library and its underlying HDF5 library. It is also necessary to compile 
    30 these libraries with the same version of the MPI library that both NEMO and XIOS 
    31 (see below) are compiled and linked with. To satisfy these requirements, it is common  
    32 to have to compile the following from source. 
    33  
    34 - `HDF5`_   (C library) (use: --enable-fortran --enable-parallel with configure) 
    35 - `NetCDF4`_ (C and Fortran libraries) 
    36  
    37 Note that particular versions of these libraries may have their own 
    38 restrictions. For example, the latest versions of the netCDF libraries: 
    39 netcdf-c-4.6.2 and netcdf-fortran-4.4.4, state the following requirements for netCDF-4 support: 
    40  
    41 - HDF5 1.8.9 or later. 
    42 - HDF5 1.10.1 or later. 
    43 - zlib 1.2.5 or later (for netCDF-4 compression) 
    44 - curl 7.18.0 or later (for DAP remote access client support) 
    45  
    46 `Important Note: When building netCDF-C library versions older than 4.4.1, 
    47 use only HDF5 1.8.x versions. Combining older netCDF-C versions with newer 
    48 HDF5 1.10 versions will create superblock 3 files that are not readable by 
    49 lots of older software.` 
    50  
     11| 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. 
     13| It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and 
     14  the IOIPSL_ library for parts of the output. 
     15 
     16System dependencies 
     17------------------- 
     18 
     19In the first place the other requirements should be provided natively by your system or 
     20can be installed from the official repositories of your Unix-like distribution: 
     21 
     22- *Perl* interpreter 
     23- *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...), 
     24- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_). 
     25- |NetCDF|_ library with its underlying |HDF|_  
     26 
     27**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.** 
     28 
     29.. hint:: 
     30 
     31   The MPI implementation is not strictly essential 
     32   since it is possible to compile and run NEMO on a single processor. 
     33   However most realistic configurations will require the parallel capabilities of NEMO and 
     34   these use the MPI standard. 
     35 
     36.. note:: 
     37 
     38   On older systems, that do not support MPI-3 features, 
     39   the ``key_mpi2`` preprocessor key should be used at compile time. 
     40   This will limit MPI features to those defined within the MPI-2 standard 
     41   (but will lose some performance benefits). 
     42 
     43Specifics for NetCDF and HDF 
     44---------------------------- 
     45 
     46NetCDF and HDF versions from . 
     47However access to all the options available with the XIOS IO-server will require 
     48the 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 
     68Particular versions of these libraries may have their own restrictions. 
     69State 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    
    5177Extract and install XIOS 
    5278======================== 
    5379 
    54 With the sole exception of running NEMO in mono-processor mode (in which case 
    55 output options are limited to those supported by the IOIPSL library), diagnostic 
    56 outputs from NEMO are handled by the third party XIOS library. This can be used 
    57 in two different modes: 
    58  
    59 * attached - Every NEMO process also acts as a XIOS server 
    60 * dettached - Every NEMO process runs as a XIOS client. Output is collected and collated by external, 
    61   stand-alone XIOS server processors. 
    62  
    63 In either case, it is important to note that XIOS needs to be compiled before 
    64 NEMO, since the libraries are needed to successfully create the NEMO executable. 
    65  
    66 Instructions on how to obtain and install the software can be found on the `XIOS Wiki`_ . 
    67  
    68 It is recommended to use XIOS version 2.5 with NEMOv4.0. This version should be more stable (in terms of  
    69 future code changes) than the XIOS trunk. It is also the version used by the NEMO system team when  
    70 testing all developments and new releases. This particular version has its own branch and can be  
    71 checked out and downloaded with: 
    72  
    73 .. code:: console 
    74  
    75         $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
     80With 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), 
     82diagnostic outputs from NEMO are handled by the third party ``XIOS`` library. 
     83This 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 
     94Instructions 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 
    76107 
    77108Download the NEMO source code 
    … …  
    80111.. code:: console 
    81112 
    82    $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0 
     113   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk 
    83114 
    84115Description of directory tree 
    … …  
    92123| ``cfgs``  | :doc:`Reference configurations <configurations>`           | 
    93124+-----------+------------------------------------------------------------+ 
    94 | ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    | 
     125| ``doc``   | - ``latex``    : LaTex source code for ref. manuals        | 
    95126|           | - ``namelists``: k start guide                             | 
    96 |           | - ``rst``:   quick start guide                             | 
    97 +-----------+------------------------------------------------------------+ 
    98 | ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                | 
     127|           | - ``rst``      : ReST files for quick start guide          | 
     128+-----------+------------------------------------------------------------+ 
     129| ``ext``   | Dependencies included (``AGRIF``, ``FCM`` & ``IOIPSL``)    | 
    99130+-----------+------------------------------------------------------------+ 
    100131| ``mk``    | Building  routines                                         | 
    … …  
    166197--------------------- 
    167198 
    168 ``makenemo`` has several other options that can control which source files are selected and the operation 
    169 of the build process itself. These are: 
    170  
    171 .. code-block:: sh 
    172  
    173         Optional: 
    174            -d   Set of new sub-components (space separated list from ./src directory) 
    175            -e   Path for alternative patch  location (default: 'MY_SRC' in configuration folder) 
    176            -h   Print this help 
    177            -j   Number of processes to compile (0: no build) 
    178            -n   Name for new configuration 
    179            -s   Path for alternative source location (default: 'src' root directory) 
    180            -t   Path for alternative build  location (default: 'BLD' in configuration folder) 
    181            -v   Level of verbosity ([0-3]) 
    182  
    183 These options can be useful for maintaining several code versions with only minor differences but they  
    184 should be used sparingly. Note however the ``-j`` option which should be used more routinely to speed up 
    185 the build process. For example: 
     199``makenemo`` has several other options that can control which source files are selected and 
     200the operation of the build process itself. 
     201These 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 
     213These options can be useful for maintaining several code versions with only minor differences but 
     214they should be used sparingly. 
     215Note however the ``-j`` option which should be used more routinely to speed up the build process. 
     216For example: 
    186217 
    187218.. code-block:: sh 
    … …  
    260291This 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. 
    261292Note that most NEMO configurations will need to specify the following CPP keys: 
    262  
    263 *   key_iomput 
    264 *   key_mpp_mpi 
    265  
    266  
    267 .. _HDF5:   http://www.hdfgroup.org/downloads/hdf5 
    268 .. _NetCDF4: http://www.unidata.ucar.edu/downloads/netcdf 
    269 .. _XIOS Wiki:    http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation 
    270 .. _XIOSSRC: http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
     293``key_iomput`` and ``key_mpp_mpi`` 
     294 
     295.. Links and substitutions 
     296 
     297.. |OpenMPI| replace:: *OpenMPI* 
     298.. _OpenMPI: https://www.open-mpi.org 
     299.. |MPICH|   replace:: *MPICH* 
     300.. _MPICH:   https://www.mpich.org 
     301.. |NetCDF|  replace:: *Network Common Data Form (NetCDF)* 
     302.. _NetCDF:  https://www.unidata.ucar.edu/downloads/netcdf 
     303.. |HDF|     replace:: *Hierarchical Data Form (HDF)* 
     304.. _HDF:     https://www.hdfgroup.org/downloads 

  • NEMO/trunk/doc/rst/Makefile

    r10186 r10604  
    1919%: Makefile 
    2020   @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 
     21 
     22# Watch source directory and rebuild the documentation when a change is detected 
     23# Browse to 127.0.0.1:8000/NEMO_guide.html 
     24htmllive: 
     25   sphinx-autobuild $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html 

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

    r10596 r10604  
    2525.. Models / Softwares 
    2626 
    27 .. _AGRIF: https://agrif.imag.fr 
    28 .. _OASIS: https://portal.enes.org/oasis 
    29 .. _XIOS:  https://forge.ipsl.jussieu.fr/ioserver 
     27.. _AGRIF:  http://agrif.imag.fr 
     28.. _FCM:    https://metomi.github.io/fcm/doc/ 
     29.. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL 
     30.. _OASIS:  https://portal.enes.org/oasis 
     31.. _XIOS:   https://forge.ipsl.jussieu.fr/ioserver 
    3032 
    3133.. NEMO 
Note: See TracChangeset for help on using the changeset viewer.