[3.0] VEE Math Functions

v5.0 / 3 of 23 / 01 sep 99 / gvg

* This chapter discusses VEE math functions and how to make use of them.

[3.1] OVERVIEW
[3.2] OPERATOR CATEGORIES
[3.3] FUNCTION CATEGORIES
[3.4] ITERATIVE COMPUTATIONS

[3.1] OVERVIEW

* As noted in earlier chapters, VEE's math functions are selected through the Math & Functions / Select Functions dialogue box:


   +--------------------------------------------------------------------+
   | Select Function                                                 [x]|
   +--------------------------------------------------------------------+
   | Type                        Category             Name              |
   | +-------------------------+ +------------------+ +---------------+ |
   | | Operators               | | <All>            | | concat        | |
   | | Built-in Functions      | | Array            | | init          | |
   | | Local User Functions    | | Bessel           | | product       | |
   | | Imported User Functions | | Bitwise          | | rotate        | |
   | | Compiled Functions      | | Calculus         | | sort          | |
   | |                         | | Complex Parts    | | sum           | |
   | |                         | | Data Filtering   | | totSize       | |
   | +-------------------------+ +------------------+ +---------------+ |
   | concat(x,y)                                                        |
   |                                                                    |
   | [ Returns concatenated containers.                               ] |
   |                                                                    |
   +--------------------------------------------------------------------+
   |                      [  OK  ] [ Cancel ] [ Help ]                  |
   +--------------------------------------------------------------------+

The features of this dialogue box relative to UserFunctions and Compiled Functions will be discussed in a later chapter.

All operators and functions obtained from this dialogue box are effectively customized versions of the Formula box, and can be modified by the user at will by adding or deleting pins, changing pin names, or editing the formula.

Note that as of VEE 4.X, the Formula box has been considerably enhanced: not only can you use array elements on both sides of operations, but you can include multiple formulas in the same formula box and (necessarily) set up multiple output pins.


		      +--------------------------------------------+
                      |                   Formula                  |
   +-----------+      +---+------------------------------+---------+
   | Integer A +----->| A |                              | Result  +-->
   +-----------+      |   |[ C = A[7], A[3,5] = B[5,7] ] |    A    +-->
                  +-->| B |                              |    B    +-->
   +-----------+  |   |   |                              |    C    +-->
   | Integer B +--+   +---+------------------------------+---------+
   +-----------+

The different VEE operators and functions are detailed following.

[3.2] OPERATOR CATEGORIES

* The dialogue provides access to the following categories of operators:

Arithmetic.
Assignment.
Comparison.
Logical.
Miscellaneous.

The Arithmetic operators operators include the conventional math operators:


   +   -   *   /   DIV   MOD   ^

This is a good place to mention that VEE is not strongly typed -- operations between different data types can be remarkably transparent -- and that most operations can be performed on both scalars and arrays (more on this in the next chapter). VEE is also remarkably transparent between numeric and string operations and almost obsessively tries to resolve string expressions. For example, if you perform:


   4 * A

-- and "A" is the string "bogus!", you'll get the concatenation:


   bogus!bogus!bogus!bogus!

One of the reasons I emphasize this is not only because this can be handy at times, but because if you get your data inputs a little scrambled you can end up with some really baffling results. (The transparency of VEE to data types is generally a plus, but sometimes it leads to problems.)

The Assignment operators are essentially a set of representative samples that show how to do various kinds of assignments in formulas:


   a[2,*,5,6,4]=b               Assign to array row/column.
   a[2]=b                       Assign to array element.
   globalA=2*b+3                Assign to variable.
   rec.field=b                  Assign to field of record.
   rec.field[2]=b               Assign to array element of field.
   rec[2].field=b               Assign to field of element of record array.
   tmp=a,a=b,b=tmp              Multiple assignments. 
   tmp=a[2],a[2]=a[3],a[3]=tmp  Multiple assignments.

The Comparison operators include:


   a != b                       Not equals.
   a < b                        Less than.
   a > b                        Greater than.
   a == b                       Equals.
   a <= b                       Less than or equals.
   a >= b                       Greater than or equals.
   a ~= b                       Almost equals (7 decimal places).

The Logical operators include:


   a AND b
   a OR  b
   a XOR b
   a NOT b

