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

nlps_master

PURPOSE ^

NLPS_MASTER Nonlinear programming (NLP) Solver wrapper function.

SYNOPSIS ^

function [x, f, eflag, output, lambda] = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt)

DESCRIPTION ^

NLPS_MASTER  Nonlinear programming (NLP) Solver wrapper function.
   [X, F, EXITFLAG, OUTPUT, LAMBDA] = ...
       NLPS_MASTER(F_FCN, X0, A, L, U, XMIN, XMAX, GH_FCN, HESS_FCN, OPT)
   [X, F, EXITFLAG, OUTPUT, LAMBDA] = NLPS_MASTER(PROBLEM)
   A common wrapper function for various NLP solvers.
   Solves the following NLP (nonlinear programming) problem:

   Minimize a function F(X) beginning from a starting point X0, subject to
   optional linear and nonlinear constraints and variable bounds.

       min F(X)
        X

   subject to

       G(X) = 0            (nonlinear equalities)
       H(X) <= 0           (nonlinear inequalities)
       L <= A*X <= U       (linear constraints)
       XMIN <= X <= XMAX   (variable bounds)

   Inputs (all optional except F_FCN and X0):
       F_FCN : handle to function that evaluates the objective function,
           its gradients and Hessian for a given value of X. If there
           are nonlinear constraints, the Hessian information is
           provided by the HESS_FCN function passed in the 9th argument
           and is not required here. Calling syntax for this function:
               [F, DF, D2F] = F_FCN(X)
       X0 : starting value of optimization vector X
       A, L, U : define the optional linear constraints. Default
           values for the elements of L and U are -Inf and Inf,
           respectively.
       XMIN, XMAX : optional lower and upper bounds on the
           X variables, defaults are -Inf and Inf, respectively.
       GH_FCN : handle to function that evaluates the optional
           nonlinear constraints and their gradients for a given
           value of X. Calling syntax for this function is:
               [H, G, DH, DG] = GH_FCN(X)
           where the columns of DH and DG are the gradients of the
           corresponding elements of H and G, i.e. DH and DG are
           transposes of the Jacobians of H and G, respectively.
       HESS_FCN : handle to function that computes the Hessian of the
           Lagrangian for given values of X, lambda and mu, where
           lambda and mu are the multipliers on the equality and
           inequality constraints, g and h, respectively. The calling
           syntax for this function is:
               LXX = HESS_FCN(X, LAM)
           where lambda = LAM.eqnonlin and mu = LAM.ineqnonlin.
       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 MIPS
               'MIPS'    : MIPS, MATPOWER Interior Point Solver
                        pure MATLAB implementation of a primal-dual
                        interior point method, if mips_opt.step_control = 1
                        it uses MIPS-sc, a step controlled variant of MIPS
               'FMINCON' : FMINCON, MATLAB Optimization Toolbox
               'IPOPT'   : IPOPT, requires MEX interface to IPOPT solver
                           https://github.com/coin-or/Ipopt
               'KNITRO'  : Artelys Knitro, requires Artelys Knitro solver
                           https://www.artelys.com/solvers/knitro/
           verbose (0) - controls level of progress output displayed
               0 = no progress output
               1 = some progress output
               2 = verbose progress output
           mips_opt    - options struct for MIPS
           fmincon_opt - options struct for FMINCON
           ipopt_opt   - options struct for IPOPT
           knitro_opt  - options struct for Artelys Knitro
       PROBLEM : The inputs can alternatively be supplied in a single
           PROBLEM struct with fields corresponding to the input arguments
           described above: f_fcn, x0, A, l, u, xmin, xmax,
                            gh_fcn, hess_fcn, opt

   Outputs:
       X : solution vector
       F : final objective function value
       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
       LAMBDA : struct containing the Langrange and Kuhn-Tucker
           multipliers on the constraints, with fields:
           eqnonlin - nonlinear equality constraints
           ineqnonlin - nonlinear inequality constraints
           mu_l - lower (left-hand) limit on linear constraints
           mu_u - upper (right-hand) limit on linear constraints
           lower - lower bound on optimization variables
           upper - upper bound on optimization variables

   Note the calling syntax is almost identical to that of FMINCON
   from MathWorks' Optimization Toolbox. The main difference is that
   the linear constraints are specified with A, L, U instead of
   A, B, Aeq, Beq. The functions for evaluating the objective
   function, constraints and Hessian are identical.

   Calling syntax options:
       [x, f, exitflag, output, lambda] = ...
           nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);

       x = nlps_master(f_fcn, x0);
       x = nlps_master(f_fcn, x0, A, l);
       x = nlps_master(f_fcn, x0, A, l, u);
       x = nlps_master(f_fcn, x0, A, l, u, xmin);
       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax);
       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn);
       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn);
       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
       x = nlps_master(problem);
               where problem is a struct with fields:
                   f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt
                   all fields except 'f_fcn' and 'x0' are optional
       x = nlps_master(...);
       [x, f] = nlps_master(...);
       [x, f, exitflag] = nlps_master(...);
       [x, f, exitflag, output] = nlps_master(...);
       [x, f, exitflag, output, lambda] = nlps_master(...);

   Example: (problem from https://en.wikipedia.org/wiki/Nonlinear_programming)
       function [f, df, d2f] = f2(x)
       f = -x(1)*x(2) - x(2)*x(3);
       if nargout > 1           %% gradient is required
           df = -[x(2); x(1)+x(3); x(2)];
           if nargout > 2       %% Hessian is required
               d2f = -[0 1 0; 1 0 1; 0 1 0];   %% actually not used since
           end                                 %% 'hess_fcn' is provided
       end
       
       function [h, g, dh, dg] = gh2(x)
       h = [ 1 -1 1; 1 1 1] * x.^2 + [-2; -10];
       dh = 2 * [x(1) x(1); -x(2) x(2); x(3) x(3)];
       g = []; dg = [];
       
       function Lxx = hess2(x, lam, cost_mult)
       if nargin < 3, cost_mult = 1; end
       mu = lam.ineqnonlin;
       Lxx = cost_mult * [0 -1 0; -1 0 -1; 0 -1 0] + ...
               [2*[1 1]*mu 0 0; 0 2*[-1 1]*mu 0; 0 0 2*[1 1]*mu];
       
       problem = struct( ...
           'f_fcn',    @(x)f2(x), ...
           'gh_fcn',   @(x)gh2(x), ...
           'hess_fcn', @(x, lam, cost_mult)hess2(x, lam, cost_mult), ...
           'x0',       [1; 1; 0], ...
           'opt',      struct('verbose', 2) ...
       );
       [x, f, exitflag, output, lambda] = nlps_master(problem);

   See also MIPS, NLPS_FMINCON, NLPS_IPOPT, NLPS_KNITRO.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function [x, f, eflag, output, lambda] = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt)
