Rather than just relying on the primary output For an element with multiple outputs, the output that has the same name as the element. (Result), most scripts will require local variables to do such things as hold intermediate results or act as counters for loops. Local script variables can also be specified to be additional outputs to the element (so that the Script element has outputs in addition to its primary output).
Script variables are created using a Variable Definition statement. Often a script will start out with multiple Variable Definition statements that create and initialize the local variables that are subsequently used throughout the script.
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 (Ctrl+D) from the main Script dialog. Doing so inserts the statement in the script (below the statement that was selected when this is done), and brings up the following dialog:
You must specify the ID of the local variable you are creating, along with its Display Units The units (e.g., m, g, $/day) in which an output is displayed within GoldSim. and Type. The Display Units determine the dimensions An output attribute for an element that defines the dimensionality (in terms of Length, Time and other fundamental dimensions) of the output. of the variable. You can specify the type and order by pressing the Type... button. The variable can be a value or a condition, and can be specified as a scalar An output consisting of a single value or condition., a vector A one-dimensional array. or a matrix A two-dimensional array.. By default, a local variable is a scalar, dimensionless value.
Note: If the variable you are defining is an array A collection of variables that share common output attributes and can be manipulated in GoldSim elements or input expressions., the Definition portion of the dialog expands to provide some additional options for defining the array.
The Description is displayed in tool-tips when viewing the script, and is also displayed when modifying the value of the variable using Variable Assignment statements.
The Definition field is used to assign a value to the variable. This field is identical to the Definition field for a Variable Assignment statement, in that it can reference:
- Outputs that are external to the Script element;
- The primary output itself (i.e., Result); and/or
- Other local variables that you define in the script.
In many cases, however, the assignment in a Variable Definition statement will simply be a constant:
This would then look like this in the script:
Alternatively, you could define the variable and immediately define its value as an expression (as opposed to a constant):
This would then look like this in the script:
Of course, you can (and almost always will) reassign a definition to a variable later in your script (using a Variable Assignment statement).
Note: User-defined local script variables cannot reference themselves in a Variable Definition statement (e.g., X = ~X + 1 would be invalid, as there is no existing initial value of X to reference in this case). This could, however, be done in a Variable Assignment statement (since X would have been previously defined, and hence could be referenced).
When you create a local variable, you can specify that you want it to be an output for the element by checking the Expose as Output checkbox (which by default is cleared). This then adds an output to the Script element.
For example, if a Script element (named Script1) had two local variables (X and Y), and only X was exposed as an output, then outputs of the Script element would look like this:
The primary output (referred to as Result in the script) would be referenced outside of the Script element as Script1. The secondary output For an element with multiple outputs, an output that has a different name than the element. X would be referenced outside of the Script element as Script1.X. The other local script variable (Y) could not be referenced outside of the Script element.