# HydroGeoSphere/Newton Iteration Parameters

The following parameters can be used to control the Newton-Raphson iteration scheme for solution of the variably-saturated flow problem as described in Section 3.13.2.

## Newton maximum iterations

* maxnewt Maximum number of Newton iterations.
Assigns a new value for the maximum number of Newton iterations, which defaults to 15. If this number is exceeded during a time step, the current time step value is reduced by half and a new solution is attempted.

## Jacobian epsilon

* epsilon Jacobian epsilon.
Assigns a new value for the Jacobian epsilon, which defaults to 1 × 10$^{−4}$. The Jacobian epsilon is the shift in pressure head used to numerically compute the derivatives in the Jacobian matrix. As a rule of thumb, a value equal to 10$^{−5}$ times the average pressure head in the domain is recommended.

## Newton absolute convergence criteria

* delnewt Newton absolute convergence criteria.
Assigns a new value for the Newton absolute convergence criteria, which defaults to 1 × 10$^{−5}$. Convergence of the solution occurs when the maximum absolute nodal change in pressure head over the domain for one Newton iteration is less than this value.

## Newton residual convergence criteria

* resnewt Newton residual convergence criteria.
Assigns a new value for the Newton residual convergence criteria, which defaults to 1 × 10$^{−8}$. Convergence of the solution occurs when the maximum absolute nodal residual (see Section 5.5.3) in the domain for one Newton iteration exceeds this value.

## Newton maximum update for head

* NR_dhtol Newton maximum update for head.
Assigns a new value for the Newton maximum update for head, which defaults to 1.0. This is used to calculate the underrelaxation factor ${\omega }_{r}$ in such a way that:
    ${\omega }_{r}=\mathbf {NR\_dhtol} /max(dh_{r})$ (Equation 5.6)
    $h_{r}=h_{r-1}+{\omega }_{r}*dh_{r}$ (Equation 5.7)
where $max(dh_{r})$ is the computed maximum update for head in the $r^{th}$ Newton iteration, and $h_{r}$ is the head flow solution after $r$ iterations. As $\mathbf {NR\_dhtol}$ becomes smaller, the Newton solution becomes more stable but with possibly more iterations. For highly nonlinear problems for which Newton linearization easily fails to converge, it is recommended to set this value smaller.

## Newton maximum update for depth

* NR_ddtol Newton maximum update for depth.
Assigns a new value for the Newton maximum update for water depth, which defaults to 1 × 10$^{−2}$. The same as $\mathbf {NR\_dhtol}$ above but applies only to water depth.

## Newton maximum residual increase

* NR_resnorm_fac Newton maximum residual increase.
Assigns a new value for the Newton maximum residual increase, which defaults to 1 × 10$^{30}$.
If the Newton maximum residual increases by more than $\mathbf {NR\_resnorm\_fac}$, the Newton loop is restarted with a smaller time step.

## Remove negative coefficients

Forces negative inter-nodal conductances to zero. Negative inter-nodal conductances result in inter-nodal flow from lower to higher heads and can cause oscillatory behavior during Newton iterations [Letniowski and Forsyth, 1991].

## Nodal flow check tolerance

* n_flow_check_tol Assigns a new value for the nodal flow check tolerance, which defaults to 1 × 10$^{−2}$.
This checks that the relative local (nodal) fluid mass balance is acceptable for all nodes:
    $[(Q_{in}-Q_{out}+dM)/Q_{in}]<\mathbf {n\_flow\_check\_tol}$
Absolute fluid mass balance can always be satisfied against the global convergence criteria, if local inflows and outflows, and mass accumulation are very small.
    $(Q_{in}-Q_{out}+dM)<\mathbf {global\_tolerance}$
and where $Q_{in}$, $Q_{out}$, and $dM$ (mass accumulation) are much less than 1.0. This can deteriorate the transport solution, as the concentration is defined as solute mass per unit fluid mass.

## No nodal flow check

Turns off the nodal flow check feature. In cases where a transport solution is not required, the nodal flow check is not necessary.

## Underrelaxation factor

* under_rel Underrelaxation factor.
Assigns a new value for the underrelaxation factor for the Newton iteration, which defaults to 1. This value can range from 0 (full underrelaxation) to 1 (no underrelaxation).

## Compute underrelaxation factor

Causes the underrelaxation factor ω to be computed according to the following method described by Cooley [1983]:
    ${\begin{aligned}{\omega }_{r+1}&={\frac {3+s}{3+\left\vert s\right\vert }}~~~if~s\geq -1\\&=~{\frac {1}{2\left\vert s\right\vert }}~~~~~if~s<-1\\\end{aligned}}$ (Equation 5.8)
where:
    ${\begin{aligned}s&={\frac {e_{r+1}}{e_{r}{\omega }_{r}}}~~~if~r>1\\&=~~~1~~~~~if~r=1\\\end{aligned}}$ (Equation 5.9)
In the equations presented above, $r$ and $r+1$ represent the previous and current iteration level, ${\omega }_{r}$ and ${\omega }_{r+1}$ represent the underrelaxation factor for the previous and current iteration levels, and $e$ represents the maximum value of the largest difference between head values for 2 successive iterations, $e_{r}=Max_{I}\left\vert {\psi }_{I}^{r}-{\psi }_{I}^{r-1}\right\vert$.

## Compute underrelaxation factor limit

* dellim Upper limit on the computed underrelaxation factor.
Assigns a new value for the upper limit on the computed underrelaxation factor, which defaults to 1000. A suggested value is 10 times the system domain thickness.

## Minimum relaxation factor allowed

* min_relfac_allowed Minimum value allowed for computed underrelaxation factor.
Assigns a new value for the lower limit on the computed underrelaxation factor, which defaults to 0.001. If not the first timestep, and the computed underrelaxation factor is less than this value, the current timestep is cut in half and the Newton Raphson iteration loop is re-started.

## Newton information

Causes HydroGeoSphere to write more detailed information to the listing file about the performance of the Newton iteration process.