Modules and Subprograms
Subprograms can be viewed to be stand-alone EES programs that can be called from the main EES program. Modules have a similar behavior but internally, their operation is more complicated, as explained below. The format of a Module / Subprogram is similar to that for an internal Procedure. The Module or Subprogram is supplied with inputs and it calculates outputs. Like a Procedure, the Module / Subprogram statement can (optionally) use a colon in the argument list to separate inputs from outputs. The number of arguments provided to the left of the colon is the number of degrees of freedom in the Module / Subprogram, or stated another way, the number of values that must be supplied to have the number of equations equal to the number of unknown. Examples of Module / Subprogram statements with a colon in the argument list are:
MODULE Testme(A, B : X, Y) or SUBPROGRAM Testme(A, B : X, Y)
In this case, EES understands that there are two inputs (A and B) and two outputs (X and Y). However, the equations in EES Modules / Subprograms are equalities rather than assignment statements as used in Procedures. In most cases, it does not matter what variables are specified as inputs as long as the appropriate number are specified. As a consequence, the colon which separates inputs from outputs is unnecessary and it can be replaced with a comma (or semi-colon for the European numerical format). However, regardless of whether or not a colon is provided, it is assumed that the argument list consists of inputs followed by outputs. The following Module / Subprogram statements are equivalent to the format shown above.
MODULE Testme(A, B, X, Y) or SUBPROGRAM Testme(A, B, X, Y)
Modules and Subprograms must be placed at the top of the Equations Window before the equations in the main body of EES or in a library file. The order in which the Modules, Subprograms, Functions, and Procedures appear is not important, as EES will use double-pass compilation if necessary to compile all of the routines.
A Module / Subprogram is accessed with a CALL statement. For example, the following statement would access the Testme Module or Subprogram.
CALL Testme(77,1.5, X,Y)
Note that if a colon is used to separate the inputs and output in the MODULE / SUBPROGRAM statement, it must also be used in the CALL statement. Similarly if a colon is not used in the MODULE /SUBPROGRAM statement, it should not be used in the CALL statement.
At this point, you must be curious as to the difference between a Module and a Subprogram. The difference is explained below.
When EES encounters a CALL statement to a SUBPROGRAM, it opens a new workspace and it then solves the equations in the SUBPROGRAM, using blocking and iteration as necessary. The calculated variables appearing as parameters in the SUBPROGRAM statement are returned to the main program. Note that if a colon is not provided to separate inputs from outputs in the SUBPROGRAM statement, EES will automatically determine the number of outputs but as the difference between the number of variable used in the equations and the number of equations in the SUBPPROGRAM. The number of outputs (N) must be greater than zero or a error message will be issued. The output variables are assumed be N variables at the end of the parameter list.
When EES encounters a CALL statement to a MODULE, it transparently grafts the equations in the module into the equations in the main program. The steps necessary for this process are as follows. First, every variable in the Module, including each input and output in the MODULE statement, is renamed with a unique qualifier that EES can recognize. Then EES adds one equation for each input and output which sets the value of the parameter in the calling program to the value of the value in the module. Note that the guess values and limits for the EES variables appearing in the CALL statement in the main program override the specified guess values and limits for the variables in the argument list of the MODULE statement. Finally, all of the equations in the module, with their renamed variables, are merged into the EES program at the point at which it is called. If the Module is called a second time, the process is repeated, but with a different qualifier for the variable names in the Module. The net effect is that a copy of all of the equations in the Module are merged into the main EES program each time a CALL statement is encountered. EES currently allows thousands of equations (3,000 (Annual license), 6,000 (Commercial license), 12,000, (Professional license), 24,000 (64-bit license)) so rather large problems can be developed. EES then uses its efficient blocking techniques to reorganize the equations for optimal solution. As a result of this reorganization, the equations in the Module may not necessarily be called in sequence. In fact, this is rarely the case. You can view the equations in the order that EES has rearranged them in the Residuals window or Computational Flow window. Equations from a Module are identified with the Module name followed by a backslash and then the call index number. For example, the following equation in the Residuals window
Turbine\2: h2=h1+Q/m
would indicate that the equation h2=h1+Q/m originated from the second call to the Turbine module.
The Module / Subprogram is terminated with an END statement. A CALL statement is used to call the Module / Subprogram, just as for a Procedure. The important difference between a Procedure and a Module / Subprogram is that the Module / Subprogram is composed of equality statements whereas the Procedure is composed of assignment statements. Consequently, a Module / Subprogram cannot support logic constructs such as IF THEN ELSE, but it can provide iterative solutions to implicit equations, when needed, and order independent equation input, just as in the main part of EES. The following example uses a Module to solve an implicit set of two equations and two unknowns.
Module testme(A, B, X, Y)
X^2+Y^3=A
sqrt(X/(Y^2+1))=B
End
Call testme(77,1.234,X1,Y1)
Call testme(88,2.345,X2,Y2)
So should you use a Module or a Subprogram? Limited tests thus far indicate that a Module tends to solve a problem more efficiently than a Subprogram, although you may wish to test both forms to determine which is better for your application. A major advantage of a Subprogram is that it can be called from a Function or Procedure. A second advantage is that each Subprogram can have the same number of variables as the main program. Conditional statements, such as the IF THEN ELSE, GOTO, and REPEAT - UNTIL are only supported in Functions and Procedures. If your application requires integration with conditional statements, you will necessarily have to use a Subprogram. Shown below is a short program which calls a Function that uses an IF THEN ELSE statement to call one of two Subprograms.
Function myfunc(a,b)
If (a<77) Then
Call mysub2(a,b:x)
Else
Call mysub1(a,b:x,y)
Endif
myfunc:=x
End
Subprogram mysub1(a,b:x,y)
x^2+y^3=sumab(a,b)
sqrt(x/(y^2+1))=b
End
Subprogram mysub2(a,b:x)
x=a+b
End
Function Sumab(a,b)
sumab:=a+b
End
x=myfunc(3,2)
Variables values are normally passed to a Module / Subprogram through the argument list. The $COMMON directive may be used to pass variables that are defined in the Main program to a Module / Subprogram. Variable information, including guess values and lower/upper limits for Module / Subprogram variables is accessible with the Variable Info command. The local variables in a Module are always real regardless of the Complex Numbers setting. Complex variables may be used in a Subprogram if a $Complex directive is provided.
Array variables may be used in a Module / Subprogram. By default, array variables are displayed in a separate tabbed window of the Solution window. A separate variable list is provided for each Call to a Module. However, array variables may be more conveniently displayed in the Arrays Table window. This display option is made possible by placing a $ARRAYS ON directive within the Module / Subprogram.
Subprograms may be stored as library files, just like Internal Functions and Procedures. Modules should NOT be used in library files. The library files can be automatically loaded if they are placed in the USERLIB subdirectory. Alternatively, a $INCLUDE directive can be used to transparently load a library file. Help can be included within the Subprogram (using the same syntax as used in internal Procedures) or it can be supplied with a separate help file having the same filename as the library file with a .TXT, .PDF, .CHM or .HTM filename extension.
COMPLEX MODE
A Subprogram can be designate to solve complex equations if a $COMPLEX ON directive is placed anywhere within the Subprogram and End statements. The real and imaginary parts of variables passed as parameters to a Subprogram configured in complex mode must appears as separate variables, as in the following example.
Subprogram test (x_r,x_i,y_r,y_i)
$Complex on
x^2=y
End
$Complex On
Call test(x_r,x_i,y_r,y_i) {note that the real and imaginary parts must be passed as separate variables}
y_r=-3
y_i=0
Modules cannot be used in complex mode.
Modules and Subprograms can significantly increase the capabilities of your EES program.