= Install the modelling framework (NEMO and XIOS) Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]''' [[PageOutline(2-3)]] == 1. Extract the NEMO code Using your `my_login` /pw registered on this web site: {{{#!sh svn --username "mylogin" co http://forge.ipsl.jussieu.fr/nemo/svn/branches/2015/nemo_v3_6_STABLE/NEMOGCM }}} === Description of directory tree The image below shows the directory tree: [[Image(wiki:Users/ModelInstall:nemogcm_tree.png,width=600, center)]] * `ARCH` : compilation option files, with format `arch_compiler.fcm`, the compiler name has to be provided with `–m` option * `CONFIG` : all configurations and a `cpp.fcm` file containing the list of CPP keys to each configuration * `EXTERNAL` : package to implement an embbeded model (AGRIF) * `NEMO` and sub-directories: FORTRAN source codes * `SETTE` : package to make tests to ensure the reproducibility and restartability of the code after user changes * `TOOLS` : useful softwares to different utilities == 2. Extract and install XIOS Diagnostic outputs from NEMO are handled by the third party XIOS library. '''Important notice: XIOS needs to be installed (dowloaded and compiled) before NEMO, since the libraries are needed to successfully create NEMO executable.''' Instructions on how to obtain and install the software see [[ModelInterfacing/InputsOutputs#ExtractingandinstallingXIOS]]. When you compile NEMO you will need to specify the following CPP keys: * key_iomput * key_mpp_mpi (if you want to use "detached mode") * key_xios2 if you wish to use XIOS2 in nemo_v3_6_STABLE. XIOS2 is the only version available in the trunk. == 3. Setup your ARCH file All compiler options in NEMO are controlled using files in NEMOGCM/ARCH/arch-my_arch_name.fcm where ''my_arch_name'' is the name of your architecture. It is recommended to modify an ARCH file from an architecture similar to your own architecture. You will need to set appropriate values for all of the variables in the file. the variables %NCDF_HOME, %HDF5_HOME and %XIOS_HOME should be set to the installation directories used above. == 4. Compile and create NEMO executable The main script to compile and create executable is called `makenemo` and located in the `CONFIG` directory. To identify the source code you need, to build the makefile and run it.[[BR]] As an example, compile `GYRE`, with ifort on linux to create a `MY_GYRE` configuration: {{{#!sh cd NEMOGCM/CONFIG; ./makenemo –m "my_arch_name" –r GYRE -n MY_GYRE }}} After successful execution of the makenemo command, the executable name `opa`is created in the EXP00 directory (in the example above, the executable is created in `CONFIG/MY_GYRE/EXP00/opa`) {{{#!comment The image below shows the directory tree characterized by [[span("MY_CONFIG", style=color: #BB4444 )]] new 'branch'. All directories and fundamental files created by makenemo are highlighted in green. In particular, even if not shown in the figure, the "WORK" folder contains links to the compiled routines. [[Image(Users/ModelInstall:nemogcm_tree._compiled.png,width=300)]] ADD here new figure with all the directories and files created by makenemo: the executable, but also the directories and their content: `WORK`, `BLD`, etc... This should be the same figure as baobe, with all new files and directories added with another color. }}} === More options * `–n` [CONFIG]: for configuration name, existent or new config to install * `–m` [COMPILER]: compiler choice (use files names in `NEMOGCM/ARCH`, see examples below) * `–h`: help * `–r` [REFCONFIG]: reference configuration as first guess when installing a new one * `–j`[num]: number of processes to compile (`-j 0`:no compilation) * `–d` [DIR]: NEMO subdirectory (not needed) * `–t` [DIR]: temporary directory to store libraries * `-clean` [CONFIG_NAME] : remove the Makefile and all the files created afterwards At the first use, you need the `-m` option to specify compiler, its options and libraries, then for next compilation, it is assumed you will be using the same compiler.[[BR]] If `–n` option is not specified, `ORCA2_LIM` is the default configuration used. `-d` option has been implemented for use in non-interactive shell. The `WORK` directory is created under each configuration directory. === Tools used during the process * `functions.sh` : bash functions used by `makenemo`, for instance to create the `WORK` directory * `cfg.txt` : text list of configurations and source directories * `bld.cfg` : FCM rules to compile === Examples * Compiling `GYRE`, with ifort on linux to create a `MY_GYRE` configuration {{{#!sh makenemo –m ifort_linux –r GYRE -n MY_GYRE }}} * Create and compile `ORCA_LIM3` {{{#!sh makenemo –n ORCA_LIM3 # and answer }}} * Create your ORCA_LIM3_v2 configuration based on the previous one {{{#!sh makenemo –n ORCA_LIM3_v2 -r ORCA_LIM3 }}} * Create and compile ORCA2_LIM_2_2, add (`add_key`) and delete (`del_key`) keys, based on ORCA2_LIM {{{#!sh makenemo –n ORCA2_LIM_2_2 -r ORCA2_LIM del_key "key_iomput" # and answer }}} * Remove a configuration {{{#!sh makenemo –n ORCA2_LIM_2_2 clean_config # and answer }}} * Get help on makenemo options {{{#!sh makenemo –h }}} == 5. Running the model Once `makenemo` has run successfully, the `opa` executable is available in `CONFIG/"MY_CONFIG"/EXP00`[[BR]] For the reference configurations, the `EXP00`directory also contains the small ASCII input file (namelists, *xml files for the IOs...). If the configuration also needs NetCDF input files, this should be downloaded into the `EXP00` directory from the corresponding tarfile, see [wiki:Users/ReferenceConfigurations] {{{#!sh cd CONFIG/"MY_CONFIG"/EXP00 mpirun -n $NPROCS ./opa # $NPROCS is the number of processes ; mpirun is your MPI wrapper }}} == 6. Viewing and changing list of active CPP keys For a given configuration (here called [[span("MY_CONFIG", style=color: #BB4444 )]]), the list of active CPP keys can be found in {{{#!sh NEMOGCM/CONFIG/"MYCONFIG"/cpp_"MY_CONFIG".fcm }}} This text file can be edited to change the list of active CPP keys. Once changed, one needs to recompile NEMO using `makenemo` command in order for this change to be taken in account.