12. Nonlinear Algebraic Solvers

SUNDIALS time integration packages are written in terms of generic nonlinear solver operations defined by the SUNNonlinSol API and implemented by a particular SUNNonlinSol module of type SUNNonlinearSolver. Users can supply their own SUNNonlinSol module, or use one of the modules provided with SUNDIALS. Depending on the package, nonlinear solver modules can either target systems presented in a rootfinding (\(F(y) = 0\)) or fixed-point (\(G(y) = y\)) formulation.

The time integrators in SUNDIALS specify a default nonlinear solver module and as such this chapter is intended for users that wish to use a non-default nonlinear solver module or would like to provide their own nonlinear solver implementation. Users interested in using a non-default solver module may skip the description of the SUNNonlinSol API in section §12.1 and proceeded to the subsequent sections in this chapter that describe the SUNNonlinSol modules provided with SUNDIALS.

For users interested in providing their own SUNNonlinSol module, the following section presents the SUNNonlinSol API and its implementation beginning with the definition of SUNNonlinSol functions in the sections §12.1.1, §12.1.2 and §12.1.3. This is followed by the definition of functions supplied to a nonlinear solver implementation in the section §12.1.4. The nonlinear solver return codes are given in the section §12.1.5. The SUNNonlinearSolver type and the generic SUNNonlinSol module are defined in the section §12.1.6. Finally, the section §12.1.7 lists the requirements for supplying a custom SUNNonlinSol module. Users wishing to supply their own SUNNonlinSol module are encouraged to use the SUNNonlinSol implementations provided with SUNDIALS as templates for supplying custom nonlinear solver modules.