Skip to content

Development Tasks / Debugging

StateMod code is complex and may result in logic sequences that result in errors that require debugging. This documentation contains the following sections:

Debugging Using StateMod Messages

StateMod creates a log file when a dataset is run. A generic Statem.log file is created and is written to when the program starts. After a dataset is specified (by specifying the response file), a log file for the dataset is created, for example wm2015B.log.

The logging level for StateMod is controlled by various control file and other settings. Turning on logging messages for detailed operations can create very large log files and should only be done when troubleshooting an issue.

Refer to the StateMod user documentation for more information.

Debugging Using a Check Version of the Executable

Periodically, running StateMod may generate "core dumps", "segmentation faults", or other errors, resulting in warning and error messages and the program will not run completely. This is typically due to a data and/or logic problem that causes one of the following cases:

  • Division by zero.
  • Array index is outside the accepted range.

StateMod is by default compiled with options that result in optimization level 3, with some run-time checks. This allows StateMod to run fast.

To compile with a higher level of run-time checks, use the makefile statemod_check target to compile the code. Performing these checks can slow down the code, which is why this version of StateMod is not typically used to run datasets in production. Compiling and running a check version of the StateMod executable may provide insight. To compile a check version, use a MSYS2 MINGW64 window and change to the /src/main/fortran folder. Run the following.

make veryclean_check
make statemod_check

The resulting executable will have a name like statemod-17.0.3-gfortran-win-64bit-check.exe (note the check in the name). Then try running the resulting executable with a dataset. If any messages are printed, check the code for related logic.

Debugging Using the gdb Debugger

If the troubleshooting approaches described in the previous sections do not pinpoint the issue, try running the gdb debugger program, which is installed with the compiler. Because this program depends on the development environment, it is generally run in an MSYS2 MINGW64 window.

The optimized and check versions of StateMod are both compiled with the -g option, which includes debug information in the executable. Running the debugger on optimized or check versions of the executable might give different results and bot may be necessary to pinpoint an issue.

To use the debugger, run StateMod as follows (with the appropriate StateMod executable):

gdb statemod.exe

The gdb program should start and then show a (gdb) prompt.

At the (gdb) prompt, type run and execute statemod as normal, for example:

(gdb) run
Starting program: D:\Users\steve\cdss-dev\StateMod\git-repos\cdss-app-statemod-fortran-test\test\datasets\ym2015_StateMod_modified\0-dataset\ym2015_StateMod_modified\ym2015_StateMod_modified\StateMod\statemod-17.0.3-gfortran-win-64bit-check.exe
[New Thread 984.0x4ccc]
 Enter base file name without .rsp (statem, yampa, etc)
[Thread 984.0x4ccc exited with code 0]
ym2015H
 Startup log file for messages to this point: ym2015H.rsp

   Closing startup log file: statem.log
   Opening dataset log file: ym2015H.log

________________________________________________________________________

        StateMod
        State of Colorado - Water Supply Planning Model

        Version:     17.0.3
        Last revision date: 2021/09/12

________________________________________________________________________

 Select primary run option by entering number:

   [0] : STOP
   [1] : Baseflow
   [2] : Simulate
   [3] : Report (prompt will ask for report type)
   [4] : Data Check
   [5] : Version
   [6] : Help
   [7] : Update
   [8] : SimulateX (without reports)
   [9] : BaseflowX (ungaged locations only)

2

If an error occurs, type where and gdb should print the line location.