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.
-
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 COHERENS root directory$ ln -s path_name COHERENS
-
Install the test case by creating a link:
where$ COHERENS/install_test -t test_name
test_name
is the name of the test case (e.g. cones) -
Compile:
where$ make target_name
target_name
equals one of the targets defined incompilers.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.