Changeset 10604
- Timestamp:
- 2019-01-29T15:48:21+01:00 (6 years ago)
- Location:
- NEMO/trunk
- Files:
-
- 3 edited
Legend:
- Unmodified
- Added
- Removed
-
NEMO/trunk/INSTALL.rst
r10596 r10604 1 ******************* **********2 Obtaining and installing NEMO 3 ******************* **********1 ******************* 2 Build the framework 3 ******************* 4 4 5 5 .. contents:: 6 7 6 :local: 7 8 8 Prerequisites 9 9 ============= 10 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 26 The following prerequisites may already be installed or be available from the 27 official repositories of your Linux distribution. However access to all the 28 options available with the XIOS IO-server will require the parallel form of the 29 netcdf4 library and its underlying HDF5 library. It is also necessary to compile 30 these 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 32 to 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 37 Note that particular versions of these libraries may have their own 38 restrictions. For example, the latest versions of the netCDF libraries: 39 netcdf-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, 47 use only HDF5 1.8.x versions. Combining older netCDF-C versions with newer 48 HDF5 1.10 versions will create superblock 3 files that are not readable by 49 lots of older software.` 50 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 16 System dependencies 17 ------------------- 18 19 In the first place the other requirements should be provided natively by your system or 20 can 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 43 Specifics for NetCDF and HDF 44 ---------------------------- 45 46 NetCDF and HDF versions from . 47 However access to all the options available with the XIOS IO-server will require 48 the 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 68 Particular versions of these libraries may have their own restrictions. 69 State 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 51 77 Extract and install XIOS 52 78 ======================== 53 79 54 With the sole exception of running NEMO in mono-processor mode (in which case 55 output options are limited to those supported by the IOIPSL library), diagnostic 56 outputs from NEMO are handled by the third party XIOS library. This can be used 57 in 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 63 In either case, it is important to note that XIOS needs to be compiled before 64 NEMO, since the libraries are needed to successfully create the NEMO executable. 65 66 Instructions on how to obtain and install the software can be found on the `XIOS Wiki`_ . 67 68 It is recommended to use XIOS version 2.5 with NEMOv4.0. This version should be more stable (in terms of 69 future code changes) than the XIOS trunk. It is also the version used by the NEMO system team when 70 testing all developments and new releases. This particular version has its own branch and can be 71 checked out and downloaded with: 72 73 .. code:: console 74 75 $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 80 With 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), 82 diagnostic outputs from NEMO are handled by the third party ``XIOS`` library. 83 This 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 94 Instructions 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 http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 76 107 77 108 Download the NEMO source code … … 80 111 .. code:: console 81 112 82 $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0 113 $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk 83 114 84 115 Description of directory tree … … 92 123 | ``cfgs`` | :doc:`Reference configurations <configurations>` | 93 124 +-----------+------------------------------------------------------------+ 94 | ``doc`` | - ``latex`` : reference manuals for |OPA|, |SI3| & |TOP||125 | ``doc`` | - ``latex`` : LaTex source code for ref. manuals | 95 126 | | - ``namelists``: k start guide | 96 | | - ``rst`` : quick start guide|97 +-----------+------------------------------------------------------------+ 98 | ``ext`` | Dependencies included ( AGRIF, FCM & IOIPSL)|127 | | - ``rst`` : ReST files for quick start guide | 128 +-----------+------------------------------------------------------------+ 129 | ``ext`` | Dependencies included (``AGRIF``, ``FCM`` & ``IOIPSL``) | 99 130 +-----------+------------------------------------------------------------+ 100 131 | ``mk`` | Building routines | … … 166 197 --------------------- 167 198 168 ``makenemo`` has several other options that can control which source files are selected and the operation169 of 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 help177 -j Number of processes to compile (0: no build)178 -n Name for new configuration179 -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 183 These options can be useful for maintaining several code versions with only minor differences but they 184 should be used sparingly. Note however the ``-j`` option which should be used more routinely to speed up 185 the build process.For example:199 ``makenemo`` has several other options that can control which source files are selected and 200 the operation of the build process itself. 201 These 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 213 These options can be useful for maintaining several code versions with only minor differences but 214 they should be used sparingly. 215 Note however the ``-j`` option which should be used more routinely to speed up the build process. 216 For example: 186 217 187 218 .. code-block:: sh … … 260 291 This 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. 261 292 Note 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 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 -
NEMO/trunk/doc/rst/Makefile
r10186 r10604 19 19 %: Makefile 20 20 @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 22 # Watch source directory and rebuild the documentation when a change is detected 23 # Browse to 127.0.0.1:8000/NEMO_guide.html 24 htmllive: 25 sphinx-autobuild $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html -
NEMO/trunk/doc/rst/source/global.rst
r10596 r10604 25 25 .. Models / Softwares 26 26 27 .. _AGRIF: https://agrif.imag.fr 28 .. _OASIS: https://portal.enes.org/oasis 29 .. _XIOS: https://forge.ipsl.jussieu.fr/ioserver 27 .. _AGRIF: http://agrif.imag.fr 28 .. _FCM: https://metomi.github.io/fcm/doc/ 29 .. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL 30 .. _OASIS: https://portal.enes.org/oasis 31 .. _XIOS: https://forge.ipsl.jussieu.fr/ioserver 30 32 31 33 .. NEMO
Note: See TracChangeset
for help on using the changeset viewer.