nleqs_fd_newton

nleqs_fd_newton(fcn, x0, opt)
nleqs_fd_newton() - Nonlinear Equation Solver based on Newton’s method.
[X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FD_NEWTON(FCN, X0, OPT)
[X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FD_NEWTON(PROBLEM)
A function providing a standardized interface for using Newton's
method to solve the nonlinear equation f(x) = 0, beginning from a
starting point x0.

Inputs:
    FCN : handle to function that evaluates the function f(x) to
        be solved. Calling syntax for this function is:
            f = FCN(x)
    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 (30) - maximum number of iterations for fast-decoupled
            Newton's method
        tol (1e-8) - tolerance on Inf-norm of f(x)
        fd_opt - options struct for Newton's method, with field:
            jac_approx_fcn (required) - handle to function with the
                following calling syntax:
                    JJ = jac_approx_fcn();
                where JJ is a cell array of matrices whose number of
                rows sum to the dimension of f and number of columns
                sum to the dimension of x. JJ{k} is a matrix
                approximating the Jacobian of block k of f and x.
            labels (optional) - cell array of same length as JJ returned
                by jac_approx_fcn(), with short string labels for
                the decoupled blocks
    PROBLEM : The inputs can alternatively be supplied in a single
        PROBLEM struct with fields corresponding to the input arguments
        described above: fcn, x0, opt

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 ('FD')
        iterations - number of iterations performed
        hist - struct array with trajectories of the following:
                normf
        message - exit message
    JAC : approximate Jacobian matrix

Note the calling syntax is almost identical to that of FSOLVE from
MathWorks' Optimization Toolbox. The function for evaluating the
nonlinear function is identical.

Calling syntax options:
    [x, f, exitflag, output, jac] = nleqs_fd_newton(fcn, x0);
    [x, f, exitflag, output, jac] = nleqs_fd_newton(fcn, x0, opt);
    x = nleqs_fd_newton(problem);
            where problem is a struct with fields: fcn, x0, opt
            and all fields except 'fcn' and 'x0' are optional
    x = nleqs_fd_newton(...);
    [x, f] = nleqs_fd_newton(...);
    [x, f, exitflag] = nleqs_fd_newton(...);
    [x, f, exitflag, output] = nleqs_fd_newton(...);
    [x, f, exitflag, output, jac] = nleqs_fd_newton(...);

Example: (problem from Christi Patton Luks, https://www.youtube.com/watch?v=pJG4yhtgerg)
    function f = f2(x)
    f = [  x(1)^2 +   x(1)*x(2)   - 10;
           x(2)   + 3*x(1)*x(2)^2 - 57  ];

    function JJ = jac_approx_fcn2()
    J = [7 2; 27 37];
    JJ = {J(1,1), J(2,2)};

    problem = struct( ...
        'fcn', @(x)f2(x), ...
        'x0',  [0; 0], ...
        'opt', struct( ...
            'verbose', 2, ...
            'fd_opt', struct( ...
                'jac_approx_fcn', @jac_approx_fcn2 )));
    [x, f, exitflag, output, jac] = nleqs_fd_newton(problem);