Home > matpower7.1 > mp-opt-model > lib > nleqs_fsolve.m

nleqs_fsolve

PURPOSE ^

NLEQS_FSOLVE Nonlinear Equation Solver based on Newton's method.

SYNOPSIS ^

function [x, f, eflag, varargout] = nleqs_fsolve(fcn, x0, opt)

DESCRIPTION ^

NLEQS_FSOLVE  Nonlinear Equation Solver based on Newton's method.
   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FSOLVE(FCN, X0, OPT)
   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FSOLVE(PROBLEM)
   A wrapper function providing a standardized interface for using
   FSOLVE 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 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 (0) - maximum number of iterations
                       (0 means use solver's own default)
           tol (0) - tolerance on f(x)
                       (0 means use solver's own default)
           fsolve_opt - options struct for FSOLVE, values to be passed
                   directly to OPTIMSET or OPTIMOPTIONS, values in verbose
                   max_it, tol override these options
       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 ('FSOLVE')
           iterations - number of iterations performed
           message - exit message
       JAC : final Jacobian matrix, J(x)

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

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

   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

       problem = struct( ...
           'fcn',    @(x)f1(x), ...
           'x0',       [0; 0], ...
           'opt',      struct('verbose', 2) ...
       );
       [x, f, exitflag, output, jac] = nleqs_fsolve(problem);

   See also NLEQS_MASTER, FSOLVE.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function [x, f, eflag, varargout] = nleqs_fsolve(fcn, x0, opt)
0002 %NLEQS_FSOLVE  Nonlinear Equation Solver based on Newton's method.
0003 %   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FSOLVE(FCN, X0, OPT)
0004 %   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_FSOLVE(PROBLEM)
0005 %   A wrapper function providing a standardized interface for using
0006 %   FSOLVE to solve the nonlinear equation f(x) = 0, beginning from a
0007 %   starting point x0.
0008 %
0009 %   Inputs:
0010 %       FCN : handle to function that evaluates the function f(x) to
0011 %           be solved and (optionally) its Jacobian, J(x). Calling syntax
0012 %           for this function is:
0013 %               f = FCN(x)
0014 %               [f, J] = FCN(x)
0015 %           If f and x are n x 1, then J is the n x n matrix of partial
0016 %           derivatives of f (rows) w.r.t. x (cols).
0017 %       X0 : starting value, x0, of vector x
0018 %       OPT : optional options structure with the following fields,
0019 %           all of which are also optional (default values shown in
0020 %           parentheses)
0021 %           verbose (0) - controls level of progress output displayed
0022 %               0 = no progress output
0023 %               1 = some progress output
0024 %               2 = verbose progress output
0025 %           max_it (0) - maximum number of iterations
0026 %                       (0 means use solver's own default)
0027 %           tol (0) - tolerance on f(x)
0028 %                       (0 means use solver's own default)
0029 %           fsolve_opt - options struct for FSOLVE, values to be passed
0030 %                   directly to OPTIMSET or OPTIMOPTIONS, values in verbose
0031 %                   max_it, tol override these options
0032 %       PROBLEM : The inputs can alternatively be supplied in a single
0033 %           PROBLEM struct with fields corresponding to the input arguments
0034 %           described above: fcn, x0, opt
0035 %
0036 %   Outputs (all optional, except X):
0037 %       X : solution vector x
0038 %       F : final function value, f(x)
0039 %       EXITFLAG : exit flag
0040 %           1 = converged
0041 %           0 or negative values = solver specific failure codes
0042 %       OUTPUT : output struct with the following fields:
0043 %           alg - algorithm code of solver used ('FSOLVE')
0044 %           iterations - number of iterations performed
0045 %           message - exit message
0046 %       JAC : final Jacobian matrix, J(x)
0047 %
0048 %   Note the calling syntax is almost identical to that of FSOLVE from
0049 %   MathWorks' Optimization Toolbox. The function for evaluating the
0050 %   nonlinear function and Jacobian is identical.
0051 %
0052 %   Calling syntax options:
0053 %       [x, f, exitflag, output, jac] = nleqs_fsolve(fcn, x0);
0054 %       [x, f, exitflag, output, jac] = nleqs_fsolve(fcn, x0, opt);
0055 %       x = nleqs_fsolve(problem);
0056 %               where problem is a struct with fields: fcn, x0, opt
0057 %               and all fields except 'fcn' and 'x0' are optional
0058 %       x = nleqs_fsolve(...);
0059 %       [x, f] = nleqs_fsolve(...);
0060 %       [x, f, exitflag] = nleqs_fsolve(...);
0061 %       [x, f, exitflag, output] = nleqs_fsolve(...);
0062 %       [x, f, exitflag, output, jac] = nleqs_fsolve(...);
0063 %
0064 %   Example: (problem from https://www.chilimath.com/lessons/advanced-algebra/systems-non-linear-equations/)
0065 %       function [f, J] = f1(x)
0066 %       f = [  x(1)   + x(2) - 1;
0067 %             -x(1)^2 + x(2) + 5    ];
0068 %       if nargout > 1
0069 %           J = [1 1; -2*x(1) 1];
0070 %       end
0071 %
0072 %       problem = struct( ...
0073 %           'fcn',    @(x)f1(x), ...
0074 %           'x0',       [0; 0], ...
0075 %           'opt',      struct('verbose', 2) ...
0076 %       );
0077 %       [x, f, exitflag, output, jac] = nleqs_fsolve(problem);
0078 %
0079 %   See also NLEQS_MASTER, FSOLVE.
0080 
0081 %   MP-Opt-Model
0082 %   Copyright (c) 2020, Power Systems Engineering Research Center (PSERC)
0083 %   by Ray Zimmerman, PSERC Cornell
0084 %
0085 %   This file is part of MP-Opt-Model.
0086 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0087 %   See https://github.com/MATPOWER/mp-opt-model for more info.
0088 
0089 %%----- input argument handling  -----
0090 %% gather inputs
0091 if nargin == 1 && isstruct(fcn) %% problem struct
0092     p = fcn;
0093     fcn = p.fcn;
0094     x0 = p.x0;
0095     if isfield(p, 'opt'),   opt = p.opt;    else,   opt = [];   end
0096 else                            %% individual args
0097     if nargin < 3
0098         opt = struct();
0099     end
0100 end
0101 
0102 %% set default options
0103 if isfield(opt, 'verbose') && ~isempty(opt.verbose)
0104     verbose = opt.verbose;
0105 else
0106     verbose = 0;
0107 end
0108 if isfield(opt, 'fsolve_opt')
0109     fsolve_opt = opt.fsolve_opt;
0110 else
0111     fsolve_opt = struct();
0112 end
0113 if verbose > 1
0114     fsolve_opt.Display = 'iter';
0115 elseif verbose > 0
0116     fsolve_opt.Display = 'final';
0117 else
0118     fsolve_opt.Display = 'off';
0119 end
0120 if isfield(opt, 'max_it') && opt.max_it     %% not empty or zero
0121     fsolve_opt.MaxIter = opt.max_it;
0122 end
0123 if isfield(opt, 'tol') && opt.tol           %% not empty or zero
0124     fsolve_opt.TolFun = opt.tol;
0125 end
0126 fsolve_opt.Jacobian = 'on';
0127 fsolve_opt.JacobMult = [];
0128 
0129 %% call the solver
0130 [x, f, eflag, varargout{1:nargout-3}] = fsolve(fcn, x0, fsolve_opt);
0131 
0132 if nargout > 3
0133     varargout{1}.alg = 'FSOLVE';
0134     varargout{1}.exitflag = eflag;
0135 end
0136 if eflag > 0
0137     eflag = 1;
0138 end

Generated on Fri 09-Oct-2020 11:21:31 by m2html © 2005