source: NEMO/trunk/INSTALL.rst @ 13159

Last change on this file since 13159 was 11734, checked in by nicolasmartin, 18 months ago

Review README for reference confgiurations

File size: 10.8 KB
2Build the framework
[11734]5.. todo::
[10279]9.. contents::
[10604]10   :local:
[10604]15| The NEMO source code is written in *Fortran 95* and
[11723]16  some of its prerequisite tools and libraries are already included in the download.
[10604]17| It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and
18  the IOIPSL_ library for parts of the output.
[10604]20System dependencies
[10604]23In the first place the other requirements should be provided natively by your system or
24can be installed from the official repositories of your Unix-like distribution:
[10604]26- *Perl* interpreter
27- *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...),
28- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_).
[11708]29- |NetCDF|_ library with its underlying |HDF|_
[10604]31**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.**
[10604]33.. hint::
[10604]35   The MPI implementation is not strictly essential
36   since it is possible to compile and run NEMO on a single processor.
37   However most realistic configurations will require the parallel capabilities of NEMO and
38   these use the MPI standard.
40.. note::
42   On older systems, that do not support MPI-3 features,
43   the ``key_mpi2`` preprocessor key should be used at compile time.
44   This will limit MPI features to those defined within the MPI-2 standard
45   (but will lose some performance benefits).
[11723]47.. |OpenMPI| replace:: *OpenMPI*
48.. _OpenMPI:
49.. |MPICH|   replace:: *MPICH*
50.. _MPICH:
51.. |NetCDF|  replace:: *Network Common Data Form (NetCDF)*
52.. _NetCDF:
53.. |HDF|     replace:: *Hierarchical Data Form (HDF)*
54.. _HDF:
[10604]56Specifics for NetCDF and HDF
[11723]59NetCDF and HDF versions from official repositories may have not been compiled with MPI support.
[10604]60However access to all the options available with the XIOS IO-server will require
[11723]61the parallelism of these libraries.
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
[11723]66  both NEMO and XIOS (see below) have been compiled and linked with.
68.. hint::
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
75   .. code-block:: console
77      $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
79   It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
81Particular versions of these libraries may have their own restrictions.
82State the following requirements for netCDF-4 support:
84.. caution::
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.
[10557]90Extract and install XIOS
[10604]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.
[11723]96It can be used in two different modes:
[11723]98:*attached*:  Every NEMO process also acts as a XIOS server
99:*detached*:  Every NEMO process runs as a XIOS client.
[10604]100  Output is collected and collated by external, stand-alone XIOS server processors.
[11723]102Instructions on how to install XIOS can be found on its :xios:`wiki<>`.
[10604]104.. hint::
[11723]106   It is recommended to use XIOS 2.5 release.
[10604]107   This version should be more stable (in terms of future code changes) than the XIOS trunk.
[11723]108   It is also the one used by the NEMO system team when testing all developments and new releases.
[11723]110   This particular version has its own branch and can be checked out with:
[10604]112   .. code:: console
[10991]114      $ svn co
[11723]116Download and install the NEMO code
[11723]119Checkout the NEMO sources
[10557]122.. code:: console
[10604]124   $ svn co
[11723]126Description of 1\ :sup:`st` level tree structure
130| :file:`arch`  | Compilation settings                   |
132| :file:`cfgs`  | :doc:`Reference configurations <cfgs>` |
134| :file:`doc`   | :doc:`Documentation <doc>`             |
136| :file:`ext`   | Dependencies included                  |
137|               | (``AGRIF``, ``FCM`` & ``IOIPSL``)      |
139| :file:`mk`    | Compilation scripts                    |
141| :file:`src`   | :doc:`Modelling routines <src>`        |
143| :file:`tests` | :doc:`Test cases <tests>`              |
144|               | (unsupported)                          |
146| :file:`tools` | :doc:`Utilities <tools>`               |
147|               | to {pre,post}process data              |
150Setup your architecture configuration file
[11723]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
[10557]162.. code-block:: sh
[11723]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
[11723]169Create and compile a new configuration
[11734]172The main script to {re}compile and create executable is called :file:`makenemo` located at
[11723]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':
[10187]177.. code-block:: sh
[11723]179   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
[11723]181Then at the end of the configuration compilation,
182:file:`MY_GYRE` directory will have the following structure.
185| Directory  | Purpose                                                                    |
187| ``BLD``    | BuiLD folder: target executable, headers, libs, preprocessed routines, ... |
189| ``EXP00``  | Run   folder: link to executable, namelists, ``*.xml`` and IOs             |
191| ``EXPREF`` | Files under version control only for :doc:`official configurations <cfgs>` |
193| ``MY_SRC`` | New routines or modified copies of NEMO sources                            |
195| ``WORK``   | Links to all raw routines from :file:`./src` considered                    |
[11734]198After successful execution of :file:`makenemo` command,
[11723]199the executable called `nemo` is available in the :file:`EXP00` directory
[11734]201More :file:`makenemo` options
[10604]204``makenemo`` has several other options that can control which source files are selected and
205the operation of the build process itself.
[11723]207.. literalinclude:: ../../../makenemo
208   :language: text
209   :lines: 119-143
210   :caption: Output of ``makenemo -h``
[10604]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:
217.. code-block:: sh
219        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
[11723]221will compile up to 8 processes simultaneously.
[9596]223Default behaviour
[11723]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.
232Tools used during the process
[11734]235* :file:``: 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
[11723]242.. literalinclude:: ../../../makenemo
243   :language: text
244   :lines: 146-153
[9596]246Running the model
[11734]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
[11723]252(namelists, ``*.xml`` files for the IOs, ...).
253If the configuration needs other input files, they have to be placed here.
[10558]255.. code-block:: sh
[11723]257   cd 'MY_CONFIG'/EXP00
258   mpirun -n $NPROCS ./nemo   # $NPROCS is the number of processes
259                              # mpirun is your MPI wrapper
[9596]261Viewing and changing list of active CPP keys
[11723]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`
[11734]267This text file can be edited by hand or with :file:`makenemo` to change the list of active CPP keys.
[11723]268Once changed, one needs to recompile ``nemo`` in order for this change to be taken in account.
[10558]269Note that most NEMO configurations will need to specify the following CPP keys:
[11723]270``key_iomput`` for IOs and ``key_mpp_mpi`` for parallelism.
Note: See TracBrowser for help on using the repository browser.