Home > matpower4.0 > loadcase.m

loadcase

PURPOSE ^

LOADCASE Load .m or .mat case files or data struct in MATPOWER format.

SYNOPSIS ^

function [baseMVA, bus, gen, branch, areas, gencost, info] = loadcase(casefile)

DESCRIPTION ^

LOADCASE   Load .m or .mat case files or data struct in MATPOWER format.

   [BASEMVA, BUS, GEN, BRANCH, AREAS, GENCOST] = LOADCASE(CASEFILE)
   [BASEMVA, BUS, GEN, BRANCH, GENCOST] = LOADCASE(CASEFILE)
   [BASEMVA, BUS, GEN, BRANCH] = LOADCASE(CASEFILE)
   MPC = LOADCASE(CASEFILE)

   Returns the individual data matrices or a struct containing them as fields.

   Here CASEFILE is either (1) a struct containing the fields baseMVA,
   bus, gen, branch and, optionally, areas and/or gencost, or (2) a string
   containing the name of the file. If CASEFILE contains the extension
   '.mat' or '.m', then the explicit file is searched. If CASEFILE contains
   no extension, then LOADCASE looks for a MAT-file first, then for an
   M-file.  If the file does not exist or doesn't define all required
   matrices, the routine aborts with an appropriate error message.
   Alternatively, it can be called with the syntax:

   [BASEMVA, BUS, GEN, BRANCH, AREAS, GENCOST, INFO] = LOADCASE(CASEFILE)
   [MPC, INFO] = LOADCASE(CASEFILE)

   In this case, the function will not abort, but INFO will contain an exit
   code as follows:

       0:  all variables successfully defined
       1:  input argument is not a string or struct
       2:  specified extension-less file name does not exist in search path
       3:  specified MAT-file does not exist in search path
       4:  specified M-file does not exist in search path
       5:  specified file fails to define all matrices or contains syntax err

   If the input data is from an M-file or MAT-file defining individual
   data matrices, or from a struct with out a 'version' field whose
   GEN matrix has fewer than 21 columns, then it is assumed to be a
   MATPOWER case file in version 1 format, and will be converted to
   version 2 format.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function [baseMVA, bus, gen, branch, areas, gencost, info] = loadcase(casefile)
