Math Expression Language (short:ME-L) supports numerous forms of functional, logical and vector processing semantics and has been extended to support thinkingParticles OpenVDB operations.

In it's core, ME-L is based on the highly optimized ExprTk library which, in addition, has been highly modified to enhance OpenVDB and thinkingParticles operations. If you want to learn more about the inner workings, check the following web page: http://www.partow.net/programming/exprtk/

t - current animation animation time in seconds

dt - delta time from one to the next sub sample in seconds

valueoff - return value used to to turn off a value (e.g. removing voxel)

vp - vector position in voxel space (vp[0] represents x, vp[1] represents y, vp[2] represents z)

op - vector position in object (particle) space

wp -vector position in world space

bp - vector position relative to bounding box space x,y,z normalized to 0 - 1. 0,0,0 representing bottom left corner

cbp - vector position in center of the bounding box space, x,y,z where the center is 0,0,0 extending to 1,1,1 and -1,-1,-1 respectively.

fv - scalar value from- or written to the voxel. Example: fv := 1 will set all voxels to value of 1.0. 

vv - equivalent to fv but for vector values. This is used for voxel values within a vector grid (color, uvw, or velocity).

Example:
vv[0] := 0.5; vv[1] := 0.5; vv[2] := 0.5; sets the voxel of a color grid to r,g,b gray of 0.5  

noise(x,y,z) - 3D perlin noise function

noise(x,y) - 2D perlin noise

ncellular(x,y,z) - 3D cellular

nchip(x,y,z) - 3D cellular in chip mode

nvoronoi(x,y,z) - 3D voronoi    

rndseed(s) -set random seed
    
rnd01() - random value between  0.0 to 1.0

rnd11() - random value between -1.0 to 1.0

rndxx(x,y) - random value between  x to y

lowhighcut(v, low, high) - convert range between low and high to 0.0 and 1.0    

ndistance(vector pos1, vector pos2, norm_radius) - distance between (position1 - position2).length / norm_radius

distance(vector pos1, vector pos2) - distance between (position1 - position2).length

dir_length(invector, outdirection) -  outdirection will receive the return vector (direction)

Example:
var length;
var dir[3];
length = dir_length(invec, dir);

sqrdistance(vector pos1, vectorpos2) - distance between (position1 - position2).length_sqr

Note: 
Positions can be 1D,2D, 3D or even multidimensional.

Example:
pos1[1] is 1D,
pos1[2] is 2D
pos1[3] is 3D

ME-L supports three fundamental types which can be used freely in expressions. The types are as follows:

1. Scalar
2. Vector
3. String

Scalar 
The scalar type  is a singular  numeric value. 

Vector 
The vector is a fixed size sequence of contiguous scalar  values. A  vector  can be  indexed  resulting in  a  scalar value.  Operations between a vector and scalar will result in a vector with a size  equal to that  of the  original vector,  whereas operations  between vectors will result in a  vector of size equal  to that of the  smaller of the two. In both mentioned cases, the operations will occur element-wise.

String 

The string type is a variable length sequence of 8-bit chars.  Strings can be  assigned and concatenated to  one another,  they can  also be manipulated via sub-ranges using the range definition syntax.  Strings however can not interact with scalar or vector types.

Expressions in ME-L can be  comprised of one or more statements. The following are  two examples of expressions stored in variables, the  first is a single statement and the second a multi-statement  expression:

  z := x + y;

   var temp := x; 
   x := y + z;    
   y := temp;  

In a  multi-statement expression, the final statement will determine the overall result of the expression. In the following multi-statement expression, the result of the expression when evaluated will be '2.3',
which will also be the value stored in the 'y' variable.

   z := x + y;
   y := 2.3;

As  demonstrated  in  the  expression  above,  statements  within   an expression are  separated using the semi-colon  ';' operator.  In the event  two  statements are  not  separated by  a  semi-colon, and the implied multiplication  feature is  active (enabled  by default),  the compiler  will  assume  a multiplication  operation  between  the two statements.

In the following example we have a multi-statement expression composed of two variable definitions and initialization for variables x and  y and two seemingly separate mathematical operations.

   var x:= 2;
   var y:= 3;
   x + 1
   y * 2

