= Install the modelling framework (NEMO and XIOS) Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]''' [[PageOutline(2-3, , , unnumbered)]] == Download NEMO reference code and configurations To download the NEMO reference version (for now revision 3.6): {{{#!sh svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-3.6/NEMOGCM }}} === Description of `NEMOGCM` directory tree The image below shows the directory tree: {{{#!table style="border: none; margin: auto;" {{{#!td style="border: none;" [[Image(wiki:Users/ModelInstall:nemogcm_tree.png,width=600)]] }}} {{{#!td style="border: none;" {{{#!table {{{#!th `ARCH` }}} {{{#!td Compilation option files, with format `arch_compiler.fcm`, the compiler name has to be provided with `–m` option }}} |- {{{#!th `CONFIG` }}} {{{#!td All configurations and a `cpp.fcm` file containing the list of CPP keys to each configuration }}} |- {{{#!th `EXTERNAL` }}} {{{#!td Package to implement an embedded model (AGRIF) }}} |- {{{#!th `NEMO` }}} {{{#!td FORTRAN source codes in several sub-directories }}} |- {{{#!th `SETTE` }}} {{{#!td Package to make tests to ensure the reproducibility and restartability of the code after changes }}} |- {{{#!th `TOOLS` }}} {{{#!td Useful softwares to different utilities }}} }}} }}} }}} == Extract and install XIOS Diagnostic outputs from NEMO are handled by the third party XIOS library. '''Important notice: XIOS needs to be compiled before NEMO, since the libraries are needed to successfully create NEMO executable.'''[[BR]] Instructions on how to obtain and install the software, see [wiki:Users/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 run with multiple processes and/or use "detached mode" for the IOs system XIOS) * 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. == Setup your architecture configuration file All compiler options in NEMO are controlled using files in `NEMOGCM/ARCH/arch-`[[span('my_arch', style=color: #BB4444 )]]`.fcm` where [[span('my_arch', style=color: #BB4444 )]] is the name of the computing architecture.\\ 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. [[IncludeSource(NEMO/releases/release-3.6/NEMOGCM/ARCH/arch-macport_osx.fcm, start=42, end=45, mimetype=application/x-shellscript, line_numbers=0)]] == Compile and create NEMO executable The 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.[[BR]] As an example, compile GYRE with [[span('my_arch', style=color: #BB4444 )]] to create a [[span('MY_GYRE', style=color: #BB4444 )]] configuration: {{{#!sh cd NEMOGCM/CONFIG; ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' }}} The image below shows the structure and some content of [[span("MY_CONFIG", style=color: #BB4444 )]] directory from the launching of the configuration creation ([[span(directories and fundamental files created by makenemo, style=color:green)]]). {{{#!table style="border: none; margin: auto;" {{{#!td style="border: none;" [[Image(wiki:Users/ModelInstall:nemogcm_tree_compiled.png,width=600, center)]] }}} {{{#!td style="border: none;" {{{#!table {{{#!th `WORK` }}} {{{#!td Folder with the symbolic links to all unpreprocessed routines considered in the configuration }}} |- {{{#!th `BLD` }}} {{{#!td Compilation folder (executables, headers files, libraries, preprocessed routines, flags, ...) }}} |- {{{#!th `EXP00` }}} {{{#!td Computation folder for running the model (namelists, xml, executables and inputs-outputs) }}} |- {{{#!th `MY_SRC` }}} {{{#!td Folder intended to contain your customized routines (modified from initial ones or new entire routines) }}} }}} }}} }}} After 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`). === More options [[IncludeSource(NEMO/releases/release-3.6/NEMOGCM/CONFIG/makenemo, start=129, end=144, mimetype=application/x-shellscript, line_numbers=0)]] === Default behaviour * 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.[[BR]] * If `–n` option is not specified, `ORCA2_LIM` is the default configuration used. === 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 [[IncludeSource(NEMO/releases/release-3.6/NEMOGCM/CONFIG/makenemo, /CONFIG/makenemo, start=145, end=166, mimetype=application/x-shellscript, line_numbers=0)]] == 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` 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 [wiki:Users/ReferenceConfigurations] {{{#!sh cd 'MY_CONFIG'/EXP00 mpirun -n $NPROCS ./opa # $NPROCS is the number of processes ; mpirun is your MPI wrapper }}} == 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 `opa` executable using `makenemo` command in order for this change to be taken in account.