0001 classdef opt_model < mp_idx_manager 0002 %OPT_MODEL Constructor for optimization model class. 0003 % OM = OPT_MODEL 0004 % OM = OPT_MODEL(S) 0005 % 0006 % This class implements the optimization model object used to encapsulate 0007 % a given optimization problem formulation. It allows for access to 0008 % optimization variables, constraints and costs in named blocks, keeping 0009 % track of the ordering and indexing of the blocks as variables, 0010 % constraints and costs are added to the problem. 0011 % 0012 % Below are the list of available methods for use with the Opt Model class. 0013 % Please see the help on each individual method for more details: 0014 % 0015 % Modify the OPF formulation by adding named blocks of costs, constraints 0016 % or variables: 0017 % add_quad_cost 0018 % add_nln_cost 0019 % add_lin_constraint 0020 % add_nln_constraint 0021 % add_var 0022 % init_indexed_name 0023 % 0024 % Return the number of linear constraints, nonlinear constraints or 0025 % variables, optionally for a single named block: 0026 % getN 0027 % 0028 % Return the intial values, bounds and type for optimization variables: 0029 % params_var 0030 % 0031 % Build and return full set of linear constraints: 0032 % params_lin_constraint 0033 % 0034 % Return index structure for variables, linear and nonlinear constraints 0035 % and costs: 0036 % get_idx 0037 % 0038 % Build and return cost parameters and evaluate user-defined costs: 0039 % params_nln_cost 0040 % params_quad_cost 0041 % eval_nln_cost 0042 % eval_quad_cost 0043 % 0044 % Retreive user data in the model object: 0045 % get_userdata 0046 % 0047 % Display the object (called automatically when you omit the semicolon 0048 % at the command-line): 0049 % display 0050 % 0051 % Return the value of an individual field: 0052 % get 0053 % 0054 % Indentify variable, constraint or cost row indices: 0055 % describe_idx 0056 % 0057 % Make a shallow copy of the object: 0058 % copy 0059 % 0060 % The following is the structure of the data in the Opt-Model object. 0061 % Each field of .idx or .data is a struct whose field names are the names 0062 % of the corresponding blocks of vars, constraints or costs (found in 0063 % order in the corresponding .order field). The description next to these 0064 % fields gives the meaning of the value for each named sub-field. 0065 % E.g. om.var.data.v0.Pg contains a vector of initial values for the 'Pg' 0066 % block of variables. 0067 % 0068 % om 0069 % .var - data for optimization variable sets that make up 0070 % the full optimization variable x 0071 % .idx 0072 % .i1 - starting index within x 0073 % .iN - ending index within x 0074 % .N - number of elements in this variable set 0075 % .N - total number of elements in x 0076 % .NS - number of variable sets or named blocks 0077 % .data - bounds and initial value data 0078 % .v0 - vector of initial values 0079 % .vl - vector of lower bounds 0080 % .vu - vector of upper bounds 0081 % .vt - scalar or vector of variable types 0082 % 'C' = continuous 0083 % 'I' = integer 0084 % 'B' = binary 0085 % .order - struct array of names/indices for variable 0086 % blocks in the order they appear in x 0087 % .name - name of the block, e.g. Pg 0088 % .idx - indices for name, {2,3} => Pg(2,3) 0089 % .nle - data for nonlinear equality constraints that make up the 0090 % full set of nonlinear constraints ghne(x) 0091 % .idx 0092 % .i1 - starting index within ghne(x) 0093 % .iN - ending index within ghne(x) 0094 % .N - number of elements in this constraint set 0095 % .N - total number of elements in ghne(x) 0096 % .NS - number of nonlinear constraint sets or named blocks 0097 % .data - data for nonlinear constraints 0098 % .fcn - function handle for constraints/gradient evaluation 0099 % .hess - function handle for Hessian evaluation 0100 % .vs - cell array of variable sets that define the xx for 0101 % this constraint block 0102 % .order - struct array of names/indices for nonlinear constraint 0103 % blocks in the order they appear in ghne(x) 0104 % .name - name of the block, e.g. Pmis 0105 % .idx - indices for name, {2,3} => Pmis(2,3) 0106 % .nli - data for nonlinear inequality constraints that make up the 0107 % full set of nonlinear constraints ghni(x) 0108 % .idx 0109 % .i1 - starting index within ghni(x) 0110 % .iN - ending index within ghni(x) 0111 % .N - number of elements in this constraint set 0112 % .N - total number of elements in ghni(x) 0113 % .NS - number of nonlinear constraint sets or named blocks 0114 % .data - data for nonlinear constraints 0115 % .fcn - function handle for constraints/gradient evaluation 0116 % .hess - function handle for Hessian evaluation 0117 % .vs - cell array of variable sets that define the xx for 0118 % this constraint block 0119 % .order - struct array of names/indices for nonlinear constraint 0120 % blocks in the order they appear in ghni(x) 0121 % .name - name of the block, e.g. Pmis 0122 % .idx - indices for name, {2,3} => Pmis(2,3) 0123 % .lin - data for linear constraints that make up the 0124 % full set of linear constraints ghl(x) 0125 % .idx 0126 % .i1 - starting index within ghl(x) 0127 % .iN - ending index within ghl(x) 0128 % .N - number of elements in this constraint set 0129 % .N - total number of elements in ghl(x) 0130 % .NS - number of linear constraint sets or named blocks 0131 % .data - data for l <= A*xx <= u linear constraints 0132 % .A - sparse linear constraint matrix 0133 % .l - left hand side vector, bounding A*x below 0134 % .u - right hand side vector, bounding A*x above 0135 % .vs - cell array of variable sets that define the xx for 0136 % this constraint block 0137 % .order - struct array of names/indices for linear constraint 0138 % blocks in the order they appear in ghl(x) 0139 % .name - name of the block, e.g. Pmis 0140 % .idx - indices for name, {2,3} => Pmis(2,3) 0141 % .params - cache for previously assembled aggregate parameters 0142 % .A - aggregate sparse linear constraint matrix 0143 % .l - aggregate left hand side vector, bounding A*x below 0144 % .u - aggregate right hand side vector, bounding A*x above 0145 % .qdc - quadratic costs 0146 % .idx 0147 % .i1 - starting row index within quadratic costs 0148 % .iN - ending row index within quadratic costs 0149 % .N - number of rows in this quadratic cost block 0150 % .N - total number of rows in quadratic costs 0151 % .NS - number of quadratic cost blocks 0152 % .data - data for each quadratic cost block 0153 % .Q - sparse matrix (or vector) of quadratic cost coefficients 0154 % .c - column vector of linear cost coefficients 0155 % .k - constant term 0156 % .vs - cell array of variable sets that define xx for this 0157 % quadratic cost block, where sizes of Q, c, k conform to xx 0158 % .order - struct array of names/indices for quadratic cost blocks 0159 % in the order the were added 0160 % .name - name of the block, e.g. R 0161 % .idx - indices for name, {2,3} => R(2,3) 0162 % .params - cache for previously assembled aggregate parameters 0163 % .Q - aggregate sparse matrix of quadratic cost coefficients 0164 % .c - aggregate column vector of linear cost coefficients 0165 % .k - aggregate constant term 0166 % .nlc - general nonlinear costs 0167 % .idx 0168 % .i1 - starting row index within nonlinear costs 0169 % .iN - ending row index within nonlinear costs 0170 % .N - number of rows in this nonlinear cost block 0171 % (always equal to 1 for nonlinear cost blocks) 0172 % .N - total number of rows in nonlinear costs 0173 % .NS - number of nonlinear cost blocks 0174 % .data - data for each nonlinear cost block 0175 % .fcn - function handle for cost, gradient, Hessian evaluation 0176 % .vs - cell array of variable sets that define xx for this 0177 % nonlinear cost block, where xx is the input to the 0178 % evaluation function 0179 % .order - struct array of names/indices for nonlinear cost blocks 0180 % in the order they were added 0181 % .name - name of the block, e.g. R 0182 % .idx - indices for name, {2,3} => R(2,3) 0183 % .prob_type - used to cache the return value of problem_type() 0184 % .soln - struct containing the output of the solve() method 0185 % with the following fields 0186 % .eflag - exit flag 0187 % .output - output struct with the following fields 0188 % .alg - algorithm code of solver used 0189 % (others) - solver specific fields 0190 % .x - solution vector 0191 % .f - final (objective) function value 0192 % .jac - final Jacobian matrix (if available, for LEQ/NLEQ probs) 0193 % .lambda - Lagrange and Kuhn-Tucker multipliers on constraints 0194 % .userdata - any user defined data 0195 % .(user defined fields) 0196 0197 % MP-Opt-Model 0198 % Copyright (c) 2008-2020, Power Systems Engineering Research Center (PSERC) 0199 % by Ray Zimmerman, PSERC Cornell 0200 % 0201 % This file is part of MP-Opt-Model. 0202 % Covered by the 3-clause BSD License (see LICENSE file for details). 0203 % See https://github.com/MATPOWER/mp-opt-model for more info. 0204 0205 properties 0206 var; %% variables 0207 lin; %% linear constraints 0208 nle; %% nonlinear equality constraints 0209 nli; %% nonlinear inequality constraints 0210 qdc; %% quadratic costs 0211 nlc; %% general nonlinear costs 0212 prob_type = ''; %% problem type 0213 soln = struct( ... %% results of solve() 0214 'eflag', [], ... %% exit flag 0215 'output', [], ... %% algorithm code & solver-specific fields 0216 'x', [], ... %% solution vector 0217 'f', [], ... %% final (objective) function value 0218 'jac', [], ... %% Jacobian (if available) for LEQ/NLEQ 0219 'lambda', [] ); %% constraint shadow prices 0220 end %% properties 0221 0222 methods 0223 %% constructor 0224 function om = opt_model(varargin) 0225 %% call parent constructor 0226 om@mp_idx_manager(varargin{:}); 0227 0228 if isempty(om.var) && strcmp(class(om), 'opt_model') 0229 %% skip if it's a sub-class or being constructed from existing object 0230 om.init_set_types(); %% Should be called in mp_idx_manager 0231 %% constructor, if not for: 0232 %% https://savannah.gnu.org/bugs/?52614 0233 end 0234 end 0235 0236 function om = def_set_types(om) 0237 om.set_types = struct(... 0238 'var', 'variable', ... 0239 'lin', 'linear constraint', ... 0240 'nle', 'nonlinear equality constraint', ... 0241 'nli', 'nonlinear inequality constraint', ... 0242 'qdc', 'quadratic cost', ... 0243 'nlc', 'general nonlinear cost' ... 0244 ); 0245 end 0246 0247 function om = init_set_types(om) 0248 %% call parent to create base data structures for each type 0249 init_set_types@mp_idx_manager(om); 0250 0251 %% finish initializing data structures for each type 0252 es = struct(); %% empty struct 0253 om.var.data = struct( ... 0254 'v0', es, ... 0255 'vl', es, ... 0256 'vu', es, ... 0257 'vt', es ); 0258 om.nle.data = struct( ... 0259 'fcn', [], ... 0260 'hess', [], ... 0261 'include', [], ... 0262 'vs', es ); 0263 om.nli.data = struct( ... 0264 'fcn', [], ... 0265 'hess', [], ... 0266 'include', [], ... 0267 'vs', es ); 0268 om.lin.data = struct( ... 0269 'A', es, ... 0270 'l', es, ... 0271 'u', es, ... 0272 'vs', es ); 0273 om.lin.params = []; 0274 om.qdc.data = struct( ... 0275 'Q', es, ... 0276 'c', es, ... 0277 'k', es, ... 0278 'vs', es ); 0279 om.qdc.params = []; 0280 om.nlc.data = struct( ... 0281 'fcn', es, ... 0282 'vs', es ); 0283 end 0284 end %% methods 0285 end %% classdef