0002 %NLPS_MASTER  Nonlinear programming (NLP) Solver wrapper function.
0003 %   [X, F, EXITFLAG, OUTPUT, LAMBDA] = ...
0004 %       NLPS_MASTER(F_FCN, X0, A, L, U, XMIN, XMAX, GH_FCN, HESS_FCN, OPT)
0005 %   [X, F, EXITFLAG, OUTPUT, LAMBDA] = NLPS_MASTER(PROBLEM)
0006 %   A common wrapper function for various NLP solvers.
0007 %   Solves the following NLP (nonlinear programming) problem:
0008 %
0009 %   Minimize a function F(X) beginning from a starting point X0, subject to
0010 %   optional linear and nonlinear constraints and variable bounds.
0011 %
0012 %       min F(X)
0013 %        X
0014 %
0015 %   subject to
0016 %
0017 %       G(X) = 0            (nonlinear equalities)
0018 %       H(X) <= 0           (nonlinear inequalities)
0019 %       L <= A*X <= U       (linear constraints)
0020 %       XMIN <= X <= XMAX   (variable bounds)
0021 %
0022 %   Inputs (all optional except F_FCN and X0):
0023 %       F_FCN : handle to function that evaluates the objective function,
0024 %           its gradients and Hessian for a given value of X. If there
0025 %           are nonlinear constraints, the Hessian information is
0026 %           provided by the HESS_FCN function passed in the 9th argument
0027 %           and is not required here. Calling syntax for this function:
0028 %               [F, DF, D2F] = F_FCN(X)
0029 %       X0 : starting value of optimization vector X
0030 %       A, L, U : define the optional linear constraints. Default
0031 %           values for the elements of L and U are -Inf and Inf,
0032 %           respectively.
0033 %       XMIN, XMAX : optional lower and upper bounds on the
0034 %           X variables, defaults are -Inf and Inf, respectively.
0035 %       GH_FCN : handle to function that evaluates the optional
0036 %           nonlinear constraints and their gradients for a given
0037 %           value of X. Calling syntax for this function is:
0038 %               [H, G, DH, DG] = GH_FCN(X)
0039 %           where the columns of DH and DG are the gradients of the
0040 %           corresponding elements of H and G, i.e. DH and DG are
0041 %           transposes of the Jacobians of H and G, respectively.
0042 %       HESS_FCN : handle to function that computes the Hessian of the
0043 %           Lagrangian for given values of X, lambda and mu, where
0044 %           lambda and mu are the multipliers on the equality and
0045 %           inequality constraints, g and h, respectively. The calling
0046 %           syntax for this function is:
0047 %               LXX = HESS_FCN(X, LAM)
0048 %           where lambda = LAM.eqnonlin and mu = LAM.ineqnonlin.
0049 %       OPT : optional options structure with the following fields,
0050 %           all of which are also optional (default values shown in
0051 %           parentheses)
0052 %           alg ('DEFAULT') : determines which solver to use
0053 %               'DEFAULT' : automatic, current default is MIPS
0054 %               'MIPS'    : MIPS, MATPOWER Interior Point Solver
0055 %                        pure MATLAB implementation of a primal-dual
0056 %                        interior point method, if mips_opt.step_control = 1
0057 %                        it uses MIPS-sc, a step controlled variant of MIPS
0058 %               'FMINCON' : FMINCON, MATLAB Optimization Toolbox
0059 %               'IPOPT'   : IPOPT, requires MEX interface to IPOPT solver
0060 %                           https://github.com/coin-or/Ipopt
0061 %               'KNITRO'  : Artelys Knitro, requires Artelys Knitro solver
0062 %                           https://www.artelys.com/solvers/knitro/
0063 %           verbose (0) - controls level of progress output displayed
0064 %               0 = no progress output
0065 %               1 = some progress output
0066 %               2 = verbose progress output
0067 %           mips_opt    - options struct for MIPS
0068 %           fmincon_opt - options struct for FMINCON
0069 %           ipopt_opt   - options struct for IPOPT
0070 %           knitro_opt  - options struct for Artelys Knitro
0071 %       PROBLEM : The inputs can alternatively be supplied in a single
0072 %           PROBLEM struct with fields corresponding to the input arguments
0073 %           described above: f_fcn, x0, A, l, u, xmin, xmax,
0074 %                            gh_fcn, hess_fcn, opt
0075 %
0076 %   Outputs:
0077 %       X : solution vector
0078 %       F : final objective function value
0079 %       EXITFLAG : exit flag
0080 %           1 = converged
0081 %           0 or negative values = solver specific failure codes
0082 %       OUTPUT : output struct with the following fields:
0083 %           alg - algorithm code of solver used
0084 %           (others) - algorithm specific fields
0085 %       LAMBDA : struct containing the Langrange and Kuhn-Tucker
0086 %           multipliers on the constraints, with fields:
0087 %           eqnonlin - nonlinear equality constraints
0088 %           ineqnonlin - nonlinear inequality constraints
0089 %           mu_l - lower (left-hand) limit on linear constraints
0090 %           mu_u - upper (right-hand) limit on linear constraints
0091 %           lower - lower bound on optimization variables
0092 %           upper - upper bound on optimization variables
0093 %
0094 %   Note the calling syntax is almost identical to that of FMINCON
0095 %   from MathWorks' Optimization Toolbox. The main difference is that
0096 %   the linear constraints are specified with A, L, U instead of
0097 %   A, B, Aeq, Beq. The functions for evaluating the objective
0098 %   function, constraints and Hessian are identical.
0099 %
0100 %   Calling syntax options:
0101 %       [x, f, exitflag, output, lambda] = ...
0102 %           nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
0103 %
0104 %       x = nlps_master(f_fcn, x0);
0105 %       x = nlps_master(f_fcn, x0, A, l);
0106 %       x = nlps_master(f_fcn, x0, A, l, u);
0107 %       x = nlps_master(f_fcn, x0, A, l, u, xmin);
0108 %       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax);
0109 %       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn);
0110 %       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn);
0111 %       x = nlps_master(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
0112 %       x = nlps_master(problem);
0113 %               where problem is a struct with fields:
0114 %                   f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt
0115 %                   all fields except 'f_fcn' and 'x0' are optional
0116 %       x = nlps_master(...);
0117 %       [x, f] = nlps_master(...);
0118 %       [x, f, exitflag] = nlps_master(...);
0119 %       [x, f, exitflag, output] = nlps_master(...);
0120 %       [x, f, exitflag, output, lambda] = nlps_master(...);
0121 %
0122 %   Example: (problem from https://en.wikipedia.org/wiki/Nonlinear_programming)
0123 %       function [f, df, d2f] = f2(x)
0124 %       f = -x(1)*x(2) - x(2)*x(3);
0125 %       if nargout > 1           %% gradient is required
0126 %           df = -[x(2); x(1)+x(3); x(2)];
0127 %           if nargout > 2       %% Hessian is required
0128 %               d2f = -[0 1 0; 1 0 1; 0 1 0];   %% actually not used since
0129 %           end                                 %% 'hess_fcn' is provided
0130 %       end
0131 %
0132 %       function [h, g, dh, dg] = gh2(x)
0133 %       h = [ 1 -1 1; 1 1 1] * x.^2 + [-2; -10];
0134 %       dh = 2 * [x(1) x(1); -x(2) x(2); x(3) x(3)];
0135 %       g = []; dg = [];
0136 %
0137 %       function Lxx = hess2(x, lam, cost_mult)
0138 %       if nargin < 3, cost_mult = 1; end
0139 %       mu = lam.ineqnonlin;
0140 %       Lxx = cost_mult * [0 -1 0; -1 0 -1; 0 -1 0] + ...
0141 %               [2*[1 1]*mu 0 0; 0 2*[-1 1]*mu 0; 0 0 2*[1 1]*mu];
0142 %
0143 %       problem = struct( ...
0144 %           'f_fcn',    @(x)f2(x), ...
0145 %           'gh_fcn',   @(x)gh2(x), ...
0146 %           'hess_fcn', @(x, lam, cost_mult)hess2(x, lam, cost_mult), ...
0147 %           'x0',       [1; 1; 0], ...
0148 %           'opt',      struct('verbose', 2) ...
0149 %       );
0150 %       [x, f, exitflag, output, lambda] = nlps_master(problem);
0151 %
0152 %   See also MIPS, NLPS_FMINCON, NLPS_IPOPT, NLPS_KNITRO.
0153 
0154 %   MP-Opt-Model
0155 %   Copyright (c) 2010-2020, Power Systems Engineering Research Center (PSERC)
0156 %   by Ray Zimmerman, PSERC Cornell
0157 %
0158 %   This file is part of MP-Opt-Model.
0159 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0160 %   See https://github.com/MATPOWER/mp-opt-model for more info.
0161 
0162 %%----- input argument handling  -----
0163 %% gather inputs
0164 if nargin == 1 && isstruct(f_fcn)       %% problem struct
0165     p = f_fcn;
0166     f_fcn = p.f_fcn;
0167     x0 = p.x0;
0168     nx = size(x0, 1);       %% number of optimization variables
0169     if isfield(p, 'opt'),       opt = p.opt;            else,   opt = [];       end
0170     if isfield(p, 'hess_fcn'),  hess_fcn = p.hess_fcn;  else,   hess_fcn = '';  end
0171     if isfield(p, 'gh_fcn'),    gh_fcn = p.gh_fcn;      else,   gh_fcn = '';    end
0172     if isfield(p, 'xmax'),      xmax = p.xmax;          else,   xmax = [];      end
0173     if isfield(p, 'xmin'),      xmin = p.xmin;          else,   xmin = [];      end
0174     if isfield(p, 'u'),         u = p.u;                else,   u = [];         end
0175     if isfield(p, 'l'),         l = p.l;                else,   l = [];         end
0176     if isfield(p, 'A'),         A = p.A;                else,   A=sparse(0,nx); end
0177 else                                    %% individual args
0178     nx = size(x0, 1);       %% number of optimization variables
0179     if nargin < 10
0180         opt = [];
0181         if nargin < 9
0182             hess_fcn = '';
0183             if nargin < 8
0184                 gh_fcn = '';
0185                 if nargin < 7
0186                     xmax = [];
0187                     if nargin < 6
0188                         xmin = [];
0189                         if nargin < 5
0190                             u = [];
0191                             if nargin < 4
0192                                 l = [];
0193                                 A = sparse(0,nx);
0194                             end
0195                         end
0196                     end
0197                 end
0198             end
0199         end
0200     end
0201 end
0202 
0203 %% default options
0204 if ~isempty(opt) && isfield(opt, 'alg') && ~isempty(opt.alg)
0205     alg = opt.alg;
0206 else
0207     alg = 'DEFAULT';
0208 end
0209 if ~isempty(opt) && isfield(opt, 'verbose') && ~isempty(opt.verbose)
0210     verbose = opt.verbose;
0211 else
0212     verbose = 0;
0213 end
0214 if strcmp(alg, 'DEFAULT')
0215     alg = 'MIPS';
0216 end
0217 
0218 %%----- call the appropriate solver  -----
0219 switch alg
0220     case 'MIPS'                 %% use MIPS
0221         %% set up options
0222         if ~isempty(opt) && isfield(opt, 'mips_opt') && ~isempty(opt.mips_opt)
0223             mips_opt = opt.mips_opt;
0224         else
0225             mips_opt = [];
0226         end
0227         mips_opt.verbose = verbose;
0228         
0229         %% call solver
0230         [x, f, eflag, output, lambda] = ...
0231             mips(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, mips_opt);
0232     case 'FMINCON'              %% use fmincon
0233         [x, f, eflag, output, lambda] = ...
0234             nlps_fmincon(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
0235     case 'IPOPT'                %% use IPOPT
0236         [x, f, eflag, output, lambda] = ...
0237             nlps_ipopt(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
0238     case 'KNITRO'               %% use Artelys Knitro
0239         [x, f, eflag, output, lambda] = ...
0240             nlps_knitro(f_fcn, x0, A, l, u, xmin, xmax, gh_fcn, hess_fcn, opt);
0241     otherwise
0242         error('nlps_master: ''%s'' is not a valid algorithm code', alg);
0243 end
0244 if ~isfield(output, 'alg') || isempty(output.alg)
0245     output.alg = alg;
0246 end

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