0001 classdef opt_model < handle 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_legacy_cost 0018 % add_quad_cost 0019 % add_nln_cost 0020 % add_lin_constraint 0021 % add_nln_constraint 0022 % add_var 0023 % init_indexed_name 0024 % add_costs (deprecated) 0025 % add_constraints (deprecated) 0026 % add_vars (deprecated) 0027 % 0028 % Return the number of linear constraints, nonlinear constraints, 0029 % variables or cost rows, optionally for a single named block: 0030 % getN 0031 % 0032 % Return the intial values, bounds and type for optimization variables: 0033 % params_var 0034 % getv (deprecated) 0035 % 0036 % Build and return full set of linear constraints: 0037 % params_lin_constraint 0038 % linear_constraints (deprecated) 0039 % 0040 % Return index structure for variables, linear and nonlinear constraints 0041 % and costs: 0042 % get_idx 0043 % 0044 % Build and return cost parameters and evaluate user-defined costs: 0045 % params_nln_cost 0046 % params_quad_cost 0047 % params_legacy_cost 0048 % eval_legacy_cost 0049 % eval_nln_cost 0050 % eval_quad_cost 0051 % get_cost_params 0052 % compute_cost (deprecated) 0053 % build_cost_params (deprecated) 0054 % 0055 % Retreive user data in the model object: 0056 % get_userdata 0057 % 0058 % Display the object (called automatically when you omit the semicolon 0059 % at the command-line): 0060 % display 0061 % 0062 % Return the value of an individual field: 0063 % get 0064 % 0065 % Indentify variable, constraint or cost row indices: 0066 % describe_idx 0067 % 0068 % The following is the structure of the data in the OPF model object. 0069 % Each field of .idx or .data is a struct whose field names are the names 0070 % of the corresponding blocks of vars, constraints or costs (found in 0071 % order in the corresponding .order field). The description next to these 0072 % fields gives the meaning of the value for each named sub-field. 0073 % E.g. om.var.data.v0.Pg contains a vector of initial values for the 'Pg' 0074 % block of variables. 0075 % 0076 % om 0077 % .var - data for optimization variable sets that make up 0078 % the full optimization variable x 0079 % .idx 0080 % .i1 - starting index within x 0081 % .iN - ending index within x 0082 % .N - number of elements in this variable set 0083 % .N - total number of elements in x 0084 % .NS - number of variable sets or named blocks 0085 % .data - bounds and initial value data 0086 % .v0 - vector of initial values 0087 % .vl - vector of lower bounds 0088 % .vu - vector of upper bounds 0089 % .vt - scalar or vector of variable types 0090 % 'C' = continuous 0091 % 'I' = integer 0092 % 'B' = binary 0093 % .order - struct array of names/indices for variable 0094 % blocks in the order they appear in x 0095 % .name - name of the block, e.g. Pg 0096 % .idx - indices for name, {2,3} => Pg(2,3) 0097 % .nle - data for nonlinear equality constraints that make up the 0098 % full set of nonlinear constraints ghne(x) 0099 % .idx 0100 % .i1 - starting index within ghne(x) 0101 % .iN - ending index within ghne(x) 0102 % .N - number of elements in this constraint set 0103 % .N - total number of elements in ghne(x) 0104 % .NS - number of nonlinear constraint sets or named blocks 0105 % .data - data for nonlinear constraints 0106 % .fcn - function handle for constraints/gradient evaluation 0107 % .hess - function handle for Hessian evaluation 0108 % .vs - cell array of variable sets that define the xx for 0109 % this constraint block 0110 % .order - struct array of names/indices for nonlinear constraint 0111 % blocks in the order they appear in ghne(x) 0112 % .name - name of the block, e.g. Pmis 0113 % .idx - indices for name, {2,3} => Pmis(2,3) 0114 % .nli - data for nonlinear inequality constraints that make up the 0115 % full set of nonlinear constraints ghni(x) 0116 % .idx 0117 % .i1 - starting index within ghni(x) 0118 % .iN - ending index within ghni(x) 0119 % .N - number of elements in this constraint set 0120 % .N - total number of elements in ghni(x) 0121 % .NS - number of nonlinear constraint sets or named blocks 0122 % .data - data for nonlinear constraints 0123 % .fcn - function handle for constraints/gradient evaluation 0124 % .hess - function handle for Hessian evaluation 0125 % .vs - cell array of variable sets that define the xx for 0126 % this constraint block 0127 % .order - struct array of names/indices for nonlinear constraint 0128 % blocks in the order they appear in ghni(x) 0129 % .name - name of the block, e.g. Pmis 0130 % .idx - indices for name, {2,3} => Pmis(2,3) 0131 % .lin - data for linear constraints that make up the 0132 % full set of linear constraints ghl(x) 0133 % .idx 0134 % .i1 - starting index within ghl(x) 0135 % .iN - ending index within ghl(x) 0136 % .N - number of elements in this constraint set 0137 % .N - total number of elements in ghl(x) 0138 % .NS - number of linear constraint sets or named blocks 0139 % .data - data for l <= A*xx <= u linear constraints 0140 % .A - sparse linear constraint matrix 0141 % .l - left hand side vector, bounding A*x below 0142 % .u - right hand side vector, bounding A*x above 0143 % .vs - cell array of variable sets that define the xx for 0144 % this constraint block 0145 % .order - struct array of names/indices for linear constraint 0146 % blocks in the order they appear in ghl(x) 0147 % .name - name of the block, e.g. Pmis 0148 % .idx - indices for name, {2,3} => Pmis(2,3) 0149 % .qdc - quadratic costs 0150 % .idx 0151 % .i1 - starting row index within quadratic costs 0152 % .iN - ending row index within quadratic costs 0153 % .N - number of rows in this quadratic cost block 0154 % .N - total number of rows in quadratic costs 0155 % .NS - number of quadratic cost blocks 0156 % .data - data for each quadratic cost block 0157 % .Q - sparse matrix (or vector) of quadratic cost coefficients 0158 % .c - column vector of linear cost coefficients 0159 % .k - constant term 0160 % .vs - cell array of variable sets that define xx for this 0161 % quadratic cost block, where sizes of Q, c, k conform to xx 0162 % .order - struct array of names/indices for quadratic cost blocks 0163 % in the order the were added 0164 % .name - name of the block, e.g. R 0165 % .idx - indices for name, {2,3} => R(2,3) 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 % .cost - data for legacy user-defined costs 0184 % .idx 0185 % .i1 - starting row index within full N matrix 0186 % .iN - ending row index within full N matrix 0187 % .N - number of rows in this cost block in full N matrix 0188 % .N - total number of rows in full N matrix 0189 % .NS - number of cost blocks 0190 % .data - data for each user-defined cost block 0191 % .N - see help for ADD_LEGACY_COST for details 0192 % .H - " 0193 % .Cw - " 0194 % .dd - " 0195 % .rr - " 0196 % .kk - " 0197 % .mm - " 0198 % .vs - cell array of variable sets that define xx for this 0199 % cost block, where the N for this block multiplies xx 0200 % .order - struct array of names/indices for cost blocks in the 0201 % order they appear in the rows of the full N matrix 0202 % .name - name of the block, e.g. R 0203 % .idx - indices for name, {2,3} => R(2,3) 0204 % .userdata - any user defined data 0205 % .(user defined fields) 0206 0207 % MATPOWER 0208 % Copyright (c) 2008-2017, Power Systems Engineering Research Center (PSERC) 0209 % by Ray Zimmerman, PSERC Cornell 0210 % 0211 % This file is part of MATPOWER. 0212 % Covered by the 3-clause BSD License (see LICENSE file for details). 0213 % See https://matpower.org for more info. 0214 0215 % es = struct(); 0216 0217 properties 0218 var = struct( ... 0219 'idx', struct( ... 0220 'i1', struct(), ... 0221 'iN', struct(), ... 0222 'N', struct() ), ... 0223 'N', 0, ... 0224 'NS', 0, ... 0225 'order', struct( ... 0226 'name', [], ... 0227 'idx', [] ), ... 0228 'data', struct( ... 0229 'v0', struct(), ... 0230 'vl', struct(), ... 0231 'vu', struct(), ... 0232 'vt', struct() ) ); 0233 nle = struct( ... 0234 'idx', struct( ... 0235 'i1', struct(), ... 0236 'iN', struct(), ... 0237 'N', struct() ), ... 0238 'N', 0, ... 0239 'NS', 0, ... 0240 'order', struct( ... 0241 'name', [], ... 0242 'idx', [] ), ... 0243 'data', struct( ... 0244 'fcn', [], ... 0245 'hess', [], ... 0246 'include', [], ... 0247 'vs', struct() ) ); 0248 nli = struct( ... 0249 'idx', struct( ... 0250 'i1', struct(), ... 0251 'iN', struct(), ... 0252 'N', struct() ), ... 0253 'N', 0, ... 0254 'NS', 0, ... 0255 'order', struct( ... 0256 'name', [], ... 0257 'idx', [] ), ... 0258 'data', struct( ... 0259 'fcn', [], ... 0260 'hess', [], ... 0261 'include', [], ... 0262 'vs', struct() ) ); 0263 lin = struct( ... 0264 'idx', struct( ... 0265 'i1', struct(), ... 0266 'iN', struct(), ... 0267 'N', struct() ), ... 0268 'N', 0, ... 0269 'NS', 0, ... 0270 'order', struct( ... 0271 'name', [], ... 0272 'idx', [] ), ... 0273 'data', struct( ... 0274 'A', struct(), ... 0275 'l', struct(), ... 0276 'u', struct(), ... 0277 'vs', struct() ), ... 0278 'params', [] ); 0279 qdc = struct( ... 0280 'idx', struct( ... 0281 'i1', struct(), ... 0282 'iN', struct(), ... 0283 'N', struct() ), ... 0284 'N', 0, ... 0285 'NS', 0, ... 0286 'order', struct( ... 0287 'name', [], ... 0288 'idx', [] ), ... 0289 'data', struct( ... 0290 'Q', struct(), ... 0291 'c', struct(), ... 0292 'k', struct(), ... 0293 'vs', struct() ), ... 0294 'params', [] ); 0295 nlc = struct( ... 0296 'idx', struct( ... 0297 'i1', struct(), ... 0298 'iN', struct(), ... 0299 'N', struct() ), ... 0300 'N', 0, ... 0301 'NS', 0, ... 0302 'order', struct( ... 0303 'name', [], ... 0304 'idx', [] ), ... 0305 'data', struct( ... 0306 'fcn', struct(), ... 0307 'vs', struct() ) ); 0308 cost = struct( ... 0309 'idx', struct( ... 0310 'i1', struct(), ... 0311 'iN', struct(), ... 0312 'N', struct() ), ... 0313 'N', 0, ... 0314 'NS', 0, ... 0315 'order', struct( ... 0316 'name', [], ... 0317 'idx', [] ), ... 0318 'data', struct( ... 0319 'N', struct(), ... 0320 'H', struct(), ... 0321 'Cw', struct(), ... 0322 'dd', struct(), ... 0323 'rh', struct(), ... 0324 'kk', struct(), ... 0325 'mm', struct(), ... 0326 'vs', struct() ), ... 0327 'params', [] ); 0328 userdata = struct(); 0329 end 0330 0331 methods 0332 %% constructor 0333 function om = opt_model(s) 0334 if nargin > 0 0335 if isa(s, 'opt_model') 0336 props = fieldnames(s); 0337 for k = 1:length(props) 0338 om.(props{k}) = s.(props{k}); 0339 end 0340 elseif isstruct(s) 0341 props = fieldnames(om); 0342 for k = 1:length(props) 0343 if isfield(s, props{k}) 0344 om.(props{k}) = s.(props{k}); 0345 end 0346 end 0347 else 0348 error('@opt_model/opt_model: input must be a ''opt_model'' object or a struct'); 0349 end 0350 end 0351 end 0352 end 0353 end