Interpreting phgs.exe output during a simulation

This post explains how to interpret the runtime output generated by HGS during each timestep while computing the flow solution. The output is useful for tracking the convergence of the simulation and diagnosing potential performance issues. Conceptually, the runtime output helps monitor the progress of the simulation and iteration steps, providing critical information on how the solver is performing. By understanding the output, users can adjust their simulation parameters and ensure accurate results. We find this detailed output particularly valuable when troubleshooting and improving model performance.

---

In this post we will discuss in detail the runtime output produced by HGS after each timestep when computing the flow solution. This information is useful for tracking the convergence of the simulation as well as for diagnosing and remedying any poor performance issues. Before we dig in, a brief overview of the solution process in HGS will help to aide our discussion. At each timestep, HGS employs the Newton–Raphson iterative scheme to solve the nonlinear equations that arise from discretizing the flow equations. If we denote the solution vector by x (typically pressure head), then the nonlinear equations being solved can be expressed as F(x) = 0. In its most basic form, the Newton–Raphson iterative scheme for solving F(x) = 0 can be written as:

Set initial guess x
While not converged do
	Build the Jacobian matrix J = F’(x) and Newton residual r = F(x)
	Solve the linear system Js = −r for the Newton step s
	Update the relaxation parameter a (if using), otherwise a = 1
	Update the solution x = x + a∙s
	Check for convergence:
		Norm_inf(s) ≤ tau or Norm_inf(r) ≤ eps
End

We will use the symbols and steps defined here when discussing the runtime output. The following screen capture illustrates the runtime output produced by HGS when running the Abdul verification problem.

Let’s go ahead and break this output down.

Simulation Progress:

• Global target time: This is the next target time. In brackets we can see that it is the 3rd such target time out of nine total. Note that target times comprise all points in time specified as output times (using the “Output timed…end” command) as well as any point in time where boundary condition forcing data have a change in magnitude.

• %done: The percentage of the simulation completed as measured from the initial start time to the most recent successful simulation time. Note that the final target time is used as the end time of the simulation.

• Time: The most recent successful simulation time.

• delta_t: The distance between the most recent successful simulation time and the simulation time that is currently being computed.

• Tnext: The simulation time at which the solution is currently being computed.

Summary of Nonlinear Iteration:

• Iter: The iteration number of the nonlinear solve step.

• Relfac: The underrelaxation factor for the Newton iteration (a).

• Delval: The absolute maximum value of the solution of the linear system Js = -r, i.e., the infinity norm of the Newton step vector s.

• @Node: The index at which the absolute maximum occurs.

• NcNode: The number of elements for which |s(i)| > newton_absolute_convergence_tolerance (see the command “Newton absolute convergence criteria”).

• Resval: The absolute maximum value of the Newton residual vector (r).

• @Node: The index at which the absolute maximum occurs.

• NcNode: The number of elements for which |r(i)| > newton_residual_convergence_tolerance (see the command “Newton residual convergence criteria”).

• Solv: The linear system Js = -r is solved approximately via an iterative solver, by default BiCGStab. This value is the number of iterations required by the linear solve to reach its convergence goals (see the commands “Flow solver convergence criteria” and “Flow solver maximum iterations”).

• Dom: The domains at which Delval and Resval are achieved, respectively.

The final lines of this section indicate that convergence was achieved after two iterations of the nonlinear solver. It shows the values of Delval and Resval, and their corresponding tolerances. Note that only one such convergence test needs to be satisfied.

Adaptive Timestepping Update:

• Variable: The quantity being tracked (head, water depth, saturation, and number of nonlinear solver iterations).

• Max. change: The absolute maximum difference in the quantity between the last successful simulation time and the one being computed.

• Target change: This is the targeted or expected change in the quantity over a single timestep as specified in the debug.control file. For example, in the case of head, it would be the “head change target”.

• Dt multiplier: This is the ratio of Max. change to Target change.

• At node: This is the index at which the maximum absolute difference occurs.

At the bottom of the output it indicates that the solution at time Tnext was accepted. It then shows how the next timestep is computed. The timestep multiplier (dtfac) is the minimum of all the Dt multiplier values, restricted to the interval [dtfac_min, dtfac_max] (see commands “Minimum timestep multiplier” and “Maximum timestep multiplier”). The next timestep is then computed according to the formula:

delta_t = max(min(dtfac∙delta_t, max_timestep), min_timestep)

The minimum and maximum timestep size can be set by the commands “Minimum timestep” and “Maximum timestep”, respectively.