Home > matpower5.0 > 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 %   $Id: opf_args.m 2409 2014-10-22 20:59:54Z ray $
0073 %   by Ray Zimmerman, PSERC Cornell
0074 %   and Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales
0075 %   Copyright (c) 1996-2010 by Power System Engineering Research Center (PSERC)
0076 %
0077 %   This file is part of MATPOWER.
0078 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0079 %
0080 %   MATPOWER is free software: you can redistribute it and/or modify
0081 %   it under the terms of the GNU General Public License as published
0082 %   by the Free Software Foundation, either version 3 of the License,
0083 %   or (at your option) any later version.
0084 %
0085 %   MATPOWER is distributed in the hope that it will be useful,
0086 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
0087 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0088 %   GNU General Public License for more details.
0089 %
0090 %   You should have received a copy of the GNU General Public License
0091 %   along with MATPOWER. If not, see <http://www.gnu.org/licenses/>.
0092 %
0093 %   Additional permission under GNU GPL version 3 section 7
0094 %
0095 %   If you modify MATPOWER, or any covered work, to interface with
0096 %   other modules (such as MATLAB code and MEX-files) available in a
0097 %   MATLAB(R) or comparable environment containing parts covered
0098 %   under other licensing terms, the licensors of MATPOWER grant
0099 %   you additional permission to convey the resulting work.
0100 
0101 if nargout == 2
0102   want_mpc = 1;
0103 else
0104   want_mpc = 0;
0105 end
0106 userfcn = [];
0107 if ischar(baseMVA) || isstruct(baseMVA)  %% passing filename or struct
0108   %---- opf(baseMVA,  bus,     gen, branch, areas, gencost, Au,    lbu, ubu, mpopt, N,  fparm, H, Cw, z0, zl, zu)
0109   % 12  opf(casefile, Au,      lbu, ubu,    mpopt, N,       fparm, H,   Cw,  z0,    zl, zu)
0110   % 9   opf(casefile, Au,      lbu, ubu,    mpopt, N,       fparm, H,   Cw)
0111   % 5   opf(casefile, Au,      lbu, ubu,    mpopt)
0112   % 4   opf(casefile, Au,      lbu, ubu)
0113   % 3   opf(casefile, userfcn, mpopt)
0114   % 2   opf(casefile, mpopt)
0115   % 1   opf(casefile)
0116   if any(nargin == [1, 2, 3, 4, 5, 9, 12])
0117     casefile = baseMVA;
0118     if nargin == 12
0119       zu    = fparm;
0120       zl    = N;
0121       z0    = mpopt;
0122       Cw    = ubu;
0123       H     = lbu;
0124       fparm = Au;
0125       N     = gencost;
0126       mpopt = areas;
0127       ubu   = branch;
0128       lbu   = gen;
0129       Au    = bus;
0130     elseif nargin == 9
0131       zu    = [];
0132       zl    = [];
0133       z0    = [];
0134       Cw    = ubu;
0135       H     = lbu;
0136       fparm = Au;
0137       N     = gencost;
0138       mpopt = areas;
0139       ubu   = branch;
0140       lbu   = gen;
0141       Au    = bus;
0142     elseif nargin == 5
0143       zu    = [];
0144       zl    = [];
0145       z0    = [];
0146       Cw    = [];
0147       H     = sparse(0,0);
0148       fparm = [];
0149       N     = sparse(0,0);
0150       mpopt = areas;
0151       ubu   = branch;
0152       lbu   = gen;
0153       Au    = bus;
0154     elseif nargin == 4
0155       zu    = [];
0156       zl    = [];
0157       z0    = [];
0158       Cw    = [];
0159       H     = sparse(0,0);
0160       fparm = [];
0161       N     = sparse(0,0);
0162       mpopt = mpoption;
0163       ubu   = branch;
0164       lbu   = gen;
0165       Au    = bus;
0166     elseif nargin == 3
0167       userfcn = bus;
0168       zu    = [];
0169       zl    = [];
0170       z0    = [];
0171       Cw    = [];
0172       H     = sparse(0,0);
0173       fparm = [];
0174       N     = sparse(0,0);
0175       mpopt = gen;
0176       ubu   = [];
0177       lbu   = [];
0178       Au    = sparse(0,0);
0179     elseif nargin == 2
0180       zu    = [];
0181       zl    = [];
0182       z0    = [];
0183       Cw    = [];
0184       H     = sparse(0,0);
0185       fparm = [];
0186       N     = sparse(0,0);
0187       mpopt = bus;
0188       ubu   = [];
0189       lbu   = [];
0190       Au    = sparse(0,0);
0191     elseif nargin == 1
0192       zu    = [];
0193       zl    = [];
0194       z0    = [];
0195       Cw    = [];
0196       H     = sparse(0,0);
0197       fparm = [];
0198       N     = sparse(0,0);
0199       mpopt = mpoption;
0200       ubu   = [];
0201       lbu   = [];
0202       Au    = sparse(0,0);
0203     end
0204   else
0205     error('opf_args.m: Incorrect input parameter order, number or type');
0206   end
0207   mpc = loadcase(casefile);
0208   [baseMVA, bus, gen, branch, gencost] = ...
0209     deal(mpc.baseMVA, mpc.bus, mpc.gen, mpc.branch, mpc.gencost);
0210   if isfield(mpc, 'areas')
0211     areas = mpc.areas;
0212   else
0213     areas = [];
0214   end
0215   if isempty(Au) && isfield(mpc, 'A')
0216     [Au, lbu, ubu] = deal(mpc.A, mpc.l, mpc.u);
0217   end
0218   if isempty(N) && isfield(mpc, 'N')             %% these two must go together
0219     [N, Cw] = deal(mpc.N, mpc.Cw);
0220   end
0221   if isempty(H) && isfield(mpc, 'H')             %% will default to zeros
0222     H = mpc.H;
0223   end
0224   if isempty(fparm) && isfield(mpc, 'fparm')     %% will default to [1 0 0 1]
0225     fparm = mpc.fparm;
0226   end
0227   if isempty(z0) && isfield(mpc, 'z0')
0228     z0 = mpc.z0;
0229   end
0230   if isempty(zl) && isfield(mpc, 'zl')
0231     zl = mpc.zl;
0232   end
0233   if isempty(zu) && isfield(mpc, 'zu')
0234     zu = mpc.zu;
0235   end
0236   if isempty(userfcn) && isfield(mpc, 'userfcn')
0237     userfcn = mpc.userfcn;
0238   end
0239 else    %% passing individual data matrices
0240   %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu)
0241   % 17  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu)
0242   % 14  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw)
0243   % 10  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt)
0244   % 9   opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu)
0245   % 8   opf(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt)
0246   % 7   opf(baseMVA, bus, gen, branch, areas, gencost, mpopt)
0247   % 6   opf(baseMVA, bus, gen, branch, areas, gencost)
0248   if any(nargin == [6, 7, 8, 9, 10, 14, 17])
0249     if nargin == 14
0250       zu    = [];
0251       zl    = [];
0252       z0    = [];
0253     elseif nargin == 10
0254       zu    = [];
0255       zl    = [];
0256       z0    = [];
0257       Cw    = [];
0258       H     = sparse(0,0);
0259       fparm = [];
0260       N     = sparse(0,0);
0261     elseif nargin == 9
0262       zu    = [];
0263       zl    = [];
0264       z0    = [];
0265       Cw    = [];
0266       H     = sparse(0,0);
0267       fparm = [];
0268       N     = sparse(0,0);
0269       mpopt = mpoption;
0270     elseif nargin == 8
0271       userfcn = Au;
0272       zu    = [];
0273       zl    = [];
0274       z0    = [];
0275       Cw    = [];
0276       H     = sparse(0,0);
0277       fparm = [];
0278       N     = sparse(0,0);
0279       mpopt = lbu;
0280       ubu   = [];
0281       lbu   = [];
0282       Au    = sparse(0,0);
0283     elseif nargin == 7
0284       zu    = [];
0285       zl    = [];
0286       z0    = [];
0287       Cw    = [];
0288       H     = sparse(0,0);
0289       fparm = [];
0290       N     = sparse(0,0);
0291       mpopt = Au;
0292       ubu   = [];
0293       lbu   = [];
0294       Au    = sparse(0,0);
0295     elseif nargin == 6
0296       zu    = [];
0297       zl    = [];
0298       z0    = [];
0299       Cw    = [];
0300       H     = sparse(0,0);
0301       fparm = [];
0302       N     = sparse(0,0);
0303       mpopt = mpoption;
0304       ubu   = [];
0305       lbu   = [];
0306       Au    = sparse(0,0);
0307     end
0308   else
0309     error('opf_args.m: Incorrect input parameter order, number or type');
0310   end
0311   if want_mpc
0312     mpc = struct(             ...
0313             'baseMVA',  baseMVA,    ...
0314             'bus',      bus,        ...
0315             'gen',      gen,        ...
0316             'branch',   branch,     ...
0317             'gencost',  gencost    ...
0318     );
0319   end
0320 end
0321 nw = size(N, 1);
0322 if nw
0323   if size(Cw, 1) ~= nw
0324     error('opf_args.m: dimension mismatch between N and Cw in generalized cost parameters');
0325   end
0326   if ~isempty(fparm) && size(fparm, 1) ~= nw
0327     error('opf_args.m: dimension mismatch between N and fparm in generalized cost parameters');
0328   end
0329   if ~isempty(H) && (size(H, 1) ~= nw || size(H, 2) ~= nw)
0330     error('opf_args.m: dimension mismatch between N and H in generalized cost parameters');
0331   end
0332   if size(Au, 1) > 0 && size(N, 2) ~= size(Au, 2)
0333     error('opf_args.m: A and N must have the same number of columns');
0334   end
0335   %% make sure N and H are sparse
0336   if ~issparse(N)
0337     error('opf_args.m: N must be sparse in generalized cost parameters');
0338   end
0339   if ~issparse(H)
0340     error('opf_args.m: H must be sparse in generalized cost parameters');
0341   end
0342 end
0343 if ~issparse(Au)
0344   error('opf_args.m: Au must be sparse');
0345 end
0346 if isempty(mpopt)
0347   mpopt = mpoption;
0348 end
0349 if want_mpc
0350   if ~isempty(areas)
0351     mpc.areas = areas;
0352   end
0353   if ~isempty(Au)
0354     [mpc.A, mpc.l, mpc.u] = deal(Au, lbu, ubu);
0355   end
0356   if ~isempty(N)
0357     [mpc.N, mpc.Cw ] = deal(N, Cw);
0358     if ~isempty(fparm)
0359       mpc.fparm = fparm;
0360     end
0361     if ~isempty(H)
0362       mpc.H = H;
0363     end
0364   end
0365   if ~isempty(z0)
0366     mpc.z0 = z0;
0367   end
0368   if ~isempty(zl)
0369     mpc.zl = zl;
0370   end
0371   if ~isempty(zu)
0372     mpc.zu = zu;
0373   end
0374   if ~isempty(userfcn)
0375     mpc.userfcn = userfcn;
0376   end
0377   baseMVA = mpc;
0378   bus = mpopt;
0379 end

Generated on Mon 26-Jan-2015 15:21:31 by m2html © 2005