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.

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