Home > matpower5.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 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.

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

Generated on Mon 26-Jan-2015 15:21:31 by m2html © 2005