Troubleshooting

This section covers common issues encountered when building and running OpenWQ.

Build Issues

CMake cannot find Armadillo

Ensure Armadillo is installed and that CMake can locate it. On Linux:

sudo apt-get install libarmadillo-dev

On macOS:

brew install armadillo

If installed in a non-standard location, set the ARMADILLO_ROOT environment variable.

CMake cannot find SUNDIALS

SUNDIALS is only required if you plan to use the SUNDIALS CVode solver. Install it via your package manager:

# Linux
sudo apt-get install libsundials-dev

# macOS
brew install sundials

CMake cannot find PhreeqcRM

PhreeqcRM is only required if you plan to use the PHREEQC geochemistry module. Follow the installation instructions from the USGS PhreeqcRM repository.

Linker errors with HDF5

Ensure HDF5 is compiled with C++ support. On some systems, you may need to specify the HDF5 path explicitly:

cmake -DHDF5_ROOT=/path/to/hdf5 ...

Fortran compiler mismatch (mizuRoute coupling)

When building the mizuRoute-coupled version, ensure that the Fortran and C++ compilers are compatible. Mixing compiler vendors (e.g., Intel Fortran with GNU C++) can cause linking errors.

Runtime Issues

“Number of components does not match” error

When using PHREEQC, this error means the number of chemical species defined in the OpenWQ configuration does not match the number of components discovered by PhreeqcRM’s FindComponents(). Enable RUN_MODE_DEBUG in the master config to see the full component list and adjust your configuration accordingly.

NaN or Inf values in output

This typically indicates numerical instability. Try:

  • Reducing the simulation time step

  • Switching to the SUNDIALS solver (which uses adaptive time stepping)

  • Checking that initial conditions are physically reasonable

  • Verifying that source/sink magnitudes are not excessively large

Segmentation fault at startup

Common causes:

  • Missing or incorrectly formatted JSON configuration files

  • File paths in JSON that do not exist

  • Mismatched compartment names between the host model and OpenWQ configuration

Output files are empty

Verify that:

  • The RESULTS_FOLDERPATH directory exists and is writable

  • The CHEMICAL_SPECIES list in the master config contains valid species names

  • The COMPARTMENTS_AND_CELLS section references valid compartment names

  • The TIMESTEP output interval is not larger than the simulation duration

OpenMP thread count warning

If USE_NUM_THREADS is set higher than the number of available cores, OpenMP may produce warnings. Set it to "all" to automatically use all available cores, or specify a reasonable integer value.

JSON Configuration Issues

JSON parse error

OpenWQ’s JSON parser supports C/C++ style comments (// and /* */), but the JSON structure must be valid. Common issues:

  • Missing commas between key-value pairs

  • Trailing commas after the last element in an object or array

  • Unquoted string values

  • Mismatched brackets or braces

Use a JSON validator to check your configuration files before running.

“Unknown compartment name” error

Compartment names in OpenWQ configuration files must exactly match the names exported by the host hydrological model. These are case-sensitive. Enable RUN_MODE_DEBUG to see the list of available compartment names.