Legacy Diagnostics

5.4. Legacy Diagnostics#

This section documents the runtime diagnostic files produced by SUEWS for error handling, warnings, and configuration summaries.

Note

problems.txt and warnings.txt are legacy outputs retained for older SUEWS versions. In current versions, diagnostic messages are emitted to stdout/stderr (and captured by the SuPy logger when running via Python).

5.4.1. Error Messages: problems.txt#

In older versions, if problems occur during simulation, error messages were written to problems.txt.

Serious Errors:

Usually cause the program to stop
Last line contains a non-zero error code
Check the error message for diagnostic information

Successful Run:

If the simulation completes successfully, problems.txt ends with:

Run completed.
0

SUEWS includes many error messages to help diagnose common issues. If you encounter an error without a clear message, please report the details to help improve diagnostics.

See Troubleshooting for help solving problems.

5.4.2. Warning Messages: warnings.txt#

In older versions, minor issues that don’t stop the simulation were written to warnings.txt.

Important Notes:

Always check warnings to ensure there are no serious problems
The file can grow large (several GB) during extended simulations
Use tail/head to view portions without loading the entire file

Viewing Diagnostics (Current Versions):

# Capture stdout/stderr to a log file and inspect it
suews-run config.yml 2>&1 | tee suews-run.log
tail -100 suews-run.log

# Search for specific warnings/errors
grep -E "Warning|ERROR" suews-run.log

Suppressing Warnings:

To suppress warning messages emitted by the kernel, set SuppressWarnings = 1 in RunControl.nml. For YAML configuration, refer to the configuration reference in YAML Configuration Format.

Warning Format:

Warnings typically include:

Grid number
Timestamp
Error count
Description

Initial-stage warnings (before grid numbers are assigned) show 00000 for these fields.

5.4.3. Model Parameters: SS_FileChoices.txt#

For each run, SUEWS writes a summary of the model parameters to SS_FileChoices.txt.

This file contains:

All parameter values from input files
Configuration options
Site-specific settings

Use this file to verify that the model read your configuration correctly.

5.4.4. Troubleshooting#

Common issues and solutions:

Empty problems.txt:

If the file contains only zeros or is empty, the simulation likely completed successfully.

Large warnings.txt:

This usually indicates repeated minor issues. Common causes:

Unrealistic forcing data values
Edge cases in parameterisations
Long simulation periods

Consider:

Reviewing forcing data quality
Checking parameter values
Using SuppressWarnings if warnings are understood and acceptable

Missing output files:

Check:

File paths in RunControl.nml
Write permissions in output directory
Console output / Python runtime logs for error messages