Note that these are not bitwise operators! The Miscellaneous operators are another set of representative operations:


   (a ? b : c)                  Triadic.
   Pi                           Value of Pi.
   [1,2,3]                      Array construction.
   [a,b,c]                      Array construction.
   a[2]                         Array element.
   a[5,3:4,*]                   Array row/column.
   rec.field                    Record field.

The Triadic operator is a conditional test. Given:


   (a ? b : c)

-- then if "a" is true (nonzero), "b" will be returned. If "a" is false (zero), then "c" will be returned. Any test condition can be used to replace "a"; any expression (including another triadic) can replace "b" or "c". For example:


   ( a == 1 ? "YES" : "NO" )

This returns the string "YES" if the input pin is 1 and returns "NO" otherwise. You can cascade triadics if you like:


   ( a == 1 ? "ONE" : ( a == 2 ? "TWO" : "OTHER" ))

Unlike most VEE functions, the triadic cannot perform array computations. However, it can be a lot of fun trying to figure out ingenious things to do with it (also more on this in the next chapter).

[3.3] FUNCTION CATEGORIES

* The VEE predefined functions include:

Array.
Bessel.
Bitwise.
Calculus.
Complex Parts.
Data Filtering.
Generate.
Matrix.
Panel.
Power.
Probability & Statistics.
Real Parts.
Signal Processing.
String.
System Information.
Time & Date.
Trig.

* The Array functions include:


   concat(x,y)               Concatenates elements in an array.
   init(x,value)             Initializes array to given value.
   product(x)                Multiplies all elements in an array together.
   rotate(x,numElem)         Rotates elements in array.
   sort(x)                   Sorts an array.
   sum(x)                    Sums all elements in an array.
   totSize(x)                Gives total size of an array.

* The Bessel functions (for those who understand such things) consist of:


   Ai(x)
   Bi(x)
   i0(x)
   i1(x)
   j0(x)
   j1(x)
   jn(x,n)
   k0(x)
   K1(x)
   y0(x)
   y1(x)
   yn(x,n)

* The Bitwise functions include:


   bit(x,n)                     Gets a bit value.
   bitAnd(x,y)                  AND two sets of bits.
   bitCmpl(x)                   Negate (invert) two sets of bits.
   bitOr(x,y)                   OR two sets of bits.
   bitShift(x)                  Shift bits left or right.
   bitXor(x,y)                  Exclusive-OR two sets of bits.
   bits(str)                    Returns binary value of a string of 1s & 0s.
   clearBit(x,n)                Clears a bit value.
   setBit(x,n)                  Sets a bit value.

* The Calculus functions include:


   integral(x)                  Integral as function.
   deriv(x,1)                   Derivative as function
   defIntegral(x,a,b)           Integral as value.
   derivAt(x,1,pt)              Derivative as value.

* The Complex Parts functions include:


   j(x)                         Generates complex x.
   re(x)                        Returns real part of complex number
   im(x)                        Returns imaginary part of complex number
   mag(x)                       Magnitude of complex number.
   phase(x)                     Phase angle of complex number.
   conj(x)                      Complex conjugate of complex number.

* The Data Filtering functions include:


   clipLower(x,a)               Clips above minimum given value.
   clipUpper(x,a)               Clips below maximum given value.
   maxIndex(x)                  Returns index in array of maximum element.
   maxX(x)                      Returns index in 1D array of maximum element.
   meanSmooth(x,numPts)         Smooths data by averaging around data point.
   minIndex(x)                  Returns index in array of minimum element.
   minX(x)                      Returns index in 1D array of minimum element.
   movingavg(x,numPts)          Smooths data with moving average.
   polySmooth(x)                Smooths data using a polynomial fit.

* The Generate functions include:


   logRamp(numElem,from,thru)   Generates a log-ramp array.
   ramp(numElem,from,thru)      Generates a linear-ramp array.
   xlogRamp(numElem,from,thru)  Generates a log-ramp array.
   xramp(numElem,from,thru)     Generates a linear-ramp array.

