Test case results

After running a test case, some files have been generated in the test case folder. This section describes the contents of these files and how the test case results can be viewed.

Files generated after a run

After the model has finished, something like this will be written to the terminal:

$ Main program terminated
real 0m19.678s
user 0m18.490s
sys 0m1.154s

A number of files are generated by COHERENS. All these files have a name that is generated from the name of the run (defined in the file defruns. For example, for a test case named river, these files can be listed by issuing the command:

$ ls river*

This could give the following result (the names and quantity of the files depend entirely on the contents of the defruns file:

river0T.cifmodA river0T.inilogA river0T.runlogA river0T.timingA river0T.warlogA river1T.cifmodA river1T.inilogA river1T.runlogA river1T.timingA river1T.warlogA riverT_1.resid3I riverT_1.resid3N riverT_1.tsout2I riverT_1.tsout2N riverT_1.tsout3I riverT_1.tsout3N riverT.2uvobc1N riverT.2uvobc1U riverT.modgrdN riverT.phsicsN river.txt

These files have the following meaning. Files ending at .inilogA are the files that log the initialization phase of the run. Each subroutine that is called during the initialization is written to this file. It is mainly important for code developers and less for users of the model. Files ending at .runlogA are log files written during the phase where the model is actually running. This file can become quite large. We can use it to examine the progress of the simulation. Here as well, it is more important for code developers than for model users, but sometimes an error is written to one of these two files, instead of to the errlog file that is discussed below.

The files ending at .timingA contain information on the time it took for the model to run. This file shows how long the simulation took and it also shows the percentages of the time that different parts of the calculation took (such as 2D calculation, 3D calculation, input and output etc.). Files ending at .warlogA are files with warnings about settings that were automatically changed by COHERENS. Before the start of the simulations, COHERENS checks whether the parameters in the model have valid values, if not, COHERENS resets them automatically and writes the warning. It is necessary after each simulation to inspect the .warlogA files! They can give information on some model settings that were not intended by the user and they may explain unexpected results in the simulations.

A file that should not be present is the errlogA file. In this file, error messages are written that prevent COHERENS from finishing the simulations. Examples of this are incompatible options which cannot be automatically reset. At the end of the simulation, COHERENS automatically removes this file. If this file is present, something went wrong with the simulations even if all the output seems to be there! You should examine this file and fix the problem. Make sure that there is no error log file by typing:

$ ls *.errlogA

If an error log file exists, but is empty, you can check the runlog or inilog files , maybe the error message was written to one of these files.

The file ending at cifmodA contains an automatically generated central input file (CIF, see above).

Result files

Finally, there are files with the results of the simulation. Files ending at .tsout contain time series of variables. The number after tsout indicates the dimension. As an example, riverT_1.tsout3N contains three-dimensional data. The last letter of the extension indicates the type of data, the letter N stands for NetCDF, other possibilities are A for ascii, U for binary and I for an ascii file with only a header and no data. Files with an extension that contains residare generated by the harmonic analysis functionality of COHERENS.

Because the NetCDF output contains binary files, we need a special tool for examining the data. An example is ncdump. In order to examine the results, use the following command (e.g. for a run called riverT):

$ ncdump riverT_1.tsout2N | less

Here, the command less is used as a viewer. You can close this program by typing q.

Analogously, you can examine the data in the three dimensional output file by typing (e.g. for a run called riverT):

$ ncdump riverT_1.tsout3N | less

Using ncdump, you can see which variables are in the file and which values they have. However, it is normally more instructive to visualize the data. In order to do this, here are some post-processing software packages that can be used:

  • NcView: a tool for visualizing NetCDF data files that is very easy to use but has limited limited possibilities
  • Ferret: a more advanced tool for displaying graphics, but is somewhat more difficult to use than NcView, since options are given through the command line, however it is possible to produce graphs more fit for reports and publications.

A commercial software package such as MATLAB, Python (open source) or any other software that can read the NetCDF format can also be used.