Lesson 5 - Linking Elements and Writing Expressions

As a general rule, each type of element in GoldSim has one or more inputs, and produces one or more outputs. Each element has a dialog (i.e., an input window) with one or more input fields. GoldSim models are built by linking the outputs of elements to the inputs (using the input fields) of other elements. In the example in the previous Lesson, all three elements (the two Data elements and the Expression element) had a single input field.  Other elements (e.g., the Pool) have multiple input fields.

For the most part, when editing an input field for any element in GoldSim, you can do one of three things:

• Enter a value (or condition). This is what we did in the previous Lesson when we entered values to define the Data elements Velocity1 and Velocity2. As we will discuss subsequently, as a general rule, you should only do this for Data elements.
• Enter the name of another output. This is what we did in Unit 4 when, for example, we defined the Upper Bound for the Tank (a Pool element):
  
  In this case, we linked the Pool element to the element Tank_Capacity by entering its name directly into the appropriate input field.
• Enter an expression (which may reference one or more outputs). This is what we did in the previous Lesson when we defined Velocity3:
  

When editing an input field in GoldSim, GoldSim provides a number of tools to make the task easier. The most important of these are tools to help you find and insert links to other elements. To illustrate these, open the example file we built in the last Lesson (Velocities.gsm). Open the Expression element we created (Velocity3), and select the contents of the input field and delete it, so the field is now is empty:

Now let’s start typing the expression back in (Velocity1 + Velocity2). As soon as you type the first letter (V), you will note that GoldSim immediately offers some suggestions:

While you are entering an expression into an input field, GoldSim constantly tries to parse it and displays a message if it fails. In this case, if we enter just the letter “V” it states that it cannot find an element with that name.  Of course, we can ignore this for now, because we know we have not completed entering the expression.

More importantly, note that at the bottom of the dialog, GoldSim lists all the output names that are consistent with what you have entered so far.  As you continue to type, it automatically updates the list.  To select one of the items, simply left-click on it, and GoldSim will insert it into the input field.  You can then continue to enter your expression. Let’s select Velocity1 and then add the “+” sign so our expression now looks like this:

Again, GoldSim displays an error message indicating that the expression is incomplete (since it cannot end with an operator like the plus sign).

Now instead of typing and selecting from the suggestions, we are going to use a different method to enter the second link (Velocity2).  The suggestions can work fine for a small model (where the number of suggestions is small), but for large models, the suggestion list may be rather long.  So we will illustrate a second method here. Instead of selecting a suggestion, we are going to right-click in the input field (just after the plus sign), which will display a context-menu:

Select Insert Link… and the following dialog will be displayed:

This is a browser (hierarchical) view of the entire model. In this case, double-click on Velocity2, and GoldSim will insert it into the expression (at the point you right-clicked). You may wonder why this is better than just using the suggestion list.  As we will learn in subsequent Units, GoldSim models can be very large and complex, and the complexity is managed by organizing your model into a hierarchical structure.  This browser view provides direct access to this hierarchy so you can easily find the element of interest.

The key point here is that you will rarely type a name directly into an input field (unless it is very short).  Instead, you will use one of these tools to insert it without having to type the full name.

To support writing an expression into an input field, GoldSim provides a number of standard mathematical and relational operators.  The table below summarizes these operators, along with their precedence (the precedence of the operators determines the order in which the operators are evaluated – operators with higher precedence are evaluated before operators with lower precedence).

The logical operators And, Or and Not can also be used to build logical expressions (e.g., “X > Y And A <= B”).

More details about using operators can be found in GoldSim Help.

Note: When creating expressions, spaces are ignored, so you should feel free to add spaces to increase readability.  Note, however, that spaces are not allowed in unit strings (e.g., m3/sec) or when using a unary minus to denote a negative number (e.g., -3).

In addition to the operators listed above, GoldSim also provides a number of built-in functions (e.g., sin, cos, log, if) which can be used to build expressions. You can access and insert these functions by right-clicking in an input field to access the context menu, and selecting “Functions”:

This provides a list of function categories. If you select a function category, you will see a list of functions. Left-clicking on the function inserts it into the input field. Note that each function requires one or more arguments (in parentheses):

The various functions are described in detail in GoldSim Help.

Note that in addition to inserting functions from the context menu, you can also insert constants (e.g., pi, e, the gravitational constant).

GoldSim color-codes expressions to make them easier to read. For example, numbers and functions are black, output names are green, units are blue, and operators are gray. Invalid items are underlined and marked in red.  While an expression is invalid (as it always will be until you complete it), GoldSim marks the field in light red and provides a tool-tip describing why the expression is invalid.

Two other points regarding linked elements are worth noting:

• Although names are not case-sensitive, GoldSim will respect capitalization specified in the name.  That is, when you reference a name in the input field for another element, GoldSim will always display it using the case in which it was defined.  As a result, when naming elements, you can use capitalization to make the names more readable when they are referenced in other elements (e.g., FlowRate).
• If you change the name of an element (something that is not uncommon), and that element is linked to other elements in the model, GoldSim will automatically update the name in every place it is referenced.