Home > matpower7.1 > lib > opf_args.m

opf_args

PURPOSE ^

OPF_ARGS Parses and initializes OPF input arguments.

SYNOPSIS ^

function [baseMVA, bus, gen, branch, gencost, Au, lbu, ubu,mpopt, N, fparm, H, Cw, z0, zl, zu, userfcn] =opf_args(baseMVA, bus, gen, branch, areas, gencost, Au, lbu, ubu,mpopt, N, fparm, H, Cw, z0, zl, zu)

DESCRIPTION ^

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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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

Generated on Fri 09-Oct-2020 11:21:31 by m2html © 2005