* The Matrix functions provide various common matrix-math operations:


   cofactor(x,row,col)          Take cofactor of matrix.
   det(x)                       Takes determinant of array.
   identity(x)                  Returns identity matrix.
   inverse(x)                   Takes inverse of array.
   matDivide(numer,denom)       Divide two matrices (multiply by inverse).
   matMultiply(A,B)             Multiply two matrices.
   minor(x,row,col)             Take minor of matrix.
   transpose(x)                 Transposes matrix.

* The Panel functions allow manipulation of UserFunction panels:


   hidePanel(ufname)            Hide UserFunction panel.
   lockPosition(ufname)         Lock UserFunction panel into place.
   panelPosition(ufname)        Gives panel position as coordinate data.
   panelSize(ufname)            Gives panel size as coordinate data.
   showPanel(ufname)            Show UserFunction panel.
   unlockPosition(ufname)       Allow user to move panel around.

* The Power functions provide log, exponential, and related operations:


   cubert(x)                    Cube root (x^(1/3)).
   exp(x)                       e^x.
   exp10(x)                     10^x.
   log(x)                       Natural (base-e) log of x.
   log10(x)                     Base-10 log of x.
   poly(x,...)                  Polynomial evaluation.
   recip(x)                     Reciprocal or inverse (1/x or x^-1).
   sq(x)                        Square (x^2).
   sqrt(x)                      Square root (x^(1/2)).

* The "Probability & Statistics" entry provides various functions:


   beta(x,y)                    Beta function.
   binomial(a,b)                Combinations of a objects b at a time.
   comb(n,r)                    Combinations of n objects r at a time.
   erf(x)                       Error function.
   erfc(x)                      Complementary error function. 
   factorial(n)                 Factorial of n1 (n!).
   gamma(x)                     Gamma function.
   logMagDist(x,from,thru,step) Log magnitude distribution. 
   magDist(x,from,thru,step)    Magnitude distribution.    
   max(x)                       Maximum value of data set.
   mean(x)                      Average value of data set.
   median(x)                    Median (middle) value of data set.
   min(x)                       Minimum value of data set.
   mode(x)                      Most common value of data set.
   perm(n,r)                    Permutations of n objects r at a time.
   random(low,high)             Returns random number.
   randomSeed(seed)             Creates random "seed".
   randomize(x,low,high)        Generates set of random numbers.
   rms(x)                       Root-mean-square value of data set.
   sdev(x)                      Standard deviation of data set.
   vari(x)                      Variance of data set.

* The "Real Parts" functions consist of:


   abs(x)                       Absolute value.
   ceil(x)                      Returns rounded-up value of x.
   floor(x)                     Returns rounded-down value of x.  
   fracPart(x)                  Fractional part of x. 
   intPart(x)                   Integer part of x.
   ordinal(x)                   Selects ordinal value of enumerated objects.
   round(x)                     Returns rounded-off value of x.
   signof(x)                    Sign of value ( -1 / 0 / 1 if <0 / 0 / >0).

* The "Signal Processing" entry provides Fourier and Inverse Fourier transform, convolution, and data windowing functions:


   bartlet(x)                   Bartlet window.
   blackman(x)                  Blackman window.
   convolve(a,b)                Convolution.
   fft(x)                       Fast Fourier transform.
   hamming(x)                   Hamming window.
   hanning(x)                   Hanning window.
   ifft(x)                      Inverse Fast Fourier transform.
   rect(x)                      Rectangular window.
   xcorrelate(a,b)              Correlation.

* The "String" functions include:


   charToInt(a)                 Convert character to ASCII code. 
   intToChar(a)                 Convert ASCII code number to character.
   strDown(str)                 Converts string to lowercase.
   strFromLen(str,from,len)     Returns substring of given length.
   strFromThru(str,from,thru)   Returns substring between indexes.
   strLen(str)                  Length of string.
   strPosChar(str,char)         Returns position of character in string.
   strPosStr(str1.str2)         Returns position of substring in string.
   strRev(str)                  Reverses string order.
   strTrim(str)                 Strips leading and trailing whitespace.
   strUp(str)                   Converts string to uppercase.

* The "System Information" functions include:


   errorinfo()                  Returns error message for error number.
   getEnv(envar)                Read value of environment variable.
   getHostName()                Get network name of current host.
   installDir()                 Get name of VEE install directory.
   help(topic,helpfile)         Invoke helpfile entry.
   whichOS()                    Get name of current OS.
   whichPlatform()              Get name of current platform.
   whichVersion()               Get current VEE version.

