[Next Section] [Previous Section] [FEQ Update Contents]

Enhancements and Modifications to the Full Equations (FEQ) Model, March 1995 to August 1999.
Note: This document is separate from the U.S. Geological Survey report by Franz and Melching (1997). This description of enhancements and modifications to the Full Equations Utilities Model has not been approved by the Director of the U.S. Geological Survey.

Input description for new section 13.5a Define Macros and Instructions Block-- Instruction and Macro Definition

Section 13.5a Define Macros and Instructions Block--Macro and Instruction Definition

To RELEASE.TXT


This is an optional input block. If it is used it appears immediately before the Network Matrix Control block. FEQ requires that the heading line for the block begin with the sequence DEFINE with the first letter being in column 1. See the example below. Also the NEW Network Matrix option must be used if the Define Macros and Instructions block is to have any effect.
As previously discussed in Chapter 5, FEQ uses a series of code numbers, in the range of 2 to 15 in the current version, to specify the nature of the equation that will be used to relate the flow and water surface elevation at one or more exterior nodes in the model of the stream. Code 1, also defines the equation system for the nodes on a branch. Each of the 15 codes has one or more arguments that define the nodes or branch involved together with some key parameters used in the equation. These arguments follow after the code number on a line of input in the Network-Matrix Control block. The details of the equations created are given in Chapter 5 and the details of the meaning, order, and format for each of the codes and its arguments are given below.
Each of these codes is an instruction in a language designed to describe one-dimensional stream systems. For example, code 1, that for a branch, has a single argument, the branch number involved. When FEQ encounters the following line in the Network-Matrix Control block

1 25

it will generate the equations needed to approximate the governing equations in branch 25. The needed information on the number of nodes on the branch, the cross sections on the branch, and so forth are all obtained from internal data structures built as FEQ processing the input. If the Define Macros block is not used and if the NEW option for the Network-Matrix Control input is not used, then a rigid columnar format for the code values and arguments must be followed as given below. That is the order of the arguments for a given instruction was fixed and the column width was fixed. Relaxation of the column fixity using the NEW option for the Network-Matrix Control input has solved the problems with the fixed columnar format. With this format exterior node labels with three digits would leave no spaces between adjacent fields. The same thing would occur with four digit function table numbers. This made the input error prone and hard to read. With the NEW option for the Network-Matrix Control input, the number for the instruction and the following arguments remain order dependent but are not column dependent. Details are again given below.
Three problems with using the code numbers for instructions remain with both the NEW and the old option for Network-Matrix Control input. First, the numbers give no hint of their meaning. The association between a number and its meaning is purely arbitrary. The second problem is that the patterns in the input are often obscured by the many details. That is, a pattern that requires several instructions, say 3 to 10, may not be written in the same way every time it occurs. The consistent pattern may not even be recognized as the model is being constructed. The third problem arises in revising a model when an assumption about the flow is changed. Such changes are often widespread and affect many locations in a similar manner. This is especially true if the model contain multiple nearly parallel flow paths that are to interact frequently. An example would be representing a stream and its flood plain with distinct 1-D paths that must interact frequently in order to model the exchange of water between the central channel and the flood plain.
The solution to all three problem is to provide a facility for associating names with the instruction code numbers. Then instead of have the equation for a branch defined by code 1, we could instead use

Branch 25

where the name we pick can now have meaning. With the facility to associating names with the instruction codes, we further add the ability to group instructions and give the group a name, called a macro instruction name. A macro instruction is just an organized collection of other instructions. The macro instruction, or just macro for conciseness in expression, also has arguments. These arguments are used to provide the arguments for the instructions within it. The following example of a Define Macros and Instruction block illustrates its form.

01 DEFINE MACROS AND INSTRUCTIONS
02
03 ; Here are instruction definitions. The pattern is always
04 ; an identifier that becomes the instruction name followed
05 ; with one or more intervening spaces by the corresponding
06 ; FEQ Network-Matrix Control input Code value. The following
07 ; line defines the identifier: EqZ to have the value of 3.
08
09 EqZ 3
10 Branch 1
11 MomEnr 13
12 qsum 2 3
13 FILE=TEST.MIF
14
15 JUNCTION n1 n2 n3
16 EqZ n1 n2
17 SumQ n1 n2 n3
18 EqZ n1 n3
19 END JUNCTION
20
21 ForceQ node table limit
22 6 1 node 1 table limit
23 END ForceQ
24
25
26 END MACROS

