nleqs_core

nleqs_core(sp, fcn, x0, opt)
nleqs_core() - Core Nonlinear Equation Solver with arbitrary update function.
[X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_CORE(SP, FCN, X0, OPT)
A function providing the core code for a standardized interface for
various methods of solving the nonlinear equation f(x) = 0, beginning
from a starting point x0. Allows for an arbitrary update function.

Inputs:
    SP : solver parameters, struct with the following fields (all required)
        alg : algorithm code, e.g. 'NEWTON', 'GS', etc.
        name : user-visible name to be followed by 'method' in output
            'Newton''s', 'Gauss-Seidel', etc.
        default_max_it : default value for max_it option, if not provided
        need_jac : 1 - compute Jacobian, 0 - do not compute Jacobian
        update_fcn : handle to function used to update x, with syntax:
            x = update_fcn(x, f)
            x = update_fcn(x, f, J)
    FCN : handle to function that evaluates the function f(x) to
        be solved and (optionally) its Jacobian, J(x). Calling syntax
        for this function is:
            f = FCN(x)
            [f, J] = FCN(x)
        If f and x are n x 1, then J is the n x n matrix of partial
        derivatives of f (rows) w.r.t. x (cols).
    X0 : starting value, x0, of vector x
    OPT : optional options structure with the following fields,
        all of which are also optional (default values shown in
        parentheses)
        verbose (0) - controls level of progress output displayed
            0 = no progress output
            1 = some progress output
            2 = verbose progress output
        max_it (SP.default_max_it) - maximum number of iterations
        tol (1e-8) - tolerance on Inf-norm of f(x)

Outputs (all optional, except X):
    X : solution vector x
    F : final function value, f(x)
    EXITFLAG : exit flag
        1 = converged
        0 or negative values = solver specific failure codes
    OUTPUT : output struct with the following fields:
        alg - algorithm code of solver used (SP.alg)
        iterations - number of iterations performed
        hist - struct array with trajectories of the following:
                normf
                normdx
        message - exit message
    JAC : final Jacobian matrix, J

Calling syntax options:
    [x, f, exitflag, output, jac] = nleqs_core(sp, fcn, x0);
    [x, f, exitflag, output, jac] = nleqs_core(sp, fcn, x0, opt);
    x = nleqs_core(...);
    [x, f] = nleqs_core(...);
    [x, f, exitflag] = nleqs_core(...);
    [x, f, exitflag, output] = nleqs_core(...);
    [x, f, exitflag, output, jac] = nleqs_core(...);

Example: (problem from https://www.chilimath.com/lessons/advanced-algebra/systems-non-linear-equations/)
    function [f, J] = f1(x)
    f = [  x(1)   + x(2) - 1;
          -x(1)^2 + x(2) + 5    ];
    if nargout > 1
        J = [1 1; -2*x(1) 1];
    end

    fcn = @(x)f1(x);
    x0  = [0; 0];
    opt = struct('verbose', 2);
    sp = struct( ...
        'alg',              'NEWTON', ...
        'name',             'Newton''s', ...
        'default_max_it',   10, ...
        'need_jac',         1, ...
        'update_fcn',       @newton_update_fcn, ...
        )
    [x, f, exitflag, output, jac] = nleqs_core(sp, fcn, x0, opt);