|
| 1 | +--- |
| 2 | +title: Parser Help |
| 3 | +category: info |
| 4 | +tags: parser |
| 5 | +layout: default_toc |
| 6 | +--- |
| 7 | + |
| 8 | +<link rel="stylesheet" href="css/main.css"> |
| 9 | + |
| 10 | +## Parser Description |
| 11 | + |
| 12 | + |
| 13 | +### Overview |
| 14 | + |
| 15 | +The SCIRun parser is designed to give the user the ability to evaluate almost any expression at the elements of a matrix or field. The underlying engine of the parser assumes that every field or matrix can be represented by an array of scalars, vectors, or tensors. For example a field can be represented by an array of scalars for the field data and an array of vectors for the locations of the nodes. In order to maintain a reasonable performance while interpreting a user defined function, the engine will apply each mathematical operations to the full array at same time. The logic of the parser will allow the user to write several expression at the same time, which will optimized to remove any duplicate function calls and the operations will be untangled in a series of elementary operations that have to be executed. |
| 16 | + |
| 17 | + |
| 18 | +### Using the parser |
| 19 | + |
| 20 | +Each parser has several preloaded variables available to the user. These preloaded variables in SCIRun are always denoted with an upper case variable name. For example for the [CalculateFieldData](modules.html#CalculateFieldData) has the following variables available: |
| 21 | + |
| 22 | + `DATA, X,Y,Z, POS` |
| 23 | + |
| 24 | +The variables can be used in the user to construct a new variable. For example, one can write the following equation: |
| 25 | + |
| 26 | + `MYDATA = sin(X)+cos(Y);` |
| 27 | + |
| 28 | +This will assign the value of `sin(X) + cos(Y)` to `MYDATA`, where `X` and `Y` are the arrays containing the `X` and `Y` positions of the nodes. Note that to generate a new variable, no new variable type needs to be declared. The parser will automatically derive the type of the output variable. For example the following case will generate vector data: |
| 29 | + |
| 30 | + `MYDATA = vector(Y,X,2*Z);` |
| 31 | + |
| 32 | +As the output of the expression is a vector `MYDATA` will now be an array of vectors instead of an array of scalars as in the previous example. |
| 33 | + |
| 34 | +To assign any data to the output of a module, certain variables need to be assigned. For example in case of the [CalculateFieldData](modules.html#CalculateFieldData), the output variable is called `RESULT` and hence a second expression can be added to assign the newly created vector to the output: |
| 35 | + |
| 36 | + `MYDATA = vector(Y,X,2*Z); RESULT = MYDATA;` |
| 37 | + |
| 38 | +Now this expression could have been simplified to one expression, which would result in the same operation: |
| 39 | + |
| 40 | + `RESULT = vector(Y,X,2*Z);` |
| 41 | + |
| 42 | +From a performance perspective both would be evaluated equally fast as, copying operations are generally removed by the internal optimizer. However to increase user readability one can split an expression in as many pieces as one wants. For example, the following expression is a perfectly valid expression: |
| 43 | + |
| 44 | + `DX = X-3; DY = Y-4; DZ = Z - 2; RESULT = norm(vector(DX,DY,DZ));` |
| 45 | + |
| 46 | +Hence the general grammar of the expression is: |
| 47 | + |
| 48 | + `VAR1 = function(...);` `VAR2 = function(...);` `VAR3 = function(...);` ... etc |
| 49 | + |
| 50 | +The array parser generally allows two types of input, an array with one element, or an array with many elements. When combining multiple fields or matrices, the arrays with many elements are required to have the same number of elements and the math operations are done by taking corresponding elements from each array. However an array with one element is treated special, and its value is used for every element for the arrays that have many arrays. For example, assume matrix `A = [1]`, and `B = [1,2,3,4]`. We can now evaluate the following expression: |
| 51 | + |
| 52 | + `RESULT = A+B;` |
| 53 | + |
| 54 | +In this case `RESULT` will be `[1+1,2+1,3+1,4+1]` and hence allows for scalar parameters to be added into the expressions. |
| 55 | + |
| 56 | + |
| 57 | + |
| 58 | +### Available functions |
| 59 | + |
| 60 | +The following basic operators have been implemented for Scalars, Vectors, and Tensors: |
| 61 | + |
| 62 | + `+`, `-`, `*`, `/`, `==`, `!=`, `!`, `&&`, `||` |
| 63 | + |
| 64 | +In addition to these operators the following functions are available: |
| 65 | + |
| 66 | + - `add()` |
| 67 | + - `sub()` |
| 68 | + - `mult()` |
| 69 | + - `div()` |
| 70 | + - `exp()` |
| 71 | + - `log()` |
| 72 | + - `ln()` |
| 73 | + - `log2()` |
| 74 | + - `log10()` |
| 75 | + - `sin()` |
| 76 | + - `cos()` |
| 77 | + - `tan()` |
| 78 | + - `asin()` |
| 79 | + - `acos()` |
| 80 | + - `atan()` |
| 81 | + - `sinh()` |
| 82 | + - `cosh()` |
| 83 | + - `asinh()` |
| 84 | + - `acosh()` |
| 85 | + - `pow()` |
| 86 | + - `ceil()` |
| 87 | + - `floor()` |
| 88 | + - `round()` |
| 89 | + - `boolean()` |
| 90 | + - `norm()` |
| 91 | + - `isnan()` |
| 92 | + - `isfinite()` |
| 93 | + - `isinfinite()` |
| 94 | + - `select()` |
| 95 | + - `sign()` |
| 96 | + - `sqrt()` |
| 97 | + - `not()` |
| 98 | + - `inv()` |
| 99 | + - `abs()` |
| 100 | + - `and()` |
| 101 | + - `or()` |
| 102 | + - `eq()` |
| 103 | + - `neq()` |
| 104 | + |
| 105 | + |
| 106 | + |
| 107 | +**For vectors the following functions are available:** |
| 108 | + |
| 109 | +To construct a vector use the following function: |
| 110 | + |
| 111 | + `MYVECTOR = vector(X,Y,Z);` |
| 112 | + |
| 113 | +To access the components of a vector use the following functions: |
| 114 | + |
| 115 | + `X = x(MYVECTOR);` `Y = y(MYVECTOR);` `Z = z(MYVECTOR);` |
| 116 | + |
| 117 | +The following vector specific functions are available: |
| 118 | + |
| 119 | + - `dot()` |
| 120 | + - `cross()` |
| 121 | + - `normalize()` |
| 122 | + - `find_normal1()` |
| 123 | + - `find_normal2()` |
| 124 | + |
| 125 | +**For tensors the following functions are available:** |
| 126 | + |
| 127 | +To construct a tensor use the following functions: |
| 128 | + |
| 129 | + `MYTENSOR = tensor(XX,XY,XZ,YY,YZ,ZZ);` |
| 130 | + |
| 131 | + `MYTENSOR = tensor(SCALAR);` |
| 132 | + |
| 133 | + `MYTENSOR = tensor(EIGVEC1,EIGVEC2,EIGVAl1,EIGVAL2,EIGVAL3);` |
| 134 | + |
| 135 | +To access the components of a tensor use the following functions: |
| 136 | + |
| 137 | + `XX = xx(MYTENSOR); XY = xy(MYTENSOR); XZ = xz(MYTENSOR);` |
| 138 | + |
| 139 | + `YY = yy(MYTENSOR); YZ = yz(MYTENSOR); ZZ = zz(MYTENSOR);` |
| 140 | + |
| 141 | + `EIGVEC1 = eigvec1(MYTENSOR); EIGVEC2 = eigvec2(MYTENSOR); EIGVEC3 = eigvec3(MYTENSOR)` |
| 142 | + |
| 143 | + `EIGVAL1 = eigval1(MYTENSOR); EIGVAL2 = eigval2(MYTENSOR); EIGVAL3 = eigval3(MYTENSOR);` |
| 144 | + |
| 145 | + |
| 146 | + |
| 147 | +**The following tensor specific functions are available:** |
| 148 | + |
| 149 | + `quality()`, `trace`, `det()`, `frobenius()`, `frobenius2()`, `fracanisotropy()` |
| 150 | + |
| 151 | +For converting any Scalar, Vector or Tensor in to a boolean, e.g. whether all components are equal to zero or not, the function `boolean()` provided: |
| 152 | + |
| 153 | + `RESULT = boolean(vector(X,0,Z));` |
| 154 | + |
| 155 | + `RESULT = boolean(vector(X,0,Z)) || boolean(tensor(4)*0);` |
| 156 | + |
| 157 | +The `select()` function works like the C/C++ ternary `?:` operator: |
| 158 | + |
| 159 | + `RESULT = select(X>2,1,0);` |
| 160 | + |
| 161 | +To insert a random number two functions are provided, `rand()` and `randv()`. Neither of them take any input. The first one just render a single random number and the second renders an array of the same size as the other arrays. For example to render uniform distributed noise between 0 and 2 for a field, use the following expression: |
| 162 | + |
| 163 | + `RESULT = 2*randv();` |
| 164 | + |
| 165 | +If on the other hand all the values need to be the same, but one random value, use : |
| 166 | + |
| 167 | + `RESULT = rand();` |
| 168 | + |
| 169 | +Finally, we have an object called element, which refers to the element of a mesh. The latter only exists as an input object, but allows the user to query, properties like element quality metrics and sizes. Currently the following functions are implemented: |
| 170 | + |
| 171 | + `center()`,`volume()`,`size()`,`length()`,`area()`,`dimension()` |
0 commit comments