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.
INSTALL.rst in NEMO/trunk – NEMO

source: NEMO/trunk/INSTALL.rst @ 13688

Last change on this file since 13688 was 13688, checked in by clevy, 3 years ago

update online users guide to point on 4.0.4 for install

File size: 10.8 KB
Line 
1*******************
2Build the framework
3*******************
4
5.. todo::
6
7
8
9.. contents::
10   :local:
11
12Prerequisites
13=============
14
15| The NEMO source code is written in *Fortran 95* and
16  some of its prerequisite tools and libraries are already included in the download.
17| It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and
18  the IOIPSL_ library for parts of the output.
19
20System dependencies
21-------------------
22
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:
25
26- *Perl* interpreter
27- *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...),
28- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_).
29- |NetCDF|_ library with its underlying |HDF|_
30
31**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.**
32
33.. hint::
34
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.
39
40.. note::
41
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).
46
47.. |OpenMPI| replace:: *OpenMPI*
48.. _OpenMPI: https://www.open-mpi.org
49.. |MPICH|   replace:: *MPICH*
50.. _MPICH:   https://www.mpich.org
51.. |NetCDF|  replace:: *Network Common Data Form (NetCDF)*
52.. _NetCDF:  https://www.unidata.ucar.edu
53.. |HDF|     replace:: *Hierarchical Data Form (HDF)*
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/releases/r4.0/r4.0.4
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.
Note: See TracBrowser for help on using the repository browser.