source: NEMO/trunk/INSTALL.rst @ 10448

Last change on this file since 10448 was 10279, checked in by nicolasmartin, 2 years ago

Various improvments for quick start guide

  • implementation of Rtd theme (Read the Docs) with custom layout and style file
  • add reviewed BibTeX entries for NEMO references with DOI (manuals, guide, development strategy)
  • enhancement of bibliography management and configuration file for guide building
  • standardisation of headings markup
  • numerous edits
File size: 9.2 KB
Line 
1*********************
2Install the framework
3*********************
4
5.. contents::
6   :local:
7     
8Dependencies
9============
10
11| The NEMO source code is written in Fortran 95 and part of its dependencies are already included (``./ext``):
12  AGRIF preprocessing program "conv", FCM build system and IOIPSL library for outputs.
13| And some Perl 5, Fortran compiler (ifort, gfortran, pgfortran, ...), MPI library (Open MPI or MPICH)
14
15But The following dependencies should be from the official repositories of your Linux distribution but
16you will probably have to compile them from source for enabling parallel I/O support.
17
18- `HDF5`_   (C library)
19- `NetCDF`_ (C and Fortran libraries)
20
21Extract the source code
22=======================
23
24Download the source code
25------------------------
26
27.. code:: console
28
29   $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0
30
31Description of directory tree
32-----------------------------
33
34+-----------+------------------------------------------------------------+
35| Folder    | Purpose                                                    |
36+===========+============================================================+
37| ``arch``  | Settings (per architecture-compiler pair)                  |
38+-----------+------------------------------------------------------------+
39| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
40+-----------+------------------------------------------------------------+
41| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
42|           | - ``namelists``: k start guide                             |
43|           | - ``rst``:   quick start guide                             |
44+-----------+------------------------------------------------------------+
45| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
46+-----------+------------------------------------------------------------+
47| ``mk``    | Building  routines                                         |
48+-----------+------------------------------------------------------------+
49| ``src``   | Modelling routines                                         |
50|           |                                                            |
51|           | - ``ICE``: |SI3| for sea ice                               |
52|           | - ``NST``: AGRIF for embedded zooms                        |
53|           | - ``OCE``: |OPA| for ocean dynamics                        |
54|           | - ``MBG``: |TOP| for tracers                               |
55+-----------+------------------------------------------------------------+
56| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
57+-----------+------------------------------------------------------------+
58| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
59+-----------+------------------------------------------------------------+
60
61Extract and install XIOS
62========================
63
64Diagnostic outputs from NEMO are handled by the third party XIOS library.
65
66Important notice: XIOS needs to be compiled before NEMO, since the libraries are needed to successfully create NEMO executable.
67Instructions on how to obtain and install the software, see Users/Model Interfacing/Inputs Outputs.
68
69When you compile NEMO you will need to specify the following CPP keys:
70 
71    key_iomput
72    key_mpp_mpi (if you want to run with multiple processes and/or use "detached mode" for the IOs system XIOS)
73    for nemo_v3_6_STABLE only: you can add key_xios2 if you wish to use the most recent XIOS2 release of XIOS. Doing so, you will have to change the xml files used as input for XIOS : in this release, the xml files are only XIOS1 compatible. If you add key_xios2 you can use xml files located in GYRE_XIOS/EXP00 as first templates. In future releases of NEMO XIOS2 will be the default XIOS release in use.
74
75Setup your architecture configuration file
76==========================================
77
78All compiler options in NEMO are controlled using files in NEMOGCM/ARCH/arch-'my_arch'.fcm where 'my_arch' is the name of the computing architecture.
79It is recommended to copy and rename an configuration file from an architecture similar to your owns. You will need to set appropriate values for all of the variables in the file. In particular the FCM variables %NCDF_HOME, %HDF5_HOME and %XIOS_HOME should be set to the installation directories used for XIOS installation.
80
81%NCDF_HOME           /opt/local
82%HDF5_HOME           /opt/local
83%XIOS_HOME           /Users/$( whoami )/xios-1.0
84%OASIS_HOME          /not/defined
85
86Compile and create NEMO executable
87==================================
88
89The 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.
90As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
91
92.. code-block:: sh
93
94   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
95
96The 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).
97
98+------------+----------------------------------------------------+
99| Folder     | Purpose                                            |
100+============+====================================================+
101| ``BLD``    |                                                    |
102+------------+----------------------------------------------------+
103| ``EXP00``  |                                                    |
104+------------+----------------------------------------------------+
105| ``EXPREF`` |                                                    |
106+------------+----------------------------------------------------+
107| ``MY_SRC`` |                                                    |
108+------------+----------------------------------------------------+
109| ``WORK``   |                                                    |
110+------------+----------------------------------------------------+
111
112Folder with the symbolic links to all unpreprocessed routines considered in the configuration
113Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
114Computation folder for running the model (namelists, xml, executables and inputs-outputs)
115Folder intended to contain your customised routines (modified from initial ones or new entire routines)
116
117After 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).
118More options
119
120..
121   .. literalinclude::
122
123Default behaviour
124-----------------
125
126    At the first use, you need the -m option to specify the architecture configuration file (compiler and its options, routines and libraries to include), then for next compilation, it is assumed you will be using the same compiler.
127    If –n option is not specified, ORCA2_LIM is the default configuration used.
128
129Tools used during the process
130-----------------------------
131
132    functions.sh : bash functions used by makenemo, for instance to create the WORK directory
133    cfg.txt : text list of configurations and source directories
134    bld.cfg : FCM rules to compile
135
136Examples
137--------
138
139        echo "Example to install a new configuration MY_CONFIG";
140        echo "with OPA_SRC and LIM_SRC_2 ";
141        echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\"";
142        echo "";
143        echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt;
144        echo "";
145        echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt;
146        echo "";
147        echo "Example to remove bad configuration ";
148        echo "./makenemo -n MY_CONFIG clean_config";
149        echo "";
150        echo "Example to clean ";
151        echo "./makenemo clean";
152        echo "";
153        echo "Example to list the available keys of a CONFIG ";
154        echo "./makenemo list_key";
155        echo "";
156        echo "Example to add and remove keys";
157        echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
158        echo "";
159        echo "Example to add and remove keys for a new configuration, and do not compile";
160        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
161
162Running the model
163=================
164
165Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
166For 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
167
168   cd 'MY_CONFIG'/EXP00
169   mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
170
171Viewing and changing list of active CPP keys
172============================================
173
174For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in::
175
176   NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
177
178This 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.
179
180.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5
181.. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf
Note: See TracBrowser for help on using the repository browser.