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