NLEQS_GAUSS_SEIDEL Nonlinear Equation Solver based on Gauss-Seidel method.
[X, F, EXITFLAG, OUTPUT] = NLEQS_GAUSS_SEIDEL(FCN, X0, OPT)
[X, F, EXITFLAG, OUTPUT] = NLEQS_GAUSS_SEIDEL(PROBLEM)
A function providing a standardized interface for using Gauss-Seidel
method to solve the nonlinear equation f(x) = 0, beginning from a
starting point x0.
Calls NLEQS_CORE with a user-provided update function implementing
the Gauss-Seidel update.
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 (1000) - maximum number of iterations for Gauss-Seidel method
tol (1e-8) - tolerance on Inf-norm of f(x)
gs_opt - options struct for Gauss-Seidel method, with field:
x_update_fcn (required) - handle to function that performs
the Gauss-Seidel update step, with the following calling
syntax: x = x_update_fcn(x, f);
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 ('GS')
iterations - number of iterations performed
hist - struct array with trajectories of the following:
normf
message - exit message
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] = nleqs_gauss_seidel(fcn, x0);
[x, f, exitflag, output] = nleqs_gauss_seidel(fcn, x0, opt);
x = nleqs_gauss_seidel(problem);
where problem is a struct with fields: fcn, x0, opt
and all fields except 'fcn' and 'x0' are optional
x = nleqs_gauss_seidel(...);
[x, f] = nleqs_gauss_seidel(...);
[x, f, exitflag] = nleqs_gauss_seidel(...);
[x, f, exitflag, output] = nleqs_gauss_seidel(...);
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 x = x_update_fcn2(x, f)
x(1) = sqrt(10 - x(1)*x(2));
x(2) = sqrt((57-x(2))/3/x(1));
problem = struct( ...
'fcn', @(x)f2(x), ...
'x0', [0; 0], ...
'opt', struct( ...
'verbose', 2, ...
'gs_opt', struct( ...
'x_update_fcn', @x_update_fcn2 )));
[x, f, exitflag, output] = nleqs_gauss_seidel(problem);
See also NLEQS_MASTER, NLEQS_CORE.0001 function varargout = nleqs_gauss_seidel(varargin) 0002 %NLEQS_GAUSS_SEIDEL Nonlinear Equation Solver based on Gauss-Seidel method. 0003 % [X, F, EXITFLAG, OUTPUT] = NLEQS_GAUSS_SEIDEL(FCN, X0, OPT) 0004 % [X, F, EXITFLAG, OUTPUT] = NLEQS_GAUSS_SEIDEL(PROBLEM) 0005 % A function providing a standardized interface for using Gauss-Seidel 0006 % method to solve the nonlinear equation f(x) = 0, beginning from a 0007 % starting point x0. 0008 % 0009 % Calls NLEQS_CORE with a user-provided update function implementing 0010 % the Gauss-Seidel update. 0011 % 0012 % Inputs: 0013 % FCN : handle to function that evaluates the function f(x) to 0014 % be solved. Calling syntax for this function is: 0015 % f = FCN(x) 0016 % X0 : starting value, x0, of vector x 0017 % OPT : optional options structure with the following fields, 0018 % all of which are also optional (default values shown in 0019 % parentheses) 0020 % verbose (0) - controls level of progress output displayed 0021 % 0 = no progress output 0022 % 1 = some progress output 0023 % 2 = verbose progress output 0024 % max_it (1000) - maximum number of iterations for Gauss-Seidel method 0025 % tol (1e-8) - tolerance on Inf-norm of f(x) 0026 % gs_opt - options struct for Gauss-Seidel method, with field: 0027 % x_update_fcn (required) - handle to function that performs 0028 % the Gauss-Seidel update step, with the following calling 0029 % syntax: x = x_update_fcn(x, f); 0030 % PROBLEM : The inputs can alternatively be supplied in a single 0031 % PROBLEM struct with fields corresponding to the input arguments 0032 % described above: fcn, x0, opt 0033 % 0034 % Outputs (all optional, except X): 0035 % X : solution vector x 0036 % F : final function value, f(x) 0037 % EXITFLAG : exit flag 0038 % 1 = converged 0039 % 0 or negative values = solver specific failure codes 0040 % OUTPUT : output struct with the following fields: 0041 % alg - algorithm code of solver used ('GS') 0042 % iterations - number of iterations performed 0043 % hist - struct array with trajectories of the following: 0044 % normf 0045 % message - exit message 0046 % 0047 % Note the calling syntax is almost identical to that of FSOLVE from 0048 % MathWorks' Optimization Toolbox. The function for evaluating the 0049 % nonlinear function is identical. 0050 % 0051 % Calling syntax options: 0052 % [x, f, exitflag, output] = nleqs_gauss_seidel(fcn, x0); 0053 % [x, f, exitflag, output] = nleqs_gauss_seidel(fcn, x0, opt); 0054 % x = nleqs_gauss_seidel(problem); 0055 % where problem is a struct with fields: fcn, x0, opt 0056 % and all fields except 'fcn' and 'x0' are optional 0057 % x = nleqs_gauss_seidel(...); 0058 % [x, f] = nleqs_gauss_seidel(...); 0059 % [x, f, exitflag] = nleqs_gauss_seidel(...); 0060 % [x, f, exitflag, output] = nleqs_gauss_seidel(...); 0061 % 0062 % Example: (problem from Christi Patton Luks, https://www.youtube.com/watch?v=pJG4yhtgerg) 0063 % function f = f2(x) 0064 % f = [ x(1)^2 + x(1)*x(2) - 10; 0065 % x(2) + 3*x(1)*x(2)^2 - 57 ]; 0066 % 0067 % function x = x_update_fcn2(x, f) 0068 % x(1) = sqrt(10 - x(1)*x(2)); 0069 % x(2) = sqrt((57-x(2))/3/x(1)); 0070 % 0071 % problem = struct( ... 0072 % 'fcn', @(x)f2(x), ... 0073 % 'x0', [0; 0], ... 0074 % 'opt', struct( ... 0075 % 'verbose', 2, ... 0076 % 'gs_opt', struct( ... 0077 % 'x_update_fcn', @x_update_fcn2 ))); 0078 % [x, f, exitflag, output] = nleqs_gauss_seidel(problem); 0079 % 0080 % See also NLEQS_MASTER, NLEQS_CORE. 0081 0082 % MP-Opt-Model 0083 % Copyright (c) 1996-2020, Power Systems Engineering Research Center (PSERC) 0084 % by Ray Zimmerman, PSERC Cornell 0085 % 0086 % This file is part of MP-Opt-Model. 0087 % Covered by the 3-clause BSD License (see LICENSE file for details). 0088 % See https://github.com/MATPOWER/mp-opt-model for more info. 0089 0090 %%----- input argument handling ----- 0091 %% gather inputs 0092 if nargin == 1 && isstruct(varargin{1}) %% problem struct 0093 p = varargin{1}; 0094 fcn = p.fcn; 0095 x0 = p.x0; 0096 if isfield(p, 'opt'), opt = p.opt; else, opt = []; end 0097 else %% individual args 0098 fcn = varargin{1}; 0099 x0 = varargin{2}; 0100 if nargin < 3 0101 opt = []; 0102 else 0103 opt = varargin{3}; 0104 end 0105 end 0106 0107 %% set default options 0108 if isempty(opt) 0109 opt = struct(); 0110 end 0111 if ~isfield(opt, 'gs_opt') || ~isfield(opt.gs_opt, 'x_update_fcn') 0112 error('nleqs_gauss_seidel: required ''gs_opt.x_update_fcn'' option missing'); 0113 end 0114 0115 sp = struct( ... 0116 'alg', 'GS', ... 0117 'name', 'Gauss-Seidel', ... 0118 'default_max_it', 1000, ... 0119 'need_jac', 0, ... 0120 'update_fcn', opt.gs_opt.x_update_fcn ); 0121 0122 [varargout{1:nargout}] = nleqs_core(sp, fcn, x0, opt); 0123 % opt.alg = 'CORE'; 0124 % opt.core_sp = sp; 0125 % [varargout{1:nargout}] = nleqs_master(fcn, x0, opt);