Build the framework¶
Prerequisites¶
System dependencies¶
In the first place the other requirements should be provided natively by your system or can be installed from the official repositories of your Unix-like distribution:
Perl interpreter
Fortran compiler (
ifort
,gfortran
,pgfortran
, …),Message Passing Interface (MPI) implementation (e.g. OpenMPI or MPICH).
Network Common Data Form (NetCDF) library with its underlying Hierarchical Data Form (HDF)
NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.
Hint
The MPI implementation is not strictly essential since it is possible to compile and run NEMO on a single processor. However most realistic configurations will require the parallel capabilities of NEMO and these use the MPI standard.
Note
On older systems, that do not support MPI-3 features,
the key_mpi2
preprocessor key should be used at compile time.
This will limit MPI features to those defined within the MPI-2 standard
(but will lose some performance benefits).
Specifics for NetCDF and HDF¶
NetCDF and HDF versions from official repositories may have not been compiled with MPI support. However access to all the options available with the XIOS IO-server will require the parallelism of these libraries.
Hint
$ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
It is recommended to build the tests --enable-parallel-tests
and run them with make check
Particular versions of these libraries may have their own restrictions. State the following requirements for netCDF-4 support:
Caution
Extract and install XIOS¶
With the sole exception of running NEMO in mono-processor mode
(in which case output options are limited to those supported by the IOIPSL
library),
diagnostic outputs from NEMO are handled by the third party XIOS
library.
It can be used in two different modes:
- attached
Every NEMO process also acts as a XIOS server
- detached
Every NEMO process runs as a XIOS client. Output is collected and collated by external, stand-alone XIOS server processors.
Instructions on how to install XIOS can be found on its wiki.
Hint
It is recommended to use XIOS 2.5 release. This version should be more stable (in terms of future code changes) than the XIOS trunk. It is also the one used by the NEMO system team when testing all developments and new releases.
This particular version has its own branch and can be checked out with:
$ svn co https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
Download and install the NEMO code¶
Checkout the NEMO sources¶
$ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/r4.0/r4.0.7
Description of 1st level tree structure¶
|
Compilation settings |
|
|
|
Documentation |
|
Dependencies included
( |
|
Compilation scripts |
|
Modelling routines |
|
Test cases (unsupported) |
|
Utilities to {pre,post}process data |
Setup your architecture configuration file¶
All compiler options in NEMO are controlled using files in ./arch/arch-'my_arch'.fcm
where
my_arch
is the name of the computing architecture
(generally following the pattern HPCC-compiler
or OS-compiler
).
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
%NCDF_HOME /usr/local/path/to/netcdf
%HDF5_HOME /usr/local/path/to/hdf5
%XIOS_HOME /home/$( whoami )/path/to/xios-2.5
%OASIS_HOME /home/$( whoami )/path/to/oasis
Create and compile a new configuration¶
The main script to {re}compile and create executable is called makenemo
located at
the root of the working copy.
It is used to identify the routines you need from the source code, to build the makefile and run it.
As an example, compile a MY_GYRE
configuration from GYRE with ‘my_arch’:
./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
Then at the end of the configuration compilation,
MY_GYRE
directory will have the following structure.
Directory |
Purpose |
---|---|
|
BuiLD folder: target executable, headers, libs, preprocessed routines, … |
|
Run folder: link to executable, namelists, |
|
Files under version control only for official configurations |
|
New routines or modified copies of NEMO sources |
|
Links to all raw routines from |
After successful execution of makenemo
command,
the executable called nemo is available in the EXP00
directory
More makenemo
options¶
makenemo
has several other options that can control which source files are selected and
the operation of the build process itself.
Usage:
------
./makenemo -[aru] CONFIG -m ARCH [-[dehjntv] ...] [{list_key,clean,clean_config}]
[{add_key,del_key} ...]
Mandatory
-m Computing architecture (./arch), FCM file describing the compilation settings
and one of the following option (use 'all' arg to list available items)
-r Reference configuration (./cfgs), proven with long-term support
-a Academic test case (./tests), ready-to-use configuration with no support over time
-u Scripted remote configuration (see ./tests/rmt_cfgs.txt)
Optional
-d New set of sub-components (subfolders from ./src directory)
-e Path for alter patch location (default: 'MY_SRC' in configuration folder)
-h Print this help
-j Number of processes to compile (0: dry run with no build)
-n Name for new configuration
-s Path for alter source location (default: 'src' root directory)
-t Path for alter build location (default: 'BLD' in configuration folder)
-v Level of verbosity ([0-3])
Examples
These options can be useful for maintaining several code versions with only minor differences but
they should be used sparingly.
Note however the -j
option which should be used more routinely to speed up the build process.
For example:
./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
will compile up to 8 processes simultaneously.
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.
If the -n
option is not specified the last compiled configuration will be used.
Tools used during the process¶
functions.sh
: bash functions used bymakenemo
, for instance to create the WORK directorycfg.txt
: text list of configurations and source directoriesbld.cfg
: FCM rules for compilation
Running the model¶
Once makenemo
has run successfully,
the nemo
executable is available in ./cfgs/MY_CONFIG/EXP00
.
For the reference configurations, the EXP00
folder also contains the initial input files
(namelists, *.xml
files for the IOs, …).
If the configuration needs other input files, they have to be placed here.
cd 'MY_CONFIG'/EXP00
mpirun -n $NPROCS ./nemo # $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 MY_CONFIG
),
the list of active CPP keys can be found in ./cfgs/'MYCONFIG'/cpp_MY_CONFIG.fcm
This text file can be edited by hand or with makenemo
to change the list of active CPP keys.
Once changed, one needs to recompile nemo
in order for this change to be taken in account.
Note that most NEMO configurations will need to specify the following CPP keys:
key_iomput
for IOs and key_mpp_mpi
for parallelism.