loadcase

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 following syntax, though this
   option is now deprecated and will be removed in a future version:

   [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.

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 %
0019 %   Alternatively, it can be called with the following syntax, though this
0020 %   option is now deprecated and will be removed in a future version:
0021 %
0022 %   [BASEMVA, BUS, GEN, BRANCH, AREAS, GENCOST, INFO] = LOADCASE(CASEFILE)
0023 %   [MPC, INFO] = LOADCASE(CASEFILE)
0024 %
0025 %   In this case, the function will not abort, but INFO will contain an exit
0026 %   code as follows:
0027 %
0028 %       0:  all variables successfully defined
0029 %       1:  input argument is not a string or struct
0030 %       2:  specified extension-less file name does not exist in search path
0031 %       3:  specified MAT-file does not exist in search path
0032 %       4:  specified M-file does not exist in search path
0033 %       5:  specified file fails to define all matrices or contains syntax err
0034 %
0035 %   If the input data is from an M-file or MAT-file defining individual
0036 %   data matrices, or from a struct with out a 'version' field whose
0037 %   GEN matrix has fewer than 21 columns, then it is assumed to be a
0038 %   MATPOWER case file in version 1 format, and will be converted to
0039 %   version 2 format.
0040 
0041 %   MATPOWER
0042 %   Copyright (c) 1996-2015 by Power System Engineering Research Center (PSERC)
0043 %   by Carlos E. Murillo-Sanchez, PSERC Cornell & Universidad Autonoma de Manizales
0044 %   and Ray Zimmerman, PSERC Cornell
0045 %
0046 %   $Id: loadcase.m 2644 2015-03-11 19:34:22Z ray $
0047 %
0048 %   This file is part of MATPOWER.
0049 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0050 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0051 
0052 info = 0;
0053 if nargout < 3
0054     return_as_struct = true;
0055 else
0056     return_as_struct = false;
0057 end
0058 if nargout >= 5
0059     expect_gencost = true;
0060     if nargout > 5
0061         expect_areas = true;
0062     else 
0063         expect_areas = false;
0064     end
0065 else
0066     expect_gencost = false;
0067     expect_areas = false;
0068 end
0069 
0070 %%-----  read data into struct  -----
0071 if ischar(casefile)
0072     [pathstr, fname, ext] = fileparts(casefile);
0073     if isempty(ext)
0074         if exist(fullfile(pathstr, [fname '.mat']), 'file') == 2
0075             ext = '.mat';
0076         elseif exist(fullfile(pathstr, [fname '.m']), 'file') == 2
0077             ext = '.m';
0078         else
0079             info = 2;
0080         end
0081     end
0082     
0083     %% attempt to read file
0084     if info == 0
0085         if strcmp(ext,'.mat')       %% from MAT file
0086             try
0087                 s = load(fullfile(pathstr, fname));
0088                 if isfield(s, 'mpc')    %% it's a struct
0089                     s = s.mpc;
0090                 else                    %% individual data matrices
0091                     s.version = '1';
0092                 end
0093             catch
0094                 info = 3;
0095             end
0096         elseif strcmp(ext,'.m')     %% from M file
0097             if ~isempty(pathstr)
0098                 cwd = cd;           %% save working directory to string
0099                 cd(pathstr);        %% cd to specified directory
0100             end
0101             try                             %% assume it returns a struct
0102                 s = feval(fname);
0103             catch
0104                 info = 4;
0105             end
0106             if info == 0 && ~isstruct(s)    %% if not try individual data matrices
0107                 clear s;
0108                 s.version = '1';
0109                 if expect_gencost
0110                     try
0111                         [s.baseMVA, s.bus, s.gen, s.branch, ...
0112                             s.areas, s.gencost] = feval(fname);
0113                     catch
0114                         info = 4;
0115                     end
0116                 else
0117                     if return_as_struct
0118                         try
0119                             [s.baseMVA, s.bus, s.gen, s.branch, ...
0120                                 s.areas, s.gencost] = feval(fname);
0121                         catch
0122                             try
0123                                 [s.baseMVA, s.bus, s.gen, s.branch] = feval(fname);
0124                             catch
0125                                 info = 4;
0126                             end
0127                         end
0128                     else
0129                         try
0130                             [s.baseMVA, s.bus, s.gen, s.branch] = feval(fname);
0131                         catch
0132                             info = 4;
0133                         end
0134                     end
0135                 end
0136             end
0137             if info == 4 && exist(fullfile(pathstr, [fname '.m']), 'file') == 2
0138                 info = 5;
0139                 err5 = lasterr;
0140             end
0141             if ~isempty(pathstr)    %% change working directory back to original
0142                 cd(cwd);
0143             end
0144         end
0145     end
0146 elseif isstruct(casefile)
0147     s = casefile;
0148 else
0149     info = 1;
0150 end
0151 
0152 %%-----  check contents of struct  -----
0153 if info == 0
0154     %% check for required fields
0155     if expect_areas && ~isfield(s,'areas')
0156         s.areas = [];   %% add empty missing areas if needed for output
0157     end
0158     if ~( isfield(s,'baseMVA') && isfield(s,'bus') && ...
0159             isfield(s,'gen') && isfield(s,'branch') ) || ...
0160             ( expect_gencost && ~isfield(s, 'gencost') )
0161         info = 5;           %% missing some expected fields
0162         err5 = 'missing data';
0163     else
0164         %% remove empty areas if not needed
0165         if isfield(s, 'areas') && isempty(s.areas) && ~expect_areas
0166             s = rmfield(s, 'areas');
0167         end
0168 
0169         %% all fields present, copy to mpc
0170         mpc = s;
0171         if ~isfield(mpc, 'version') %% hmm, struct with no 'version' field
0172             if size(mpc.gen, 2) < 21    %% version 2 has 21 or 25 cols
0173                 mpc.version = '1';
0174             else
0175                 mpc.version = '2';
0176             end
0177         end
0178         if strcmp(mpc.version, '1')
0179             % convert from version 1 to version 2
0180             [mpc.gen, mpc.branch] = mpc_1to2(mpc.gen, mpc.branch);
0181             mpc.version = '2';
0182         end
0183     end
0184 end
0185 
0186 %%-----  define output variables  -----
0187 if return_as_struct
0188     bus = info;
0189 end
0190 
0191 if info == 0    %% no errors
0192     if return_as_struct
0193         baseMVA = mpc;
0194     else
0195         baseMVA = mpc.baseMVA;
0196         bus     = mpc.bus;
0197         gen     = mpc.gen;
0198         branch  = mpc.branch;
0199         if expect_gencost
0200             if expect_areas
0201                 areas   = mpc.areas;
0202                 gencost = mpc.gencost;
0203             else
0204                 areas = mpc.gencost;
0205             end
0206         end
0207     end
0208 else            %% we have a problem captain
0209     if nargout == 2 || nargout == 7   %% return error code
0210         if return_as_struct
0211             baseMVA = struct([]);
0212         else
0213             baseMVA = []; bus = []; gen = []; branch = [];
0214             areas = []; gencost = [];
0215         end
0216     else                                            %% die on error
0217         switch info
0218             case 1,
0219                 error('loadcase: input arg should be a struct or a string containing a filename');
0220             case 2,
0221                 error('loadcase: specified case not in MATLAB''s search path');
0222             case 3,
0223                 error('loadcase: specified MAT file does not exist');
0224             case 4,
0225                 error('loadcase: specified M file does not exist');
0226             case 5,
0227                 error('loadcase: syntax error or undefined data matrix(ices) in the file\n%s', err5);
0228             otherwise,
0229                 error('loadcase: unknown error');
0230         end
0231     end
0232 end
0233 
0234 
0235 function [gen, branch] = mpc_1to2(gen, branch)
0236 
0237 %% define named indices into bus, gen, branch matrices
0238 [GEN_BUS, PG, QG, QMAX, QMIN, VG, MBASE, GEN_STATUS, PMAX, PMIN, ...
0239     MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN, PC1, PC2, QC1MIN, QC1MAX, ...
0240     QC2MIN, QC2MAX, RAMP_AGC, RAMP_10, RAMP_30, RAMP_Q, APF] = idx_gen;
0241 [F_BUS, T_BUS, BR_R, BR_X, BR_B, RATE_A, RATE_B, RATE_C, ...
0242     TAP, SHIFT, BR_STATUS, PF, QF, PT, QT, MU_SF, MU_ST, ...
0243     ANGMIN, ANGMAX, MU_ANGMIN, MU_ANGMAX] = idx_brch;
0244 
0245 %%-----  gen  -----
0246 %% use the version 1 values for column names
0247 if size(gen, 2) > APF
0248     error('mpc_1to2: gen matrix appears to already be in version 2 format');
0249 end
0250 shift = MU_PMAX - PMIN - 1;
0251 tmp = num2cell([MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN] - shift);
0252 [MU_PMAX, MU_PMIN, MU_QMAX, MU_QMIN] = deal(tmp{:});
0253 
0254 %% add extra columns to gen
0255 tmp = zeros(size(gen, 1), shift);
0256 if size(gen, 2) >= MU_QMIN
0257     gen = [ gen(:, 1:PMIN) tmp gen(:, MU_PMAX:MU_QMIN) ];
0258 else
0259     gen = [ gen(:, 1:PMIN) tmp ];
0260 end
0261 
0262 %%-----  branch  -----
0263 %% use the version 1 values for column names
0264 shift = PF - BR_STATUS - 1;
0265 tmp = num2cell([PF, QF, PT, QT, MU_SF, MU_ST] - shift);
0266 [PF, QF, PT, QT, MU_SF, MU_ST] = deal(tmp{:});
0267 
0268 %% add extra columns to branch
0269 tmp = ones(size(branch, 1), 1) * [-360 360];
0270 tmp2 = zeros(size(branch, 1), 2);
0271 if size(branch, 2) >= MU_ST
0272     branch = [ branch(:, 1:BR_STATUS) tmp branch(:, PF:MU_ST) tmp2 ];
0273 elseif size(branch, 2) >= QT
0274     branch = [ branch(:, 1:BR_STATUS) tmp branch(:, PF:QT) ];
0275 else
0276     branch = [ branch(:, 1:BR_STATUS) tmp ];
0277 end