source: NEMO/trunk/INSTALL.rst @ 10558

Last change on this file since 10558 was 10558, checked in by acc, 19 months ago

Update of INSTALL.rst

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|
16- Other requirements that your system needs to provide include: a Perl 5 interpreter; a modern
17  Fortran compiler (ifort, gfortran, pgfortran, ...) and (in most cases) a MPI library
18  (e.g. OpenMPI or MPICH). The latter is not strictly essential since it is possible
19  to compile and run NEMO on a single processor. However most realistic configurations
20  will require the parallel capabilities of NEMO and these use the Message Passing
21  Interface (MPI) library. NEMO v4.0, by default, uses some MPI features introduced
22  into the MPI-3 standard. On older systems, that do not support these features,
23  the key_mpi2 preprocessor key should be used at compile time. This will limit MPI
24  features to those defined within the MPI-2 standard (but will lose some performance
25  benefits).
26|
27The following prerequisites may already be installed or be available from the
28official repositories of your Linux distribution. However access to all the
29options available with the XIOS IO-server will require the parallel form of the
30netcdf4 library and its underlying HDF5 library. It is also necessary to compile
31these libraries with the same version of the MPI library that both NEMO and XIOS
32(see below) are compiled and linked with. To satisfy these requirements, it is common
33to have to compile the following from source.
34
35- `HDF5`_   (C library) (use: --enable-fortran --enable-parallel with configure)
36- `NetCDF4`_ (C and Fortran libraries)
37
38Note that particular versions of these libraries may have their own
39restrictions. For example, the latest versions of the netCDF libraries:
40netcdf-c-4.6.2 and netcdf-fortran-4.4.4, state the following requirements for netCDF-4 support:
41
42* HDF5 1.8.9 or later.
43* HDF5 1.10.1 or later.
44* zlib 1.2.5 or later (for netCDF-4 compression)
45* curl 7.18.0 or later (for DAP remote access client support)
46
47|
48`Important Note: When building netCDF-C library versions older than 4.4.1,
49use only HDF5 1.8.x versions. Combining older netCDF-C versions with newer
50HDF5 1.10 versions will create superblock 3 files that are not readable by
51lots of older software.`
52
53Extract and install XIOS
54========================
55
56With the sole exception of running NEMO in mono-processor mode (in which case
57output options are limited to those supported by the IOIPSL library), diagnostic
58outputs from NEMO are handled by the third party XIOS library. This can be used
59in two different modes:
60
61* attached - Every NEMO process also acts as a XIOS server
62* dettached - Every NEMO process runs as a XIOS client. Output is collected and collated by external,
63  stand-alone XIOS server processors.
64
65In either case, it is important to note that XIOS needs to be compiled before
66NEMO, since the libraries are needed to successfully create the NEMO executable.
67
68Instructions on how to obtain and install the software can be found on the `XIOS Wiki`_ .
69
70It is recommended to use XIOS version 2.5 with NEMOv4.0. This version should be more stable (in terms of
71future code changes) than the XIOS trunk. It is also the version used by the NEMO system team when
72testing all developments and new releases. This particular version has its own branch and can be
73checked out and downloaded with:
74
75.. code:: console
76
77        $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
78
79Download the NEMO source code
80=============================
81
82.. code:: console
83
84   $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0
85
86Description of directory tree
87-----------------------------
88
89+-----------+------------------------------------------------------------+
90| Folder    | Purpose                                                    |
91+===========+============================================================+
92| ``arch``  | Settings (per architecture-compiler pair)                  |
93+-----------+------------------------------------------------------------+
94| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
95+-----------+------------------------------------------------------------+
96| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
97|           | - ``namelists``: k start guide                             |
98|           | - ``rst``:   quick start guide                             |
99+-----------+------------------------------------------------------------+
100| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
101+-----------+------------------------------------------------------------+
102| ``mk``    | Building  routines                                         |
103+-----------+------------------------------------------------------------+
104| ``src``   | Modelling routines                                         |
105|           |                                                            |
106|           | - ``ICE``: |SI3| for sea ice                               |
107|           | - ``NST``: AGRIF for embedded zooms                        |
108|           | - ``OCE``: |OPA| for ocean dynamics                        |
109|           | - ``TOP``: |TOP| for tracers                               |
110+-----------+------------------------------------------------------------+
111| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
112+-----------+------------------------------------------------------------+
113| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
114+-----------+------------------------------------------------------------+
115
116Setup your architecture configuration file
117==========================================
118
119All compiler options in NEMO are controlled using files in
120NEMOGCM/ARCH/arch-'my_arch'.fcm where 'my_arch' is the name of the computing
121architecture.  It is recommended to copy and rename an configuration file from
122an architecture similar to your owns. You will need to set appropriate values
123for all of the variables in the file. In particular the FCM variables:
124``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to the
125installation directories used for XIOS installation.
126
127.. code-block:: sh
128
129        %NCDF_HOME           /opt/local
130        %HDF5_HOME           /opt/local
131        %XIOS_HOME           /Users/$( whoami )/xios-2.5
132        %OASIS_HOME          /not/defined
133
134Compile and create NEMO executable
135==================================
136
137The 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.
138As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
139
140.. code-block:: sh
141
142   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
143
144The 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).
145
146+------------+----------------------------------------------------+
147| Folder     | Purpose                                            |
148+============+====================================================+
149| ``BLD``    |                                                    |
150+------------+----------------------------------------------------+
151| ``EXP00``  |                                                    |
152+------------+----------------------------------------------------+
153| ``EXPREF`` |                                                    |
154+------------+----------------------------------------------------+
155| ``MY_SRC`` |                                                    |
156+------------+----------------------------------------------------+
157| ``WORK``   |                                                    |
158+------------+----------------------------------------------------+
159
160Folder with the symbolic links to all unpreprocessed routines considered in the configuration
161Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
162Computation folder for running the model (namelists, xml, executables and inputs-outputs)
163Folder intended to contain your customised routines (modified from initial ones or new entire routines)
164
165After 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).
166
167More makenemo options
168---------------------
169
170``makenemo`` has several other options that can control which source files are selected and the operation
171of the build process itself. These are:
172
173.. code-block:: sh
174
175        Optional:
176           -d   Set of new sub-components (space separated list from ./src directory)
177           -e   Path for alternative patch  location (default: 'MY_SRC' in configuration folder)
178           -h   Print this help
179           -j   Number of processes to compile (0: no build)
180           -n   Name for new configuration
181           -s   Path for alternative source location (default: 'src' root directory)
182           -t   Path for alternative build  location (default: 'BLD' in configuration folder)
183           -v   Level of verbosity ([0-3])
184
185These options can be useful for maintaining several code versions with only minor differences but they
186should be used sparingly. Note however the ``-j`` option which should be used more routinely to speed up
187the build process. For example:
188
189.. code-block:: sh
190
191        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
192
193which will compile up to 8 modules simultaneously.
194
195
196Default behaviour
197-----------------
198
199At the first use, you need the -m option to specify the architecture
200configuration file (compiler and its options, routines and libraries to
201include), then for next compilation, it is assumed you will be using the
202same compiler.  If the –n option is not specified the last compiled configuration
203will be used.
204
205Tools used during the process
206-----------------------------
207
208*   functions.sh : bash functions used by makenemo, for instance to create the WORK directory
209*   cfg.txt : text list of configurations and source directories
210*   bld.cfg : FCM rules to compile
211
212Examples
213--------
214
215.. code-block:: sh
216
217        echo "Example to install a new configuration MY_CONFIG";
218        echo "with OPA_SRC and LIM_SRC_2 ";
219        echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\"";
220        echo "";
221        echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt;
222        echo "";
223        echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt;
224        echo "";
225        echo "Example to remove bad configuration ";
226        echo "./makenemo -n MY_CONFIG clean_config";
227        echo "";
228        echo "Example to clean ";
229        echo "./makenemo clean";
230        echo "";
231        echo "Example to list the available keys of a CONFIG ";
232        echo "./makenemo list_key";
233        echo "";
234        echo "Example to add and remove keys";
235        echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
236        echo "";
237        echo "Example to add and remove keys for a new configuration, and do not compile";
238        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
239
240Running the model
241=================
242
243Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
244For 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
245
246.. code-block:: sh
247
248        cd 'MY_CONFIG'/EXP00
249        mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
250
251
252Viewing and changing list of active CPP keys
253============================================
254
255For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in:
256
257.. code-block:: sh
258
259        NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
260
261
262This 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.
263Note that most NEMO configurations will need to specify the following CPP keys:
264
265*   key_iomput
266*   key_mpp_mpi
267
268
269.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5
270.. _NetCDF4: http://www.unidata.ucar.edu/downloads/netcdf
271.. _XIOS Wiki:    http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
272.. _XIOSSRC: http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
Note: See TracBrowser for help on using the repository browser.