GoldSim’s new Script element is designed to make it easier to carry out iterative calculations, work with vectors and matrices, and develop other highly customized calculations. The Script element is inserted like any other element in GoldSim. The Script element has all the tools needed to build the script line by line through a guided process that keeps you from having to memorize syntax.
Scripts usually include variable definition and assignment statements to create and work with variables that are local to the script. Variable definition statements define the units and dimensions of a variable and make an initial assignment to it. Variable assignment statements change the values of variables after they have been defined. Scripts can also include statements to control the flow of calculations, such as if statements, for loops, do loops, while loops, and repeat loops, as well as break and continue statements to alter the behavior of loops. You can insert comments throughout your scripts, and also insert statements that cause messages, warnings or errors to be written to the model’s run log or pop-up windows. There is a powerful debugging capability for scripts that makes it possible to pause part way through completion and step through statements line by line while using the mouse to see variable values in tooltips.
Let's introduce the Script element in a couple of examples.
First Script Example: Iterative Calculations
This simple example illustrates how the Script element can be used to carry out an iterative calculation. It can be found in a file (Script.gsm) that is located in the General Examples folder of your GoldSim directory. The example uses Newton’s method to calculate the square root of 101. While you’re certainly not likely to need to calculate the square root of 101 by Newton’s method, the model does provide a nice example of how to iterate within a script. Newton’s method is a successive approximation method for finding real roots of differentiable functions. For a function f(X), which in this case represents the error in the approximation, which we wish to go to zero, the formula for Newton’s method is:
Where f ’ (Xn) is the first derivative with respect to X, and Xn is the nth approximation of the root (X0 is an initial guess for the root). Therefore, in our example of finding the square root of 101:
The script used for this simple example to solve for the square root of the variable Val is shown below:
The script starts out with Variable Definition statements in lines 1 and 2. Note that when script variables are referenced on the right side of equations (e.g., in line 4), a ~ symbol is required. This is because script variables are locally available properties. In line 1, the script references an element outside this Script element called Val (a constant whose square root is being sought, 101). Note that referencing another element’s output does not require the ~ symbol.
After the Variable Definition statements, a FOR loop is defined. The FOR loop starting in line 3 shows that it creates a loop variable (named “I”) that is initially 1 and is incremented by 1 on each iteration, continuing while the expression “I<=MaxIterat” is true. Hence, the FOR loop executes the statements it contains until it is broken by a BREAK statement, or the loop count reaches the specified maximum number of iterations possible. In each FOR loop iteration, two more Variable Definition statements (with expressions as the assignments) compute the values for the function (F) and the derivative (FPrime). A Variable Assignment statement (line 13) then generates a new approximation of the square root at the bottom of the loop.
The IF statement block beginning at line 7 tests the approximation error in the current estimate of the square root. If it is sufficiently small, a BREAK statement is executed to terminate the FOR loop.
If the approximation error remains high and the maximum number of iterations is reached, a LOG statement (line 10) is written to the Run Log noting that the script failed to converge. Line 6 is another LOG statement reporting the progress of the successive approximations for each iteration of the FOR loop.
Second Script Example: Working with Matrices
A very common application of the Script element is to construct and/or manipulate arrays. This is typically facilitated by using one of the Script element’s looping constructs to assign values to rows, columns and/or individual items. The simple example described here illustrates how the Script element can be used to carry out array operations such as these. It can be found in a file (Script.gsm) that is located in the General Examples folder of your GoldSim directory.
The example starts with an input matrix. In the input matrix, each column represents a variable, and each row represents an observation of the variable. The script computes the correlations among the various columns (variables) of the matrix, producing a symmetric correlation matrix (rows and columns both indexed by variable). The correlation coefficient, Cxy, between two columns of data (i.e., the correlation between two variables) is given by the following equation:
In this equation, x and y are the variables. xi and yi are the ith observations of variable x and y, respectively. mx and my are the means of the observations for those variables (i.e., the means of all values in a particular column). sx and sy are the standard deviations for those observations. n is the number of observations (i.e., the number of rows).
The script used for this simple example is shown below:
At the top of the script (lines 2 and 4), Variable Definition statements (with expressions as the assignments) compute the means and standard deviations of each column. The calculation of the correlation coefficient for each column pair is then carried out using two Variable Assignment statements. The first (line 11) is in the middle of three nested DO loops. The second (line 14) is at the bottom of the second nested loop.
More Examples in the Model Library
If you are interested in Script element applications, please see two recent additions to the model library. One model is In that model a Script element is used to carry out a binary search for the headloss in pump. It solves a recursive loop in which the flow rate depends on the headloss of a pump and the headloss depends on the flow rate. Another recent addition to the model library is Muskingum channel routing is the simplest kinematic wave routing method. It is used for channel routing problems that are unidirectional without backwater effects, which includes most GoldSim water model situations where a travel time simulation is necessary. It is a specialized sort of material delay with dispersion for water in channels.