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/releases/release-4.0.1 – NEMO

source: NEMO/releases/release-4.0.1/INSTALL.rst @ 11698

Last change on this file since 11698 was 11698, checked in by nicolasmartin, 5 years ago

Modify the release version accordingly (trunk -> release-4.0.1)

File size: 13.1 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 ``./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
77Extract and install XIOS
78========================
79
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 https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
107
108Download the NEMO source code
109=============================
110
111.. code:: console
112
113   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0.1
114
115Description 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
145Setup your architecture configuration file
146==========================================
147
148All compiler options in NEMO are controlled using files in
149``./arch/arch-'my_arch'.fcm`` where 'my_arch' is the name of the computing
150architecture.  It is recommended to copy and rename an configuration file from
151an architecture similar to your owns. You will need to set appropriate values
152for 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
154installation 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
163Compile and create NEMO executable
164==================================
165
166The 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.
167As 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
173The 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
189Folder with the symbolic links to all unpreprocessed routines considered in the configuration
190Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
191Computation folder for running the model (namelists, xml, executables and inputs-outputs)
192Folder intended to contain your customised routines (modified from initial ones or new entire routines)
193
194After 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
196More makenemo options
197---------------------
198
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:
217
218.. code-block:: sh
219
220        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
221
222which will compile up to 8 modules simultaneously.
223
224
225Default behaviour
226-----------------
227
228At the first use, you need the -m option to specify the architecture
229configuration file (compiler and its options, routines and libraries to
230include), then for next compilation, it is assumed you will be using the
231same compiler.  If the –n option is not specified the last compiled configuration
232will be used.
233
234Tools 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
241Examples
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
269Running the model
270=================
271
272Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
273For 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
281Viewing and changing list of active CPP keys
282============================================
283
284For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in:
285
286.. code-block:: sh
287
288        ./cfgs/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
289
290
291This 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.
292Note that most NEMO configurations will need to specify the following CPP keys:
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
Note: See TracBrowser for help on using the repository browser.