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