However the result of  the expression will not  be 6 as may  have been assumed based on  the calculation of  'y * 2',  but rather the  result will be 8. This  is because the compiler  will have conjoined the  two mathematical statements into one  via a multiplication operation. The expression when compiled will actually evaluate as the following:

   var x:= 2;
   var y:= 3;
   x + 1 * y * 2;   // 2 + 1 * 3 * 2 == 8

Any valid statement will itself return a value.  This value can  further  be  used  in conjunction with other statements. This includes language structures such as if-statements, loops (for, while) and the switch statement. Typically the last statement executed in the given construct (conditional, loop etc), will be the value that is returned.

In the following example, the  return value of the expression  will be 11, which is the sum of the variable 'x' and the final value  computed within the loop body on its last iteration:

   var x := 1;
   x + for (var i := x; i < 10; i += 1)
       {
         i / 2;
         i + 1;
       }

ME-L support two forms of conditional branching or  otherwise known as if-statements. The first form, is a  simple  function   based conditional  statement, that  takes exactly  three input  expressions: condition, consequent  and alternative.  The following  is an  example expression that utilizes the function based if-statement.

   x := if (y < z, y + 1, 2 * z)

In the  example above,  if the condition 'y< z'  is true, then the consequent 'y + 1' will be evaluated, its value will be  returned  and subsequently assigned to the  variable 'x'. Otherwise the  alternative '2 *  z' will  be evaluated  and its  value will  be returned. This is essentially the  simplest form of  an if-then-else statement. A simple variation of the expression where the value of the if-statement is used within another statement is as follows:

   x := 3 * if (y < z, y + 1, 2 * z) / 2

The second form of if-statement resembles the standard syntax found in most imperative languages. There are two variations of the statement:

   If-Statement
   If-Then-Else Statement

This version  of the  conditional statement  returns the  value of the consequent expression when the condition expression is true,  else it will return a quiet NaN value as its result.

   Example 1:
   x := if (y < z) y + 3;

   Example 2:
   x := if (y < z)
        {
          y + 3
        }

The two  example expressions  above are  equivalent. If  the condition 'y < z' is true, the  'x' variable will be  assigned the value of  the consequent 'y + 3', otherwise it  will be assigned the value of  quiet NaN.  As  previously  discussed,  if-statements  are  value  returning constructs, and if  not properly terminated  using a semi-colon,  will end-up  combining  with  the  next  statement  via a multiplication
operation. The following example will NOT result in the expected value of 'w + x' being returned:

   x := if (y < z) y + 3  // missing semi-colon ';'
   w + x

When the  above supposed  multi-statement expression  is compiled, the expression  will  have  a multiplication  inserted  between  the  two 'intended' statements resulting in the unanticipated expression:

   x := (if (y < z) y + 3) * w + x

The  solution  to  the  above situation  is  to simply  terminate the conditional statement with a semi-colon as follows:

   x := if (y < z) y + 3;
   w + x

The second variation of  the if-statement is to  allow for the use  of Else and If-Else cascading statements. Examples of such statements are as follows:

In  the case  where  there  is no  final else  statement and  the flow through the conditional  arrives at this  final point, the  same rules apply to this form of if-statement as to the previous. That is a quiet NaN will be  returned as the  result of the  if-statement. Furthermore the same requirements of terminating the statement with a semi-colon apply.

Variables are of numeric type denoting a single value. They can be explicitly initialized to a value, otherwise they will be defaulted to zero. The following are examples of variable definitions:

   Initialize x to zero
       var x;

   Initialize y to three
       var y := 3;

   Initialize z to the expression
       var z := if (max(1, x + y) > 2, w, v);

Vectors are arrays of a common numeric type. The elements in a  vector can be explicitly initialized, otherwise they will all be defaulted to zero.The following are examples of vector definitions:

   initialize all values to zero
       var x[3];

   initialize all values to zero
       var x[3] := {};

   initialize all values to given expression
       var x[3] := [123 + 3y + sin(w / z)];

   initialize the first two values, all other elements to zero
       var x[3] := { 1 + x[2], sin(y[0] / x[]) + 3 };

   initialize the first three (all) values
       var x[3] := { 1, 2, 3 };

   initialize vector from a vector
       var x[4] := { 1, 2, 3, 4 };
       var y[3] := x;

   initialize vector from a smaller vector
       var x[3] := { 1, 2, 3 };
       var y[5] := x;   // 1, 2, 3, ??, ??

   Non-initialized vector
       var x[3] := null; // ?? ?? ??

   Error as there are too many initializers
       var x[3] := { 1, 2, 3, 4 };

   Error as a vector of size zero is not allowed.
       var x[0];

