Home > matpower5.1 > 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-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

Generated on Fri 20-Mar-2015 18:23:34 by m2html © 2005