Introduction to the Script Element (December 2015)

A similar webinar was presented more recently on this subject as well. You can find it here: Introduction to the Script Element - Pumping Example (Sep 2022)

GoldSim’s 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 makes it so you do not need to remember a specific syntax.

Below are several Script Element examples that illustrate the various capabilities and features of these Elements. You can download a copy of the model that contains these examples by clicking the download link at the bottom of the article. Covered in these examples are the following:

1) Variable Definition and Assignment
2) FOR and DO Loops
3) REPEAT-UNTIL and WHILE Loops
4) IF-THEN Statements
5) Run Log Messages

Be sure to run the model and then read descriptions of the examples in the text boxes. Screenshots of the scripts are shown to the left of each Script Element.

Variable Definition and Assignment

The most fundamental of the Script element’s statements is the Variable Definition and the Assignment. Rather than just relying on the primary output (Result), most scripts will require local variables to do such things as hold intermediate results or act as counters for loops. 

You add a local variable to a script by selecting “Variable Definition” from the Script element’s Insert menu, or by simply pressing the hot-key shortcut, Ctrl+D, on your keyboard (note that all hot-key shortcuts can be seen in the Insert menu of the Script dialog).  You can also assign a value (or condition) to a variable using the "Variable Assignment" command, or by pressing Ctrl-A. 

As seen in the simple Script example below, you can define a state variable (with an initial value) and assign a new value to it later in a sequence of calculations. In this example, the value of 'Y' is initialized to 0. It is assigned a new value (which is a function of a variable 'X') and then the value of 'Y' is assigned to the Script Element primary output 'Result'.

FOR Loops

FOR loops are one of four different types of loops provided in the Script element.  They are used to loop through a set of statements a fixed number of times. Common applications of FOR loops are defining and manipulating arrays, and doing iterative calculations. FOR loops will be familiar to those with scripting and programming experience. These require an initial integer value for the loop variable, a “Loop while true” condition, and an integer defining how the loop variable is incremented.

This example, below, shows how a FOR loop can be used to iterate over several index values, calculating the result of an expression at each index value. These results are stored in the 'Result' vector output of the Script Element.

DO Loops

DO loops are one of four different types of loops provided in the Script element. They are similar to FOR loops in the sense that they can be used to loop through a set of statements a fixed number of times.

The example below shows how a DO loop can be used to iterate over several index values, calculating the result of an expression at each index value. Results are generated for a matrix using a DO loop nested inside another. The outer DO loop iterates over column indexes. The inner DO loop iterates over a number of indexes equal to the number of rows in the matrix.

Note that the inner loop loads values term by term into a temporary vector variable. The outer loop then copies this full vector of values into a column of the 'Result' matrix.

REPEAT-UNTIL and WHILE Loops

The example below shows how REPEAT-UNTIL and WHILE loops can be used to calculate the sum and product of a series of integers in an input vector. In the case of the REPEAT-UNTIL loop, an index variable is incremented on each loop until the index value is greater than the size of the input vector. In the case of the WHILE loop, an index variable is also incremented on each iteration. Looping continues while the index is less than or equal to the size of the input vector.

After running the model, left-click on the output port of the Script element and hover over the exposed 'sum' and 'product' output items to check their values in the tool-tip that appears.

Note that the statements inside a REPEAT-UNTIL loop will always be executed at least once, since the condition is evaluated at the end of the statement list. In contrast, the statements in a WHILE loop may not be executed at all, since the condition is evaluated at the start of the statement list.

Also note that, while FOR and DO loops are used to execute a set of statements a predefined or fixed number of times, REPEAT-UNTIL and WHILE loops are typically used when doing iterative calculations for which the number of iterations may differ from one execution to the next.

IF-ELSE Statements and Run Log Messages

IF-ELSE statement blocks are used to test conditions that control branching of statement execution within a script. You can also include Else-if and Else instructions within the statement block to provide a significant amount of control and flexibility.

The example below shows how an IF-ELSE statement can be used to check that certain requirements on the value of an input are satisfied. If the conditions are not met, a message can be written to the run log with user-specified information. This example checks that a value input is below an upper bound and above a lower bound. When either condition is not met, the run log message displays the value of the input and the value of the upper or lower bound.

After running the model, open the run log to view the messages. Also, open the Script Element, double-click on one of the rows that defines a run log message/warning and see the syntax for referencing values of elements or local variables within the script.

In December 2015, an introduction to the Script Element was presented in a Webinar.

You can also download the materials used during the webinar by clicking on the link below.

Download Model Example and Webinar Materials: