Home > matpower4.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, areas] =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( ... )
       [baseMVA, bus, gen, branch, gencost, A, l, u, mpopt, ...
           N, fparm, H, Cw, z0, zl, zu, userfcn, areas] = 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, areas] = ...
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 %       [baseMVA, bus, gen, branch, gencost, A, l, u, mpopt, ...
0020 %           N, fparm, H, Cw, z0, zl, zu, userfcn, areas] = opf_args( ... )
0021 %
0022 %       Input arguments options:
0023 %
0024 %       opf_args(mpc)
0025 %       opf_args(mpc, mpopt)
0026 %       opf_args(mpc, userfcn, mpopt)
0027 %       opf_args(mpc, A, l, u)
0028 %       opf_args(mpc, A, l, u, mpopt)
0029 %       opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw)
0030 %       opf_args(mpc, A, l, u, mpopt, N, fparm, H, Cw, z0, zl, zu)
0031 %
0032 %       opf_args(baseMVA, bus, gen, branch, areas, gencost)
0033 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, mpopt)
0034 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt)
0035 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u)
0036 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, mpopt)
0037 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ...
0038 %                                   mpopt, N, fparm, H, Cw)
0039 %       opf_args(baseMVA, bus, gen, branch, areas, gencost, A, l, u, ...
0040 %                                   mpopt, N, fparm, H, Cw, z0, zl, zu)
0041 %
0042 %   The data for the problem can be specified in one of three ways:
0043 %   (1) a string (mpc) containing the file name of a MATPOWER case
0044 %     which defines the data matrices baseMVA, bus, gen, branch, and
0045 %     gencost (areas is not used at all, it is only included for
0046 %     backward compatibility of the API).
0047 %   (2) a struct (mpc) containing the data matrices as fields.
0048 %   (3) the individual data matrices themselves.
0049 %
0050 %   The optional user parameters for user constraints (A, l, u), user costs
0051 %   (N, fparm, H, Cw), user variable initializer (z0), and user variable
0052 %   limits (zl, zu) can also be specified as fields in a case struct,
0053 %   either passed in directly or defined in a case file referenced by name.
0054 %
0055 %   When specified, A, l, u represent additional linear constraints on the
0056 %   optimization variables, l <= A*[x; z] <= u. If the user specifies an A
0057 %   matrix that has more columns than the number of "x" (OPF) variables,
0058 %   then there are extra linearly constrained "z" variables. For an
0059 %   explanation of the formulation used and instructions for forming the
0060 %   A matrix, see the manual.
0061 %
0062 %   A generalized cost on all variables can be applied if input arguments
0063 %   N, fparm, H and Cw are specified.  First, a linear transformation
0064 %   of the optimization variables is defined by means of r = N * [x; z].
0065 %   Then, to each element of r a function is applied as encoded in the
0066 %   fparm matrix (see manual). If the resulting vector is named w,
0067 %   then H and Cw define a quadratic cost on w: (1/2)*w'*H*w + Cw * w .
0068 %   H and N should be sparse matrices and H should also be symmetric.
0069 %
0070 %   The optional mpopt vector specifies MATPOWER options. See MPOPTION
0071 %   for details and default values.
0072 
0073 %   MATPOWER
0074 %   $Id: opf_args.m,v 1.9 2010/04/26 19:45:25 ray Exp $
0075 %   by Ray Zimmerman, PSERC Cornell
0076 %   and Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales
0077 %   Copyright (c) 1996-2010 by Power System Engineering Research Center (PSERC)
0078 %
0079 %   This file is part of MATPOWER.
0080 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0081 %
0082 %   MATPOWER is free software: you can redistribute it and/or modify
0083 %   it under the terms of the GNU General Public License as published
0084 %   by the Free Software Foundation, either version 3 of the License,
0085 %   or (at your option) any later version.
0086 %
0087 %   MATPOWER is distributed in the hope that it will be useful,
0088 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
0089 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0090 %   GNU General Public License for more details.
0091 %
0092 %   You should have received a copy of the GNU General Public License
0093 %   along with MATPOWER. If not, see <http://www.gnu.org/licenses/>.
0094 %
0095 %   Additional permission under GNU GPL version 3 section 7
0096 %
0097 %   If you modify MATPOWER, or any covered work, to interface with
0098 %   other modules (such as MATLAB code and MEX-files) available in a
0099 %   MATLAB(R) or comparable environment containing parts covered
0100 %   under other licensing terms, the licensors of MATPOWER grant
0101 %   you additional permission to convey the resulting work.
0102 
0103 if nargout == 2
0104   want_mpc = 1;
0105 else
0106   want_mpc = 0;
0107 end
0108 userfcn = [];
0109 if ischar(baseMVA) || isstruct(baseMVA)  %% passing filename or struct
0110   %---- opf(baseMVA,  bus,     gen, branch, areas, gencost, Au,    lbu, ubu, mpopt, N,  fparm, H, Cw, z0, zl, zu)
0111   % 12  opf(casefile, Au,      lbu, ubu,    mpopt, N,       fparm, H,   Cw,  z0,    zl, zu)
0112   % 9   opf(casefile, Au,      lbu, ubu,    mpopt, N,       fparm, H,   Cw)
0113   % 5   opf(casefile, Au,      lbu, ubu,    mpopt)
0114   % 4   opf(casefile, Au,      lbu, ubu)
0115   % 3   opf(casefile, userfcn, mpopt)
0116   % 2   opf(casefile, mpopt)
0117   % 1   opf(casefile)
0118   if any(nargin == [1, 2, 3, 4, 5, 9, 12])
0119     casefile = baseMVA;
0120     if nargin == 12
0121       zu    = fparm;
0122       zl    = N;
0123       z0    = mpopt;
0124       Cw    = ubu;
0125       H     = lbu;
0126       fparm = Au;
0127       N     = gencost;
0128       mpopt = areas;
0129       ubu   = branch;
0130       lbu   = gen;
0131       Au    = bus;
0132     elseif nargin == 9
0133       zu    = [];
0134       zl    = [];
0135       z0    = [];
0136       Cw    = ubu;
0137       H     = lbu;
0138       fparm = Au;
0139       N     = gencost;
0140       mpopt = areas;
0141       ubu   = branch;
0142       lbu   = gen;
0143       Au    = bus;
0144     elseif nargin == 5
0145       zu    = [];
0146       zl    = [];
0147       z0    = [];
0148       Cw    = [];
0149       H     = sparse(0,0);
0150       fparm = [];
0151       N     = sparse(0,0);
0152       mpopt = areas;
0153       ubu   = branch;
0154       lbu   = gen;
0155       Au    = bus;
0156     elseif nargin == 4
0157       zu    = [];
0158       zl    = [];
0159       z0    = [];
0160       Cw    = [];
0161       H     = sparse(0,0);
0162       fparm = [];
0163       N     = sparse(0,0);
0164       mpopt = mpoption;
0165       ubu   = branch;
0166       lbu   = gen;
0167       Au    = bus;
0168     elseif nargin == 3
0169       userfcn = bus;
0170       zu    = [];
0171       zl    = [];
0172       z0    = [];
0173       Cw    = [];
0174       H     = sparse(0,0);
0175       fparm = [];
0176       N     = sparse(0,0);
0177       mpopt = gen;
0178       ubu   = [];
0179       lbu   = [];
0180       Au    = sparse(0,0);
0181     elseif nargin == 2
0182       zu    = [];
0183       zl    = [];
0184       z0    = [];
0185       Cw    = [];
0186       H     = sparse(0,0);
0187       fparm = [];
0188       N     = sparse(0,0);
0189       mpopt = bus;
0190       ubu   = [];
0191       lbu   = [];
0192       Au    = sparse(0,0);
0193     elseif nargin == 1
0194       zu    = [];
0195       zl    = [];
0196       z0    = [];
0197       Cw    = [];
0198       H     = sparse(0,0);
0199       fparm = [];
0200       N     = sparse(0,0);
0201       mpopt = mpoption;
0202       ubu   = [];
0203       lbu   = [];
0204       Au    = sparse(0,0);
0205     end
0206   else
0207     error('opf_args.m: Incorrect input parameter order, number or type');
0208   end
0209   mpc = loadcase(casefile);
0210   [baseMVA, bus, gen, branch, gencost] = ...
0211     deal(mpc.baseMVA, mpc.bus, mpc.gen, mpc.branch, mpc.gencost);
0212   if isfield(mpc, 'areas')
0213     areas = mpc.areas;
0214   else
0215     areas = [];
0216   end
0217   if isempty(Au) && isfield(mpc, 'A')
0218     [Au, lbu, ubu] = deal(mpc.A, mpc.l, mpc.u);
0219   end
0220   if isempty(N) && isfield(mpc, 'N')             %% these two must go together
0221     [N, Cw] = deal(mpc.N, mpc.Cw);
0222   end
0223   if isempty(H) && isfield(mpc, 'H')             %% will default to zeros
0224     H = mpc.H;
0225   end
0226   if isempty(fparm) && isfield(mpc, 'fparm')     %% will default to [1 0 0 1]
0227     fparm = mpc.fparm;
0228   end
0229   if isempty(z0) && isfield(mpc, 'z0')
0230     z0 = mpc.z0;
0231   end
0232   if isempty(zl) && isfield(mpc, 'zl')
0233     zl = mpc.zl;
0234   end
0235   if isempty(zu) && isfield(mpc, 'zu')
0236     zu = mpc.zu;
0237   end
0238   if isempty(userfcn) && isfield(mpc, 'userfcn')
0239     userfcn = mpc.userfcn;
0240   end
0241 else    %% passing individual data matrices
0242   %---- opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu)
0243   % 17  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw, z0, zl, zu)
0244   % 14  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt, N, fparm, H, Cw)
0245   % 10  opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu, mpopt)
0246   % 9   opf(baseMVA, bus, gen, branch, areas, gencost, Au,      lbu, ubu)
0247   % 8   opf(baseMVA, bus, gen, branch, areas, gencost, userfcn, mpopt)
0248   % 7   opf(baseMVA, bus, gen, branch, areas, gencost, mpopt)
0249   % 6   opf(baseMVA, bus, gen, branch, areas, gencost)
0250   if any(nargin == [6, 7, 8, 9, 10, 14, 17])
0251     if nargin == 14
0252       zu    = [];
0253       zl    = [];
0254       z0    = [];
0255     elseif nargin == 10
0256       zu    = [];
0257       zl    = [];
0258       z0    = [];
0259       Cw    = [];
0260       H     = sparse(0,0);
0261       fparm = [];
0262       N     = sparse(0,0);
0263     elseif nargin == 9
0264       zu    = [];
0265       zl    = [];
0266       z0    = [];
0267       Cw    = [];
0268       H     = sparse(0,0);
0269       fparm = [];
0270       N     = sparse(0,0);
0271       mpopt = mpoption;
0272     elseif nargin == 8
0273       userfcn = Au;
0274       zu    = [];
0275       zl    = [];
0276       z0    = [];
0277       Cw    = [];
0278       H     = sparse(0,0);
0279       fparm = [];
0280       N     = sparse(0,0);
0281       mpopt = lbu;
0282       ubu   = [];
0283       lbu   = [];
0284       Au    = sparse(0,0);
0285     elseif nargin == 7
0286       zu    = [];
0287       zl    = [];
0288       z0    = [];
0289       Cw    = [];
0290       H     = sparse(0,0);
0291       fparm = [];
0292       N     = sparse(0,0);
0293       mpopt = Au;
0294       ubu   = [];
0295       lbu   = [];
0296       Au    = sparse(0,0);
0297     elseif nargin == 6
0298       zu    = [];
0299       zl    = [];
0300       z0    = [];
0301       Cw    = [];
0302       H     = sparse(0,0);
0303       fparm = [];
0304       N     = sparse(0,0);
0305       mpopt = mpoption;
0306       ubu   = [];
0307       lbu   = [];
0308       Au    = sparse(0,0);
0309     end
0310   else
0311     error('opf_args.m: Incorrect input parameter order, number or type');
0312   end
0313   if want_mpc
0314     mpc = struct(             ...
0315             'baseMVA',  baseMVA,    ...
0316             'bus',      bus,        ...
0317             'gen',      gen,        ...
0318             'branch',   branch,     ...
0319             'gencost',  gencost    ...
0320     );
0321   end
0322 end
0323 nw = size(N, 1);
0324 if nw
0325   if size(Cw, 1) ~= nw
0326     error('opf_args.m: dimension mismatch between N and Cw in generalized cost parameters');
0327   end
0328   if ~isempty(fparm) && size(fparm, 1) ~= nw
0329     error('opf_args.m: dimension mismatch between N and fparm in generalized cost parameters');
0330   end
0331   if ~isempty(H) && (size(H, 1) ~= nw || size(H, 2) ~= nw)
0332     error('opf_args.m: dimension mismatch between N and H in generalized cost parameters');
0333   end
0334   if size(Au, 1) > 0 && size(N, 2) ~= size(Au, 2)
0335     error('opf_args.m: A and N must have the same number of columns');
0336   end
0337   %% make sure N and H are sparse
0338   if ~issparse(N)
0339     error('opf_args.m: N must be sparse in generalized cost parameters');
0340   end
0341   if ~issparse(H)
0342     error('opf_args.m: H must be sparse in generalized cost parameters');
0343   end
0344 end
0345 if ~issparse(Au)
0346   error('opf_args.m: Au must be sparse');
0347 end
0348 if isempty(mpopt)
0349   mpopt = mpoption;
0350 end
0351 if want_mpc
0352   if ~isempty(areas)
0353     mpc.areas = areas;
0354   end
0355   if ~isempty(Au)
0356     [mpc.A, mpc.l, mpc.u] = deal(Au, lbu, ubu);
0357   end
0358   if ~isempty(N)
0359     [mpc.N, mpc.Cw ] = deal(N, Cw);
0360     if ~isempty(fparm)
0361       mpc.fparm = fparm;
0362     end
0363     if ~isempty(H)
0364       mpc.H = H;
0365     end
0366   end
0367   if ~isempty(z0)
0368     mpc.z0 = z0;
0369   end
0370   if ~isempty(zl)
0371     mpc.zl = zl;
0372   end
0373   if ~isempty(zu)
0374     mpc.zu = zu;
0375   end
0376   if ~isempty(userfcn)
0377     mpc.userfcn = userfcn;
0378   end
0379   baseMVA = mpc;
0380   bus = mpopt;
0381 end

Generated on Mon 26-Jan-2015 14:56:45 by m2html © 2005