Using the debug.control file for real-time tuning of HGS simulation performance

This post explains how to use the debug.control file to modify the performance of an HGS simulation in real-time. By adjusting settings in the debug.control file, users can tweak parameters like convergence and time stepping without needing to restart the simulation. This is particularly helpful for optimizing the simulation's behavior during runtime. We find that using debug.control is a great way to test different settings and improve model performance on the fly. The file also provides the flexibility to pause simulations or adjust output, making it an essential tool for users looking to troubleshoot or fine-tune their models.

---

debug.control is a file generated by phgs.exe that allows a user to modify the performance of an HGS simulation in real-time while the simulation is running. During a simulation, HGS checks for the presence of a file called debug.control in the same directory as the prefix.grok file and, if found, it preferentially honours settings in the debug.control file over those set via the grok file. This allows the user to adjust simulation parameters and see the impacts of these changes on model performance in real-time without having to stop the model and restart it.

If, at simulation start up, the debug.control file is not found by HGS, a new debug.control file will be created.

The head and tail of the debug.control file are shown in the file excerpt below. Lines beginning with the comment character (!) are ignored. When first generated, the only uncommented line is the first one, debug off, which causes HGS to run normally, and not to take any run-time debug actions.

To use the debug.control file, the user adds a comment (!) before “debug off” and then removes the comment (!) from in front of the instructions they wish HGS to use. You should then save the file, at which point the instructions you used will immediately take effect. HGS checks the debug.control file at the beginning of every Newton iteration, and the beginning of every timestep.

debug off
! ------------------------------------------------- Pause execution
! pause timestep
! pause at time
!         10000.00000
! pause flow convergence loop
! ------------------------------------------------- Produce output
! write output files
! write saturated flow matrices

...etc...

! ------------------------------------------------- Adaptive timestep targets
! concentration change target
!             0.05000
! mass change target
!         0.10000E+21
! mass error target
!           100.00000
! minimum timestep multiplier
!             0.50000
! maximum timestep multiplier
!             2.00000

Commands in debug.control fall into three main categories:

1. Pausing a simulation

2. Writing additional simulation output, and

3. Convergence and time stepping controls

Typically, when I use the debug.control file I am adjusting convergence and time stepping controls to improve the simulation’s behaviour.

Note: Since the settings in the debug.control file override those in the grok file, it is a good idea, if you have modified the debug.control file during a simulation, to delete it before running your next simulation to avoid changes to your grok file not being honoured.

More details on debug.control can be found in Appendix C of the HydroGeoSphere User Manual.

Sample Problem

You can download a sample problem here in which the settings in the grok file lead to a very slow model run (I’m not sure how long it will take to run with the current settings because I got bored and fixed it through the debug.control file). Try editing the debug control file to see if you can get the model to complete in under a few minutes, if you need to cheat you can take a look at my debug.control file in the /good_debug folder.