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.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);