source: NEMO/trunk/INSTALL.rst @ 11723

Last change on this file since 11723 was 11723, checked in by nicolasmartin, 15 months ago

Review of INSTALL.rst

File size: 10.6 KB
Line 
1*******************
2Build the framework
3*******************
4
5.. contents::
6   :local:
7
8Prerequisites
9=============
10
11| The NEMO source code is written in *Fortran 95* and
12  some of its prerequisite tools and libraries are already included in the download.
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
43.. |OpenMPI| replace:: *OpenMPI*
44.. _OpenMPI: https://www.open-mpi.org
45.. |MPICH|   replace:: *MPICH*
46.. _MPICH:   https://www.mpich.org
47.. |NetCDF|  replace:: *Network Common Data Form (NetCDF)*
48.. _NetCDF:  https://www.unidata.ucar.edu
49.. |HDF|     replace:: *Hierarchical Data Form (HDF)*
50.. _HDF:     https://www.hdfgroup.org
51
52Specifics for NetCDF and HDF
53----------------------------
54
55NetCDF and HDF versions from official repositories may have not been compiled with MPI support.
56However access to all the options available with the XIOS IO-server will require
57the parallelism of these libraries.
58
59| **To satisfy these requirements, it is common to have to compile from source
60  in this order HDF (C library) then NetCDF (C and Fortran libraries)**
61| It is also necessary to compile these libraries with the same version of the MPI implementation that
62  both NEMO and XIOS (see below) have been compiled and linked with.
63
64.. hint::
65
66   | It is difficult to define the options for the compilation as
67     they differ from one architecture to another according to
68     the hardware used and the software installed.
69   | The following is provided without any warranty
70
71   .. code-block:: console
72
73      $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
74
75   It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
76
77Particular versions of these libraries may have their own restrictions.
78State the following requirements for netCDF-4 support:
79
80.. caution::
81
82   | When building NetCDF-C library versions older than 4.4.1, use only HDF5 1.8.x versions.
83   | Combining older NetCDF-C versions with newer HDF5 1.10 versions will create superblock 3 files
84     that are not readable by lots of older software.
85
86Extract and install XIOS
87========================
88
89With the sole exception of running NEMO in mono-processor mode
90(in which case output options are limited to those supported by the ``IOIPSL`` library),
91diagnostic outputs from NEMO are handled by the third party ``XIOS`` library.
92It can be used in two different modes:
93
94:*attached*:  Every NEMO process also acts as a XIOS server
95:*detached*:  Every NEMO process runs as a XIOS client.
96  Output is collected and collated by external, stand-alone XIOS server processors.
97
98Instructions on how to install XIOS can be found on its :xios:`wiki<>`.
99
100.. hint::
101
102   It is recommended to use XIOS 2.5 release.
103   This version should be more stable (in terms of future code changes) than the XIOS trunk.
104   It is also the one used by the NEMO system team when testing all developments and new releases.
105
106   This particular version has its own branch and can be checked out with:
107
108   .. code:: console
109
110      $ svn co https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
111
112Download and install the NEMO code
113==================================
114
115Checkout the NEMO sources
116-------------------------
117
118.. code:: console
119
120   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk
121
122Description of 1\ :sup:`st` level tree structure
123------------------------------------------------
124
125+-----------+----------------------------------------+
126| ``arch``  | Compilation settings                   |
127+-----------+----------------------------------------+
128| ``cfgs``  | :doc:`Reference configurations <cfgs>` |
129+-----------+----------------------------------------+
130| ``doc``   | :doc:`Documentation <doc>`             |
131+-----------+----------------------------------------+
132| ``ext``   | Dependencies included                  |
133|           | (``AGRIF``, ``FCM`` & ``IOIPSL``)      |
134+-----------+----------------------------------------+
135| ``mk``    | Compilation scripts                    |
136+-----------+----------------------------------------+
137| ``src``   | :doc:`Modelling routines <src>`        |
138+-----------+----------------------------------------+
139| ``tests`` | :doc:`Test cases <tests>`              |
140|           | (unsupported)                          |
141+-----------+----------------------------------------+
142| ``tools`` | :doc:`Utilities <tools>`               |
143|           | to {pre,post}process data              |
144+-----------+----------------------------------------+
145
146Setup your architecture configuration file
147------------------------------------------
148
149All compiler options in NEMO are controlled using files in :file:`./arch/arch-'my_arch'.fcm` where
150``my_arch`` is the name of the computing architecture
151(generally following the pattern ``HPCC-compiler`` or ``OS-compiler``).
152It is recommended to copy and rename an configuration file from an architecture similar to your owns.
153You will need to set appropriate values for all of the variables in the file.
154In particular the FCM variables:
155``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to
156the installation directories used for XIOS installation
157
158.. code-block:: sh
159
160   %NCDF_HOME    /usr/local/path/to/netcdf
161   %HDF5_HOME    /usr/local/path/to/hdf5
162   %XIOS_HOME    /home/$( whoami )/path/to/xios-2.5
163   %OASIS_HOME   /home/$( whoami )/path/to/oasis
164
165Create and compile a new configuration
166======================================
167
168The main script to {re}compile and create executable is called ``makenemo`` located at
169the root of the working copy.
170It is used to identify the routines you need from the source code, to build the makefile and run it.
171As an example, compile a :file:`MY_GYRE` configuration from GYRE with 'my_arch':
172
173.. code-block:: sh
174
175   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
176
177Then at the end of the configuration compilation,
178:file:`MY_GYRE` directory will have the following structure.
179
180+------------+----------------------------------------------------------------------------+
181| Directory  | Purpose                                                                    |
182+============+============================================================================+
183| ``BLD``    | BuiLD folder: target executable, headers, libs, preprocessed routines, ... |
184+------------+----------------------------------------------------------------------------+
185| ``EXP00``  | Run   folder: link to executable, namelists, ``*.xml`` and IOs             |
186+------------+----------------------------------------------------------------------------+
187| ``EXPREF`` | Files under version control only for :doc:`official configurations <cfgs>` |
188+------------+----------------------------------------------------------------------------+
189| ``MY_SRC`` | New routines or modified copies of NEMO sources                            |
190+------------+----------------------------------------------------------------------------+
191| ``WORK``   | Links to all raw routines from :file:`./src` considered                    |
192+------------+----------------------------------------------------------------------------+
193
194After successful execution of ``makenemo`` command,
195the executable called `nemo` is available in the :file:`EXP00` directory
196
197More ``makenemo`` options
198-------------------------
199
200``makenemo`` has several other options that can control which source files are selected and
201the operation of the build process itself.
202
203.. literalinclude:: ../../../makenemo
204   :language: text
205   :lines: 119-143
206   :caption: Output of ``makenemo -h``
207
208These options can be useful for maintaining several code versions with only minor differences but
209they should be used sparingly.
210Note however the ``-j`` option which should be used more routinely to speed up the build process.
211For example:
212
213.. code-block:: sh
214
215        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
216
217will compile up to 8 processes simultaneously.
218
219Default behaviour
220-----------------
221
222At the first use,
223you need the ``-m`` option to specify the architecture configuration file
224(compiler and its options, routines and libraries to include),
225then for next compilation, it is assumed you will be using the same compiler.
226If the ``-n`` option is not specified the last compiled configuration will be used.
227
228Tools used during the process
229-----------------------------
230
231* ``functions.sh`` : bash functions used by ``makenemo``, for instance to create the WORK directory
232* ``cfg.txt`` : text list of configurations and source directories
233* ``bld.cfg`` : FCM rules to compile
234
235Examples
236--------
237
238.. literalinclude:: ../../../makenemo
239   :language: text
240   :lines: 146-153
241
242Running the model
243=================
244
245Once ``makenemo`` has run successfully,
246the ``nemo`` executable is available in ``./cfgs/MY_CONFIG/EXP00``.
247For the reference configurations, the ``EXP00`` folder also contains the initial input files
248(namelists, ``*.xml`` files for the IOs, ...).
249If the configuration needs other input files, they have to be placed here.
250
251.. code-block:: sh
252
253   cd 'MY_CONFIG'/EXP00
254   mpirun -n $NPROCS ./nemo   # $NPROCS is the number of processes
255                              # mpirun is your MPI wrapper
256
257Viewing and changing list of active CPP keys
258============================================
259
260For a given configuration (here called ``MY_CONFIG``),
261the list of active CPP keys can be found in :file:`./cfgs/'MYCONFIG'/cpp_MY_CONFIG.fcm`
262
263This text file can be edited by hand or with ``makenemo`` to change the list of active CPP keys.
264Once changed, one needs to recompile ``nemo`` in order for this change to be taken in account.
265Note that most NEMO configurations will need to specify the following CPP keys:
266``key_iomput`` for IOs and ``key_mpp_mpi`` for parallelism.
Note: See TracBrowser for help on using the repository browser.