APPENDIX A: DIAGNOSING COMPUTATIONAL PROBLEMS IN FEQ

SECTION ONE

1. ERRORS IN PROCESSING MODEL INPUT

The first error that the user will usually encounter is related to data input to the model. FEQ detects many errors as it processes the input files defining the unsteady-flow model of the hydraulic system. FEQ is designed to continue processing the files despite most errors. This maximizes the number of errors that are detected for each run. However, it also can result in many errors that are artifacts of an earlier error. Therefore, always check for the earliest error first, because many or all of the subsequent errors may follow from it. The subsequent errors that follow from the first error depend on the context. For example, in order to continue processing, FEQ must sometimes give a value to an invalid input. If a table number is missing or invalid, the table will be assigned the number 1. However, this may cause an error message if a table with the number 1 has already been encountered. In many cases the error messages caused by an earlier error are obvious. Even if they are not, it is always most efficient to fix the earliest error first as the dependent errors also will disappear.

1.1 Conversion Errors

A conversion error that results in the message:

*ERR:500* Conversion error in line:

always stops the input processing. The input line that contains the conversion error is output following the message. A conversion error results whenever FEQ is attempting to process a number but a non-numeric character is encountered instead. This is a format error. Newer users of FEQ and FEQUTL frequently encounter unfamiliar error messages that are caused by minor data entry or alphanumeric label correspondence errors. These errors are trivial to correct, but can require a large amount of time to find and correct until the user is more familiar with the possible causes for the error messages. The experience of new users has been utilized to produce the following list of suggestions for successfully completing the FEQ input processing:

1. Are the numbers in the line in the correct ranges of columns? FEQ reads strictly fixed-format input files. Be warned that it is possible to mix digits such that no conversion error results. The input value will be wrong but it is still a valid number that FEQ can read and use incorrectly.
2. Check to make sure that an upper case letter "O" was not used in place of the digit "0". They are close to each other on the keyboard and look much the same in print and on the computer screen.
3. Make sure that all the numbers are valid: only one decimal point used (if required), no spaces in the numbers, no letters other than "E" or "D", and so forth.
4. Conversion errors also result if a line of input is missing. A common example is using a blank line for one of the required three lines describing the run at the start of the input file. This is not allowed; nor should any comments appear between the three lines. This means that the first three lines of input to FEQ should be non-blank and non-comments. FEQ skips blank lines except when processing the nodes on a branch. A blank line in the first three lines of the input will cause a subsequent line to be read as a line describing the model. This will disorder the input processing and the subsequent error messages will result from misinterpretations of the input data.
5. Tabs inserted by the editing program used to complete or modify the input result in conversion errors. Be sure that the editor outputs spaces rather than tab characters. An example of such an error is shown in the "No visible format error" section.

1.1.1 No visible format error

FUNCTION TABLES BLOCK

 NEXT FUNCTION TABLE FILE NAME=tables\tsf\tabtest.tsf

 TABLE#=  601
 TYPE=   -7
 REFERENCE LEVEL=       0. FAC=        1.000 SHIFT=       0.
  YR  MN DY      HOUR DISCHARGE       ds of glencrest creek conflu
*ERR:500* Conversion error in line:
1971  2  16 5.00    21.00

The conversion error is an indication that a format error, though not visible, is present.

Solution

Check the line given in the conversion error message with an editor that shows formatting characters, or delete and reenter the lines. Non-printing characters may be present in the problem input. Because these characters are not printed, they are invisible to the user; they are, however, read by the compiled FEQ program. The most frequent problem character of this type is the tab character. Some Fortran compilers will process tabs but most do not. The only safe course of action is to make sure that no tab characters are present in any file to be processed by FEQ or by FEQUTL. Check whether your editor will replace tabbed delimiters with spaces. On UNIX systems, all files must end with a newline command. No file on either UNIX or DOS should end with a blank line.

1.1.2 End-of-file reached or wrong line read

Another error that results in no runtime message is failure to end the time-series table properly with a time that is earlier than the last simulated time. Removing the last two lines from the time-series table listed below yields:

TABLE#=  601
TYPE=   -7
REFL=0.0       FAC= 1.0
 YR  MN DY      HOUR DISCHARGE       ds of glencrest creek conflu
