source: NEMO/trunk/INSTALL.rst @ 9596

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

Reorganisation plan for NEMO repository: preliminary implementation of the new trunk structure (ref #2015)

  • Deletion of useless 1st level, add new explicit names for folders
  • Extract dev tools (SETTE and Trusting) to /utils/CI
  • Extract figures folder from documentation to /utils/figures
  • Extrac TEST_CASES to /utils/test_cases
  • Move ./TOOLS/COMPILE to ./mk
  • Add few wiki files at the root: README, INSTALL and LICENSE with full text of CeCILL v2.0
  • Style: uppercase for wiki files, lowercase for folder names

Additionally, inclusion of routines renaming in NST: agrif_si3 → agrif_ice

File size: 7.6 KB
Line 
1Install the modelling framework (NEMO and XIOS)
2
3Last edition: 2018-02-14 21:32 CET by nicolasmartin
4
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
16
17Extract the NEMO code
18
19Using your account registered here ('my_login' with password)
20
21.. code:: console
22svn --username 'mylogin' co http://forge.ipsl.jussieu.fr/nemo/svn/branches/2015/nemo_v3_6_STABLE/NEMOGCM
23
24Description of NEMOGCM directory tree
25
26The image below shows the directory tree:
27
28simple 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
35
36Extract and install XIOS
37
38Diagnostic outputs from NEMO are handled by the third party XIOS library.
39
40Important notice: XIOS needs to be compiled before NEMO, since the libraries are needed to successfully create NEMO executable.
41Instructions on how to obtain and install the software, see Users/Model Interfacing/Inputs Outputs.
42
43When you compile NEMO you will need to specify the following CPP keys:
44
45    key_iomput
46    key_mpp_mpi (if you want to run with multiple processes and/or use "detached mode" for the IOs system XIOS)
47    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.
48
49Setup your architecture configuration file
50
51All 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.
52It 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.
53
54%NCDF_HOME           /opt/local
55%HDF5_HOME           /opt/local
56%XIOS_HOME           /Users/$( whoami )/xios-1.0
57%OASIS_HOME          /not/defined
58
59Compile and create NEMO executable
60
61The 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.
62As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
63
64   cd NEMOGCM/CONFIG; ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
65
66The 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).
67
68   
69
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)
93
94After 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).
95More options
96
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 "";
113
114Default behaviour
115
116    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.
117    If –n option is not specified, ORCA2_LIM is the default configuration used.
118
119Tools used during the process
120
121    functions.sh : bash functions used by makenemo, for instance to create the WORK directory
122    cfg.txt : text list of configurations and source directories
123    bld.cfg : FCM rules to compile
124
125Examples
126
127        echo "Example to install a new configuration MY_CONFIG";
128        echo "with OPA_SRC and LIM_SRC_2 ";
129        echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\"";
130        echo "";
131        echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt;
132        echo "";
133        echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt;
134        echo "";
135        echo "Example to remove bad configuration ";
136        echo "./makenemo -n MY_CONFIG clean_config";
137        echo "";
138        echo "Example to clean ";
139        echo "./makenemo clean";
140        echo "";
141        echo "Example to list the available keys of a CONFIG ";
142        echo "./makenemo list_key";
143        echo "";
144        echo "Example to add and remove keys";
145        echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
146        echo "";
147        echo "Example to add and remove keys for a new configuration, and do not compile";
148        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
149
150Running the model
151
152Once makenemo has run successfully, the opa executable is available in CONFIG/"MY_CONFIG"/EXP00
153For 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
154
155   cd 'MY_CONFIG'/EXP00
156   mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
157
158Viewing and changing list of active CPP keys
159
160For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in
161
162   NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
163
164This 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.
Note: See TracBrowser for help on using the repository browser.