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

nleqs_master

PURPOSE ^

NLEQS_MASTER Nonlinear Equation Solver wrapper function.

SYNOPSIS ^

function varargout = nleqs_master(fcn, x0, opt)

DESCRIPTION ^

NLEQS_MASTER  Nonlinear Equation Solver wrapper function.
   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_MASTER(FCN, X0, OPT)
   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_MASTER(PROBLEM)
   A common wrapper function for various nonlinear equation solvers.
   Solves 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 its (optionally, depending on the selected
           solver) 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)
           alg ('DEFAULT') : determines which solver to use
               'DEFAULT' : automatic, current default is NEWTON
               'NEWTON'  : standard, full-Jacobian Newton's method
               'CORE'    : core algorithm, with arbitrary update function
               'FD'      : fast-decoupled Newton's method
               'FSOLVE'  : FSOLVE, MATLAB Optimization Toolbox
               'GS'      : Gauss-Seidel method
           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) - termination tolerance on f(x)
                       (0 means use solver's own default)
           core_sp - solver parameters struct for NLEQS_CORE, required
               when alg = 'CORE' (see NLEQS_CORE for details)
           fd_opt - options struct for fast-decoupled Newton, NLEQS_FD_NEWTON
           fsolve_opt - options struct for FSOLVE
           gs_opt - options struct for Gauss-Seidel method, NLEQS_GAUSS_SEIDEL
           newton_opt - options struct for Newton's method, NLEQS_NEWTON
       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
           (others) - algorithm specific fields
       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_master(fcn, x0);
       [x, f, exitflag, output, jac] = nleqs_master(fcn, x0, opt);
       x = nleqs_master(problem);
               where problem is a struct with fields: fcn, x0, opt
               and all fields except 'fcn' and 'x0' are optional
       x = nleqs_master(...);
       [x, f] = nleqs_master(...);
       [x, f, exitflag] = nleqs_master(...);
       [x, f, exitflag, output] = nleqs_master(...);
       [x, f, exitflag, output, jac] = nleqs_master(...);

   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_master(problem);

   See also NLEQS_NEWTON, NLEQS_CORE, NLEQS_FD_NEWTON, NLEQS_FSOLVE,
   NLEQS_GAUSS_SEIDEL, FSOLVE.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function varargout = nleqs_master(fcn, x0, opt)
0002 %NLEQS_MASTER  Nonlinear Equation Solver wrapper function.
0003 %   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_MASTER(FCN, X0, OPT)
0004 %   [X, F, EXITFLAG, OUTPUT, JAC] = NLEQS_MASTER(PROBLEM)
0005 %   A common wrapper function for various nonlinear equation solvers.
0006 %   Solves the nonlinear equation f(x) = 0, beginning from a starting
0007 %   point x0.
0008 %
0009 %   Inputs:
0010 %       FCN : handle to function that evaluates the function f(x) to
0011 %           be solved and its (optionally, depending on the selected
0012 %           solver) Jacobian, J(x). Calling syntax 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 %           alg ('DEFAULT') : determines which solver to use
0022 %               'DEFAULT' : automatic, current default is NEWTON
0023 %               'NEWTON'  : standard, full-Jacobian Newton's method
0024 %               'CORE'    : core algorithm, with arbitrary update function
0025 %               'FD'      : fast-decoupled Newton's method
0026 %               'FSOLVE'  : FSOLVE, MATLAB Optimization Toolbox
0027 %               'GS'      : Gauss-Seidel method
0028 %           verbose (0) - controls level of progress output displayed
0029 %               0 = no progress output
0030 %               1 = some progress output
0031 %               2 = verbose progress output
0032 %           max_it (0) - maximum number of iterations
0033 %                       (0 means use solver's own default)
0034 %           tol (0) - termination tolerance on f(x)
0035 %                       (0 means use solver's own default)
0036 %           core_sp - solver parameters struct for NLEQS_CORE, required
0037 %               when alg = 'CORE' (see NLEQS_CORE for details)
0038 %           fd_opt - options struct for fast-decoupled Newton, NLEQS_FD_NEWTON
0039 %           fsolve_opt - options struct for FSOLVE
0040 %           gs_opt - options struct for Gauss-Seidel method, NLEQS_GAUSS_SEIDEL
0041 %           newton_opt - options struct for Newton's method, NLEQS_NEWTON
0042 %       PROBLEM : The inputs can alternatively be supplied in a single
0043 %           PROBLEM struct with fields corresponding to the input arguments
0044 %           described above: fcn, x0, opt
0045 %
0046 %   Outputs (all optional, except X):
0047 %       X : solution vector x
0048 %       F : final function value, f(x)
0049 %       EXITFLAG : exit flag
0050 %           1 = converged
0051 %           0 or negative values = solver specific failure codes
0052 %       OUTPUT : output struct with the following fields:
0053 %           alg - algorithm code of solver used
0054 %           (others) - algorithm specific fields
0055 %       JAC : final Jacobian matrix, J(x)
0056 %
0057 %   Note the calling syntax is almost identical to that of FSOLVE from
0058 %   MathWorks' Optimization Toolbox. The function for evaluating the
0059 %   nonlinear function and Jacobian is identical.
0060 %
0061 %   Calling syntax options:
0062 %       [x, f, exitflag, output, jac] = nleqs_master(fcn, x0);
0063 %       [x, f, exitflag, output, jac] = nleqs_master(fcn, x0, opt);
0064 %       x = nleqs_master(problem);
0065 %               where problem is a struct with fields: fcn, x0, opt
0066 %               and all fields except 'fcn' and 'x0' are optional
0067 %       x = nleqs_master(...);
0068 %       [x, f] = nleqs_master(...);
0069 %       [x, f, exitflag] = nleqs_master(...);
0070 %       [x, f, exitflag, output] = nleqs_master(...);
0071 %       [x, f, exitflag, output, jac] = nleqs_master(...);
0072 %
0073 %   Example: (problem from https://www.chilimath.com/lessons/advanced-algebra/systems-non-linear-equations/)
0074 %       function [f, J] = f1(x)
0075 %       f = [  x(1)   + x(2) - 1;
0076 %             -x(1)^2 + x(2) + 5    ];
0077 %       if nargout > 1
0078 %           J = [1 1; -2*x(1) 1];
0079 %       end
0080 %
0081 %       problem = struct( ...
0082 %           'fcn',    @(x)f1(x), ...
0083 %           'x0',       [0; 0], ...
0084 %           'opt',      struct('verbose', 2) ...
0085 %       );
0086 %       [x, f, exitflag, output, jac] = nleqs_master(problem);
0087 %
0088 %   See also NLEQS_NEWTON, NLEQS_CORE, NLEQS_FD_NEWTON, NLEQS_FSOLVE,
0089 %   NLEQS_GAUSS_SEIDEL, FSOLVE.
0090 
0091 %   MP-Opt-Model
0092 %   Copyright (c) 2010-2020, Power Systems Engineering Research Center (PSERC)
0093 %   by Ray Zimmerman, PSERC Cornell
0094 %
0095 %   This file is part of MP-Opt-Model.
0096 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0097 %   See https://github.com/MATPOWER/mp-opt-model for more info.
0098 
0099 %%----- input argument handling  -----
0100 %% gather inputs
0101 if nargin == 1 && isstruct(fcn) %% problem struct
0102     p = fcn;
0103     fcn = p.fcn;
0104     x0 = p.x0;
0105     if isfield(p, 'opt'),   opt = p.opt;    else,   opt = [];   end
0106 else                            %% individual args
0107     if nargin < 3
0108         opt = [];
0109     end
0110 end
0111 
0112 %% default options
0113 if ~isempty(opt) && isfield(opt, 'alg') && ~isempty(opt.alg)
0114     alg = opt.alg;
0115 else
0116     alg = 'DEFAULT';
0117 end
0118 if strcmp(alg, 'DEFAULT')
0119     alg = 'NEWTON';
0120 end
0121 
0122 %%----- call the appropriate solver  -----
0123 switch alg
0124     case 'NEWTON'               %% use Newton's method solver
0125         nleqs_fcn = @nleqs_newton;
0126     case 'FD'                   %% use fast-decoupled Newton's method solver
0127         nleqs_fcn = @nleqs_fd_newton;
0128     case 'FSOLVE'               %% use fsolve
0129         nleqs_fcn = @nleqs_fsolve;
0130     case 'GS'                   %% use Gauss-Seidel solver
0131         nleqs_fcn = @nleqs_gauss_seidel;
0132     case 'CORE'                 %% use core solver
0133         nleqs_fcn = @(f, x, o)nleqs_core(opt.core_sp, f, x, o);
0134     otherwise
0135         error('nleqs_master: ''%s'' is not a valid algorithm code', alg);
0136 end
0137 [varargout{1:nargout}] = nleqs_fcn(fcn, x0, opt);

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