Nonlinear Equations

solveNonlinearEquations!(F!::Function,
                         m::Integer,
                         x::Vector,
                         scale::Union{Vector, Nothing};
                         nonlinearity::Nonlinearity = high,
                         restricted = false,
                         xtol = 1e-6,
                         maxiter = 50,
                         quasi = true,
                         forwardjac = false,
                         loglevel::Loglevel = info) -> convergence::Bool

Solve nonlinear equation system $F(x) = 0$ with $length(F) <= length(x)$ by global Gauss-Newton method with error oriented convergence criterion and adaptive trust region strategy. Optionally Broyden's 'good' Jacobian rank-1 updates are used. In case of underdetermined and/or rank-deficient equation system, a least squares solution is computed such that the norm of the scaled solution vector is minimal.

F! is a C1 continuous function with length $n$ of input and $m$ of output vector where $n >= m$ (determined or underdetermined system of equations). It has to be defined by F!(F::Vector, x::Vector) -> success::Bool returning true in case of successful evaluation.

m is the length of the output vector of F!.

x is the vector of unknowns. On input it must contain an initial guess of the problem's solution, which is used as the start vector of the iteration. On output it contains the iteration result. If solveNonlinearEquations! returns true, the iteration converged and x contains an approximation of the solution which satisfies the error tolerance xtol.

scale is a vector of length $n$ which contains positive scaling values used in computations of scaled norms and Jacobian scaling due to $x_i / {scale}_i$. In case of nothing automatic scaling depends on nonlinearity.

nonlinearity defines the grade of non-linearity of the problem. Possible @enum values are mild, high and extreme. In case of extreme restricted is automatically set true.

restricted can be used to restrict the monotonicity test (i.e. damping factor) such that large iteration steps are avoided.

xtol is the error tolerance which the final approximate solution x must satisfy.

maxiter is the maximum number of allowed iterations.

quasi enables switch to local quasi Newton iteration (which avoids costly Jacobian evaluations) in case of advanced convergence.

forwardjac enables analytic Jacobian evaluation using ForwardDiff package. Otherwise numeric computation by FiniteDiff is used.

loglevel is the log message level. Possible @enum values are quiet, info, verbose and debug.

Reference: P. Deuflhard: Newton Methods for Nonlinear Problems. - Affine Invariance and Adaptive Algorithms (section 4.4). Series Computational Mathematics 35, Springer (2004).