`scipy`: what does `scipy.integrate.odeint`'s Repeated convergence failures (perhaps bad Jacobian or tolerances)." error mean?

Question

What does the following scipy.integrate.odeint error mean numerically?

Repeated convergence failures (perhaps bad Jacobian or tolerances).

That is, if I have some certainty that the model's programmatic implementation is correct, then what does the error message itself regarding the numerical scheme's issue with the solution process?

Answer 1

What does the following scipy.integrate.odeint error mean numerically?

Repeated convergence failures (perhaps bad Jacobian or tolerances).

You'll have to tell us what method you're using. I can think of two broad (not necessarily exhaustive) scenarios:

• You're using an explicit method, so there are no nonlinear equation solves. Then any adaptive-time-stepping method is going to base adapting the time step on an error criterion involving some tolerances set either by you, the user, or by default in the software. The test in the error criterion will reduce the time step if the error is too large relative to the tolerances, and once the suggested time step becomes too small, the program typically returns an error message saying that the error tolerances cannot be met. (See, for instance, Hairer and Wanner, Volume I, Section II.4, where they discuss a strategy for Runge-Kutta methods; a similar strategy is also briefly discussed in the SUNDIALS documentation around equation (2.6) in that text.)
• You're using an implicit method, in which case there are nonlinear equation solves, and more potential points of failure. For instance, there could be an issue with tolerances, again, which usually manifests itself as in the case with explicit methods described above: if tolerances are too tight and the error criterion in the step size selection step cannot be met by the minimum time step defined in the implementation, the implementation will return a convergence failure. There could also be issues where the nonlinear solver fails to converge to a given tolerance (either user set, or hardcoded in the implementation) within a sufficient number of iterations. Depending on the method used for solving the nonlinear equations embedded in the implicit method, there could be embedded linear solves, and these solves may not converge; in many cases, this convergence failure can be due to errors in implementing the Jacobian, or due to an insufficiently accurate approximation to the Jacobian. (For instance, I have seen convergence failures for stiff problems that occur when a finite difference approximation to the Jacobian matrix is used, and I have seen these convergence failures resolve when the finite difference approximation is replaced with an analytical expression for the Jacobian.) Chapter 2 of the SUNDIALS documentation does a good job of overviewing these general considerations as they apply to the BDF method implemented in CVODE.

That is, if I have some certainty that the model's programmatic implementation is correct, then what does the error message itself regarding the numerical scheme's issue with the solution process?

It really means you have to do more diagnosis.

SciPy is a fine package, and they do a great job of wrapping established numerical software in Python wrappers (dopri5, vode, etc.), but these codes weren't written with ease of numerical diagnostics in mind, and consequently, you'll have to rig up a lot more in the way of "tools" (ways to get output regarding the convergence of any linear or nonlinear solver iterations) than you would if you were using a library like PETSc (where the developers, through experience in having to experiment with different numerical methods, have built in many tools that provide helpful diagnostic output).

The tradeoff between these two sets of tools is that SciPy-like tools are simpler to learn, are great when they "just work", and provide small, simple public APIs, while PETSc-like tools have larger and more complicated public APIs, are more powerful, and require more time and effort to learn.

Generally speaking, you need to look at the residual versus iteration output for any equation solves in your ODE solver, and probably also output from the step size error test in your ODE solver in order to distinguish where the point of failure is in your application, and then from there, you need to figure out how to address that point of failure (which could be as simple as loosening tolerances, or as complicated as using a different discretization because there could be fundamental flaws in the numerical methods you are using, which could be inapplicable to your problem).