In addition to simple mathematical statements, you can use multiline programmatic statements in your equations to evaluate more complex conditions. To enter these statements, you will need to access the extended equation editor by clicking on the arrow on the right side of any equation entry field (if you create a multiline statement, the standard equation editor will automatically be disabled):
Though Simgua equations might appear at first appear like simple mathematical equations, they are in actuality Visual Basic programmatic statements. This fact becomes obvious when you manipulate multiline expressions. The following is a selected set of advanced structures that can be useful in developing your equations. You should see the Programming Simgua section of this document for more details.
Note that when you use multiline statements, you need to explicitly return a value using the return command. The value that is returned is the result of the equation. Think of the return statement as an equals sign. In fact, you always need the return command, even with single line statements. Fortunately, Simgua automatically inserts it for you when you use a single line mathematical expression.
The Visual Basic If statement is probably the most useful advanced programmatic feature. It lets your equations take on a variety of different values depending on some logical conditional. It is like the IfThenElse function but more extensible and powerful.
If [Beta] > 0 Then
Return [Beta]^0.5
Else
Return [Beta]^2
End If
This is an example of an If statement that returns different manipulations of the Beta primitive’s value depending on whether the value of Beta is greater or less than zero. If Beta is greater than zero, the square root of beta is returned. Otherwise (and this is controlled by the else clause) the square of Beta is returned.
The logical statement used in this simple example is elementary; we can additionally use the following comparison operators[9]:
Table of Comparison Operators
|
Operator |
Meaning |
Examples |
|
< |
Less Than |
1 > 2 → False 2 > 1 → True |
|
> |
Greater Than |
1 < 2 → True 2 < 1 → False |
|
<= |
Less Than or Equal To |
2 <= 1 → False 2 <= 2 → True |
|
>= |
Great Than or Equal To |
2 >= 1 → True 2 >= 2 → True |
|
<> |
Not Equal To |
2 <> 1 → True 2 <> 2 → False |
|
= |
Equal To |
2 = 1 → False 2 = 2 → True |
You can chain together different comparisons using the following logical operators:
Table of Logical Operators
|
Operator |
Meaning |
Examples |
|
a and b |
True if both a and b are true, otherwise false. |
True and False → False False and False → False True and True → True |
|
a or b |
True if either a or b are true, otherwise false. |
True or False → True False or False → False True or True → True |
|
a xor b |
True if only exactly one of either a or b are true, otherwise false. |
True xor False → True False xor False → False True xor True → False |
|
not a |
True if a is false, otherwise false. |
not False → True not True → False |
For example the following two statements are equivalent:
Not ([Water Volume] > 0)
and
[Water Volume] <= 0
Check this yourself. When you think about it, the two statements both mean the same thing. The logical operator Not simply reverses the comparison operator
To continue with our discussion of If statements, the else clause can be omitted from If statements if it is not needed. Conversely, any number of ElseIf statements may also be added and strung together. For instance the following is a valid statement:
If Seconds < 100 Then
Return 1
ElseIf Seconds >= 100 and Seconds < 200 Then
Return 2
ElseIf Seconds >= 200 and Seconds < 10000 Then
Return 3
ElseIf Seconds < 200 Then
Return -99 //This will never happen
Else
Return 4
End If
This statement returns one of four values based on what the current time is in seconds. The statements are evaluated iteratively so the equation will never return -99 because one of the previous statements will be evaluated to true if the time in seconds is less than 200. Each If statement must have exactly one if command, one End If command, any number of ElseIf clauses, and one or zero else clauses. The Else clause, if it exists, must appear after all the ElseIf clauses.
This simple example illustrates another Simgua feature: comments. Any text following a ‘//’ or a single apostrophe will be treated as a comment by the equation evaluator and will be ignored when the equation is evaluated. For instance:
'I am a comment
Return 1 //I’m a comment too
Only the ‘Return 1’ part of the above code will be evaluated. Everything else is a comment and will be stripped out by the expression evaluator. All comments are terminated by the end of line character.
One additional important note is that if statements – along with most other Visual Basic programmatic statements – can be nested. For instance, the following is a valid expression:
If Seconds < 100 then
If [Alpha] > 10 then
Return 1
Else
Return -1
End If
Else
Return 4
End If
This example illustrates two if statements, one nested within the other. The inner statement will only be evaluated if the time in seconds is less than one hundred. The extended code editor will automatically indent and format your text for you as you type so that it has the same, easy to read appearance.
Variables allow you to store the values of certain items and then use them in other parts of your equations. You declare variables using the Dim statement. Here are some examples:
Dim i As Integer
Dim rain_level As Double
Dim row_val, col_val As Integer
Dim is_it_true As Boolean
You will notice that in addition to the Dim statement we also have to give the variable a type. There are three main types you will use: they are Integers, Doubles, and Booleans. An integer represents a numeric value without any decimals (ex. 1, 2, -123, 3,453). An integer can range in value from approximately negative two billion to positive two billion[10]. The double type represents a number that contains decimal places and has a much larger range than integers (ex. 1.2, 4.01, 4, -77.9012). Finally, a Boolean variable represents a simple True/False value.
Once a variable has been declared, you can then reference it in your equations. For example, the following is a simple demonstration of the use of variables where we declare and then reference the variable distance:
Dim distance As Double
distance = sqrt(x^2 + y^2)
If distance >= 100 Then
Return distance
Else
Msgbox “Distance is too short, must be at least 100 units long.”
Return -1
End If
The Msgbox function displays an alert window containing the specified text. Text in Visual Basic is known as a String. You can also declare string variables to store text and there are a number of functions available to manipulate strings (such as Uppercase, Lowercase, and TitleCase). All strings must be enclosed in a pair of double quotation marks.
Variable names can contain letters, numbers, and underscores. They must start with a letter and are case-insensitive. Variables are extremely powerful. We recommend that the reader refer to Visual Basic texts or other computer programming references to gain a further understanding of them.
A loop is a programmatic structure that allows you to repeat a block of code over and over again for a set number of times. There are many uses for such structures. For instance, in the case of an iterative algorithm, you will need to repeat a function until some condition is met (such as an error falling below a set threshold). The following is an example of a While loop:
Dim myError As Integer = 25
While myError > 10
WriteLn “reducing error”
myError = myError - 1
Wend
In the above example, the string “reducing error” would be printed to the console 15 times as the block of code bounded by the While statement is evaluated 15 times before its test condition becomes False. While statements are ended with the Wend command.
A For loop is executed a fixed number of times. The following is an example:
Dim i As Integer
For i=1 To 13
WriteLn str(i^2)
Next
This will print out the numbers “1”, “4” … “169” to the console. i is automatically updated by Simgua taking on the values 1 to 13 and the code within the block is executed for each one of those values. For loops are terminated with the Next command. Some additional syntax features can be used in for statements. For instance, the following is also a valid command.
Dim i As Integer
For i=7 DownTo 1 Step 3
WriteLn str(i^2)
Next
This block of code would print “49”, “16”, and “1”. This time due to the use of DownTo the loop counts downwards and because of Step it jumps three numbers at a time for each iteration of the loop.
There are many other useful programmatic structures in addition to the ones listed here. For example, there are select case statements, Do Until loops, and additional variants of the already listed structures. The reader is referred to Visual Basic programming books and tutorials to learn more about what is possible using Simgua’s Visual Basic equation engine.