Setting up a COHERENS test case

About this section

This section takes you through the setup of a test case. You can install, study and run a predefined test case that comes with the model code. The steps for doing this are provided in the first section. As in the previous section, replace the nomenclature in the text that refers to the model code version V2.0 with that which pertains to the version you are using. Should you wish to design your own test case, you will need to know more about the different ways of setting up a test case. These ways are explained further below.

Installing a predefined test case

The aim of the predefined test cases is to:

  • test the installation and compilation of the code
  • provide examples of model setups
  • show how model results are affected by different setups (e.g. numerical schemes, turbulence closures, different kinds of processes

Each case is composed of a series of experiments. The nomenclature of each experiment is the nameof the test case followed by an upper case letter. For examples, the cones test consists of four experiments each representing a separate simulation: conesA, conesB, conesC, conesD.

The procedure for installing a specific test case is analogous to the one presented in section 2 above. The complete procedure, including running the application, is as follows.

  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 COHERENS root directory
  3. Install the test case by creating a link:
    $ COHERENS/install_test -t test_name
    where test_name is the name of the test case (e.g. cones)
  4. Compile:
    $ make target_name
    where target_name equals one of the targets defined in compilers.cmp.
    Possible test cases are bedload , bendflow, front, plume, river, seich, wavload, bohai, flood2d, optos, bcz , ptests, seddens, thacker, cones, flood3d, csm pycno, sedhprof, totload csnsp, fredy, nos rhone, sedvprof, tutorial. These test cases demonstrate several features of coherens.

Running the test case

In COHERENS, the different runs that are done during a simulation are defined in the file defruns, which is located in the working directory. Each line in this document represents one run you want to carry out. A series of input lines thus represents a series of consecutive runs.

All the runs (i.e. all input lines) are defined with the following syntax:

Run name, CIF options, CIF file name

Note that the last two inputs (CIF option and CIF file name. are optional, which means you can leave them empty. [For more info on CIF files, please read the following section] However, you must always put the two commas on this line. Otherwise, COHERENS will generate an error. Comments can be set in the defruns file by adding an exclamation mark (!). Thus, if a ! is inserted at the beginning of a line, the corresponding run will be skipped. Read the next section for more info on the CIF files.

Once you are satisfied with the contents of the defruns file, you can run the model with the command:

$ ./Run &

This command will run the model. The (optional) ampersand (&) makes the model run in the background, which means that you can keep working on the command line.

Setting up a test case using Usrdef files

Model setup consists in (1) defining a series of model parameters for initialisation and (2) providing input data of different kinds at run-time. This is implemented in the code via calls to routines located in Usrdef-files. These routines need to be programmed by the user. The following Usrdef-files exist:

Usrdef_Model.f90:

  • parameters for monitoring
  • model switches to activate/deactivate program modules and to make a selection of a specific numerical/physical scheme
  • parameters which determine the kind of forcing input (e.g. file name, type of file, ...)
  • parameters for parallel setup
  • define external surface data grids if regular
  • model grid, bathymetry, locations of open boundaries
  • initial conditions
  • open boundary conditions for 2-D and 3-D mode
  • insert code to read open boundary data

Usrdef_Surface_Data.f90 meteorological and/or SST (Sea Surface Temperature) forcing

  • define surface grid(s) if non-regular
  • insert code for reading forcing data

Usrdef_Nested_Grids.f90 define locations of nested sub-grids

Usrdef_Time_Series.f90 time series model output

  • define metadata information
  • define output resolution in space and time
  • define output parameters
  • define output data

Usrdef_Time_Averages.f90 time averaged model output

Usrdef_Harmonic_Analysis.f90 time averaged model outputtime averaged model output

Usrdef_Output.f90 user-defined output

Usrdef_Sediment.f90 parameters and arrays related to the sediment transport model

The easiest way to create these Usrdef-files, is by studying those of an existing test case (e.g. by installing one of the test cases supplied with the source code as described above) and changing them where necessary. This method is recommended for applications which do not require a complicated setup. You can also use a set of generic Usrdef-files located in the /setups/examples subdirectory. All parameters are listed with their default values or with an undefined value (given by a ?). The user may re-define the default and either replace the question mark by a specific value or remove those lines. Each time changes to the Usrdef-files have been made, the test case needs to be recompiled before it can be run.

Setting up a test case using Central Input files (CIF)

The way of setting up a test case using Usrdef-files described above is very powerful, yet requires some knowledge of FORTRAN and a detailed knowledge of how COHERENS works. As not all users are equally familiar with the COHERENS model code, this method could prove to be challenging at first, as it is not very user-friendly. As an alternative, more user-friendly way of setting up a test case, the Central Input Files, or CIF-files, were developed.

As with Usrdef-files, the easiest way of using CIF-files is by changing the CIF-file from another test case. In order to generate a CIF-file from an existing test case, you can use the CIF options that were mentioned above. There are two options for CIF-file. In order to write (i.e. generate) a CIF-file, one must add the letter W (note that this option is case sensitive) and Run the test case using Usrdef-files. After running the test case with the CIF-option W included, a file will appear in the test case folder with the extension .cifmodA. It contains some lists of the different parameters in the model. Each of these lists is separated from the others with a hash sign (#). Comments can be given with an exclamation mark (!). This file can be then be copied to a new test case folder, opened and adjusted as you will. Once you have adapted the CIF-file to set up your own test case, open up the defruns file and use R — i.e. read CIF-file- as an option. When you run the model, the CIF-file will now be used as a model input file, instead of the Usrdef-files.

Using CIF-files has the added advantage of not having to recompile the test case after changes have been made, as data in the CIF-files can be introduced to the program by means of data located in external files and not in the code.