Note: the line numbers have been added to aid in referring to a particular line. They are not part of the input.
Line 9 is an example of defining an instruction. This associates the identifier, EqZ, with the number 3. Code 3 is the equal-water-surface elevation instruction in FEQ. Line 16 is an example of the use of the instruction defined in line 9. Line 17 is an example of the use of a special instruction to force the sum of flows at the exterior nodes at a junction to zero. Notice that line 17 does not contain the number of nodes involved. The instruction, SumQ, counts the number of arguments that it has and then supplies the number of nodes to FEQ. This instruction is built into FEQ. Line 12 shows how to define an instruction name that does the same thing as SumQ. The difference is that the instruction name is followed by two numbers instead of one number like the other instructions. The first number is the Code value to be used, 2. The second number is always 3. This defines the proper internal value so that the command being defined will place the number of nodes in the proper place for FEQ.
An example of a definition of a macro instruction appears in lines 15 through 19. It represents a junction involving three nodes. There are then three arguments following the macro instruction name. Each of these arguments appears one or more times in the body of the macro instruction, lines 16-18. The macro instruction definition is completed by the END statement in line 19.
Line 13 shows that the definitions can also appear in a file. The key word FILE is reserved. You should not try to name an instruction using this word. Neither should you try using the word END. The contents of the file, TEST.MIF, follows: (note: MIF or mif is the suggesting extension for a file containing macro instructions-Macro Instruction File.)

01 Bran A1
02 1 A1
03 END Bran
04
05 Rating node table datum width
06 4 1 node -1 node table datum width
07 END Rating

Lines 1-3 define a name for the branch code option. We have already defined another instruction for the branch code number. Lines 5-7 define a name for the rating table option for a one-node control structure.
Here is an example input that uses some of the above definitions:

