source: NEMO/trunk/INSTALL.rst @ 10596

Last change on this file since 10596 was 10596, checked in by nicolasmartin, 19 months ago

Fixes for a unsuccessful Python Sphinx building, no more warnings but still crashing

File size: 12.7 KB
Line 
1*****************************
2Obtaining and installing NEMO
3*****************************
4
5.. contents::
6   :local:
7     
8Prerequisites
9=============
10
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
26The following prerequisites may already be installed or be available from the
27official repositories of your Linux distribution. However access to all the
28options available with the XIOS IO-server will require the parallel form of the
29netcdf4 library and its underlying HDF5 library. It is also necessary to compile
30these 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
32to 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
37Note that particular versions of these libraries may have their own
38restrictions. For example, the latest versions of the netCDF libraries:
39netcdf-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,
47use only HDF5 1.8.x versions. Combining older netCDF-C versions with newer
48HDF5 1.10 versions will create superblock 3 files that are not readable by
49lots of older software.`
50
51Extract and install XIOS
52========================
53
54With the sole exception of running NEMO in mono-processor mode (in which case
55output options are limited to those supported by the IOIPSL library), diagnostic
56outputs from NEMO are handled by the third party XIOS library. This can be used
57in 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
63In either case, it is important to note that XIOS needs to be compiled before
64NEMO, since the libraries are needed to successfully create the NEMO executable.
65
66Instructions on how to obtain and install the software can be found on the `XIOS Wiki`_ .
67
68It is recommended to use XIOS version 2.5 with NEMOv4.0. This version should be more stable (in terms of
69future code changes) than the XIOS trunk. It is also the version used by the NEMO system team when
70testing all developments and new releases. This particular version has its own branch and can be
71checked out and downloaded with:
72
73.. code:: console
74
75        $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
76
77Download the NEMO source code
78=============================
79
80.. code:: console
81
82   $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0
83
84Description of directory tree
85-----------------------------
86
87+-----------+------------------------------------------------------------+
88| Folder    | Purpose                                                    |
89+===========+============================================================+
90| ``arch``  | Settings (per architecture-compiler pair)                  |
91+-----------+------------------------------------------------------------+
92| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
93+-----------+------------------------------------------------------------+
94| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
95|           | - ``namelists``: k start guide                             |
96|           | - ``rst``:   quick start guide                             |
97+-----------+------------------------------------------------------------+
98| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
99+-----------+------------------------------------------------------------+
100| ``mk``    | Building  routines                                         |
101+-----------+------------------------------------------------------------+
102| ``src``   | Modelling routines                                         |
103|           |                                                            |
104|           | - ``ICE``: |SI3| for sea ice                               |
105|           | - ``NST``: AGRIF for embedded zooms                        |
106|           | - ``OCE``: |OPA| for ocean dynamics                        |
107|           | - ``TOP``: |TOP| for tracers                               |
108+-----------+------------------------------------------------------------+
109| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
110+-----------+------------------------------------------------------------+
111| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
112+-----------+------------------------------------------------------------+
113
114Setup your architecture configuration file
115==========================================
116
117All compiler options in NEMO are controlled using files in
118trunk/arch/arch-'my_arch'.fcm where 'my_arch' is the name of the computing
119architecture.  It is recommended to copy and rename an configuration file from
120an architecture similar to your owns. You will need to set appropriate values
121for all of the variables in the file. In particular the FCM variables:
122``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to the
123installation directories used for XIOS installation.
124
125.. code-block:: sh
126
127        %NCDF_HOME           /opt/local
128        %HDF5_HOME           /opt/local
129        %XIOS_HOME           /Users/$( whoami )/xios-2.5
130        %OASIS_HOME          /not/defined
131
132Compile and create NEMO executable
133==================================
134
135The 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.
136As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
137
138.. code-block:: sh
139
140   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
141
142The 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).
143
144+------------+----------------------------------------------------+
145| Folder     | Purpose                                            |
146+============+====================================================+
147| ``BLD``    |                                                    |
148+------------+----------------------------------------------------+
149| ``EXP00``  |                                                    |
150+------------+----------------------------------------------------+
151| ``EXPREF`` |                                                    |
152+------------+----------------------------------------------------+
153| ``MY_SRC`` |                                                    |
154+------------+----------------------------------------------------+
155| ``WORK``   |                                                    |
156+------------+----------------------------------------------------+
157
158Folder with the symbolic links to all unpreprocessed routines considered in the configuration
159Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
160Computation folder for running the model (namelists, xml, executables and inputs-outputs)
161Folder intended to contain your customised routines (modified from initial ones or new entire routines)
162
163After 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).
164
165More makenemo options
166---------------------
167
168``makenemo`` has several other options that can control which source files are selected and the operation
169of 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
183These options can be useful for maintaining several code versions with only minor differences but they
184should be used sparingly. Note however the ``-j`` option which should be used more routinely to speed up
185the build process. For example:
186
187.. code-block:: sh
188
189        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
190
191which will compile up to 8 modules simultaneously.
192
193
194Default behaviour
195-----------------
196
197At the first use, you need the -m option to specify the architecture
198configuration file (compiler and its options, routines and libraries to
199include), then for next compilation, it is assumed you will be using the
200same compiler.  If the –n option is not specified the last compiled configuration
201will be used.
202
203Tools used during the process
204-----------------------------
205
206*   functions.sh : bash functions used by makenemo, for instance to create the WORK directory
207*   cfg.txt : text list of configurations and source directories
208*   bld.cfg : FCM rules to compile
209
210Examples
211--------
212
213.. code-block:: sh
214
215        echo "Example to install a new configuration MY_CONFIG";
216        echo "with OPA_SRC and LIM_SRC_2 ";
217        echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\"";
218        echo "";
219        echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt;
220        echo "";
221        echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt;
222        echo "";
223        echo "Example to remove bad configuration ";
224        echo "./makenemo -n MY_CONFIG clean_config";
225        echo "";
226        echo "Example to clean ";
227        echo "./makenemo clean";
228        echo "";
229        echo "Example to list the available keys of a CONFIG ";
230        echo "./makenemo list_key";
231        echo "";
232        echo "Example to add and remove keys";
233        echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
234        echo "";
235        echo "Example to add and remove keys for a new configuration, and do not compile";
236        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
237
238Running the model
239=================
240
241Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
242For 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
243
244.. code-block:: sh
245
246        cd 'MY_CONFIG'/EXP00
247        mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
248
249
250Viewing and changing list of active CPP keys
251============================================
252
253For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in:
254
255.. code-block:: sh
256
257        trunk/cfgs/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
258
259
260This 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.
261Note 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
Note: See TracBrowser for help on using the repository browser.