New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 10557 for NEMO/trunk/INSTALL.rst – NEMO

Ignore:
Timestamp:
2019-01-22T17:31:57+01:00 (5 years ago)
Author:
acc
Message:

Update of INSTALL.rst and minor correction to global.rst

File:
1 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/INSTALL.rst

    r10279 r10557  
    66   :local: 
    77       
    8 Dependencies 
    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  
    15 But The following dependencies should be from the official repositories of your Linux distribution but 
    16 you 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  
    21 Extract the source code 
    22 ======================= 
    23  
    24 Download the source code 
    25 ------------------------ 
     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============================= 
    2681 
    2782.. code:: console 
    … …  
    52107|           | - ``NST``: AGRIF for embedded zooms                        | 
    53108|           | - ``OCE``: |OPA| for ocean dynamics                        | 
    54 |           | - ``MBG``: |TOP| for tracers                               | 
     109|           | - ``TOP``: |TOP| for tracers                               | 
    55110+-----------+------------------------------------------------------------+ 
    56111| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               | 
    … …  
    58113| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         | 
    59114+-----------+------------------------------------------------------------+ 
    60  
    61 Extract and install XIOS 
    62 ======================== 
    63  
    64 Diagnostic outputs from NEMO are handled by the third party XIOS library. 
    65  
    66 Important notice: XIOS needs to be compiled before NEMO, since the libraries are needed to successfully create NEMO executable. 
    67 Instructions on how to obtain and install the software, see Users/Model Interfacing/Inputs Outputs. 
    68  
    69 When 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.  
    74115 
    75116Setup your architecture configuration file 
    76117========================================== 
    77118 
    78 All 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. 
    79 It 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 
     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 
    85133 
    86134Compile and create NEMO executable 
    … …  
    115163Folder intended to contain your customised routines (modified from initial ones or new entire routines) 
    116164 
     165When you compile NEMO you will need to specify the following CPP keys: 
     166 
     167*   key_iomput 
     168*   key_mpp_mpi 
     169 
    117170After 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). 
    118171More options 
    … …  
    179232 
    180233.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5 
    181 .. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf 
     234.. _NetCDF4: http://www.unidata.ucar.edu/downloads/netcdf 
     235.. _XIOS Wiki:    http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation 
     236.. _XIOSSRC: http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 
Note: See TracChangeset for help on using the changeset viewer.