Internal Functions
EES provides support for both internal and external functions. Internal functions are entered directly in the Equations window. The rules for these functions are as follows:
1. The user functions must appear at the top of the Equations window, before any of the equations in the main program of the EES file appear.
2. User functions begin with the keyword FUNCTION. The function name and arguments, enclosed in parentheses and separated by commas, follow on the same line. Array range notation (e.g., X[1..5]) may be used as a shorthand argument list format.
3. The function is terminated by the keyword END.
4. Arguments are separated by a list separator which is the comma in the U.S. system and the semicolon in the European system.
5. The equations appearing in EES functions and procedures are fundamentally different from those appearing in the main program of EES. The equations in functions and procedures are more properly called assignment statements, similar to those used in FORTRAN, C, Pascal and MatLab. An assignment statement sets the variable identified on the left of the statement to the numerical value on the right. X:=X+1 is a valid assignment statement. The := sign (rather than the = sign) is used to signify assignment. However, EES will accept an equal sign in assignment statements if the Allow = in Functions/Procedures control in the Preferences dialog window in the Options menu is selected.
6. EES normally processes the assignment statements in a function or procedure in the order they appear. However, IF - THEN - ELSE, CASE,REPEAT-UNTIL, GOTO statements, Return and other logic control statements may be used in Functions and Procedures.
7. In the main program or in Subprograms, the statements within Duplicate - End blocks are literally duplicated. This is not necessary within a Function or Procedure as assignment statements, rather than equalities, are employed. Duplicate - End blocks within Functions and Procedures are internally rewritten as Repeat-Until blocks.
8. Functions are called simply by using their name in an equation. The arguments must follow the name, enclosed in parentheses. The Function must be called with the same number of arguments appearing in the FUNCTION statement. Arguments are separated by a comma (U.S. numerical format) or a semicolon (European numerical format). Array range notation may be used.
9. Equations in user functions may call any of the built-in functions. In addition, they may call any user Function, Procedure or Subprogram. Recursive calls in which a function calls itself are, however, not allowed. A Function cannot call a module.
10. All variables used in the Function body are local to the function. The values are not initialized and they do not remain in memory after the calculations are completed. The Function returns the value to which its name is assigned. Variables that are defined in the Function will display in Solution window. Array variables that are defined and used in the Function can be displayed in the Arrays table window by placing a $ARRAYS ON directive in the function.
11. Variable values can also be passed to the Function using the $COMMON directive.
12. Optional Help information can be provided by placing the help text anywhere in the function or procedure file as a comment between braces { }. The comment must begin with $ followed by the function or procedure name. The text on following lines, up to the closing comment braced is assumed to be the help information. This help information will be displayed when the user selects the Info button in the Function Information dialog. An example of the help format is provided below. Help can alternatively be provided in a separate text or Windows .pdf, .chm or .htm file that has the same parent file name as the function.
13. Functions always operate in real mode regardless of the Complex Numbers setting.
14. The Print command can be used in Functions and Procedures
15. Functions that are called from the main program or a Subprogram in complex mode are not allowed.
Functions can be used to implement an analytical relationship between two or more variables. For example, the specific exergy (or availability) of a flowing stream, psi, is
psi = (h - ho) - To * (s - so) + V2/2 + g*z
where
h and s are the specific enthalpy and entropy of the state, respectively
ho and so are the specific enthalpy and entropy at the dead state condition, To and Po
V is the velocity
g is gravitational acceleration
z is the elevation of the state, relative to a selected zero point
Once the temperature and pressure of the dead state are selected, ho and so are constants. A user function for the exergy of steam, with To=530 R and Po=1 atm, could be implemented by placing the following statements at the top of the worksheet. An equation of the form psi_1=psi(T1, P1, V1, Z1) in the worksheet would return the specific exergy of steam in Btu/lbm corresponding to the values supplied as arguments to the function.
FUNCTION PSI(T, P, V, Z)
{$PSI
This function returns the specific exergy of steam in Btu/lbm as a function of T [F], P [psia], V [ft/sec] and Z [ft]}
T0:=77 [F]
TR=convertTemp(F,R,T0)
P0:=14.697 [psia]
h := Enthalpy(Steam, T=T, P=P)
s := Entropy(Steam, T=T, P=P)
h0:= Enthalpy(Steam, T=T0, P=P0)
s0:= Entropy(Steam, T=T0, P=P0)
g=32.17 [ft/s^2]
PSI := (h-h0) - TR*(s-s0) + V^2/2*convert(ft^2/s^2,Btu/lb_m) + g*z*convert(ft^2/s^2,Btu/lb_m)
END
Functions can also be used to change the name of any built-in function and/or to shorten the argument list. For example, the following function changes the name of HumRat, the built-in function for humidity ratio, to w, eliminates the need to specify the substance AirH2O as an argument, and sets the total pressure to 101.3 kPa in each case.
FUNCTION w(T,RH)
{$w
This function return the humidity ratio of moist air as a function of temperature and relative humidity. Atmospheric pressure is assumed.}
w := HumRat(AirH2O, T=T, P=101.3 [kPa], R=RH)
END
Functions can have any number of input arguments. An example of a function which finds the smallest of three arguments is shown below. This function (which could be more simply written with the Min function) demonstrates the format of the IF - THEN - ELSE and GOTO statements that are allowed in Functions and Procedures. CASE statements can also be used in Functions and Procedures for logic control.
FUNCTION Smallest(X,Y,Z)
if (X<Y) then S:=X else S:=Y
if (S<Z) then goto 10
S:=Z
10: Smallest:=S;
END