The "whichOS()" function obtains the operating system type; it returns:


   Windows
   Windows95
   WindowsNT
   HP-UX
   SunOS

The "whichPlatform()" function returns the hardware platform name:


   PC
   HP9000s300
   HP9000s700
   SPARCstation

* The "Time & Date" functions include:


   dmyToDate(d,m,y)             Convert day-month-year to date.
   hmsToHour(h,m,s)             Converts hours-minutes-seconds to hours.
   hmsToSec(h,m,s)              Converts hours-minutes-seconds to seconds.
   mday(aDate)                  Convert time to day of month.
   month(aDate)                 Convert time to month.
   now()                        Current time (in seconds since day zero).
   wday(aDate)                  Convert time to day of week.
   year(aDate)                  Convert time to year.

* The "Trig" functions include:


   acos(x)
   acosh(x)
   acot(x)
   acoth(x)
   asin(x)
   asinh(x)
   atan(x)
   atan2(y,x)
   atanh(x)
   cos(x)
   cosh(x)
   cot(x)
   coth(x)
   sin(x)
   sinh(x)
   tan(x)
   tanh(x)

* There are also functions that allow you to force data to be of a particular type. This is handy on occasion:


   asInt16()
   asInt32()
   asReal()
   asText()

[3.4] ITERATIVE COMPUTATIONS

* The VEE math functions are powerful, and as mentioned can be used to perform array computations (as will be explained in detail in the next chapter).

However, performing interative or recursive computations is tricky. For example:


   X(n) = X(n-1) + B*U(n)

-- where X and U are vectors (1D arrays) and B is a real scalar. Performing such calculations isn't hard in the absolute sense, but it's one of those things which requires having your brain pretty well wrapped around VEE -- and so it also makes an excellent tutorial example.

In any case, the solution is as follows:


                                                           +--------------+
                                                           | AlphaNumeric |
							   +--------------+
	     +-------------------------------------+       | 0: 9         |
   +------+  |                                     |       | 1: 21        |
   | Init |  +-->+-----+                           |   +-->| 2: 39        |
   +------+      | JCT +--+                        |   |   | 3: 75        |
   | 0    +----->+-----+  |                        |   |   | 4: 84        |
   +------+ Real          |                        |   |   | 5: 87        |
                          |   +-----------------+  |   |   +--------------+
   +------+               |   |     Formula     |  |   |
   |  B   |               |   +---+-------------+  |   +--------------+
   +------+               +-->| X |             |  |                  |
   | 3    +------------------>| B | X + B*U[N]  +--+-->+-----------+  |
   +------+ Real      +------>| U |             |      | Collector +--+
                      |   +-->| N |             |  +-->+-----------+   
                      |   |   +---+-------------+  |                   
                      |   |                        |
   +---------------+  |   |                        +------+
   |       U       |  |   |                               |
   +---------------+  |   +----------------------------+  |
   | 0000: 3       |  |                                |  |
   | 0001: 4       |  |   +---------+   +-----------+  |  |
   | 0002: 6       +--+-->| TotSize +-->| For Count +--+  |
   | 0003: 12      |      +---------+   +-----+-----+     |
   | 0004: 3       |                          |           |
   | 0005: 1       |                          +-----------+
   +---------------+ Real

This program works as follows:

There are three Real Constants driving the program: an initial value for X, the constant B, and the constant array U.
The output array X is produced dynamically by a collector that obtains the results of each iteration of the computation.
The number of iterations is given by the size of the array B (through the Totsize() function); this is the same as the size of the output array X. The size is loaded into a For Count object, which drives the computation through its iterations and then fires its Sequence Out pin when done.
A Formula box performs the actual computation, X + B*U[N]. The input pin X is fed through a Junction that connects to the Init constant (for the initial value in the first iteration) and to the output of the Formula itself (for all other iterations).
The outputs of the Formula box are also put into an array by a Collector and then output when the For Count object reaches the end of its count.

Note that if you are using feedback loops in versions of VEE before 4.0, you will need to put a Start button on the Init object. It was one of the eccentricities of VEE that it insisted on having one for feedback loops.