Why Tolerances Matter
A GLMM fitting algorithm searches for parameter values that optimize a likelihood-based objective. It cannot generally verify that it has found the exact optimum, so it uses numerical stopping rules. A tolerance sets how close a diagnostic must be to its target before the algorithm is allowed to stop. The choice affects the reported convergence status, computational effort, and sometimes the estimates returned.
A tolerance is not itself a measure of model fit. A small gradient or parameter step can support the claim that an algorithm has settled near a stationary point, but does not establish that this point is the best available solution. Conversely, a smaller value of the objective can indicate a better fit under the same objective and data, even if a chosen convergence check has not yet passed. These distinctions are important when reviewing GLMM output.
For clarity, let \(\boldsymbol{\theta}\) denote the vector of parameters being optimized and let \(Q(\boldsymbol{\theta})\) be the objective that the fitting procedure minimizes. For example, \(Q\) may be a negative log-likelihood or an approximation used by the fitting method. All comparisons below assume the same model, data, objective definition, and treatment of constants in that objective.
Gradient and Step-Size Checks
At an interior local minimum of a differentiable objective, the gradient is zero: \(\nabla Q(\boldsymbol{\theta})=\boldsymbol{0}\). In computation, the gradient will rarely be exactly zero, so an optimizer may stop when a norm of the gradient is below a specified threshold. The gradient describes how rapidly the objective would change for a small change in each parameter. A large gradient suggests that a small move could still reduce the objective.
A raw gradient norm can be hard to interpret. Its numerical size depends on the units and scaling of the parameters and the objective. For instance, changing a predictor from units of one to units of one thousand can change the scale of a coefficient and its derivative. Implementations may therefore use a scaled gradient, transforming or standardizing gradient components before comparing them with a tolerance. Always identify which gradient is checked and what scale the software uses; a tolerance value alone is not portable across algorithms or packages.
A step-size check asks whether the latest update to the parameter vector was small. One possible relative measure is the largest component-wise change divided by a scale for that component:
If \(r_{\text{step}}\) is below the step tolerance, the algorithm may stop. This condition says that the latest update was small relative to the chosen scale; it does not prove that the gradient is small. Steps can be tiny because the algorithm is near a minimum, but also because progress has stalled or an attempted update was heavily restricted. That is why step-size evidence should be read with gradient and objective information, not in isolation.
Some methods also stop when the change in objective is small. This can be useful, but a small objective change alone is not decisive: it may occur near a minimum, or because a proposed step made little progress. The checks answer related but different questions. In practice, optimizer implementations may use more than one criterion, and some report a status even when a particular diagnostic has not passed.
Worked Example: A Gradient Tolerance Is Met, but the Check Is Not Strong
Suppose a hypothetical random-intercept logistic GLMM is fitted to binary outcomes from 12 clinics, with 20 patients per clinic. The fitting algorithm minimizes a negative log-likelihood objective \(Q\), and reports the scaled gradient vector \((0.012,-0.004,0.018)\). For this example, assume its stopping rule compares the largest absolute scaled-gradient component with the stated tolerance.
The reported gradient measure is \( \max(0.012,0.004,0.018)=0.018 \). With tolerance \(0.020\), the check passes because \(0.018<0.020\). With a stricter tolerance of \(0.005\), it fails because \(0.018>0.005\). The fit and gradient have not changed; only the standard required by the check has changed.
Now suppose two runs on the same data and objective return \(Q_A=412.30\) with scaled-gradient norm \(0.018\), and \(Q_B=412.34\) with norm \(0.003\). Run B passes the stricter gradient check, while run A has the smaller objective. The arithmetic difference is \(Q_B-Q_A=412.34-412.30=0.04\). The stricter gradient check establishes that B meets a tighter stopping criterion; it does not establish that B fits better. On this objective, A has the lower value. The small difference should be considered in light of numerical precision and the fitting method, rather than treated as a meaningful improvement by itself.
Why a Small Step Is Not Enough
The connection between gradient and step size can be seen from a local Taylor approximation. Suppose \(Q\) is twice differentiable near a current value \(\boldsymbol{\theta}\), and let \(\boldsymbol{\delta}\) be a proposed update. For a sufficiently small update,
where \(H(\boldsymbol{\theta})\) is the matrix of second derivatives of \(Q\). This approximation explains why both diagnostics are informative. If the gradient is small and the update is small, the first-order contribution to objective change is typically small. But a small update by itself does not imply a small gradient: the algorithm may have taken a very cautious step despite a substantial remaining slope.
This is a local justification, not a guarantee of global optimality. It assumes sufficient smoothness in the neighborhood and describes behavior near the current parameter value. For parameters constrained to a boundary, the ordinary condition of a zero gradient in every direction need not apply; constrained methods use conditions that account for the allowed directions. Therefore, interpret gradient reports using the optimizer’s documented definition, particularly when parameters are constrained.
Worked Example: A Small Step with a Remaining Gradient
In a hypothetical GLMM fit, suppose the parameter vector before an update is \((0.40,1.20)\) and the new vector is \((0.4003,1.1992)\). The component changes are \(0.0003\) and \(-0.0008\). Using the relative step definition above,
Thus a step tolerance of \(0.001\) is met. Suppose, however, that the reported scaled-gradient norm is \(0.14\), against a gradient tolerance of \(0.01\). The gradient check fails because \(0.14>0.01\). It would be incorrect to conclude that the optimizer is well converged solely because the update was small. The algorithm may need more iterations or further diagnosis; the small step could reflect limited progress rather than proximity to a stationary point.
Choosing and Comparing Tolerances
There is no single tolerance value that is appropriate for every GLMM, optimizer, parameterization, and objective. A numerical threshold is meaningful only together with the quantity being tested and its scaling. A tolerance of \(0.001\) for a relative step is not directly comparable with \(0.001\) for a scaled gradient or an objective change. Nor does reducing a tolerance by a factor of ten necessarily demand ten times as much accuracy in the estimates.
A practical approach is to use the optimizer’s documented defaults as a starting point, then assess whether the fit is stable and the diagnostics are satisfactory. If a fit is sensitive to a modest tightening of tolerances, report that sensitivity and investigate rather than selecting whichever run gives the most appealing result. Tightening thresholds can increase computation, and may expose numerical difficulties without resolving them. Loosening thresholds can allow earlier termination, but can also stop while the estimates remain materially sensitive to further optimization.
The following comparison helps keep the interpretations separate:
| Quantity checked | What passing supports | What passing does not establish |
|---|---|---|
| Gradient norm | The reported derivative measure is below its threshold. | A global minimum, a better fit than another run, or model adequacy. |
| Step size | The latest parameter update is small under the specified scaling. | A small gradient or successful progress toward an optimum. |
| Objective change | The objective changed little over the checked update or updates. | That the parameters are stable or the solution is globally best. |
| Objective value | Among comparable runs, a lower value is preferable for a minimization objective. | That the optimizer has met a chosen convergence criterion. |
Worked Example: Checking Sensitivity Across Tolerances
A hypothetical study records a binary outcome for 300 patients in 15 clinics. An analyst fits the same random-intercept logistic GLMM three times, changing only a documented scaled-gradient tolerance. The table reports the exposure coefficient, the minimized objective \(Q\), and the scaled-gradient norm. For this illustration, the stated stopping rule requires the norm to be less than the tolerance.
| Gradient tolerance | Exposure coefficient | Objective \(Q\) | Gradient norm |
|---|---|---|---|
| 0.050 | 0.61 | 198.42 | 0.041 |
| 0.010 | 0.60 | 198.39 | 0.008 |
| 0.002 | 0.60 | 198.39 | 0.0016 |
For the first run, \(0.041<0.050\), so the gradient rule passes. For the second, \(0.008<0.010\), and for the third, \(0.0016<0.002\); both pass their respective rules. Tightening from \(0.010\) to \(0.002\) does not change the coefficient at the displayed precision, and the objective is unchanged at two decimal places. That pattern supports numerical stability to the displayed precision for these reported quantities. It does not prove exact equality of the estimates or global optimality.
The first run has a slightly larger objective, \(198.42-198.39=0.03\), and its coefficient is \(0.01\) larger at the displayed precision. This suggests that the first run may have stopped earlier, but the output alone does not establish why. The analyst should inspect the optimizer’s full status and compare the parameters and objective at adequate precision. A stricter threshold is a more demanding check, not a promise of a substantively different or better-fitting model.
Diagnostics, Alternatives, and Common Pitfalls
When a convergence message is uncertain or estimates change across runs, examine more than one output field. Check the exact stopping rule and the reported gradient or step measure; compare the objective and parameter estimates across reasonable reruns; and confirm that the same data, model, and objective were used. A message saying “converged” summarizes an algorithm’s stopping decision. It is not a general certificate that every numerical or modeling concern has been resolved.
Alternative stopping checks have complementary roles. A gradient-based rule targets stationarity directly for a differentiable interior solution. A step-based rule detects small updates and can be useful when parameter changes are the practical concern. An objective-change rule tracks improvement in the optimized criterion. Agreement among these checks is more reassuring than relying on one alone, but none alone rules out an unsuitable model, a numerical problem, or a non-global solution. Comparing optimizers on the same model is another useful check: compare objective values and estimates as well as convergence messages, rather than counting messages alone.
A common mistake is to reason, “The tolerance was made ten times stricter, so the resulting fit must be ten times more accurate and must fit better.” The correction is that the tolerance changes a numerical acceptance threshold, not the objective’s definition. A stricter gradient requirement means the reported gradient must be smaller; it does not order solutions by objective value or measure uncertainty in the estimates.
Report enough detail for another analyst to interpret the check: identify the optimizer and fitting objective, state the relevant tolerance settings and convergence status, and include available gradient or step diagnostics. If results depend on tolerance, say which estimates or objective values changed and by how much. Avoid reporting a bare claim of “convergence” when the status is ambiguous or other diagnostics disagree.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A scaled-gradient norm is \(0.006\). Does it pass a tolerance of \(0.005\)? Does it pass a tolerance of \(0.010\)?
- An optimizer reports a step measure below its tolerance, but its gradient norm is above the gradient tolerance. What can and cannot be concluded?
- Two runs minimize the same objective on the same data. Run A has objective \(87.20\) and gradient norm \(0.012\); run B has objective \(87.23\) and gradient norm \(0.003\). Which has the lower objective, and what does the gradient comparison show?
- Why should a tolerance value be reported with the quantity it applies to?
Solutions. (1) It fails at \(0.005\), because \(0.006>0.005\), and passes at \(0.010\), because \(0.006<0.010\). (2) The latest update is small under the reported scaling, but the gradient check is not met. Small steps alone do not establish that the algorithm is near a stationary point. (3) Run A has the lower objective, since \(87.20<87.23\). Run B has the smaller gradient norm, so it meets a tighter gradient condition if the tolerance is suitably set; this does not make its objective lower. (4) Gradient, step-size, and objective-change tolerances apply to different quantities and scales, so the number alone cannot be interpreted or compared meaningfully.