Program Name: 2jd

Description: Converts gensal, genrou and gentpf records to gentpj records in a WECC PSLF dynamics data (dyd) file. Performs data checking on all converted generator data records. Allows data records for selected generators to be 'certified' as valid and, having been certified, to be left unchecked and untouched by the current execution of 2jd.

Prerequisites: The dyd file must exist

Invocation: 2jd <dydfile> <cfile> <outfile> <kiss> <kisf> <kisr> <logfile> <chfile> <tcmin>
 
<dydfile> Name of the WECC dyd file to be converted

<cfile>   Name of the generator selection file containing or 'none' to bypass 
          selection and convert all generators of selected type

<outfile> Name of the converted dyd file to be created

<kiss>    Default value of the gentpj model parameter, kis, to be applied 
          to generators represented by gensal in the original dyd file

<kisf>    Default value of the gentpj model parameter, kis, to be applied 
          to generators represented by gentpf in the original dyd file

<kisr>    Default value of the gentpj model parameter, kis, to be applied
          to generators represented by genrou in the original dyd file

<erfile>  Name of the error message file

<chfile>  Name of the parameter changes file

<tcmin>  Minimum allowable value of subtransient time constants

Notes:

In the input dyd file the identifier stanza for each generator must be complete. The model name, bus number, bus name, base voltage, and unit identifier must all be present. The following is a model identifier in correct form:
gensal 79200 "NAV1 " 13.80 "1 " :
The recording level and generator base mva entries may be present but are not required.
The parameter name feature of the dyd file may be used but is not required.
The generator selection file specifies which generators are to be converted. Each record identifies one generator by its bus number and unit identifier. The record format is:
<number> <id> <cf> <kis> "<busnam>" <any other informative content>
All fields up to and including the bus name must be present. The bus name must be enclosed in quotes and must be 8 characters in length (trailing blanks must be included). Remarks may be present on the record after the bus name but are ignored by 2jd. The following are valid records:
```
	  43297 1  0 0.0  "Bus-A   " 
	  43298 1  0 0.0  "BUS-B   "  The cow jumped over the moon
          16431 A  2 0.0  "BIGPLNT "  24 "01" :
          19214 2  1 0.1  "BusNo265"  23.0 AREA 77  ZONE 243
          51291 ST 0 0.1  "BUSNO123"  New value of kis 
            743 1  0  -1  "BUS-743 "  The -1 value of kis gives temporary suppression of conversion
```
The <cf> entry indicates how the generator record in the input dyd file is to be treated.
If the <cf> entry is zero the record is checked for data errors and consistency of parameter values, parameters are changed as necessary to achieve consistency with the data checking rules, error messages are produced and the changed parameter values are shown in stanzas in the changes file.
If the <cf> entry is nonzero the data in the input dyd file is considered to have been checked and certified to be correct. If <cf> is 1 the input parameter values are checked and error messages are produced (as if the certification did not exist) but no values are changed. If <cf> is 2 no error messages are produced and no values are changed.
This converter changes only gensal, gentpf, and genrou records; all other records are 'passed through' without change.
The use of the generator selection list can be suppressed by entering a file name of none for <busfile>. If <busfile> is none, or if the file is not found, the program converts all generator models in accordance with the rules given below.
When the generator selection file is not used
- the value <kiss> is given to the kis parameter of the gentpj record created for every gensal record in the input file.
- the value <kisf> is given to the kis parameter of the gentpj record created for every gentpf record in the input file.
- the value <kisr> is given to the kis parameter of the gentpj record created for every genrou record in the input file.
When the value of <kiss>, <kisf>, or <kisr> is less than zero the corresponding input records are not converted, regardless of the presence of their bus numbers in the bus list file, but are passed through without change.
When a generator selection file is used and a generator is not found in the file, the data record for that generator is not changed.
Messages identifying errors and inconsistencies in the input gensal, gentpf, and genrou records are written to the error message file <erfile>. If the <erfile> argument is omitted from the command line the error messages are sent to the terminal.
A listing of data errors and inconsistencies is written to the error message file, <erfile>. The following two records indicate errors found in the parameter list for generator 1 at bus 20231.
```
Model   Bus No        Bus Name  BaseKv   ID   Code   Message
genrou, 20231       , MXI-U2  , 13.80   , 1  ,208,  ,lq >  ld
genrou, 20231       , MXI-U2  , 13.80   , 1  ,213,  ,ll > 0.95*lppd
```
The error codes shown in the Code field of these records can be used for sorting the errors by type in a spread sheet. Each error message shown in this file is also shown in the parameter changes file alongside the parameter that triggered the error.

A record of the parameters assigned to the gentpj record constructed for each gensal, gentpf, and genrou record is written to the file <chfile>. If the <chfile> argument is omitted from the command line these output are sent to the terminal. The following is the stanza showing the gentpj parameters assigned to a generator whose data in the original dyd file was for the genrou model. The data error messages indicating why a parameter was changed are shown to the right of each stanza. genrou, 20231 , MXI-U2 , 13.80 , 1 ,genrou ,gentpj mbase, 27.69 , 27.69 tpdo, 5.8200 , 5.8200 tppdo, 0.0240 , 0.0240 tpqo, 0.4600 , 0.4600 tppqo, 0.0570 , 0.0570 h, 4.0000 , 4.0000 d, 0.0000 , 0.0000 ld, 1.8100 , 1.8100 lq, 1.9660 , 1.8100 , ,lq > ld lpd, 0.1600 , 0.1600 lpq, 0.4370 , 0.4370 lppd, 0.1180 , 0.1180 lppq, 0.1180 , 0.1180 ll, 0.1430 , 0.1121 , ,ll > 0.95*lppd s1, 0.1120 , 0.1120 s12, 0.5610 , 0.5610 ra, 0.0000 , 0.0000 rcomp, 0.0000 , 0.0000 xcomp, 0.0000 , 0.0000 accel, 0.5000 , 0.5000 kis, 0.0000 , 0.0000

The following are examples of command lines to run the program:

 2jd <dydfile> <cfile> <outfile> <kiss> <kisf> <kisr> <logfile> <chfile> <tcmin>       
 2jd 08hs41.dyd none   c41.dyd     0.1    0.     -1. 

     - converts file 08hs41.dyd
     - file <none> does not exist - convert generators at all buses
     - creates or overwrites file c41.dyd
     - converts gensal records with kis = 0.1  
     - converts gentpf records with kis = 0.0
     - leaves genrou records unchanged
     - sends error messages to the terminal
     - sends the changes descriptions to the terminal

 2jd <dydfile>  <cfile> <outfile> <kiss> <kisf> <kisr> <logfile> <chfile> <tcmin>       
 2jd 08hs41.dyd  b.list  c41.dyd     0.1    0.    -1.   e41.csv
  
     - converts gensal and gentpf records with kis values given in the bus list file
     - converts generators at buses whose numbers are in b.list
     - sends error messages to file e41.csv
     - sends the changes descriptions to the terminal

 2jd <dydfile>  <cfile> <outfile> <kiss> <kisf> <kisr> <logfile> <chfile> <tcmin>       	
 2jd 08hs41.dyd  b.list  c41.dyd    0.1    0.     -1.   e41.csv   c41.txt  0.02

     - is the same as the preceding example except that the change descriptions are sent to the file c41.txt
     - the default minimum value of subtransient tine constant is replaced by 0.02