Adding debugging info

Adding debugging info#

If the log files do not clearly indicate the cause of a failure, CESM provides two useful debugging options.

Option 1: Increase the coupler debug level#

You can increase the amount of information written to the log files by setting the PIO_DEBUG_LEVEL XML variable.

./xmlchange PIO_DEBUG_LEVEL=2

Advantages:

  • Does not require rebuilding the model.

  • Adds additional diagnostic information to *.log.*.

  • Can help identify the issue.

Because it is inexpensive to enable, this is usually the first debugging option to try.

Option 2: Build the model in debug mode#

If the error is still unclear, rebuild the model with the DEBUG option enabled:

./xmlchange DEBUG=TRUE
./case.build --clean-all
qcmd -- ./case.build

Note: Changing DEBUG requires rebuilding the model.

Debug mode enables additional runtime checks that can detect programming errors such as:

  • out-of-bounds array indexing,

  • divide-by-zero operations,

  • floating-point exceptions,

  • use of uninitialized variables (compiler dependent),

  • and other runtime errors.

These checks often cause the model to stop closer to the point where the actual error occurs, making debugging much easier.

Note: Running with DEBUG=TRUE is significantly slower than a normal optimized build. If your model crashes only after running for many simulated years, a debug build may not be practical. In those cases, first try increasing INFO_DBUG or reproduce the problem with a shorter test case if possible.

Which option should I try first?#

For most runtime failures, the recommended order is:

  1. Inspect the component log files (*.log.*).

  2. Set PIO_DEBUG_LEVEL=2 and rerun (no rebuild required).

  3. If the problem persists, rebuild with DEBUG=TRUE and rerun.

This progression minimizes turnaround time while providing increasingly detailed diagnostic information.

Contents