OPF_ARGS Parses and initializes OPF input arguments.
[MPC, MPOPT] = OPF_ARGS( ... )
[BASEMVA, BUS, GEN, BRANCH, GENCOST, A, L, U, MPOPT, ...
N, FPARM, H, CW, Z0, ZL, ZU, USERFCN] = OPF_ARGS( ... )
Returns the full set of initialized OPF input arguments, filling in
default values for missing arguments. See Examples below for the
possible calling syntax options.
Examples:
Output argument options:
[mpc, mpopt] = opf_args( ... )
[baseMVA, bus, gen, branch, gencost, A, l, u, mpopt, ...
N, fparm, H, Cw, z0, zl, zu, userfcn] = opf_args( ... )
Input arguments options:
opf_args(mpc)
opf_args(mpc, mpopt)
opf_args(mpc, userfcn, mpopt)
opf_args(mpc, A, l, u)
opf_args(mpc, A, l, u, mpopt)
opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw)
opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw, z0, zl, zu)
opf_args(baseMVA, bus, gen, branch, areas, gencost)
opf_args(baseMVA, bus, gen, branch, areas, gencost, mpopt)
opf_args(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt)
opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u)
opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, mpopt)
opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ...
mpopt, N, fparm, H, Cw)
opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ...
mpopt, N, fparm, H, Cw, z0, zl, zu)
The data for the problem can be specified in one of three ways:
(1) a string (mpc) containing the file name of a MATPOWER case
which defines the data matrices baseMVA, bus, gen, branch, and
gencost (areas is not used at all, it is only included for
backward compatibility of the API).
(2) a struct (mpc) containing the data matrices as fields.
(3) the individual data matrices themselves.
The optional user parameters for user constraints (A, l, u), user costs
(N, fparm, H, Cw), user variable initializer (z0), and user variable
limits (zl, zu) can also be specified as fields in a case struct,
either passed in directly or defined in a case file referenced by name.
When specified, A, l, u represent additional linear constraints on the
optimization variables, l <= A*[x; z] <= u. If the user specifies an A
matrix that has more columns than the number of "x" (OPF) variables,
then there are extra linearly constrained "z" variables. For an
explanation of the formulation used and instructions for forming the
A matrix, see the manual.
A generalized cost on all variables can be applied if input arguments
N, fparm, H and Cw are specified. First, a linear transformation
of the optimization variables is defined by means of r = N * [x; z].
Then, to each element of r a function is applied as encoded in the
fparm matrix (see manual). If the resulting vector is named w,
then H and Cw define a quadratic cost on w: (1/2)*w'*H*w + Cw * w .
H and N should be sparse matrices and H should also be symmetric.
The optional mpopt vector specifies MATPOWER options. See MPOPTION
for details and default values.0001 function [baseMVA, bus, gen, branch, gencost, Au, lbu, ubu, ... 0002 mpopt, N, fparm, H, Cw, z0, zl, zu, userfcn] = ... 0003 opf_args(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, ... 0004 mpopt, N, fparm, H, Cw, z0, zl, zu) 0005 %OPF_ARGS Parses and initializes OPF input arguments. 0006 % [MPC, MPOPT] = OPF_ARGS( ... ) 0007 % [BASEMVA, BUS, GEN, BRANCH, GENCOST, A, L, U, MPOPT, ... 0008 % N, FPARM, H, CW, Z0, ZL, ZU, USERFCN] = OPF_ARGS( ... ) 0009 % Returns the full set of initialized OPF input arguments, filling in 0010 % default values for missing arguments. See Examples below for the 0011 % possible calling syntax options. 0012 % 0013 % Examples: 0014 % Output argument options: 0015 % 0016 % [mpc, mpopt] = opf_args( ... ) 0017 % [baseMVA, bus, gen, branch, gencost, A, l, u, mpopt, ... 0018 % N, fparm, H, Cw, z0, zl, zu, userfcn] = opf_args( ... ) 0019 % 0020 % Input arguments options: 0021 % 0022 % opf_args(mpc) 0023 % opf_args(mpc, mpopt) 0024 % opf_args(mpc, userfcn, mpopt) 0025 % opf_args(mpc, A, l, u) 0026 % opf_args(mpc, A, l, u, mpopt) 0027 % opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw) 0028 % opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw, z0, zl, zu) 0029 % 0030 % opf_args(baseMVA, bus, gen, branch, areas, gencost) 0031 % opf_args(baseMVA, bus, gen, branch, areas, gencost, mpopt) 0032 % opf_args(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt) 0033 % opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u) 0034 % opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, mpopt) 0035 % opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ... 0036 % mpopt, N, fparm, H, Cw) 0037 % opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ... 0038 % mpopt, N, fparm, H, Cw, z0, zl, zu) 0039 % 0040 % The data for the problem can be specified in one of three ways: 0041 % (1) a string (mpc) containing the file name of a MATPOWER case 0042 % which defines the data matrices baseMVA, bus, gen, branch, and 0043 % gencost (areas is not used at all, it is only included for 0044 % backward compatibility of the API). 0045 % (2) a struct (mpc) containing the data matrices as fields. 0046 % (3) the individual data matrices themselves. 0047 % 0048 % The optional user parameters for user constraints (A, l, u), user costs 0049 % (N, fparm, H, Cw), user variable initializer (z0), and user variable 0050 % limits (zl, zu) can also be specified as fields in a case struct, 0051 % either passed in directly or defined in a case file referenced by name. 0052 % 0053 % When specified, A, l, u represent additional linear constraints on the 0054 % optimization variables, l <= A*[x; z] <= u. If the user specifies an A 0055 % matrix that has more columns than the number of "x" (OPF) variables, 0056 % then there are extra linearly constrained "z" variables. For an 0057 % explanation of the formulation used and instructions for forming the 0058 % A matrix, see the manual. 0059 % 0060 % A generalized cost on all variables can be applied if input arguments 0061 % N, fparm, H and Cw are specified. First, a linear transformation 0062 % of the optimization variables is defined by means of r = N * [x; z]. 0063 % Then, to each element of r a function is applied as encoded in the 0064 % fparm matrix (see manual). If the resulting vector is named w, 0065 % then H and Cw define a quadratic cost on w: (1/2)*w'*H*w + Cw * w . 0066 % H and N should be sparse matrices and H should also be symmetric. 0067 % 0068 % The optional mpopt vector specifies MATPOWER options. See MPOPTION 0069 % for details and default values. 0070 0071 % MATPOWER 0072 % $Id: opf_args.m 2409 2014-10-22 20:59:54Z ray $ 0073 % by Ray Zimmerman, PSERC Cornell 0074 % and Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales 0075 % Copyright (c) 1996-2010 by Power System Engineering Research Center (PSERC) 0076 % 0077 % This file is part of MATPOWER. 0078 % See http://www.pserc.cornell.edu/matpower/ for more info. 0079 % 0080 % MATPOWER is free software: you can redistribute it and/or modify 0081 % it under the terms of the GNU General Public License as published 0082 % by the Free Software Foundation, either version 3 of the License, 0083 % or (at your option) any later version. 0084 % 0085 % MATPOWER is distributed in the hope that it will be useful, 0086 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0087 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0088 % GNU General Public License for more details. 0089 % 0090 % You should have received a copy of the GNU General Public License 0091 % along with MATPOWER. If not, see <http://www.gnu.org/licenses/>. 0092 % 0093 % Additional permission under GNU GPL version 3 section 7 0094 % 0095 % If you modify MATPOWER, or any covered work, to interface with 0096 % other modules (such as MATLAB code and MEX-files) available in a 0097 % MATLAB(R) or comparable environment containing parts covered 0098 % under other licensing terms, the licensors of MATPOWER grant 0099 % you additional permission to convey the resulting work. 0100 0101 if nargout == 2 0102 want_mpc = 1; 0103 else 0104 want_mpc = 0; 0105 end 0106 userfcn = []; 0107 if ischar(baseMVA) || isstruct(baseMVA) %% passing filename or struct 0108 %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0109 % 12 opf(casefile, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0110 % 9 opf(casefile, Au, lbu, ubu, mpopt, N, fparm, H, Cw) 0111 % 5 opf(casefile, Au, lbu, ubu, mpopt) 0112 % 4 opf(casefile, Au, lbu, ubu) 0113 % 3 opf(casefile, userfcn, mpopt) 0114 % 2 opf(casefile, mpopt) 0115 % 1 opf(casefile) 0116 if any(nargin == [1, 2, 3, 4, 5, 9, 12]) 0117 casefile = baseMVA; 0118 if nargin == 12 0119 zu = fparm; 0120 zl = N; 0121 z0 = mpopt; 0122 Cw = ubu; 0123 H = lbu; 0124 fparm = Au; 0125 N = gencost; 0126 mpopt = areas; 0127 ubu = branch; 0128 lbu = gen; 0129 Au = bus; 0130 elseif nargin == 9 0131 zu = []; 0132 zl = []; 0133 z0 = []; 0134 Cw = ubu; 0135 H = lbu; 0136 fparm = Au; 0137 N = gencost; 0138 mpopt = areas; 0139 ubu = branch; 0140 lbu = gen; 0141 Au = bus; 0142 elseif nargin == 5 0143 zu = []; 0144 zl = []; 0145 z0 = []; 0146 Cw = []; 0147 H = sparse(0,0); 0148 fparm = []; 0149 N = sparse(0,0); 0150 mpopt = areas; 0151 ubu = branch; 0152 lbu = gen; 0153 Au = bus; 0154 elseif nargin == 4 0155 zu = []; 0156 zl = []; 0157 z0 = []; 0158 Cw = []; 0159 H = sparse(0,0); 0160 fparm = []; 0161 N = sparse(0,0); 0162 mpopt = mpoption; 0163 ubu = branch; 0164 lbu = gen; 0165 Au = bus; 0166 elseif nargin == 3 0167 userfcn = bus; 0168 zu = []; 0169 zl = []; 0170 z0 = []; 0171 Cw = []; 0172 H = sparse(0,0); 0173 fparm = []; 0174 N = sparse(0,0); 0175 mpopt = gen; 0176 ubu = []; 0177 lbu = []; 0178 Au = sparse(0,0); 0179 elseif nargin == 2 0180 zu = []; 0181 zl = []; 0182 z0 = []; 0183 Cw = []; 0184 H = sparse(0,0); 0185 fparm = []; 0186 N = sparse(0,0); 0187 mpopt = bus; 0188 ubu = []; 0189 lbu = []; 0190 Au = sparse(0,0); 0191 elseif nargin == 1 0192 zu = []; 0193 zl = []; 0194 z0 = []; 0195 Cw = []; 0196 H = sparse(0,0); 0197 fparm = []; 0198 N = sparse(0,0); 0199 mpopt = mpoption; 0200 ubu = []; 0201 lbu = []; 0202 Au = sparse(0,0); 0203 end 0204 else 0205 error('opf_args.m: Incorrect input parameter order, number or type'); 0206 end 0207 mpc = loadcase(casefile); 0208 [baseMVA, bus, gen, branch, gencost] = ... 0209 deal(mpc.baseMVA, mpc.bus, mpc.gen, mpc.branch, mpc.gencost); 0210 if isfield(mpc, 'areas') 0211 areas = mpc.areas; 0212 else 0213 areas = []; 0214 end 0215 if isempty(Au) && isfield(mpc, 'A') 0216 [Au, lbu, ubu] = deal(mpc.A, mpc.l, mpc.u); 0217 end 0218 if isempty(N) && isfield(mpc, 'N') %% these two must go together 0219 [N, Cw] = deal(mpc.N, mpc.Cw); 0220 end 0221 if isempty(H) && isfield(mpc, 'H') %% will default to zeros 0222 H = mpc.H; 0223 end 0224 if isempty(fparm) && isfield(mpc, 'fparm') %% will default to [1 0 0 1] 0225 fparm = mpc.fparm; 0226 end 0227 if isempty(z0) && isfield(mpc, 'z0') 0228 z0 = mpc.z0; 0229 end 0230 if isempty(zl) && isfield(mpc, 'zl') 0231 zl = mpc.zl; 0232 end 0233 if isempty(zu) && isfield(mpc, 'zu') 0234 zu = mpc.zu; 0235 end 0236 if isempty(userfcn) && isfield(mpc, 'userfcn') 0237 userfcn = mpc.userfcn; 0238 end 0239 else %% passing individual data matrices 0240 %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0241 % 17 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0242 % 14 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw) 0243 % 10 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt) 0244 % 9 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu) 0245 % 8 opf(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt) 0246 % 7 opf(baseMVA, bus, gen, branch, areas, gencost, mpopt) 0247 % 6 opf(baseMVA, bus, gen, branch, areas, gencost) 0248 if any(nargin == [6, 7, 8, 9, 10, 14, 17]) 0249 if nargin == 14 0250 zu = []; 0251 zl = []; 0252 z0 = []; 0253 elseif nargin == 10 0254 zu = []; 0255 zl = []; 0256 z0 = []; 0257 Cw = []; 0258 H = sparse(0,0); 0259 fparm = []; 0260 N = sparse(0,0); 0261 elseif nargin == 9 0262 zu = []; 0263 zl = []; 0264 z0 = []; 0265 Cw = []; 0266 H = sparse(0,0); 0267 fparm = []; 0268 N = sparse(0,0); 0269 mpopt = mpoption; 0270 elseif nargin == 8 0271 userfcn = Au; 0272 zu = []; 0273 zl = []; 0274 z0 = []; 0275 Cw = []; 0276 H = sparse(0,0); 0277 fparm = []; 0278 N = sparse(0,0); 0279 mpopt = lbu; 0280 ubu = []; 0281 lbu = []; 0282 Au = sparse(0,0); 0283 elseif nargin == 7 0284 zu = []; 0285 zl = []; 0286 z0 = []; 0287 Cw = []; 0288 H = sparse(0,0); 0289 fparm = []; 0290 N = sparse(0,0); 0291 mpopt = Au; 0292 ubu = []; 0293 lbu = []; 0294 Au = sparse(0,0); 0295 elseif nargin == 6 0296 zu = []; 0297 zl = []; 0298 z0 = []; 0299 Cw = []; 0300 H = sparse(0,0); 0301 fparm = []; 0302 N = sparse(0,0); 0303 mpopt = mpoption; 0304 ubu = []; 0305 lbu = []; 0306 Au = sparse(0,0); 0307 end 0308 else 0309 error('opf_args.m: Incorrect input parameter order, number or type'); 0310 end 0311 if want_mpc 0312 mpc = struct( ... 0313 'baseMVA', baseMVA, ... 0314 'bus', bus, ... 0315 'gen', gen, ... 0316 'branch', branch, ... 0317 'gencost', gencost ... 0318 ); 0319 end 0320 end 0321 nw = size(N, 1); 0322 if nw 0323 if size(Cw, 1) ~= nw 0324 error('opf_args.m: dimension mismatch between N and Cw in generalized cost parameters'); 0325 end 0326 if ~isempty(fparm) && size(fparm, 1) ~= nw 0327 error('opf_args.m: dimension mismatch between N and fparm in generalized cost parameters'); 0328 end 0329 if ~isempty(H) && (size(H, 1) ~= nw || size(H, 2) ~= nw) 0330 error('opf_args.m: dimension mismatch between N and H in generalized cost parameters'); 0331 end 0332 if size(Au, 1) > 0 && size(N, 2) ~= size(Au, 2) 0333 error('opf_args.m: A and N must have the same number of columns'); 0334 end 0335 %% make sure N and H are sparse 0336 if ~issparse(N) 0337 error('opf_args.m: N must be sparse in generalized cost parameters'); 0338 end 0339 if ~issparse(H) 0340 error('opf_args.m: H must be sparse in generalized cost parameters'); 0341 end 0342 end 0343 if ~issparse(Au) 0344 error('opf_args.m: Au must be sparse'); 0345 end 0346 if isempty(mpopt) 0347 mpopt = mpoption; 0348 end 0349 if want_mpc 0350 if ~isempty(areas) 0351 mpc.areas = areas; 0352 end 0353 if ~isempty(Au) 0354 [mpc.A, mpc.l, mpc.u] = deal(Au, lbu, ubu); 0355 end 0356 if ~isempty(N) 0357 [mpc.N, mpc.Cw ] = deal(N, Cw); 0358 if ~isempty(fparm) 0359 mpc.fparm = fparm; 0360 end 0361 if ~isempty(H) 0362 mpc.H = H; 0363 end 0364 end 0365 if ~isempty(z0) 0366 mpc.z0 = z0; 0367 end 0368 if ~isempty(zl) 0369 mpc.zl = zl; 0370 end 0371 if ~isempty(zu) 0372 mpc.zu = zu; 0373 end 0374 if ~isempty(userfcn) 0375 mpc.userfcn = userfcn; 0376 end 0377 baseMVA = mpc; 0378 bus = mpopt; 0379 end