| The NEMO source code is written in *Fortran 95* and
| The NEMO source code is written in *Fortran 2008* and
some of its prerequisite tools and libraries are already included in the download.
| It contains the AGRIF_ mesh refinement library; the FCM_ build system ; the PPR_ polynomial reconstruction library and
the IOIPSL_ library for parts of the output.
System dependencies
-------------------
System prerequisites
--------------------
Other requirements should be provided natively by your system or
can be installed from the official repositories of your Unix-like distribution:
The following should be provided natively by your system, if not, they need to be installed from the official repositories:
- You need a Unix-like machine (e.g. Linux Distributions, MacOS)
- *subversion (svn)* for version control of XIOS sources
- *git* for version control of NEMO sources
- *Perl* interpreter
...
...
@@ -30,21 +30,12 @@ can be installed from the official repositories of your Unix-like distribution:
- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_).
- |NetCDF|_ library with its underlying |HDF|_
**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.**
.. hint::
The MPI implementation is not strictly essential
since it is possible to compile and run NEMO on a single processor.
However most realistic configurations will require the parallel capabilities of NEMO and
these use the MPI standard.
.. note::
On older systems, that do not support MPI-3 features,
the ``key_mpi2`` preprocessor key should be used at compile time.
This will limit MPI features to those defined within the MPI-2 standard
(but will lose some performance benefits).
| By default, NEMO requires MPI-3. However, it is possible to circumnavigate this by using the following work-arounds:
- Activate the ``key_mpi2`` preprocessor key at compile time. This will allow you to run the model using MPI-2, but keep in mind that you will lose some performance benefits.
- Activate the ``key_mpi_off`` preprocessor key at compile time. This will allow you to run the model only on a single process (no MPI parallelization) and you will not be able to use XIOS.
.. |OpenMPI| replace:: *OpenMPI*
.. _OpenMPI: https://www.open-mpi.org
...
...
@@ -58,71 +49,64 @@ can be installed from the official repositories of your Unix-like distribution:
Specifics for NetCDF and HDF
----------------------------
NetCDF and HDF versions from official repositories may have not been compiled with MPI support.
However access to all the options available with the XIOS IO-server will require
the parallelism of these libraries.
In order to take full advantage of the XIOS IO-server (one_file option; i.e. combines all of your output into one file), HDF (C library) and NetCDF (C and Fortran libraries) must be compiled with MPI support. To do this:
| **To satisfy these requirements, it is common to have to compile from source
in this order HDF (C library) then NetCDF (C and Fortran libraries)**
| It is also necessary to compile these libraries with the same version of the MPI implementation that
both NEMO and XIOS (see below) have been compiled and linked with.
.. hint::
| It is difficult to define the options for the compilation as
they differ from one architecture to another according to
the hardware used and the software installed.
| The following is provided without any warranty
- You need to compile these libraries with the same version of the MPI implementation that
both NEMO and XIOS will be compiled and linked with (see below).
- When compiling the HDF library, you need to use the ``--enable-parallel`` option when calling configure:
It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
$ ./configure --enable-parallel ...
.. note::
Particular versions of these libraries may have their own restrictions.
Note the following requirements for netCDF-4 support:
| For XIOS you need to use NetCDF-4. NetCDF-3 can still be used in NEMO if you do not wish to use XIOS.
.. caution::
| When building NetCDF-C library versions older than 4.4.1, use only HDF5 1.8.x versions.
| Combining older NetCDF-C versions with newer HDF5 1.10 versions will create superblock 3 files
that are not readable by lots of older software.
| The output created by XIOS are NetCDF-4 and not NetCDF4-classic, and are therefore incompatible with NetCDF-3 software. In order to handle any XIOS output, you need a software which is compatible with true NetCDF-4 files (e.g. ncview, Matlab, Python). If you would like to use other software (which is not compatible with NetCDF-4), then you can convert your XIOS output into NetCDF4-classic format by using the following command:
.. code-block:: console
Install XIOS library
--------------------
$ cdo -f nc4c copy infile outfile
With the sole exception of running NEMO in mono-processor mode
(in which case output options are limited to those supported by the internal ``IOIPSL`` library),
diagnostic outputs in NEMO are handled by the third party ``XIOS`` library (:xios:`XIOS homepage<>`).
or
1. Install the NetCDF4 library.
If you want to use single file output you will need to compile the HDF & NetCDF libraries to
allow parallel IO.
2. Download the version of XIOS that you wish to use.
The recommended version is now XIOS2:
.. code-block:: console
.. code-block:: console
$ ncks -7 infile outfile
$ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS2/trunk
and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
If you find problems at this stage, support can be found by subscribing to
the :xios:`XIOS mailing list <../mailman/listinfo.cgi/xios-users>` and sending a mail message to it.
Install XIOS library
--------------------
With the sole exception of running NEMO without MPI
(in which case output options are limited to the default minimum),
diagnostic outputs from NEMO are handled by the third party ``XIOS`` library.
It can be used in two different modes:
Use of XIOS for NEMO IOs is activated using the pre-compiler key ``key_xios``.
:*attached*: Each NEMO process directly deals with its own output.
:*detached*: You have separate XIOS processes that deal with the output.
For both of these options, you can activate the option for "one_file" or "multiple_file" mode. For the former, output is collected and collated to directly produce one single file for your domain. For the latter option, you will have as many output files as your number of NEMO processes (if in attached) or XIOS processes (if in detatched).
.. hint::
Instructions on how to install XIOS can be found on its :xios_doc:`wiki<>`.
Since version 4.2.1 it is also supported the use of XIOS3 by means of the pre-compiler key ``key_xios3``.
This can be checked out with:
.. note::
.. code:: console
Prior to NEMO version 4.2.0 it was recommended to use XIOS 2.5 release. However,
versions 4.2.0 and beyond utilise some newer features of XIOS2 and users will need to
upgrade to the trunk version of XIOS2. Note 4.2.1 does support the use of XIOS3 by activating "key_xios3" (in this case you cannot use the tiling capability).
svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS3/trunk
XIOS2 trunk can be checked out with:
.. code-block:: console
$ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS2/trunk
If you find problems at this stage, support can be found by subscribing to
the :xios:`XIOS mailing list <../mailman/listinfo.cgi/xios-users>` and sending a mail message to it.
**********************************
...
...
@@ -133,7 +117,7 @@ Checkout the NEMO source
------------------------
There are several ways to obtain the NEMO source code. Users who are not familiar with ``git``
and simply want a fixed code to compile and run, can download a tarball from the :tarrepo:`4.2.0 release site<>`
and simply want a fixed code to compile and run, can download a tarball from the :tarrepo:`4.2.1 release site<>`
Users who are familiar with ``git`` and likely to use it to manage their own local branches and
modifications, can clone the repository at the release tag:
...
...
@@ -153,7 +137,7 @@ and then switch to the tagged release:
