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 with the ./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.

Installation

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 coherensV20.tar is 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

Compilation

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.
  • C-preprocessor, usually cpp

Compilation is performed with the UNIX/LINUX makeutility. For example

$ 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 found below.

The rules that the make command uses to produce the executable file COHERENS are defined in the file Makefile located in the comps directory.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 compilers.cmp 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 compilers.cmp:

target_name:

$(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 f90 or /usr/bin/gfortran. This macro needs to be defined always.
  • FCOPTS: Optimisation options for the Fortran compiler.
  • FCDEFS: Set to CPPDFLAGS if the C-preprocessor is implicitly invoked by the Fortran compiler, or left undefined otherwise.
  • FCDEBUGS: Debugging options for the Fortran compiler option, e.g. -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 @cp otherwise.
  • CPPOPTS: Options for the C-preprocessor, excluding -D options, in case that the C-preprocessor is defined by CPPF, undefined otherwise.
  • CPPDEFS: Undefined if FCDEFS is defined, set to $(CPPDFLAGS) otherwise.

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:

  1. Select a working directory, e.g.
    $ cd /home/models/work
  2. Create a link with the COHERENS root directory:
    $ ln -s path_name COHERENS
    where path_name is the path name of the coherensV2.0 root directory
  3. Install COHERENS by creating a link:
    $ COHERENS/install_test
  4. Test if the compilation works fine: 
    $ make target_name
    where target_name equals one of the targets defined in compilers.cmpYou will see a bunch of object files appear in your working directory. More info on object files can be found here.

The 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.