Introduction

The following is a collection of tips for debugging various types of unexpected behavior when building and/or running ISSM.

NOTE: Some of this information may overlap with the public-facing ​ISSM Web site, and in some cases it may be best to simply host it there.

Valgrind

Information on using Valgrind can be found on the ISSM Web site ​"Debugging" page.

BinRead.py

Sometimes you may observe results from ISSM that exceed a given tolerance, differ depending on operating system and/or configuration, or seem to be incorrect altogether. It may be helpful in such cases to use a script designed for marshaling human-readable model settings from binary ISSM input files.

Running Tests

Individual regression tests (designed for our Jenkins testing suite, but available to all users through the SVN repo) and the drivers for them are located at test/NightlyRun. With this as the working directory, tests can be run from within MATLAB with,

runme('id',<test_num>)

Python tests can be run from a Unixy command line by setting first setting the environment with,

export PYTHONPATH="$ISSM_DIR/src/m/dev"
export PYTHONSTARTUP="${PYTHONPATH}/devpath.py"
export PYTHONUNBUFFERED=1

then calling the Python test driver with options,

./runme.py -i <test_no>

Various input and output files are generated for such runs, and are located in execution/test<test_num>-<date>-<time>-<pid>/.

NOTE: It may be difficult to sort out which subdirectory of execution/ corresponds to a given test run. As such, if you are doing multiple runs of the same test with the intention of comparing the results, it is recommended that you make note of the name of the new subdirectory.

Marshalling Binary Input Files

Now that we have run one or more tests, we can inspect contents of the binary input file by running,

scripts/BinRead.py execution/test<test_num>-<date>-<time>-<pid>/test<test_num>.bin

If we wish to compare the input files for, say, MATLAB versus Python runs of the same test, we can redirect the output of BinRead.py to a text file, then run,

diff path/to/BinRead_output_1 path/to/BinRead_output_2

Comparing Queue Scripts

It is worth noting here that it might also be helpful to compare the queue scripts for MATLAB vs Python runs of the same test, with,

diff execution/test-<MATLAB_test>/test<test_num>.queue execution/test-<Python_test>/test<test_num>.queue