|
SimQuest 6.4 help |
|
|
Typing equations
An equation model is entered as a series of equations. There are some restrictions regarding what you can and cannot type in an equation. The SimQuest Equation Model Editor has its own debugger, which will let you know if you made a mistake after you have pressed Accept. Make sure however that you stick to the basic rules below.
A typical simple equation model takes the form:
force = mass * gravity torque = force * length
In this model the output variable force is calculated by multiplying the input variables mass and gravity. In the second equation, force is used as input variable to calculate torque. SimQuest uses the value of force from the first equation in the second.
Note: The order in which you enter equations does not matter; SimQuest determines the order of computation itself. Note: The case of the names is important; Velocity is different from velocity.
A typical differential equation model takes the form:
acceleration = force/mass velocity = acceleration dposition/dt = velocity
The meaning of this model is that at any moment during the simulation the first two equations hold, that is acceleration is computed from force, velocity is computed from acceleration. The third equation means that the change of the position is computed from the velocity. If at t=0 the position is 10, and the velocity is 2, at t = 1, the position will be 12, assuming the velocity does not change in this period. In mathematical terms, the equation dposition/dt is a differential equation and SimQuest knows how to handle these.
Apart from simple equations and differential equations, SimQuest also knows discrete state equations. These equations compute the new value of a variable out of the current state. These can be useful to handle discrete events, such as throwing a dice. For instance:
dice = random(1,6,true) new(total) = total + dice new(counter) = counter + 1 average = total/counter
Every time this model is computed, a random value is computed, which is added to an existing total. Also, a counter is incremented, so that the average can be computed. The equations starting with new(…) = are the discrete state equations. Discrete state equations can NOT be combined in one model with differential equations, (d../dt = …).
As will be clear, variables play a central role in SimQuest equation models. We have four types:
In order for a model to be able to run, all state, discrete state and input variables need to get an initial value. After your model has compiled, you can set the initial values in the model editor.
The general syntax of equation models is as follows:
<variable name> = <expression>
OR
<differential expression> = <expression> (where <differential expression> is d<variable name>/dt)
OR
<discrete state expression> = <expression> (where <discrete state expression> is new(<variable name>))
Variable names may be any sequence of letters and numbers, starting with a letter. Expressions are written down as simple mathematics expressions like:
a + b 3 4 * a a ^ 3 (i.e. a to the power of 3, a*a*a) sin a 5 * z + 8 * cos a 3 *(c + d) ‘a string’ (use single quotes for strings). true false (Boolean values) a & b (logical and) pi (= 3.1415926…)
Note: there is no need for parentheses as part of functions that take one argument, such as sin and cos, however they are not forbidden: cos(a) is as good as cos a.
Also, these functions have a low priority in computation order: cos a + 1 is computed as (cos a) + 1, not as cos(a+1). If you need the latter, parentheses should be used. Functions that can take more than one argument, such as random(), always get parentheses, even if the number of arguments is zero!
Conditional expressions are also possible:
b = if a > 0 then 5 else –5 endif
OR: b = 5 * if a > 0 then 1 else –1 endif
An if-then-else-endif construct is part of an expression, it is not a statement. It is not allowed to write:
if x < 0 then a = 1 else a = -1 endif (WRONG!)
This does not match the pattern for an equation.
Equations may extend over multiple lines. In most cases, especially with if-then-else-endif constructions, you can format the equations as you like such as:
b = if a> 0 then <some long expression> else <some long alternative expression> endif
In some cases you must tell the compiler explicitly that the next line is also part of the same equation. You can do this by typing an underscore (_) at the end of the line.
Comments can be inserted in the model. There are two ways for doing this. Short comments can be added at the end of the line by putting a semicolon (;) followed by the comment. The comment ends at the end of the line. Longer comments can be marked by double quotes:
a = b + c ; short comment b = squared d “a longer comment Spreading over multiple lines” d = 5 * z _ + 3 ; equation explicitly extended over two lines.
Above a few operators and functions (sin, cos) were introduced in the examples above. The complete list of functions and operators available in SimQuest is:
Apart from working with numbers, SimQuest can also calculate with a lot of numbers at a time. Consider the following example:
dx/dt = v dv/dt = a A = F/m F = - unity x * lengthSquared x * Q
At first this looks like a simple equation model, apart from the last line. But we can interpret x as a vector. A vector is a variable that consists of a number of numbers. For instance x may be equal to [3, 4, 6] (which may be entered in the model editor as initial value).. So x represents a three-dimensional vector. In this case dx/dt means that the change of each of the vector components is computed. In fact, almost every operation with vectors, applies to the individual components of the vectors. Some examples of vector operations are:
x = [0,2,5] assign a vector value to a variable [2,4,6] * [1,2,3] yields: [2,8,18] 4 * [1,2,3] yields: [4,8,12] sin [1,2] yields: [sin 1, sin 2]
and so on. Of course there are a few specific vector operations:
Sometimes it is handy to display a string instead of a numeric value. Therefore SimQuest equations can also handle strings, and convert strings to numbers and vice versa:
In some cases equations may result in errors. E.g., y = 1/x, will fail when x = 0. Of course this can be solved with an if-construction:
y = if x ~= 0 then toString(1/x) else ‘undefined’ endif
but if there are multiple points for error in an equation (e.g. y = 1/((x-3) * (x-a) *(x-b))), then there are three cases to be checked. SimQuest offers an easy way to trap all errors, using the try function:
y = try(toString(1/((x-3) * (x-a) *(x-b))), ‘undefined’)
The try function tries to compute and return the expression entered as its first argument. If an error occurs during this computation, the second argument is returned. The user should take care that the second argument will not result in an error as well.
|