Strings are sequences comprised of 8-bit characters. They can only be defined with an explicit  initialization value. The following are examples of string variable definitions:

   Initialize to a string
       var x := 'abc';

   Initialize to an empty string
       var x := '';

   Initialize to a string expression
       var x := 'abc' + '123';

   Initialize to a string range
       var x := 'abc123'[2:4];

   Initialize to another string variable
       var x := 'abc';
       var y := x;

   Initialize to another string variable range
       var x := 'abc123';
       var y := x[2:4];

   Initialize to a string expression
       var x := 'abc';
       var y := x + '123';

   Initialize to a string expression range
       var x := 'abc';
       var y := (x + '123')[1:3];

Variable and vector definitions have a  return value. In  the case of variable definitions, the value  to which the variable  is initialized will be returned. Where as for vectors, the value of the first element
(eg: v[0]) will be returned.

   8 == ( (var x := 7;) + 1)
   4 == (var y[3] := {4, 5, 6};)

The value of a variable can be assigned to a vector and a vector or a vector expression can be assigned to a variable.

Variable To Vector:
      Every element of the vector is assigned the value of the variable
      or expression.
      var x    := 3;
      var y[3] := { 1, 2, 3 };
      y := x + 1;

Vector To Variable:
      The variable is assigned the value of the first element of the
      vector (aka vec[0])
      var x    := 3;
      var y[3] := { 1, 2, 3 };
      x := y + 1;

ME-L provides  support  for various forms of vector oriented arithmetic, inequalities and processing. The various  supported pairs are as follows:

   vector and vector (eg: v0 + v1)
   vector and scalar (eg: v  + 33)
   scalar and vector (eg: 22 *  v)

The following is a list of operations that can be used in  conjunction with vectors:

   Arithmetic:       +, -, *, /, %
   Exponentiation:   vector ^ scalar
   Assignment:       :=, +=, -=, *=, /=, %=, ⇔
   Inequalities:     <, ⇐, >, >=, ==, =, equal
   Boolean logic:    and, nand, nor, or, xnor, xor
   Unary operations:
       abs, acos, acosh, asin, asinh, atan, atanh, ceil, cos,  cosh,
       cot, csc,  deg2grad, deg2rad,  erf, erfc,  exp, expm1, floor,
       frac, grad2deg, log, log10, log1p, log2, rad2deg, round, sec,
       sgn, sin, sinc, sinh, sqrt, swap, tan, tanh, trunc
   Aggregate and Reduce operations:
       avg, max, min, mul,  dot, dotk, sum, sumk,  count, all_true,
       all_false, any_true, any_false
   Transformation operations:
       copy, rotate-left/right, shift-left/right, sort, nth_element
   BLAS-L1:
       axpy, axpby, axpyz, axpbyz, axpbz

Note: When one of  the above  described operations is being performed between two  vectors, the operation will  only span  the size  of the smallest vector. The elements  of the  larger vector  outside of the range will  not be included. The  operation  itself will be processed element-wise over values the smaller of the two ranges.

The  following  simple  example  demonstrates  the vector processing capabilities by computing the dot-product of the vectors v0 and v1 and then assigning it to the variable v0dotv1:

   var v0[3] := { 1, 2, 3 };
   var v1[3] := { 4, 5, 6 };
   var v0dotv1 := sum(v0 * v1);

The following is a for-loop based implementation that is equivalent to the previously mentioned dot-product computation expression:

   var v0[3] := { 1, 2, 3 };
   var v1[3] := { 4, 5, 6 };
   var v0dotv1;

   for (var i := 0; i < min(v0[],v1[]); i += 1)
   {
     v0dotv1 += (v0[i] * v1[i]);
   }

Note: When  the aggregate or reduction  operations denoted  above are used  in conjunction with a  vector or  vector  expression, the return value is not a vector but rather a single value.

   var x[3] := { 1, 2, 3 };

   sum(x)      ==  6
   sum(1 + 2x) == 15
   avg(3x + 1) ==  7
   min(1 / x)  == (1 / 3)
   max(x / 2)  == (3 / 2)
   sum(x > 0 and x < 5) == x[]