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 10187 for NEMO/trunk/INSTALL.rst – NEMO

Ignore:
Timestamp:
2018-10-09T19:08:59+02:00 (6 years ago)
Author:
nicolasmartin
Message:

Push draft versions of RST root files

File:
1 edited

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/INSTALL.rst

    r9596 r10187  
    1 Install the modelling framework (NEMO and XIOS) 
     1===================== 
     2Install the framework 
     3===================== 
    24 
    3 Last edition: 2018-02-14 21:32 CET by nicolasmartin 
     5.. contents:: \ 
     6   :local: 
     7       
     8Dependencies 
     9============ 
    410 
    5     Extract the NEMO code 
    6         Description of NEMOGCM directory tree 
    7     Extract and install XIOS 
    8     Setup your architecture configuration file 
    9     Compile and create NEMO executable 
    10         More options 
    11         Default behaviour 
    12         Tools used during the process 
    13         Examples 
    14     Running the model 
    15     Viewing and changing list of active CPP keys 
     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) 
    1614 
    17 Extract the NEMO code 
     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. 
    1817 
    19 Using your account registered here ('my_login' with password) 
     18- `HDF5`_   (C library) 
     19- `NetCDF`_ (C and Fortran libraries) 
     20 
     21Extract the source code 
     22======================= 
     23 
     24Download the source code  
    2025 
    2126.. code:: console 
    22 svn --username 'mylogin' co http://forge.ipsl.jussieu.fr/nemo/svn/branches/2015/nemo_v3_6_STABLE/NEMOGCM 
    2327 
    24 Description of NEMOGCM directory tree 
     28   $ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0 
    2529 
    26 The image below shows the directory tree: 
     30Description of directory tree 
     31============================= 
    2732 
    28 simple table: 
    29     ARCH    Compilation option files, with format arch_compiler.fcm, the compiler name has to be provided with –m option 
    30     CONFIG  All configurations and a cpp.fcm file containing the list of CPP keys to each configuration 
    31     EXTERNAL    Package to implement an embedded model (AGRIF) 
    32     NEMO    FORTRAN source codes in several sub-directories 
    33     SETTE    Package to make tests to ensure the reproducibility and restartability of the code after changes 
    34     TOOLS    Useful softwares to different utilities 
     33+-----------+---------------------------------------------------------------+ 
     34| Folder    | Purpose                                                       | 
     35+===========+===============================================================+ 
     36| ``arch``  | Settings (per architecture-compiler pair)                     | 
     37+-----------+---------------------------------------------------------------+ 
     38| ``cfgs``  | Reference configurations                                      | 
     39+-----------+---------------------------------------------------------------+ 
     40| ``doc``   | - ``latex``: reference manuals for NEMO, SI\ :sup:`3`\  & TOP | 
     41|           | - ``rst``:   quick start guide                                | 
     42+-----------+---------------------------------------------------------------+ 
     43| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                   | 
     44+-----------+---------------------------------------------------------------+ 
     45| ``mk``    | Building  routines                                            | 
     46+-----------+---------------------------------------------------------------+ 
     47| ``src``   | Modelling routines                                            | 
     48|           |                                                               | 
     49|           | - ``ICE``: SI\ :sup:`3`\ for sea ice                          | 
     50|           | - ``NST``: AGRIF         for embedded zooms                   | 
     51|           | - ``OCE``: OPA           for ocean dynamics                   | 
     52|           | - ``MBG``: TOP           for tracers                          | 
     53+-----------+---------------------------------------------------------------+ 
     54| ``tests`` | Test cases                                                    | 
     55+-----------+---------------------------------------------------------------+ 
     56| ``tools`` | Utilities to [pre|post]process data                           | 
     57+-----------+---------------------------------------------------------------+ 
    3558 
    3659Extract and install XIOS 
     60======================== 
    3761 
    3862Diagnostic outputs from NEMO are handled by the third party XIOS library. 
    … …  
    4266 
    4367When you compile NEMO you will need to specify the following CPP keys: 
    44  
     68   
    4569    key_iomput 
    4670    key_mpp_mpi (if you want to run with multiple processes and/or use "detached mode" for the IOs system XIOS) 
    … …  
    4872 
    4973Setup your architecture configuration file 
     74========================================== 
    5075 
    5176All 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. 
    … …  
    5883 
    5984Compile and create NEMO executable 
     85================================== 
    6086 
    6187The 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. 
    6288As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration: 
    6389 
    64    cd NEMOGCM/CONFIG; ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' 
     90.. code-block:: sh 
     91 
     92   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' 
    6593 
    6694The 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). 
    6795 
    68     
     96+------------+----------------------------------------------------+ 
     97| Folder     | Purpose                                            | 
     98+============+====================================================+ 
     99| ``BLD``    |                                                    | 
     100+------------+----------------------------------------------------+ 
     101| ``EXP00``  |                                                    | 
     102+------------+----------------------------------------------------+ 
     103| ``EXPREF`` |                                                    | 
     104+------------+----------------------------------------------------+ 
     105| ``MY_SRC`` |                                                    | 
     106+------------+----------------------------------------------------+ 
     107| ``WORK``   |                                                    | 
     108+------------+----------------------------------------------------+ 
    69109 
    70     WORK 
    71  
    72     
    73  
    74     Folder with the symbolic links to all unpreprocessed routines considered in the configuration 
    75  
    76     BLD 
    77  
    78     
    79  
    80     Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …) 
    81  
    82     EXP00 
    83  
    84     
    85  
    86     Computation folder for running the model (namelists, xml, executables and inputs-outputs) 
    87  
    88     MY_SRC 
    89  
    90     
    91  
    92     Folder intended to contain your customized routines (modified from initial ones or new entire routines) 
     110Folder with the symbolic links to all unpreprocessed routines considered in the configuration 
     111Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …) 
     112Computation folder for running the model (namelists, xml, executables and inputs-outputs) 
     113Folder intended to contain your customised routines (modified from initial ones or new entire routines) 
    93114 
    94115After 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). 
    95116More options 
    96117 
    97         echo "Usage      : "${b_n} \ 
    98             " [-h] [-n name] [-m arch] [-d "dir1 dir2"] [-r conf] [-u conf] [-s Path] [-e Path] [-j No] [-v No] [-k 0/1]"; 
    99         echo " -h               : help"; 
    100         echo " -h institute : specific help for consortium members"; 
    101         echo " -n name      : config name, [-n help] to list existing configurations"; 
    102         echo " -m arch      : choose compiler, [-m help] to list existing compilers"; 
    103         echo " -d dir       : choose NEMO sub-directories"; 
    104         echo " -r conf      : choose reference configuration"; 
    105         echo " -u conf      : choose an unsupported (external) configuration"; 
    106         echo " -s Path      : choose alternative location for NEMO main directory"; 
    107         echo " -e Path      : choose alternative location for MY_SRC directory"; 
    108         echo " -j No        : number of processes used to compile (0=nocompilation)"; 
    109         echo " -v No        : set verbosity level for compilation [0-3]"; 
    110         echo " -k 0/1       : used cpp keys check (default = 1 -> check activated)"; 
    111         echo " -t dir       : temporary directory for compilation" 
    112         echo ""; 
     118.. includefile:: 
    113119 
     120    
     121 
     122----------------- 
    114123Default behaviour 
     124----------------- 
    115125 
    116126    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. 
    117127    If –n option is not specified, ORCA2_LIM is the default configuration used.  
    118128 
     129----------------------------- 
    119130Tools used during the process 
     131----------------------------- 
    120132 
    121133    functions.sh : bash functions used by makenemo, for instance to create the WORK directory 
    … …  
    123135    bld.cfg : FCM rules to compile  
    124136 
     137-------- 
    125138Examples 
     139-------- 
    126140 
    127141        echo "Example to install a new configuration MY_CONFIG"; 
    … …  
    148162        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" "; 
    149163 
     164----------------- 
    150165Running the model 
     166----------------- 
    151167 
    152168Once makenemo has run successfully, the opa executable is available in CONFIG/"MY_CONFIG"/EXP00 
    … …  
    156172   mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper 
    157173 
     174-------------------------------------------- 
    158175Viewing and changing list of active CPP keys 
     176-------------------------------------------- 
    159177 
    160 For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in 
     178For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in:: 
    161179 
    162    NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm 
     180   NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm 
    163181 
    164182This 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. 
     183 
     184.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5 
     185.. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf 
Note: See TracChangeset for help on using the changeset viewer.