1971  2 16      0.50 20.40
1971  2 16      1.00 20.50
1971  2 16      2.00 20.60
      .
      .
      .
1971  3  1     23.00 39.30            .
1971  3  1     24.00 39.30
1971  3  1     23.00 0.00

NEXT FUNCTION TABLE FILE NAME=tables\tsf\enderr.tsf
 TABLE#=  601
 TYPE=   -7
 REFERENCE LEVEL=        0. FAC=     1.000 SHIFT=       0.
  YR  MN DY      HOUR DISCHARGE     ds of glencrest creek conflu
*ERR:500* Conversion error in line:
ENDFILE

Solution

End the time-series table with a backward time. Check for lack of proper termination for some earlier part of the input. FEQ often requires a special value to indicate that a part of the input is complete. For example, the input for a branch in the Branch Description Block is signaled by inputting a negative number in the NODE column. By convention, a -1 is used. If that signal is missing, FEQ will continue to process the input, expecting a line of input for the description of nodes on the branch. However, the next line will have other values in it and a conversion error will result. A related error is inadvertently terminating a function table too early. This can result when the table argument decreases as the result of a typing error. Recall that the argument for a function always increases in a function table so that a decrease in the argument signals the end of the table. Because the table was ended prematurely, the expected input will not be read by FEQ. The program will be expecting a line that gives the table number for the next function table and not another line of input for the previous table. Again, a conversion error will result.

1.2 Table Type and Range Errors

After conversion errors, the next most common input-processing errors are related to the correct interpretation of the required input tables. The cause of these errors is not always apparent from the error message, and so a few examples are given below.

1.2.1 Invalid table type

The next error results when there is insufficient year and day data in the time-series table columns as shown in table 350 below.

TABLE#= 350
TYPE=  -7
REFL=0.0       FAC= 1.0
 YR  MN DY      HOUR ELEVATION    upstream side of rt53 bridge
1971  2 16      0.50 664.12
                1.00 664.12
                2.00 664.13
                3.00 664.13
      .
      .
      .
               21.00 664.26
               22.00 664.27
               23.00 664.28
1971  2 16     24.00 664.31
                1.00 664.34
                2.00 664.37
                3.00 664.39

The time-series table is interpreted as terminated at hour 24.00 because the next time hour is earlier if the date field is not updated. The date field must be provided at least the start of each day or the error message printed below will result.

NEXT FUNCTION TABLE FILE NAME=tables\tsf\misdat.tsf
 TABLE#=  350
 TYPE=   -7
 REFERENCE LEVEL=        0. FAC=      1.000 SHIFT=       0.
  YR  MN DY      HOUR ELEVATION    upstream side of rt53 bridge

 TABLE#=    0
0*ERR: 9* 
 REFERENCE VALUE=          0
 TABLE NUMBER OUT OF VALID RANGE
 TYPE=    0
*BUG:14* INVALID TABLE TYPE IN FTABIN. TYPE=       0 

Solution

Add the month and day fields at the start of each day.

1.2.2 Argument below range in time-series table.

The correspondence between the start time (STIME) in the model input and the time-series table must either be exact, or overlap with extra time-series data. The input file fragment below shows a start time that is before the earliest time available in the time-series table.

STIME=1971/02/15:01.0
ETIME=1971/03/01:24.0

The following table is the associated time-series table. Note that the earliest time available is after the start time shown in the input file fragment above.

TABLE#=  601
TYPE=   -7
REFL=0.0       FAC= 1.0
 YR  MN DY      HOUR DISCHARGE     ds of glencrest creek conflu
1971  2 16      0.50 20.40
1971  2 16      1.00 20.50
1971  2 16      2.00 20.60

The following excerpt is from the end of the output file that results when the input is run. A setup time is echoed to the standard output; the run, however, fails with the following message when unsteady-flow computations are attempted:

0*ERR:70* ARGUMENT BELOW RANGE IN LKTAB
TABLE NUMBER     =  601
TIME             =         0.
ARGUMENT         =     0.0000

Solution

Because table 601 is a time-series table, make sure that the start time (STIME) in the input file matches or is later than the earliest time available in the time-series table.