makeAvl

MAKEAVL Construct linear constraints for constant power factor var loads.
   [AVL, LVL, UVL, IVL]  = MAKEAVL(MPC)
   [AVL, LVL, UVL, IVL]  = MAKEAVL(BASEMVA, GEN) (deprecated)

   Constructs parameters for the following linear constraint enforcing a
   constant power factor constraint for dispatchable loads.

        LVL <= AVL * [Pg; Qg] <= UVL

   IVL is the vector of indices of generators representing variable loads.

   Example:
       [Avl, lvl, uvl, ivl]  = makeAvl(mpc);
       [Avl, lvl, uvl, ivl]  = makeAvl(baseMVA, gen);  %% deprecated

0001 function [Avl, lvl, uvl, ivl]  = makeAvl(baseMVA, gen)
0002 %MAKEAVL Construct linear constraints for constant power factor var loads.
0003 %   [AVL, LVL, UVL, IVL]  = MAKEAVL(MPC)
0004 %   [AVL, LVL, UVL, IVL]  = MAKEAVL(BASEMVA, GEN) (deprecated)
0005 %
0006 %   Constructs parameters for the following linear constraint enforcing a
0007 %   constant power factor constraint for dispatchable loads.
0008 %
0009 %        LVL <= AVL * [Pg; Qg] <= UVL
0010 %
0011 %   IVL is the vector of indices of generators representing variable loads.
0012 %
0013 %   Example:
0014 %       [Avl, lvl, uvl, ivl]  = makeAvl(mpc);
0015 %       [Avl, lvl, uvl, ivl]  = makeAvl(baseMVA, gen);  %% deprecated
0016 
0017 %   MATPOWER
0018 %   Copyright (c) 1996-2018, Power Systems Engineering Research Center (PSERC)
0019 %   by Ray Zimmerman, PSERC Cornell
0020 %   and Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Nacional de Colombia
0021 %
0022 %   This file is part of MATPOWER.
0023 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0024 %   See https://matpower.org for more info.
0025 
0026 %% define named indices into data matrices
0027 [GEN_BUS, PG, QG, QMAX, QMIN, VG, MBASE, GEN_STATUS, PMAX, PMIN, ...
0028     MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN, PC1, PC2, QC1MIN, QC1MAX, ...
0029     QC2MIN, QC2MAX, RAMP_AGC, RAMP_10, RAMP_30, RAMP_Q, APF] = idx_gen;
0030 
0031 if nargin < 2
0032     mpc = baseMVA;
0033     baseMVA = mpc.baseMVA;
0034     gen = mpc.gen;
0035 else
0036     mpc = [];
0037 end
0038 
0039 %% data dimensions
0040 ng = size(gen, 1);      %% number of dispatchable injections
0041 Pg   = gen(:, PG) / baseMVA;
0042 Qg   = gen(:, QG) / baseMVA;
0043 Pmin = gen(:, PMIN) / baseMVA;
0044 Qmin = gen(:, QMIN) / baseMVA;
0045 Qmax = gen(:, QMAX) / baseMVA;
0046 
0047 
0048 % Find out if any of these "generators" are actually dispatchable loads.
0049 % (see 'help isload' for details on what constitutes a dispatchable load)
0050 % Dispatchable loads are modeled as generators with an added constant
0051 % power factor constraint. The power factor is derived from the original
0052 % value of Pmin and either Qmin (for inductive loads) or Qmax (for capacitive
0053 % loads). If both Qmin and Qmax are zero, this implies a unity power factor
0054 % without the need for an additional constraint.
0055 
0056 
0057 ivl = find( isload(gen) & (Qmin ~= 0 | Qmax ~= 0) );
0058 nvl  = size(ivl, 1);  %% number of dispatchable loads
0059 
0060 %% at least one of the Q limits must be zero (corresponding to Pmax == 0)
0061 if any( Qmin(ivl) ~= 0 & Qmax(ivl) ~= 0 )
0062     if isempty(mpc)
0063         s = '';
0064     else
0065         k = find(Qmin(ivl) ~= 0 & Qmax(ivl) ~= 0);
0066         if isfield(mpc, 'order') && mpc.order.state == 'i'
0067             gidx = mpc.order.gen.i2e(ivl(k));
0068         else
0069             gidx = ivl(k);
0070         end
0071         s = sprintf('Invalid Q limits for dispatchable load in row %d of gen matrix\n', gidx);
0072     end
0073     error('makeAvl: Either Qmin or Qmax must be equal to zero for each dispatchable load.\n%s', s);
0074 end
0075 
0076 % Initial values of PG and QG must be consistent with specified power factor
0077 % This is to prevent a user from unknowingly using a case file which would
0078 % have defined a different power factor constraint under a previous version
0079 % which used PG and QG to define the power factor.
0080 Qlim = (Qmin(ivl) == 0) .* Qmax(ivl) + ...
0081     (Qmax(ivl) == 0) .* Qmin(ivl);
0082 if any( abs( Qg(ivl) - Pg(ivl) .* Qlim ./ Pmin(ivl) ) > 1e-6 )
0083     if isempty(mpc)
0084         s = '';
0085     else
0086         k = find(abs( Qg(ivl) - Pg(ivl) .* Qlim ./ Pmin(ivl) ) > 1e-6);
0087         if isfield(mpc, 'order') && mpc.order.state == 'i'
0088             gidx = mpc.order.gen.i2e(ivl(k));
0089         else
0090             gidx = ivl(k);
0091         end
0092         s = sprintf('QG for dispatchable load in row %d of gen matrix must be PG * %g\n', [gidx Qlim ./ Pmin(ivl)]');
0093     end
0094     error('makeAvl: %s\n         %s\n         %s\n         %s\n%s', ...
0095         'For a dispatchable load, PG and QG must be consistent', ...
0096         'with the power factor defined by PMIN and the relevant', ...
0097         '(non-zero) QMIN or QMAX limit.', ...
0098         'Note: Setting PG = QG = 0 satisfies this condition.', s);
0099 end
0100 
0101 % make Avl, lvl, uvl, for lvl <= Avl * [Pg; Qg] <= uvl
0102 if nvl > 0
0103   xx = Pmin(ivl);
0104   yy = Qlim;
0105   pftheta = atan2(yy, xx);
0106   pc = sin(pftheta);
0107   qc = -cos(pftheta);
0108   ii = [ (1:nvl)'; (1:nvl)' ];
0109   jj = [ ivl; ivl+ng ];
0110   Avl = sparse(ii, jj, [pc; qc], nvl, 2*ng);
0111   lvl = zeros(nvl, 1);
0112   uvl = lvl;
0113 else
0114   Avl = sparse(0, 2*ng);
0115   lvl =[];
0116   uvl =[];
0117 end