kinsol SUNDIALS general-purpose nonlinear system solver

## Syntax

                [y,val,info,extra] = kinsol(f,y0,options)

## Arguments

f | a function, a string or a list, the right hand side of the nonlinear system
y0 | a double array: initial guess
options | a sequence of optional named arguments, see the solvers options
y,val | double arrays: approximate solution at the end of solver iterations and value of the system function, at y, respectively
info | an integer, the solver exit code, see the related section below
extra | a MList containing solver information and statistics, see the related section below

## Description

`kinsol` computes the solution of a real or complex system of nonlinear algebraic equations under the classical form

0=F(y)

or under the fixed-point form

y=G(y).

It is an interface to kinsol solver of SUNDIALS library with default inexact Newton method for classical form or fixed-point iterations with Anderson acceleration for fixed-point form. The solver has a specific feature which allows to constrain the sign of solution components (see the options page). Unlike the native implementation, the Scilab interface allows to solve the system when the function and/or solution is complex (see the Complex solutions help page).

In its simplest form, the solver call takes the form

    y = kinsol(f,y0)

where `y0` is the initial guess, `y` is the approximate solution yielded by the solver given default tolerance (which can be changed in

options
). The right hand side can be computed by a Scilab function with one argument, but if you need to pass extra parameters and/or want to use DLL entrypoints see the user functions help page.

## Example

In the following example, we solve the following system of equations

\begin{array}{rcl} 2x_1-x_2-\exp(-x_1) &=&0\\ -x_1+2x_2-\exp(-2x_2) &=&0 \end{array}

with the initial guess [0,0], default inexact Newton method and display solver iterations:

            function F = fun(x)
                F = [2*x(1)-x(2)-exp(-x(1))
                      -x(1)+2*x(2)-exp(-2*x(2))];
            end
            x=kinsol(fun, [0 0], display="iter")

## PDE example

In the following example, we approximate the solution of the following nonlinear pde

\frac{\partial^2 f}{\partial x^2}+\frac{\partial^2 f}{\partial y^2} = \frac{2}{1+f^2}

with finite differences, on [-1,1]x[-1,1] and a particular nonhomogeneous Dirichlet boundary condition. The band Jacobian is approximated with finite differences.

                function out=fun(f,lap,bdy)
                    out = lap*f - 2./(1+f.*f)
                    out(bdy) = f(bdy)-sign(cos(%pi*(X(bdy)+Y(bdy))));
                endfunction

                // define square domain [-1,1] x [-1,1]
                n = 50;
                x=linspace(-1,1,n); y=x;
                [X,Y]=meshgrid(x,x);

                // build Laplacian operator
                dx=x(2)-x(1);
                d1x=sparse(ones(n-1,1));
                d0x=sparse(ones(n,1));
                lap = (diag(d1x,-1)+diag(d1x,1)-2*diag(d0x))/dx/dx;
                // use Kronecker product to build matrix of d/dx^2 and d/dy^2
                LAP = lap .*. speye(n,n) + speye(n,n) .*. lap;
                // Find boundary nodes
                BDY = find(X(:)==x(1) | X(:)==x($) | Y(:)==y(1) | Y(:)==y($))';

                f = kinsol(list(fun,LAP,BDY),ones(n*n,1), jacBand=[n,n], display="iter");

                clf
                gcf().color_map=parula(128);
                surf(x,x,matrix(f,n,n))

function out=fun(f,lap,bdy) out = lap*f - 2./(1+f.*f) out(bdy) = f(bdy)-sign(cos(%pi*(X(bdy)+Y(bdy)))); endfunction // define square domain [-1,1] x [-1,1] n = 50; x=linspace(-1,1,n); y=x; [X,Y]=meshgrid(x,x); // build Laplacian operator dx=x(2)-x(1); d1x=sparse(ones(n-1,1)); d0x=sparse(ones(n,1)); lap = (diag(d1x,-1)+diag(d1x,1)-2*diag(d0x))/dx/dx; // use Kronecker product to build matrix of d/dx^2 and d/dy^2 LAP = lap .*. speye(n,n) + speye(n,n) .*. lap; // Find boundary nodes BDY = find(X(:)==x(1) | X(:)==x($) | Y(:)==y(1) | Y(:)==y($))'; f = kinsol(list(fun,LAP,BDY),ones(n*n,1), jacBand=[n,n], display="iter"); clf gcf().color_map=parula(128); surf(x,y,matrix(f,n,n))

## Exit codes

0 | Successful function return
1 | The initial user-supplied guess already satisfies the stopping criterion
2 | The stopping tolerance on scaled step length was satisfied
-5 | The linesearch algorithm was unable to find an iterate sufficiently distinct from the current iterate
-6 | The maximum number of nonlinear iterations has been reached
-7 | Five consecutive steps have been taken that satisfy a scaled step length test
-99 | The solver has been stopped by user callback

## Extra output and statistics

The

extra
optional output argument is a MList with fields:

solver | the solver name, "kinsol"
method | the name of the method used by the solver: "Newton" (inexact Newton method), "lineSearch" (inexact Newton method with linesearch globalization), "Picard" (Picard iterations), and "fixedPoint" (fixed-point iterations)
linearSolver | the linear solver used by the method, if applicable. This field is "none" when using fixed-point iterations. In other cases this field can be "dense", "band" or "sparse" depending on the format of the Jacobian provided by the user.
stats | a structure gathering the solver statistics:
nIters | the number of iterations
nRhsEvals | the number of right hand side evaluations
nRhsEvalsFD | the number of right hand side evaluations that have been used to approximate the Jacobian
nJacEvals | the number of Jacobian evaluations, when this one has been given by the user
nBacktrack | the number of backtracking steps (lineSearch method)
funcNorm | The scaled Euclidian norm of the system function
stepLength | the length of the last step (Newton and lineSearch methods)
etime | elapsed time by the solver

## See also

- User functions
- Options (kinsol)

## Bibliography

A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, "SUNDIALS: Suite of Nonlinear and Differential/Algebraic Equation Solvers," ACM Transactions on Mathematical Software, 31(3), pp. 363-396, 2005. Also available as LLNL technical report UCRL-JP-200037.

Alan C. Hindmarsh and Radu Serban and Cody J. Balos and David J. Gardner and Daniel R. Reynolds and Carol S. Woodward, "User Documentation for kinsol, 2021, v6.1.1, available online at https://sundials.readthedocs.io/en/latest/kinsol