Let's run COHERENS
COHERENS is a code written in FORTRAN 90, you as a user will add things
to the code in order to apply to your specific case. This section will
explain how to run the code of a prepared case study, so you don't
have to worry yet about adapting the code to your specific situation. To
run a program written in FORTRAN 90 obviously you first have to place
the code on your disk, the next step is to compile this program.
Compiling means that you converse the code into an executable. The
executable tool on linux is usually called with the command 'make'.
Once you have created the executable you can run it and expect results
./Run command. In COHERENS, this command expects input from a
defruns file, more information can be found below (for example in
the ‘setting up a COHERENS test case’ section)
The following sections will guide you through the installation and use of version V2.7 of the COHERENS code. Should you install a different version (naturally, it is recommended to install the latest version of the model code), replace any mention of V2.7 in the following text (e.g. in the filename coherensV2.7.tar.gz) with the nomenclature relevant to the version you are using.
First of all make sure you have installed a working version of the COHERENS code on your computer.
In the following it is assumed that the file
downloaded on the user's home directory. To retrieve the files use:
$ tar -zxvf coherensV2.7.tar.gz
This creates the root directory coherensV2.7 which contains the following subtrees:
- The file COHERENS_License contains the license, install_test is a script to install COHERENS, install_utils is of minor importance to external users.
- code: which contains the subdirectories physics, biology and sediment. These subdirectories contain the source code (source) and the files used for compilation are stored in comps.
- scr: examples script for running the code on a UNIX platform. For serial runs, Run is the most obvious choice. Run_vic and Run_hpd_par have been used in parallel applications.
- data: data files used in some of the test case applications
- setups: each subdirectory contains the setup files of one of the pre-defined test cases. Exceptions are examples which contains example code for all Usrdef files needed to create a model application, and ptests which provides check-up tables for all test case runs.
- utils: directory specific for code development, of minor importance to external users
To compile the COHERENS source code, the following tools are essential:
- FORTRAN 90 compiler (for example free source gfortran from gnu if you are working with Ubuntu). Note that the MPI library needs to be installed for parallel execution of the program and that MPI is not supported by all compilers.
Compilation is performed with the UNIX/LINUX
$ make linux-gfort
linux-gfort is the target, which provides the details of the
compiler you have available, more information about the target can be
The rules that the
make command uses to produce the executable
COHERENS are defined in the file
Makefile reads input form a
series of additional files. Most of them are user-independent and should
not be modified by the user. Only exceptions are the files
where a new target needs to be defined, and
options.cpp with a
list of options for the C-preprocessor (CPP). Contrary to the previous
V1 version of COHERENS this file is given in a portable format, i.e.
independent of the type of compiler or operating system.
If your compiler is not defined already in
compilers.cmp, you can add a
new target using the format below in
$(MAKE) $(EXEFILE) "FC=gfortran" "FCOPTS= -O3" "FCDEFS=" "FCDEBUG=" \ "CPP=" "CPPF=cpp" "CPPOPTS=-traditional-cpp" "CPPDEFS=$(CPPDFLAGS)"
where target_name is arbitrarily defined by the user. Line 2 is indented by one TAB position, the following ones by blanks only (this example only shows 2 lines).
These macro definitions have the following meaning:
FC: name of the Fortran 90 compiler, eventually preceded by its directory path, such as
/usr/bin/gfortran. This macro needs to be defined always.
FCOPTS: Optimisation options for the Fortran compiler.
FCDEFS: Set to
CPPDFLAGSif the C-preprocessor is implicitly invoked by the Fortran compiler, or left undefined otherwise.
FCDEBUGS: Debugging options for the Fortran compiler option, e.g.
CPP: Name of the C-preprocessor including options, such as
gcc -E, if invoked implicitly by the Fortran compiler, undefined otherwise.
CPPF: Name of the C-preprocessor, if not invoked by the Fortran compiler or set to
CPPOPTS: Options for the C-preprocessor, excluding
-Doptions, in case that the C-preprocessor is defined by CPPF, undefined otherwise.
CPPDEFS: Undefined if
FCDEFSis defined, set to
In the file
coherensflags.cmp the macro’s that are depending of the model set-up
are defined and will be explained there.
The following procedure is recommended to test the compilation:
Select a working directory, e.g.
$ cd /home/models/work
Create a link with the COHERENS root directory:
where path_name is the path name of the coherensV2.0 root directory
$ ln -s path_name COHERENS
Install COHERENS by creating a link:
Test if the compilation works fine:
where target_name equals one of the targets defined in
$ make target_name
compilers.cmpYou will see a bunch of object files appear in your working directory. More info on object files can be found here.
Makefile reads the
coherensflags.cpp were the simulation
dependent macro definitions are defined. First run the test case without any options,
afterwards you can test the other options. The macro CPPDFLAGS is defined in the
file coherensflags.cmp. The syntax is:
CPPDFLAGS = -Dname1 -Dname2 ...
where name corresponds to a C-language statement in the source code. The following values can be awarded to name:
MPI: needed for parallel execution of the program. An error is issued by the compiler of the MPI library is not installed and linked to the main source code.
CDF: needed for data input/output in netCDF format. An error occurs if the netCDF library is not installed and linked to the main source code.
ALLOC: option for allocation of most local arrays in the model. This will provide a more efficient memory management, but may have a negative impact on CPU performace.
To activate the use of the netCDF file type you should also define the path to the netCDF installation and define the netCDF library file. Usually the syntax looks like this (you’ll probably have to remove some of the default #’s).
# netCDF directory path NETCDF_PATH = /usr/local # netCDF library file NETCDF_LIB_FILE = netcdf # netCDF include options FCIFLAGS_NETCDF = -I$(NETCDF_PATH)/include # netCDF library options #FLIBS_NETCDF = -L$(NETCDF_PATH)/lib -l$(NETCDF_LIB_FILE)
By default the biology and sediment module are switched of by defining the sediment path as equal to the physics path:
# physics directory path PHYSMOD = COHERENS/code/physics # sediment directory path SEDMOD = $(PHYSMOD)
If you want to use the sediment module define the sediment path to the directory of the code where the sediment routines are stored:
SEDMOD = COHERENS/code/sediment
Switching on the biology module is analogous.