Why Solver Messages Need Interpretation
An ODE solver can stop with a warning, return a partial trajectory, or report success while the simulated states are implausible. The status message describes what the numerical algorithm encountered; it does not, by itself, identify the biological or programming cause. A useful diagnosis combines four kinds of evidence: the termination status, the step-size history, the state trajectory near the problem, and the values returned by the model's derivative function.
Write the model as \(dy/dt=f(t,y,\theta)\), where \(y\) is the vector of states, \(t\) is time, and \(\theta\) is the parameter vector. An integration attempt assumes that the right-hand-side function can be evaluated at the times and states required by the solver. For ordinary smooth segments, it also assumes that the function behaves regularly enough locally for the solver's error-control method to estimate its numerical error. Discontinuities, such as a dose input, require the solver to handle or stop at the discontinuity as specified by the model.
Status labels and warning text differ among software packages. Interpret the underlying facts rather than relying on a particular label: Did the solver reach the requested end time? Did it stop at a finite time? Did a derivative evaluation return a non-finite value? Did step sizes repeatedly shrink? Did the states become unreasonable before termination? These questions are more portable than any one software's message.
What Step-Size Histories Can Reveal
Adaptive solvers estimate local numerical error and adjust the step size. If an estimated error is too large, a step is rejected and the solver tries again with a smaller step. A sudden series of rejections can indicate that the solution changes rapidly, that a discontinuity was not handled correctly, or that the right-hand side has become irregular or invalid.
A simplified error-control argument explains why shrinking steps appear in logs. For a method of order \(q\), suppose its local error estimate behaves approximately as \(E(h)\approx C h^{q+1}\) over a smooth region, where \(h\) is the step size and \(C\) depends on the local solution and method. If a step is accepted only when the error is below a target \(\tau\), then reducing an excessive error estimate \(E\) suggests a new step size of approximately:
This relation is an explanatory approximation, not a universal formula for every solver. It shows that repeatedly small steps may be the solver's response to rapid local change. But the same pattern can occur when the model approaches a singularity, crosses a discontinuity unexpectedly, or contains an incorrect derivative. A small step size is therefore evidence to investigate, not proof of stiffness.
Stiffness is a property of the dynamics: substantially different time scales can make explicit methods take very small steps for stability, even when the solution of interest changes slowly. A solver that takes many tiny steps, especially while the states remain finite and smooth, may be encountering stiffness. Compare the behavior with a suitable stiff solver as a diagnostic, but do not treat a successful run from that solver as proof that the model is correct.
Worked Example: Repeated Step Rejections in a Stiff System
Consider the hypothetical system \(dy_1/dt=-1000(y_1-y_2)\) and \(dy_2/dt=-(y_2-1)\), with initial state \(y_1(0)=0\), \(y_2(0)=0\). An explicit solver is asked to integrate to \(t=5\) time units. Its illustrative log reports many rejected steps early in the run, accepted step sizes decreasing from about \(0.01\) to \(0.0002\), finite derivative evaluations, and eventual termination because its maximum number of steps was reached.
The two rates in the equations differ greatly: the first equation contains a rate scale of \(1000\) per time unit, while the second contains a rate scale of \(1\) per time unit. This separation of time scales is consistent with stiffness. The log does not show a non-finite derivative, and the states remain finite in the reported portion, so a direct domain failure is not the leading explanation.
The appropriate next diagnostic is to run the same equations, initial conditions, parameters, and requested interval with a solver intended for stiff systems. If that run completes with finite, smooth states and reasonable solver work, stiffness becomes a stronger explanation for the explicit solver's behavior. If both methods fail at the same time with the same non-finite derivative or implausible state, investigate the model and inputs instead. The step history alone cannot settle the diagnosis.
Trace the Failure Back to a State and Derivative
When an integration stops, first locate the earliest suspicious point, not merely the final warning. Inspect the last accepted time and state, any rejected trial states the software exposes, and the derivative evaluation at or near that point. A non-finite derivative, such as NaN or infinity, often narrows the search to an invalid operation or a state outside the function's mathematical domain. A finite but implausibly large derivative can also signal a coding or parameter problem.
Use the model's state mapping to identify each component by name, then compare its trajectory with expected signs, scales, and constraints. For example, a negative concentration may be a small numerical excursion near zero, a substantial violation caused by an incorrect balance, or a permissible mathematical state in a model that does not impose non-negativity. The interpretation depends on the equations; do not silently replace negative values with zero just to eliminate a warning.
A derivative function can be evaluated directly at selected time-state-parameter combinations, independently of a full integration. This can reveal wrong vector order, an incorrect parameter, a missing return value, a division by zero, or an invalid function argument. Check values at the initial condition first, then at the last credible state before failure. If evaluation at the initial condition already fails, the problem is not a late-emerging stiffness issue.
Worked Example: A State-Indexing Error Produces a Non-Finite Derivative
Suppose a model has two states, \(A\) and \(B\), stored in the order \(y=(A,B)\), and the intended equation is \(dA/dt=-kA\), with \(k=0.4\) per hour. At a particular evaluation, the state is \(A=2\) mg/L and \(B=0\) mg/L. The intended derivative for \(A\) is:
Imagine the implemented function instead uses the second state in this calculation and divides by it: \(dA/dt=-kA/B\). At the stated evaluation, it attempts to divide by zero. The derivative is not finite, so an integration warning at or near this state is consistent with a coding defect. The equation also has incorrect units: \(kA/B\) has units of inverse time if both states are concentrations, rather than concentration per time. That dimensional mismatch provides independent evidence of an implementation error.
The correction is to use the intended state and equation, \(dA/dt=-kA\), not to loosen tolerances or switch solvers. Then evaluate the corrected derivative at the same state and confirm that it returns \(-0.8\ \mathrm{mg\,L}^{-1}\mathrm{h}^{-1}\). This direct check identifies the fault before another integration attempt.
Check Parameters and Domains Before Changing Solver Settings
A mathematically valid solver cannot compensate for an invalid parameter value or undefined model expression. Check that parameters satisfy their intended constraints and units, and that expressions such as logarithms, square roots, and denominators are evaluated in their valid domains. A negative volume, a zero denominator, or a parameter in the wrong unit scale can produce extreme derivatives, non-finite values, or explosive trajectories.
Worked Example: Zero Volume Causes Failure at the Initial Time
For a one-compartment concentration state \(C\), suppose the model is \(dC/dt=-(CL/V)C\), where clearance \(CL\) has units L/h and volume \(V\) has units L. Let \(C(0)=10\) mg/L and \(CL=0.6\) L/h, but suppose the parameter table supplies \(V=0\) L. Evaluating the initial derivative requires:
The division by zero makes this derivative undefined. A warning at the initial time is therefore consistent with an invalid parameter value, not evidence that the model is stiff. Check the parameter source, units, and any parameter transformations; do not substitute a small positive volume unless that value is scientifically and computationally justified.
For comparison, if the intended hypothetical volume is \(3\) L, then \(CL/V=0.2\ \mathrm{h}^{-1}\), and the initial derivative is \(-(0.2\ \mathrm{h}^{-1})(10\ \mathrm{mg/L})=-2\ \mathrm{mg\,L}^{-1}\mathrm{h}^{-1}\), a finite value with the correct units. This calculation checks the initial derivative only; it does not by itself verify the entire implementation or trajectory.
A Practical Diagnostic Sequence
Use a sequence that separates immediate defects from numerical difficulty. Preserve the original warning and settings so that each diagnostic change can be compared with the original run. The sequence below is a triage method, not a substitute for understanding the model.
Record whether the requested end time was reached, the last accepted time, and the status message. Distinguish a completed integration from a partial trajectory.
Identify which states first become non-finite, unexpectedly large, negative, or inconsistent with the model's intended constraints. Check whether the problem begins at the initial condition or later.
At the initial condition and last credible state, inspect every derivative component, its units, and the operations used to calculate it. Check state ordering and parameter values against their definitions.
Repeated rejections and very small steps with finite, smooth states can indicate stiffness. Abrupt failure at a non-finite derivative points more directly to a domain, coding, or input problem.
Correct a demonstrated defect first. If stiffness is plausible after the model and inputs have been checked, compare with a suitable stiff solver. Keep the equations and inputs fixed when making that comparison.
Comparing Explanations and Avoiding Misdiagnosis
| Evidence | Likely explanation to investigate | Useful next check |
|---|---|---|
| Derivative is NaN or infinite at the initial state | Invalid initial value or parameter, division by zero, or invalid function argument | Evaluate each expression at the initial state and check parameter domains and units |
| Derivative becomes non-finite only after a state crosses a boundary | Domain restriction, incorrect state evolution, or an unhandled event | Inspect the state trajectory and the expression whose domain is violated |
| Many rejected steps; states and derivatives remain finite | Stiffness, rapid local change, or a discontinuity | Inspect where rejections occur; compare an appropriate solver while keeping the model fixed |
| Integration completes but states are implausible | Possible coding, parameter, mapping, or model-specification error | Inspect state definitions and derivative calculations; a success status is not validation |
Changing the solver is useful when numerical difficulty is plausible, but it is not a general repair. Loosening tolerances may reduce the number of steps while concealing important behavior; tightening them may increase work without resolving a coding error. Likewise, clipping states to an allowed range can change the model equations and hide the reason a state left that range. Make such changes only when they are part of the intended model or a justified numerical treatment.
These diagnostics are not a proof that the model is correct. A solver may complete despite an incorrect state ordering, wrong parameter units, or a scientifically inappropriate equation. Conversely, a valid model may be difficult to integrate with a particular method. The distinction comes from combined evidence: direct evaluation of the implemented derivatives, parameter and domain checks, trajectory behavior, and the response to a solver change. The earlier material on sign, scale, and indexing errors is particularly relevant when the trajectory is finite but its direction or magnitude is unexpected.
Common Pitfall
Check Your Understanding
For each question, decide what the evidence supports and identify the next useful check. Brief solutions follow.
- A solver repeatedly rejects steps, but the states and derivatives remain finite. Does this establish stiffness? What should be checked next?
- A model's derivative is infinite at the initial condition because a parameter appears in a denominator and is zero. Is switching to a stiff solver the first correction?
- A solver reports successful completion, but a concentration rises when its implemented equation specifies a negative derivative throughout the interval. What does success establish, and what should be examined?
- Why can repeatedly shrinking step sizes be consistent with both stiffness and a coding or domain problem?
Solutions. (1) No. It is consistent with stiffness but not diagnostic; inspect where the rejections occur, verify the model and inputs, and consider a suitable stiff solver if the states and derivatives remain regular. (2) No. Check and correct the parameter value or its definition first; a solver cannot evaluate an undefined derivative. (3) It establishes only that the solver met its completion criteria. Check the implemented derivative, state mapping, and parameter values against the specified equation. (4) The solver reduces step size when its error control or stability requirements are not met, but rapid dynamics, irregular or undefined expressions, and unhandled discontinuities can all trigger that response.