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