psse_parse

PSSE_PARSE  Parses the data from a PSS/E RAW data file.
   DATA = PSSE_PARSE(RECORDS, SECTIONS)
   DATA = PSSE_PARSE(RECORDS, SECTIONS, VERBOSE)
   DATA = PSSE_PARSE(RECORDS, SECTIONS, VERBOSE, REV)
   [DATA, WARNINGS] = PSSE_PARSE(RECORDS, SECTIONS, ...)

   Parses the data from a PSS/E RAW data file (as read by PSSE_READ)
   into a struct.

   Inputs:
       RECORDS : cell array of strings, corresponding to the lines
                 in the RAW file
       SECTIONS : struct array with indexes marking the beginning
                  and end of each section, and the name of the
                  section, fields are:
           first   : index into RECORDS of first line of section
           last    : index into RECORDS of last line of section
           name    : name of the section, as extracted from the
                     END OF ... DATA comments
       VERBOSE      :  1 (default) to display progress info, 0 otherwise
       REV          :  (optional) assume the input file is of this
                       PSS/E revision number, attempts to determine
                       REV from the file by default

   Output(s):
       DATA :  a struct with the following fields, each with two
               sub-fields, 'num' and 'txt' containing the numeric and
               text data read from the file for the corresponding section
           id
           bus
           load
           gen
           shunt
           branch
           trans2
           trans3
           area
           twodc
           swshunt
       WARNINGS :  cell array of strings containing accumulated
                   warning messages

   See also PSSE2MPC, PSSE_READ, PSSE_PARSE_SECTION, PSSE_PARSE_LINE

