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 % Copyright (c) 1996-2015 by Power System Engineering Research Center (PSERC) 0073 % by Ray Zimmerman, PSERC Cornell 0074 % and Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales 0075 % 0076 % $Id: opf_args.m 2644 2015-03-11 19:34:22Z ray $ 0077 % 0078 % This file is part of MATPOWER. 0079 % Covered by the 3-clause BSD License (see LICENSE file for details). 0080 % See http://www.pserc.cornell.edu/matpower/ for more info. 0081 0082 if nargout == 2 0083 want_mpc = 1; 0084 else 0085 want_mpc = 0; 0086 end 0087 userfcn = []; 0088 if ischar(baseMVA) || isstruct(baseMVA) %% passing filename or struct 0089 %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0090 % 12 opf(casefile, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0091 % 9 opf(casefile, Au, lbu, ubu, mpopt, N, fparm, H, Cw) 0092 % 5 opf(casefile, Au, lbu, ubu, mpopt) 0093 % 4 opf(casefile, Au, lbu, ubu) 0094 % 3 opf(casefile, userfcn, mpopt) 0095 % 2 opf(casefile, mpopt) 0096 % 1 opf(casefile) 0097 if any(nargin == [1, 2, 3, 4, 5, 9, 12]) 0098 casefile = baseMVA; 0099 if nargin == 12 0100 zu = fparm; 0101 zl = N; 0102 z0 = mpopt; 0103 Cw = ubu; 0104 H = lbu; 0105 fparm = Au; 0106 N = gencost; 0107 mpopt = areas; 0108 ubu = branch; 0109 lbu = gen; 0110 Au = bus; 0111 elseif nargin == 9 0112 zu = []; 0113 zl = []; 0114 z0 = []; 0115 Cw = ubu; 0116 H = lbu; 0117 fparm = Au; 0118 N = gencost; 0119 mpopt = areas; 0120 ubu = branch; 0121 lbu = gen; 0122 Au = bus; 0123 elseif nargin == 5 0124 zu = []; 0125 zl = []; 0126 z0 = []; 0127 Cw = []; 0128 H = sparse(0,0); 0129 fparm = []; 0130 N = sparse(0,0); 0131 mpopt = areas; 0132 ubu = branch; 0133 lbu = gen; 0134 Au = bus; 0135 elseif nargin == 4 0136 zu = []; 0137 zl = []; 0138 z0 = []; 0139 Cw = []; 0140 H = sparse(0,0); 0141 fparm = []; 0142 N = sparse(0,0); 0143 mpopt = mpoption; 0144 ubu = branch; 0145 lbu = gen; 0146 Au = bus; 0147 elseif nargin == 3 0148 userfcn = bus; 0149 zu = []; 0150 zl = []; 0151 z0 = []; 0152 Cw = []; 0153 H = sparse(0,0); 0154 fparm = []; 0155 N = sparse(0,0); 0156 mpopt = gen; 0157 ubu = []; 0158 lbu = []; 0159 Au = sparse(0,0); 0160 elseif nargin == 2 0161 zu = []; 0162 zl = []; 0163 z0 = []; 0164 Cw = []; 0165 H = sparse(0,0); 0166 fparm = []; 0167 N = sparse(0,0); 0168 mpopt = bus; 0169 ubu = []; 0170 lbu = []; 0171 Au = sparse(0,0); 0172 elseif nargin == 1 0173 zu = []; 0174 zl = []; 0175 z0 = []; 0176 Cw = []; 0177 H = sparse(0,0); 0178 fparm = []; 0179 N = sparse(0,0); 0180 mpopt = mpoption; 0181 ubu = []; 0182 lbu = []; 0183 Au = sparse(0,0); 0184 end 0185 else 0186 error('opf_args.m: Incorrect input parameter order, number or type'); 0187 end 0188 mpc = loadcase(casefile); 0189 [baseMVA, bus, gen, branch, gencost] = ... 0190 deal(mpc.baseMVA, mpc.bus, mpc.gen, mpc.branch, mpc.gencost); 0191 if isfield(mpc, 'areas') 0192 areas = mpc.areas; 0193 else 0194 areas = []; 0195 end 0196 if isempty(Au) && isfield(mpc, 'A') 0197 [Au, lbu, ubu] = deal(mpc.A, mpc.l, mpc.u); 0198 end 0199 if isempty(N) && isfield(mpc, 'N') %% these two must go together 0200 [N, Cw] = deal(mpc.N, mpc.Cw); 0201 end 0202 if isempty(H) && isfield(mpc, 'H') %% will default to zeros 0203 H = mpc.H; 0204 end 0205 if isempty(fparm) && isfield(mpc, 'fparm') %% will default to [1 0 0 1] 0206 fparm = mpc.fparm; 0207 end 0208 if isempty(z0) && isfield(mpc, 'z0') 0209 z0 = mpc.z0; 0210 end 0211 if isempty(zl) && isfield(mpc, 'zl') 0212 zl = mpc.zl; 0213 end 0214 if isempty(zu) && isfield(mpc, 'zu') 0215 zu = mpc.zu; 0216 end 0217 if isempty(userfcn) && isfield(mpc, 'userfcn') 0218 userfcn = mpc.userfcn; 0219 end 0220 else %% passing individual data matrices 0221 %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0222 % 17 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu) 0223 % 14 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt, N, fparm, H, Cw) 0224 % 10 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu, mpopt) 0225 % 9 opf(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu) 0226 % 8 opf(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt) 0227 % 7 opf(baseMVA, bus, gen, branch, areas, gencost, mpopt) 0228 % 6 opf(baseMVA, bus, gen, branch, areas, gencost) 0229 if any(nargin == [6, 7, 8, 9, 10, 14, 17]) 0230 if nargin == 14 0231 zu = []; 0232 zl = []; 0233 z0 = []; 0234 elseif nargin == 10 0235 zu = []; 0236 zl = []; 0237 z0 = []; 0238 Cw = []; 0239 H = sparse(0,0); 0240 fparm = []; 0241 N = sparse(0,0); 0242 elseif nargin == 9 0243 zu = []; 0244 zl = []; 0245 z0 = []; 0246 Cw = []; 0247 H = sparse(0,0); 0248 fparm = []; 0249 N = sparse(0,0); 0250 mpopt = mpoption; 0251 elseif nargin == 8 0252 userfcn = Au; 0253 zu = []; 0254 zl = []; 0255 z0 = []; 0256 Cw = []; 0257 H = sparse(0,0); 0258 fparm = []; 0259 N = sparse(0,0); 0260 mpopt = lbu; 0261 ubu = []; 0262 lbu = []; 0263 Au = sparse(0,0); 0264 elseif nargin == 7 0265 zu = []; 0266 zl = []; 0267 z0 = []; 0268 Cw = []; 0269 H = sparse(0,0); 0270 fparm = []; 0271 N = sparse(0,0); 0272 mpopt = Au; 0273 ubu = []; 0274 lbu = []; 0275 Au = sparse(0,0); 0276 elseif nargin == 6 0277 zu = []; 0278 zl = []; 0279 z0 = []; 0280 Cw = []; 0281 H = sparse(0,0); 0282 fparm = []; 0283 N = sparse(0,0); 0284 mpopt = mpoption; 0285 ubu = []; 0286 lbu = []; 0287 Au = sparse(0,0); 0288 end 0289 else 0290 error('opf_args.m: Incorrect input parameter order, number or type'); 0291 end 0292 if want_mpc 0293 mpc = struct( ... 0294 'baseMVA', baseMVA, ... 0295 'bus', bus, ... 0296 'gen', gen, ... 0297 'branch', branch, ... 0298 'gencost', gencost ... 0299 ); 0300 end 0301 end 0302 nw = size(N, 1); 0303 if nw 0304 if size(Cw, 1) ~= nw 0305 error('opf_args.m: dimension mismatch between N and Cw in generalized cost parameters'); 0306 end 0307 if ~isempty(fparm) && size(fparm, 1) ~= nw 0308 error('opf_args.m: dimension mismatch between N and fparm in generalized cost parameters'); 0309 end 0310 if ~isempty(H) && (size(H, 1) ~= nw || size(H, 2) ~= nw) 0311 error('opf_args.m: dimension mismatch between N and H in generalized cost parameters'); 0312 end 0313 if size(Au, 1) > 0 && size(N, 2) ~= size(Au, 2) 0314 error('opf_args.m: A and N must have the same number of columns'); 0315 end 0316 %% make sure N and H are sparse 0317 if ~issparse(N) 0318 error('opf_args.m: N must be sparse in generalized cost parameters'); 0319 end 0320 if ~issparse(H) 0321 error('opf_args.m: H must be sparse in generalized cost parameters'); 0322 end 0323 end 0324 if ~issparse(Au) 0325 error('opf_args.m: Au must be sparse'); 0326 end 0327 if isempty(mpopt) 0328 mpopt = mpoption; 0329 end 0330 if want_mpc 0331 if ~isempty(areas) 0332 mpc.areas = areas; 0333 end 0334 if ~isempty(Au) 0335 [mpc.A, mpc.l, mpc.u] = deal(Au, lbu, ubu); 0336 end 0337 if ~isempty(N) 0338 [mpc.N, mpc.Cw ] = deal(N, Cw); 0339 if ~isempty(fparm) 0340 mpc.fparm = fparm; 0341 end 0342 if ~isempty(H) 0343 mpc.H = H; 0344 end 0345 end 0346 if ~isempty(z0) 0347 mpc.z0 = z0; 0348 end 0349 if ~isempty(zl) 0350 mpc.zl = zl; 0351 end 0352 if ~isempty(zu) 0353 mpc.zu = zu; 0354 end 0355 if ~isempty(userfcn) 0356 mpc.userfcn = userfcn; 0357 end 0358 baseMVA = mpc; 0359 bus = mpopt; 0360 end