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

nleqs_gauss_seidel

PURPOSE ^

NLEQS_GAUSS_SEIDEL Nonlinear Equation Solver based on Gauss-Seidel method.

SYNOPSIS ^

function varargout = nleqs_gauss_seidel(varargin)

DESCRIPTION ^

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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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

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