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