01 NEW NETWORK-MATRIX CONTROL INPUT
02 CODE N1 N2 N3 N4 N5 N6 N7 N8 N9 N10 F1 F2 F3 F4 F5
03 ForceQ U1 100 *
04 Bran 1
05 Branch 2
06 ForceQ U2 102 *
07 JUNCTION D1 D2 U3
09 Bran 3
10 Rating D3 110 103.0 32.0
11 -1
The first thing to notice is that the old headings don't work anymore. We will need to develop new methods for structuring the input. With a careful choice of names and macros, the input should be much easier to develop and read. Notice also that the place-holder, the asterisk, is required for the ForceQ macro if we want to leave a blank for the F1 value. If a F1 value is supplied it must have a decimal point in it. Otherwise FEQ will treat it as if it were a N5 value which is not what we want. A place holder is required because FEQ requires that the number of actual arguments, the items given after the macro name in the Network-Matrix Control Input, must be the same as the number of dummy arguments, the identifiers given after the macro name in the Define Macros block.
Here are the current general rules for defining instructions and using them:
1. All names and dummy arguments must be identifiers. A dummy argument is an argument following the macro name in the Define Macros block. For example line 1,Bran A1, in file TEST.MIF has one dummy argument, A1. The macro instruction in line 5, Rating, has four dummy arguments: node, table, datum, and width. An identifier in FEQ is a sequence of alphabetic and numeric characters with the first character being an alphabetic character. The following characters are added to the alphabet and are considered to be alphabetic: underline, _, slash, /, and back slash, . The colon, :, and period, ., are considered to be numeric. This means that an identifier must have a first character taken from the letters a through z, underline, slash, or back slash. After the first character the digits 0 through 9 and the colon and period plus any of the extended alphabet can appear. Using this definition, a file name in either DOS or UNIX format can be treated as an identifier.
Here are some examples of valid identifiers for FEQ:
d:usffeqtesttest.mif BRANCH Branch CS CS_2D
Note that case is important. BRANCH and Branch are NOT the same.
2. The current maximum length of an identifier used as a macro instruction name, an instruction name, or a dummy argument is 16 characters.
3. An identifier used as a file name can be up to 64 characters counting all character, that is the drive letter, colon, and slashes and the period are counted as part of the limit of 64.
4. The actual arguments can be anything required by FEQ. They can be table numbers, node labels, etc. However, any number that is a measurement and not a counting value or label should have a decimal point. This is needed so that the column-free input can be processed properly.
5. The number of actual arguments and dummy arguments must match. If an actual argument in the sequence is to be passed over, use the place-holder, the asterisk, for that argument.
6. Comments can appear in a macro definition but they will not be transferred to the usage of the macro.
7. Currently the special instruction, SumQ also has the following aliases: SUMQ, SQ,QSUM, and sumq. These are coded within FEQ. If you do not like any of these names, you can define your own as outlined above.
It also proves useful to be able to compose some of the values in the body of a macro instruction. There may be many instances of similar structures in a model. Careful choice of numbers can allow composition of the needed values within the macro so that the numeric part of free node labels can be computed from a single id number. It is also possible to then give branch numbers as arguments to a macro instruction and have the exterior node label on the end of the branch be composed in the macro.
Four operators have been defined for the composition of identifiers and numbers to use as arguments. The operators are:
addition:
subtraction:
replication:
concatenation:
Here is an example of using some of these operators. Again the numbers for each line are not part of the input to FEQ-they have been added for reference.
01 ; Macro for a gravity connection via one path to a LPR
02
03 SWCG1 nup ndn swcid lprtab hdatum
04 13 D|nup U|ndn
05 SumQ D|nup U|ndn F|lprtab7000
06 LPR lprtab
07 6 1 F|lprtab6900 1 0 0.0
08 5 6 F|lprtab7000 D|nup F|lprtab7000 2*swcid4200 hdatum
09 END SWCG1
This macro has five dummy arguments. They have the following meaning:
nup- branch number upstream of the two-branch junction
ndn- branch number downstream of the junction
swcid- surface water connection identification number. Is in the range of 1001 through 1099. Identifies a culvert under a levee.
lprtab- table number for a level-pool reservoir that will be connected to the two-branch junction using the culvert defined by the swcid number.
hdatum- datum for head for the 2-D table describing the flow through the culvert.
Line 4 shows the use of the concatenation operator where we construct the labels for the nodes on the branches in this junction. Notice that the concatenation operator appears with no spaces. The concatenation operator must always be immediately adjacent to the items that are to be concatenated.
Line 5 shows an example of using the subtraction operator. We need the downstream node on the level-pool reservoir. The node ids have been selected so that we can compute them from the capacity table number of the level-pool reservoir. In the current case all of the reservoir capacity tables have table numbers in the range 7200-7299. This means that all level pool reservoirs to be used with this macro instruction will have downstream nodes in the range of F200 through F299. The argument: F|lprtab7000 is evaluated in the following order:
1. lprtab is replaced by its numeric value from the actual argument.
2. The subtraction is done to yield the value in the range 200 through 299.
3. The concatenation operation is done last to form the free node id in the range of F200 through F299.
Line 8 shows an example of all four of the operators. The replication operator repeats an item. The order of operation must be kept in mind. The replication operator has the lowest precedence. That is, it is always done last. Thus the argument:2*swcid4200 is evaluated as follows:
1. swcid is replaced by its numeric value from the actual argument.
2. The addition is done to yield a number in the range of 5201 through 5299.
3. The replication operator is done to produce two instances of the argument.
Line 7 creates the upstream free node id for the level pool reservoir. In this case the upstream free node id has a numeric portion that exceeds the numeric portion of the downstream node id by 100.
The rules for evaluation of the operators, including the implied operator of value replacement is as follows:
1. Replace all identifiers with the proper numeric value. If an identifier has an unknown value it is retained and a warning message is issued indicating that the value is unknown and it may cause later errors.
2. Do the addition and subtraction operations. Note that these must take place on numbers NOT on identifiers.
3. Do the concatenation operation.
4. Do the replication operation.
There can be no spaces next to any of the four operators. Also these operators are always binary; that is, they are between two items.

Back to Franz and Melching (1997a), p. 169, beginning of next section 13.6, Network-Matrix Control Block-- Network-Matrix Table