0002 %LOADCASE   Load .m or .mat case files or data struct in MATPOWER format.
0003 %
0004 %   [BASEMVA, BUS, GEN, BRANCH, AREAS, GENCOST] = LOADCASE(CASEFILE)
0005 %   [BASEMVA, BUS, GEN, BRANCH, GENCOST] = LOADCASE(CASEFILE)
0006 %   [BASEMVA, BUS, GEN, BRANCH] = LOADCASE(CASEFILE)
0007 %   MPC = LOADCASE(CASEFILE)
0008 %
0009 %   Returns the individual data matrices or a struct containing them as fields.
0010 %
0011 %   Here CASEFILE is either (1) a struct containing the fields baseMVA,
0012 %   bus, gen, branch and, optionally, areas and/or gencost, or (2) a string
0013 %   containing the name of the file. If CASEFILE contains the extension
0014 %   '.mat' or '.m', then the explicit file is searched. If CASEFILE contains
0015 %   no extension, then LOADCASE looks for a MAT-file first, then for an
0016 %   M-file.  If the file does not exist or doesn't define all required
0017 %   matrices, the routine aborts with an appropriate error message.
0018 %   Alternatively, it can be called with the syntax:
0019 %
0020 %   [BASEMVA, BUS, GEN, BRANCH, AREAS, GENCOST, INFO] = LOADCASE(CASEFILE)
0021 %   [MPC, INFO] = LOADCASE(CASEFILE)
0022 %
0023 %   In this case, the function will not abort, but INFO will contain an exit
0024 %   code as follows:
0025 %
0026 %       0:  all variables successfully defined
0027 %       1:  input argument is not a string or struct
0028 %       2:  specified extension-less file name does not exist in search path
0029 %       3:  specified MAT-file does not exist in search path
0030 %       4:  specified M-file does not exist in search path
0031 %       5:  specified file fails to define all matrices or contains syntax err
0032 %
0033 %   If the input data is from an M-file or MAT-file defining individual
0034 %   data matrices, or from a struct with out a 'version' field whose
0035 %   GEN matrix has fewer than 21 columns, then it is assumed to be a
0036 %   MATPOWER case file in version 1 format, and will be converted to
0037 %   version 2 format.
0038 
0039 %   MATPOWER
0040 %   $Id: loadcase.m,v 1.24 2010/04/26 19:45:25 ray Exp $
0041 %   by Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales
0042 %   and Ray Zimmerman, PSERC Cornell
0043 %   Copyright (c) 1996-2010 by Power System Engineering Research Center (PSERC)
0044 %
0045 %   This file is part of MATPOWER.
0046 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0047 %
0048 %   MATPOWER is free software: you can redistribute it and/or modify
0049 %   it under the terms of the GNU General Public License as published
0050 %   by the Free Software Foundation, either version 3 of the License,
0051 %   or (at your option) any later version.
0052 %
0053 %   MATPOWER is distributed in the hope that it will be useful,
0054 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
0055 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0056 %   GNU General Public License for more details.
0057 %
0058 %   You should have received a copy of the GNU General Public License
0059 %   along with MATPOWER. If not, see <http://www.gnu.org/licenses/>.
0060 %
0061 %   Additional permission under GNU GPL version 3 section 7
0062 %
0063 %   If you modify MATPOWER, or any covered work, to interface with
0064 %   other modules (such as MATLAB code and MEX-files) available in a
0065 %   MATLAB(R) or comparable environment containing parts covered
0066 %   under other licensing terms, the licensors of MATPOWER grant
0067 %   you additional permission to convey the resulting work.
0068 
0069 info = 0;
0070 if nargout < 3
0071     return_as_struct = true;
0072 else
0073     return_as_struct = false;
0074 end
0075 if nargout >= 5
0076     expect_gencost = true;
0077     if nargout > 5
0078         expect_areas = true;
0079     else 
0080         expect_areas = false;
0081     end
0082 else
0083     expect_gencost = false;
0084     expect_areas = false;
0085 end
0086 
0087 %%-----  read data into struct  -----
0088 if ischar(casefile)
0089     %% check for explicit extension
0090     l = length(casefile);
0091     if l > 2
0092         if strcmp(casefile(l-1:l), '.m')
0093             rootname = casefile(1:l-2);
0094             extension = '.m';
0095         elseif l > 4
0096             if strcmp(casefile(l-3:l), '.mat')
0097                 rootname = casefile(1:l-4);
0098                 extension = '.mat';
0099             end
0100         end
0101     end
0102 
0103     %% set extension if not specified explicitly
0104     if ~exist('rootname', 'var')
0105         rootname = casefile;
0106         if exist([casefile '.mat'], 'file') == 2
0107             extension = '.mat';
0108         elseif exist([casefile '.m'], 'file') == 2
0109             extension = '.m';
0110         else
0111             info = 2;
0112         end
0113     end
0114     
0115     %% attempt to read file
0116     if info == 0
0117         if strcmp(extension,'.mat')         %% from MAT file
0118             try
0119                 s = load(rootname);
0120                 if isfield(s, 'mpc')        %% it's a struct
0121                     s = s.mpc;
0122                 else                        %% individual data matrices
0123                     s.version = '1';
0124                 end
0125             catch
0126                 info = 3;
0127             end
0128         elseif strcmp(extension,'.m')       %% from M file
0129             try                             %% assume it returns a struct
0130                 s = feval(rootname);
0131             catch
0132                 info = 4;
0133             end
0134             if info == 0 && ~isstruct(s)    %% if not try individual data matrices
0135                 clear s;
0136                 s.version = '1';
0137                 if expect_gencost
0138                     try
0139                         [s.baseMVA, s.bus, s.gen, s.branch, ...
0140                             s.areas, s.gencost] = feval(rootname);
0141                     catch
0142                         info = 4;
0143                     end
0144                 else
0145                     if return_as_struct
0146                         try
0147                             [s.baseMVA, s.bus, s.gen, s.branch, ...
0148                                 s.areas, s.gencost] = feval(rootname);
0149                         catch
0150                             try
0151                                 [s.baseMVA, s.bus, s.gen, s.branch] = feval(rootname);
0152                             catch
0153                                 info = 4;
0154                             end
0155                         end
0156                     else
0157                         try
0158                             [s.baseMVA, s.bus, s.gen, s.branch] = feval(rootname);
0159                         catch
0160                             info = 4;
0161                         end
0162                     end
0163                 end
0164             end
0165             if info == 4 && exist([rootname '.m'], 'file') == 2
0166                 info = 5;
0167                 err5 = lasterr;
0168             end
0169         end
0170     end
0171 elseif isstruct(casefile)
0172     s = casefile;
0173 else
0174     info = 1;
0175 end
0176 
0177 %%-----  check contents of struct  -----
0178 if info == 0
0179     %% check for required fields
0180     if ~( isfield(s,'baseMVA') && isfield(s,'bus') && ...
0181             isfield(s,'gen') && isfield(s,'branch') ) || ...
0182             ( expect_gencost && ~isfield(s, 'gencost') ) || ...
0183             ( expect_areas &&   ~isfield(s,'areas') )
0184         info = 5;           %% missing some expected fields
0185         err5 = 'missing data';
0186     else
0187         %% remove empty areas if not needed
0188         if isfield(s, 'areas') && isempty(s.areas) && ~expect_areas
0189             s = rmfield(s, 'areas');
0190         end
0191 
0192         %% all fields present, copy to mpc
0193         mpc = s;
0194         if ~isfield(mpc, 'version') %% hmm, struct with no 'version' field
0195             if size(mpc.gen, 2) < 21    %% version 2 has 21 or 25 cols
0196                 mpc.version = '1';
0197             else
0198                 mpc.version = '2';
0199             end
0200         end
0201         if strcmp(mpc.version, '1')
0202             % convert from version 1 to version 2
0203             [mpc.gen, mpc.branch] = mpc_1to2(mpc.gen, mpc.branch);
0204             mpc.version = '2';
0205         end
0206     end
0207 end
0208 
0209 %%-----  define output variables  -----
0210 if return_as_struct
0211     bus = info;
0212 end
0213 
0214 if info == 0    %% no errors
0215     if return_as_struct
0216         baseMVA = mpc;
0217     else
0218         baseMVA = mpc.baseMVA;
0219         bus     = mpc.bus;
0220         gen     = mpc.gen;
0221         branch  = mpc.branch;
0222         if expect_gencost
0223             if expect_areas
0224                 areas   = mpc.areas;
0225                 gencost = mpc.gencost;
0226             else
0227                 areas = mpc.gencost;
0228             end
0229         end
0230     end
0231 else            %% we have a problem captain
0232     if nargout == 2 || nargout == 7   %% return error code
0233         if return_as_struct
0234             baseMVA = struct([]);
0235         else
0236             baseMVA = []; bus = []; gen = []; branch = [];
0237             areas = []; gencost = [];
0238         end
0239     else                                            %% die on error
0240         switch info
0241             case 1,
0242                 error('loadcase: input arg should be a struct or a string containing a filename');
0243             case 2,
0244                 error('loadcase: specified case not in MATLAB''s search path');
0245             case 3,
0246                 error('loadcase: specified MAT file does not exist');
0247             case 4,
0248                 error('loadcase: specified M file does not exist');
0249             case 5,
0250                 error('loadcase: syntax error or undefined data matrix(ices) in the file\n%s', err5);
0251             otherwise,
0252                 error('loadcase: unknown error');
0253         end
0254     end
0255 end
0256 
0257 
0258 function [gen, branch] = mpc_1to2(gen, branch)
0259 
0260 %% define named indices into bus, gen, branch matrices
0261 [GEN_BUS, PG, QG, QMAX, QMIN, VG, MBASE, GEN_STATUS, PMAX, PMIN, ...
0262     MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN, PC1, PC2, QC1MIN, QC1MAX, ...
0263     QC2MIN, QC2MAX, RAMP_AGC, RAMP_10, RAMP_30, RAMP_Q, APF] = idx_gen;
0264 [F_BUS, T_BUS, BR_R, BR_X, BR_B, RATE_A, RATE_B, RATE_C, ...
0265     TAP, SHIFT, BR_STATUS, PF, QF, PT, QT, MU_SF, MU_ST, ...
0266     ANGMIN, ANGMAX, MU_ANGMIN, MU_ANGMAX] = idx_brch;
0267 
0268 %%-----  gen  -----
0269 %% use the version 1 values for column names
0270 if size(gen, 2) > APF
0271     error('mpc_1to2: gen matrix appears to already be in version 2 format');
0272 end
0273 shift = MU_PMAX - PMIN - 1;
0274 tmp = num2cell([MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN] - shift);
0275 [MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN] = deal(tmp{:});
0276 
0277 %% add extra columns to gen
0278 tmp = zeros(size(gen, 1), shift);
0279 if size(gen, 2) >= MU_QMIN
0280     gen = [ gen(:, 1:PMIN) tmp gen(:, MU_PMAX:MU_QMIN) ];
0281 else
0282     gen = [ gen(:, 1:PMIN) tmp ];
0283 end
0284 
0285 %%-----  branch  -----
0286 %% use the version 1 values for column names
0287 shift = PF - BR_STATUS - 1;
0288 tmp = num2cell([PF, QF, PT, QT, MU_SF, MU_ST] - shift);
0289 [PF, QF, PT, QT, MU_SF, MU_ST] = deal(tmp{:});
0290 
0291 %% add extra columns to branch
0292 tmp = ones(size(branch, 1), 1) * [-360 360];
0293 tmp2 = zeros(size(branch, 1), 2);
0294 if size(branch, 2) >= MU_ST
0295     branch = [ branch(:, 1:BR_STATUS) tmp branch(:, PF:MU_ST) tmp2 ];
0296 elseif size(branch, 2) >= QT
0297     branch = [ branch(:, 1:BR_STATUS) tmp branch(:, PF:QT) ];
0298 else
0299     branch = [ branch(:, 1:BR_STATUS) tmp ];
0300 end

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