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