Python Procedures
The Professional license of EES is able to call Python to run scripts. The script can do anything Python is capable of doing, provided that it accepts one or more numerical inputs and returns one or more numerical outputs. The script can be set up to provide the units of the input and output variables, which are then used in the EES unit checking algorithms. It is of course necessary to have Python installed on your computer and the path must be set so that entering "Python" in the command field of the Start dialog will start the Python program. Use the $Python directive to specify the location of the Python interpreter. EES will look for the Pythonw.exe application at startup. Any version of Python is acceptable.
The use and calling format are similar to those for EES Internal and External Procedures. A call to a Python script will have the following form:
Call Python('filename.pyw', 'optional string', In1, In2, ... : Out1, Out2, ....)
The first argument in the parameter list is the file name of the Python script that is to be run. Note that the file name must have a .pyw file name extension. Python scripts should normally be placed in the EES Userlib\Python directory. In this case, the script information and associated help files can be viewed in the Function Information dialog after selecting the External routines button. In addition, when the script is located in the Userlib\Python folder, the file name used in the Call statement does not need to include directory information. It is possible to run a script in any other directory by providing the complete path and file name. The Python script name can provided with a string constant as shown above, or with a string variable that has been set to the file name.
An optional string can follow the file name in the Call statement. This string is passed as the first input which is read by the Python script. If this string is not provided, EES will automatically supply a blank string.
Input values (In1, In2, ...) follow the file name or optional string in the argument list. The values can be EES variables or numerical constants. The Python script must be designed to read the number of inputs that are provided, each on a separate line. An example script is shown below. Note that the input values can be provided using an array using array range notation, e.g., Inputs[1..10].
The Python script must provide one or more numerical outputs, which are assigned to the EES variables that are placed to the right of the colon in the argument list (e.g., Out1, Out2, ...). Array range notation can be used for the outputs, e.g., Outputs[1..10]. There is no explicit limit on the number of inputs and outputs, other than each variable counts against the total variable limit in EES, which is 3,000, 6,000 for the Annual and Commercial licenses, 12,000 for the Professional license and 24,000 for the 64-bit license.
An example Python script is shown next. This script is mdas.pyw, which resides in the EES Userlib\Python folder.
_________________________________________________________________________________________________________________
#This is a test program to demonstrate the capability of EES to call Python scripts.
import math
import sys
import string
SR=sys.stdin.readline() #string input - usually blank
mode=int(sys.stdin.readline()) #read the mode
if (mode==-1): #return example calling sequence
SR="Call Python('MDAS.pyw',X,Y:M,D,A,S)"
if (mode==-2): #return units of the inputs
SR='m,m'
if (mode==-3): #return units of the outputs
SR='m^2, ,m,m'
if (mode<0):
print(SR)
sys.exit(0)#return
x=float(sys.stdin.readline()) #read the inputs
y=float(sys.stdin.readline())
if (y==0):
mode=2
SR='Attempted division by zero in MDAS Python program'
print(SR)
print(mode)
sys.exit(0) #return
try:
m=x*y #do the calculations
d=x/y
a=x+y
s=x-y
SR=''
mode=0 #return mode=0 if there are no errors
except:
SR='Unexpected error occurred in the MDAS Python program.'
mode=1
m=-999
d=-999
a=-999
s=-999
print(SR) # print a string. Normally blank unless there is an error
print(mode) # print the mode. Normally, mode=0, but it can be set to a value >0 to indicate an error
print('{}\n{}\n{}\n{}'.format(m, d, a, s)) # print the outputs, each on a separate line.
_________________________________________________________________________________________________________________
Note that the Python script reads inputs from the stdIn and outputs to stdout. It can be tested before calling it from EES using normal console input and output. When called, the inputs and outputs will be piped to EES and they will not appear on the console.
The first input to the Python script is a string (SR). This string contains the optional string in the EES Call Python statement. Normally, this will be a blank string, but it is possible to provide string information in the Call statement that will be provided in this way to the script.
The next input is an integer called mode. Mode is used for both input and output. On input, mode=-1 indicates that the script should return a string indicating its calling parameters. Mode=-2 indicates that the script should return a string with the units of the inputs, separated by commas. Mode=-3 indicates that the script should return a string with the units of the outputs separated by commas. It is not necessary to provide the example call or the input/output units. However, the script should be designed to return without doing calculations if mode<0. On input, mode>=0 indicates that the script should calculate its outputs. Normally, the script should return mode=0 and an empty script. If an error occurs in the script, mode should be set to a value >0 to indicate the error number and the string can provide an error message, as shown in the example when y==0.
When mode>=0, the script should read the numerical inputs, one per line and then initiate the calculations. The number and order of inputs and outputs in the script must be exactly the same as in the CALL statement.
Return information is provided to EES by the print command directed to sys.stdout. When mode<0, the script must return a string, which can be blank. Unit checking will be disabled if the script returns a blank string for mode=-2 and mode=-3. When mode>=0, the script must return a string (usually blank), a mode (usually zero) and the numerical outputs, each on separate lines.
Python scripts can be called from the main program, an internal EES Function or Procedure, or a Subprogram or Module that is configured to operate in complex mode. Scripts cannot be used in complex mode.
Help from within EES can be provided in a separate help file having the same parent name as the script and a .chm, .pdf, .htm. or .txt file name extension. The help file must be placed in the Userlib\Python directory.