0001 function [data, warns] = psse_parse(records, sections, verbose, rev)
0002 %PSSE_PARSE  Parses the data from a PSS/E RAW data file.
0003 %   DATA = PSSE_PARSE(RECORDS, SECTIONS)
0004 %   DATA = PSSE_PARSE(RECORDS, SECTIONS, VERBOSE)
0005 %   DATA = PSSE_PARSE(RECORDS, SECTIONS, VERBOSE, REV)
0006 %   [DATA, WARNINGS] = PSSE_PARSE(RECORDS, SECTIONS, ...)
0007 %
0008 %   Parses the data from a PSS/E RAW data file (as read by PSSE_READ)
0009 %   into a struct.
0010 %
0011 %   Inputs:
0012 %       RECORDS : cell array of strings, corresponding to the lines
0013 %                 in the RAW file
0014 %       SECTIONS : struct array with indexes marking the beginning
0015 %                  and end of each section, and the name of the
0016 %                  section, fields are:
0017 %           first   : index into RECORDS of first line of section
0018 %           last    : index into RECORDS of last line of section
0019 %           name    : name of the section, as extracted from the
0020 %                     END OF ... DATA comments
0021 %       VERBOSE      :  1 (default) to display progress info, 0 otherwise
0022 %       REV          :  (optional) assume the input file is of this
0023 %                       PSS/E revision number, attempts to determine
0024 %                       REV from the file by default
0025 %
0026 %   Output(s):
0027 %       DATA :  a struct with the following fields, each with two
0028 %               sub-fields, 'num' and 'txt' containing the numeric and
0029 %               text data read from the file for the corresponding section
0030 %           id
0031 %           bus
0032 %           load
0033 %           gen
0034 %           shunt
0035 %           branch
0036 %           trans2
0037 %           trans3
0038 %           area
0039 %           twodc
0040 %           swshunt
0041 %       WARNINGS :  cell array of strings containing accumulated
0042 %                   warning messages
0043 %
0044 %   See also PSSE2MPC, PSSE_READ, PSSE_PARSE_SECTION, PSSE_PARSE_LINE
0045 
0046 %   MATPOWER
0047 %   Copyright (c) 2014-2016, Power Systems Engineering Research Center (PSERC)
0048 %   by Ray Zimmerman, PSERC Cornell
0049 %   Based on mpreadraw.m, written by: Yujia Zhu, Jan 2014, yzhu54@asu.edu.
0050 %
0051 %   This file is part of MATPOWER.
0052 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0053 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0054 
0055 %% default args
0056 if nargin < 4
0057     rev = 0;
0058     if nargin < 3
0059         verbose = 0;
0060     end
0061 end
0062 defaultrev = 23;
0063 
0064 %% inititialize section counter
0065 s = 1;
0066 warns = {};
0067 
0068 %%-----  case identification data  -----
0069 %% In some files, SBASE is followed by a comment with the REV number such as:
0070 %%  / PSS/E-29.0
0071 %%  / PSS(tm)E-30 RAW
0072 if verbose
0073     if rev
0074         fprintf('Forcing interpretation as PSS/E revision %d\n', rev);
0075     else
0076         fprintf('Attempting to determine PSS/E revision from content.\n');
0077     end
0078     fprintf('Parsing case identification data ...');
0079 end
0080 if rev
0081     warns{end+1} = sprintf('Conversion explicitly using PSS/E revision %d', rev);
0082 end
0083 [d, c] = psse_parse_line(records{1}, 'dfdfff');
0084 nn = length(d);
0085 data.id.IC = d{1};
0086 if isempty(d{2}) || d{2} <= 0
0087     error('ERROR: Probable corrupt file, unable to read a valid SBASE value from the first line.');
0088 else
0089     data.id.SBASE = d{2};
0090 end
0091 if ~isempty(d{3})
0092     data.id.REV = d{3};
0093 else    %% attempt to extract revision from comment
0094     tmp = regexp(c, 'PSS(/|\(tm\))E-(?<rev>\d+)', 'tokens');
0095     if ~isempty(tmp) && size(tmp{1}, 2) == 2
0096         data.id.REV = str2num(tmp{1}{2});
0097     else
0098         data.id.REV = 0;
0099     end
0100 end
0101 if ~isempty(d{4})
0102     data.id.XFRRAT = d{4};
0103 else
0104     data.id.XFRRAT = 0;
0105 end
0106 if ~isempty(d{5})
0107     data.id.NXFRAT = d{5};
0108 else
0109     data.id.NXFRAT = 0;
0110 end
0111 if ~isempty(d{6})
0112     data.id.BASFRQ = d{6};
0113 else
0114     data.id.BASFRQ = 0;
0115 end
0116 data.id.comment0 = c;
0117 data.id.comment1 = records{2};
0118 data.id.comment2 = records{3};
0119 if verbose
0120     if rev
0121         if data.id.REV
0122             fprintf('.. override detected rev %2d w/%2d ... done.\n', data.id.REV, rev);
0123         else
0124             fprintf('...... unknown rev, using rev %2d ... done.\n', rev);
0125         end
0126     else
0127         if data.id.REV
0128             fprintf('......... rev %2d format detected ... done.\n', data.id.REV);
0129         else
0130             fprintf('...... unknown rev, using rev %2d ... done.\n', defaultrev);
0131         end
0132     end
0133 end
0134 if ~rev
0135     if data.id.REV
0136         rev = data.id.REV;      %% use detected value
0137     else
0138         rev = defaultrev;       %% none detected, use default value
0139         data.id.REV = defaultrev;
0140         warns{end+1} = sprintf('Unknown REV, using REV %2d format.', defaultrev);
0141     end
0142 else
0143     data.id.REV = rev;          %% use override value
0144 end
0145 if isempty(data.id.IC) || data.id.IC ~= 0
0146     warns{end+1} = sprintf('IC = %d indicates that this may be a change case, rather than base case\n         PSSE2MPC is NOT designed to handle change cases.', data.id.IC);
0147     if verbose
0148         fprintf('WARNING : %s\n', warns{end});
0149     end
0150 end
0151 s = s + 1;
0152 
0153 %%-----  bus data  -----
0154 if rev < 24         %% includes load data
0155     [data.bus, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0156         'bus', 'ddffffdffsfd');
0157 elseif rev < 31     %% includes fixed shunt data, load separate
0158     [data.bus, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0159         'bus', 'dsfdffddffd');
0160 else                %% fixed shunt and load data separate
0161     [data.bus, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0162         'bus', 'dsfddddffff..');
0163 %       'bus', 'dsfddddffffff');
0164 end
0165 s = s + 1;
0166 
0167 %%-----  load data  -----
0168 if rev >= 24
0169     [data.load, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0170         'load', 'd.d..ffffff...');
0171 %       'load', 'dsdddffffffddd');
0172     s = s + 1;
0173 end
0174 
0175 %%-----  fixed shunt data  -----
0176 if rev > 30     %% fixed shunt data is included in bus data for rev <= 30
0177     [data.shunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0178         'fixed shunt', 'd.dff');
0179 %       'fixed shunt', 'dsdff');
0180     s = s + 1;
0181 end
0182 
0183 %%-----  generator data  -----
0184 [data.gen, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0185     'generator', 'd.fffff.f.....d.ff...........');
0186 %   'generator', 'dsfffffdffffffdfffdfdfdfdfsdf');
0187 s = s + 1;
0188 
0189 %%-----  branch data  -----
0190 if rev <= 27   %% includes transformer ratio, angle
0191     [data.branch, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0192         'branch', 'dd.ffffffffffffd');
0193 %       'branch', 'dddffffffffffffd');
0194 elseif rev < 31
0195     [data.branch, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0196         'branch', 'dd.ffffffffffd');
0197 %       'branch', 'ddsffffffffffdfdfdfdfdf');
0198 else
0199     [data.branch, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0200         'branch', 'dd.ffffffffffd');
0201 %       'branch', 'ddsffffffffffddfdfdfdfdf');
0202 end
0203 s = s + 1;
0204 
0205 %%-----  skip transformer adjustment data  -----
0206 if rev <= 27
0207     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'transformer adjustment');
0208 end
0209 
0210 %%-----  transformer data  -----
0211 if rev > 27
0212     %% PSS/E stores two winding and three winding transformer data in the same
0213     %% section in RAW file. We read in 2 passes, first pass determines the type of
0214     %% each, second pass reads the data.
0215     label = 'transformer';
0216     if ~isempty(sections(s).name) && ~strcmpi(label, sections(s).name)
0217         if verbose > 1
0218             fprintf('-----  WARNING:  Expected section labeled: ''%s''\n', upper(label));
0219             fprintf('-----            Found section labeled:    ''%s''\n', sections(s).name);
0220         end
0221     end
0222 
0223     %% Step 1 : Count and collect transformer types
0224     if verbose
0225         fprintf('Analyzing transformer types ...');
0226     end
0227 
0228     %% estimate max number of transformers by number of lines in section
0229     nt2 = round((sections(s).last - sections(s).first + 1) / 4);
0230     nt3 = round((sections(s).last - sections(s).first + 1) / 5);
0231 
0232     %% initialize indexes for transformer types
0233     idx2 = zeros(nt2, 1);
0234     idx3 = zeros(nt3, 1);
0235 
0236     %% set up counters
0237     i = sections(s).first;      %% initialize record index
0238     i2 = 0;
0239     i3 = 0;
0240 
0241     while i <= sections(s).last
0242         %% determine transformer type
0243         pat = '[^''",\s/]+\s*(,|\s)\s*[^''",\s/]+\s*(,|\s)\s*([^''",\s/]+)';
0244         m = regexp(records{i}, pat, 'tokens', 'once');
0245         if length(m) ~= 3
0246             disp(m);
0247             error('m should be length 3');
0248         end
0249         if length(m{3}) == 1 && m{3}(1) == '0'  %% two-winding
0250             i2 = i2 + 1;
0251             idx2(i2) = i;
0252             i = i + 4;
0253         else                                    %% three-winding
0254             i3 = i3 + 1;
0255             idx3(i3) = i;
0256             i = i + 5;
0257         end
0258     end
0259     nt2 = i2;
0260     nt3 = i3;
0261 
0262     if verbose
0263         str = sprintf(' %d(%d) two(three)-winding.', nt2, nt3);
0264         spacers = repmat('.', 1, 36-length(str));
0265         fprintf('%s %s ... done.\n', spacers, str);
0266     end
0267 
0268     %% trim index vectors down to size
0269     idx2 = idx2(1:nt2);
0270     idx3 = idx3(1:nt3);
0271 
0272     %% parse record 1 (cols 1-20)
0273     [t2_1, warns] = psse_parse_section(warns, records(idx2), verbose, ...
0274         '2-winding transformers (1)', 'dd..ddd....d........');
0275 %       '2-winding transformers (1)', 'dddsdddffdsddfdfdfdf');
0276     [t3_1, warns] = psse_parse_section(warns, records(idx3), verbose, ...
0277         '3-winding transformers (1)', 'ddd.ddd....d........');
0278 %       '3-winding transformers (1)', 'dddsdddffdsddfdfdfdf');
0279 
0280     %% two-winding
0281     %% parse record 2 (cols 21-23)
0282     [t2_2, warns] = psse_parse_section(warns, records(idx2+1), verbose, ...
0283         '2-winding transformers (2)', 'fff');
0284 
0285     %% parse record 3 (cols 24-39)
0286     %% parse up to CX1, should warn if CNXA1 is present and non-zero
0287     [t2_3, warns] = psse_parse_section(warns, records(idx2+2), verbose, ...
0288         '2-winding transformers (3)', 'ffffff..........');
0289 %       '2-winding transformers (3)', 'ffffffddffffddff');
0290 
0291     %% parse record 4 (cols 40-41)
0292     [t2_4, warns] = psse_parse_section(warns, records(idx2+3), verbose, ...
0293         '2-winding transformers (4)', 'ff');
0294 
0295     %% three-winding
0296     %% parse record 2 (cols 21-31)
0297     [t3_2, warns] = psse_parse_section(warns, records(idx3+1), verbose, ...
0298         '3-winding transformers (2)', 'fffffffffff');
0299 %       '3-winding transformers (2)', 'fffffffffff');
0300 
0301     %% parse record 3 (cols 32-47)
0302     %% parse up to CX1, should warn if CNXA1 is present and non-zero
0303     [t3_3, warns] = psse_parse_section(warns, records(idx3+2), verbose, ...
0304         '3-winding transformers (3)', 'ffffff..........');
0305 %       '3-winding transformers (3)', 'ffffffddffffddff');
0306 
0307     %% parse record 4 (cols 48-63)
0308     %% parse up to CX2
0309     [t3_4, warns] = psse_parse_section(warns, records(idx3+3), verbose, ...
0310         '3-winding transformers (4)', 'ffffff..........');
0311 %       '3-winding transformers (4)', 'ffffffddffffddff');
0312 
0313     %% parse record 5 (cols 64-79)
0314     %% parse up to CX3
0315     [t3_5, warns] = psse_parse_section(warns, records(idx3+4), verbose, ...
0316         '3-winding transformers (5)', 'ffffff..........');
0317 %       '3-winding transformers (5)', 'ffffffddffffddff');
0318 
0319     %% assemble two-winding transformer records
0320     data.trans2.num = [t2_1.num(:, 1:20) t2_2.num(:, 1:3) t2_3.num(:, 1:16) t2_4.num(:, 1:2)];
0321     data.trans2.txt = [t2_1.txt(:, 1:20) t2_2.txt(:, 1:3) t2_3.txt(:, 1:16) t2_4.txt(:, 1:2)];
0322 
0323     %% assemble three-winding transformer records
0324     data.trans3.num = [t3_1.num(:, 1:20) t3_2.num(:, 1:11) t3_3.num(:, 1:16) t3_4.num(:, 1:16) t3_5.num(:, 1:16)];
0325     data.trans3.txt = [t3_1.txt(:, 1:20) t3_2.txt(:, 1:11) t3_3.txt(:, 1:16) t3_4.txt(:, 1:16) t3_5.txt(:, 1:16)];
0326 
0327     % if verbose
0328     %     fprintf('%s\n', upper(label));
0329     %     fprintf('%s\n', sections(s).name);
0330     % end
0331     s = s + 1;
0332 end
0333 
0334 %%-----  area interchange data  -----
0335 [data.area, warns] = psse_parse_section(warns, records, sections, s, verbose, 'area', 'ddffs');
0336 s = s + 1;
0337 
0338 %%-----  two-terminal DC transmission line data  -----
0339 label = 'two-terminal DC';
0340 if ~isempty(sections(s).name) && ~strcmpi(label, sections(s).name)
0341     if verbose > 1
0342         fprintf('-----  WARNING:  Expected section labeled: ''%s''\n', upper(label));
0343         fprintf('-----            Found section labeled:    ''%s''\n', sections(s).name);
0344     end
0345 end
0346 idx = sections(s).first:3:sections(s).last;
0347 if rev < 31
0348     [dc1, warns] = psse_parse_section(warns, records(idx), verbose, ...
0349         'two-terminal DC (1)', '.d.ff.......');
0350 %       'two-terminal DC (1)', 'ddffffffsfdf');
0351     [dc2, warns] = psse_parse_section(warns, records(idx+1), verbose, ...
0352         'two-terminal DC (2)', 'd.ff.............');
0353 %       'two-terminal DC (2)', 'ddffffffffffdddsf');
0354     [dc3, warns] = psse_parse_section(warns, records(idx+2), verbose, ...
0355         'two-terminal DC (3)', 'd.ff.............');
0356 %       'two-terminal DC (3)', 'ddffffffffffdddsf');
0357 else
0358     [dc1, warns] = psse_parse_section(warns, records(idx), verbose, ...
0359         'two-terminal DC (1)', '.d.ff.......');
0360 %       'two-terminal DC (1)', 'sdffffffsfdf');
0361     [dc2, warns] = psse_parse_section(warns, records(idx+1), verbose, ...
0362         'two-terminal DC (2)', 'd.ff.............');
0363 %       'two-terminal DC (2)', 'ddffffffffffdddDf');
0364     [dc3, warns] = psse_parse_section(warns, records(idx+2), verbose, ...
0365         'two-terminal DC (3)', 'd.ff.............');
0366 %       'two-terminal DC (3)', 'ddffffffffffdddDf');
0367 end
0368 
0369 %% assemble two-terminal DC transmission line
0370 data.twodc.num = [dc1.num dc2.num dc3.num];
0371 data.twodc.txt = [dc1.txt dc2.txt dc3.txt];
0372 % if verbose
0373 %     fprintf('%s\n', upper(label));
0374 %     fprintf('%s\n', sections(s).name);
0375 % end
0376 s = s + 1;
0377 
0378 %%-----  skip voltage source converter data  -----
0379 if rev > 28
0380     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'voltage source converter');
0381 end
0382 
0383 %%-----  switched shunt data  -----
0384 if rev < 31
0385     %% parse up to B1
0386     if rev <= 27
0387         [data.swshunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0388             'switched shunt', 'd....f');
0389 %           'switched shunt', 'ddffdfdfdfdfdfdfdfdfdf');
0390     elseif rev <= 29
0391         [data.swshunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0392             'switched shunt', 'd.....f');
0393 %           'switched shunt', 'ddffdsfdfdfdfdfdfdfdfdf');
0394     else    %%  rev == 30
0395         [data.swshunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0396             'switched shunt', 'd......f');
0397 %           'switched shunt', 'ddffdfsfdfdfdfdfdfdfdfdf');
0398     end
0399     s = s + 1;
0400 end
0401 
0402 %%-----  skip impedance correction data  -----
0403 [s, warns] = psse_skip_section(warns, sections, s, verbose, 'impedance correction');
0404 
0405 %%-----  skip multi-terminal DC data  -----
0406 [s, warns] = psse_skip_section(warns, sections, s, verbose, 'multi-terminal DC');
0407 
0408 %%-----  skip multi-section line data  -----
0409 [s, warns] = psse_skip_section(warns, sections, s, verbose, 'multi-section line');
0410 
0411 %%-----  skip zone data  -----
0412 [s, warns] = psse_skip_section(warns, sections, s, verbose, 'zone');
0413 
0414 %%-----  skip inter-area transfer data  -----
0415 [s, warns] = psse_skip_section(warns, sections, s, verbose, 'inter-area transfer');
0416 
0417 %%-----  skip owner data  -----
0418 if rev > 24
0419     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'owner');
0420 end
0421 
0422 %%-----  skip FACTS control device data  -----
0423 if rev > 25
0424     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'FACTS control device');
0425 end
0426 
0427 %%-----  switched shunt data  -----
0428 if rev > 30
0429     %% parse up to B1
0430     if rev < 32
0431         [data.swshunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0432             'switched shunt', 'd......f');
0433 %           'switched shunt', 'ddffdfsfdfdfdfdfdfdfdfdf');
0434     else
0435         [data.swshunt, warns] = psse_parse_section(warns, records, sections, s, verbose, ...
0436             'switched shunt', 'd........f');
0437 %           'switched shunt', 'ddddffdfsfdfdfdfdfdfdfdfdf');
0438     end
0439     s = s + 1;
0440 end
0441 
0442 %%-----  skip GNE device data  -----
0443 if rev > 31
0444     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'GNE device');
0445 end
0446 
0447 %%-----  skip induction machine data  -----
0448 if rev > 32
0449     [s, warns] = psse_skip_section(warns, sections, s, verbose, 'induction machine');
0450 end
0451 
0452 %%-----  check for extra sections  -----
0453 if s <= length(sections)
0454     warns{end+1} = sprintf('Found %d additional section(s)', length(sections)-s+1);
0455     if verbose > 1
0456         fprintf('-----  WARNING:   Found %d additional section(s):\n', length(sections)-s+1);
0457     end
0458 end
0459 while s <= length(sections)
0460     n = sections(s).last - sections(s).first + 1;
0461     if n
0462         str = sprintf('with %d line(s)', n);
0463     else
0464         str = sprintf('(empty)');
0465     end
0466     if isempty(sections(s).name)
0467         warns{end+1} = sprintf('  unlabeled section %s', str);
0468         if verbose > 1
0469             fprintf('-----            unlabeled section %s\n', str);
0470         end
0471     else
0472         warns{end+1} = sprintf('  ''%s DATA'' %s', sections(s).name, str);
0473         if verbose > 1
0474             fprintf('-----            ''%s DATA'' %s\n', sections(s).name, str);
0475         end
0476     end
0477     s = s + 1;
0478 end
0479 
0480 
0481 
0482 %%---------------------------------------------------------------------
0483 function [s, warns] = psse_skip_section(warns, sections, s, verbose, label)
0484 %PSSE_SKIP_SECTION  Skips over a section without extracting any data.
0485 %   [SIDX, WARNINGS] = PSSE_SKIP_SECTION(WARNINGS, SECTIONS, SIDX, VERBOSE, LABEL)
0486 
0487 if s > length(sections)
0488     if verbose
0489         spacers = repmat('.', 1, 58-length(label));
0490         fprintf('No %s data read %s done.\n', label, spacers);
0491     end
0492 else
0493     nr = sections(s).last - sections(s).first + 1;
0494     if nr > 1
0495         ss = 'lines';
0496     else
0497         ss = 'line';
0498     end
0499     if nr
0500         warns{end+1} = sprintf('Skipped %d %s of %s data.', nr, ss, label);
0501     end
0502     if ~isempty(sections(s).name) && ~strcmp(upper(label), sections(s).name)
0503         warns{end+1} = sprintf('Section label mismatch, found ''%s'', expected ''%s''', ...
0504             sections(s).name, upper(label));
0505         if verbose
0506             fprintf('-----  WARNING:  Found section labeled:    ''%s''\n', sections(s).name);
0507             fprintf('-----            Expected section labeled: ''%s''\n', upper(label));
0508         end
0509     end
0510     if verbose && nr
0511         spacers = repmat('.', 1, 47-length(ss)-length(label));
0512         fprintf('Skipping%6d %s of %s data %s done.\n', nr, ss, label, spacers);
0513     end
0514     s = s + 1;
0515 end