________________________________________________________________
   
                       VPCalc Documentation, Part 3
     ________________________________________________________________
   
   Functions - 
   
   Functions are used on the right hand side of an equation or
   assignment statement. Functions do not change the value of their
   arguments, but produce a single result that can be used to further
   complete the evaluation of the expression that contains the function
   reference. If a statement starts with a function reference like a
   procedure, then the function is evaluated and this value is assigned
   to the current active item.
   
   Abs(X) = AbsoluteValue(X):
   
   Absolute value function = |X|.
   
   ACos(X) = ArcCoSine(X):
   
   Inverse of Trigonometric CoSine function, error if |X| > 1. If the
   degree mode is set, the answer, A, will be in the range 0 <= A <=
   180. If the radian mode is set, the answer will be in the range 0 <=
   A <= Pi.
   
   ACosH(X) = ArcHyperbolicCoSine(X):
   
   The positive inverse of Hyperbolic CoSine function, error if X < 1.
   
   ASin(X) = ArcSin(X):
   
   Inverse of Trigonometric Sine function, error if |X| > 1. If the
   degree mode is set, the answer, A, will be in the range -90 <= A <=
   90. If the radian mode is set, the answer will be in the range -Pi/2
   <= A <= Pi/2.
   
   ASinH(X) = ArcHyperbolicSine(X):
   
   Inverse of Hyperbolic Sine function.
   
   ATan(X) = ArcTangent(X):
   
   Inverse of Trigonometric Tangent function. If the degree mode is set,
   the answer, A, will be in the range -90 <= A <= 90. If the radian
   mode is set, the answer will be in the range -Pi/2 <= A <= Pi/2.
   
   ATan2(Y' X) = ArcTangent(Y over X):
   
   Trigonometric ArcTangent function. Used to find the Polar coordinates
   angle coordinate of the Cartesian coordinates (X, Y). If the degree
   mode is set, the answer, A, will be in the range -180 < A <= 180. If
   the radian mode is set, the answer will be in the range -Pi < A <=
   Pi. If both X and Y are zero, an answer of zero will be given.
   
   ATanH(X) = ArcHyperbolicTangent(X):
   
   Inverse of Hyperbolic Tangent function, error if|X| >= 1.
   
   Cos(X) = CoSine(X):
   
   Trigonometric CoSine function, error if |X| is very large.
   
   CosH(X) = HyperbolicCoSine(X):
   
   Hyperbolic CoSine function.
   
   Exp(X) = eToThePower(X):
   
   Evaluates to e raised to the X power, where e is the base of the
   natural logarithms. The item Ln10 = Ln(10) is put on the list when
   needed by the exponential functions. If Ln10 is not on the list, the
   file Ln10.VPN is read-in and Ln10 added to the list. If the file
   Ln10.VPN is not found, Ln10 is computed.
   
   ExpL(X) = eToThePower(X) - 1:
   
   Evaluates to one less than e raised to the X power, where e is the
   base of the natural logarithms. This function is needed when an
   expression contains Exp(X) - 1 and X can take on small values.
   ExpL(X) is accurate for small X.
   
   Fac(X) = Factorial of Int(X):
   
   Factorial function = 1 * 2 * 3 * ... * X. Only the integer portion of
   X is used in the calculation.
   
   Frac(X) = FractionalPart(X):
   
   Fractional part function. Frac(X) = X - Int(X).
   
   GCD(X' Y) = Greatest Common Divisor:
   
   Greatest common divisor function. Uses the oldest algorithm in the
   book, Euclid's algorithm (see Euclid's Elements, Book 7, Proposi-
   tions 1 and 2). Only the integer parts of X and Y are used in the
   computation. For example, the GCD of 12 and 18 is 6.
   
   Int(X) = IntegerPart(X):
   
   Integer part function. For X >= 0, Int(X) is the largest integer less
   than or equal to X. Int(-X) = -Int(X);
   
   Inv(X) = 1 / X:
   
   Inverse or reciprocal function, 1.0 divided by X, error if X = 0.
   
   Ln(X) = NaturalLog(X):
   
   Evaluates to the Log base e of X, where e is the base of the natural
   logarithms, error if X <= 0.
   
   LnL(X) = NaturalLog(X + 1):
   
   Evaluates to the Log base e of (X + 1), where e is the base of the
   natural logarithms, error if X <= -1. This function is needed when an
   expression contains Ln(X + 1) and X can take on a value near zero.
   ExpL(X) is accurate for values of X near zero.
   
   Log(X) = LogBase10(X):
   
   Evaluates to the Log base 10 of X, error if X <= 0.
   
   Lop(X) = ReducePrecision(X):
   
   This function evaluates to X with its least significant super-digit
   removed. If rounding is turned on, the removed super-digit is used to
   round into the new least significant super-digit. In VPCalc numbers
   are normalized from both sides. If a calculation results in a number
   with some trailing zero bytes, these bytes are removed by reducing
   the count of the number of bytes in the mantissa, and memory is
   reallocated. The Lop function can result in many bytes being removed
   if removing one byte results in many trailing zeros.
   
   Mag(X' Y) = SqRt(Sq(X), Sq(Y)):
   
   Magnitude of (Y, X) function Used to find the Polar coordinates
   radius coordinate of the Cartesian coordinates (X, Y).
   
   Mod(X' Y) = X - (Int(X/Y) * Y):
   
   Modulo function. Mod(X' Y) = X - (Int(X/Y) * Y). Where Int(X/Y) is
   the integer part of X/Y. The sign of Mod(X' Y) is equal to the sign
   of X. An error message is generated if Y = 0.
   
   PowM(X' Y) = (X to the power Y) Mod FMB:
   
   The Exponential function with modulo arithmetic. This function
   operates differently depending on whether Y is an exact integer. If Y
   is an exact integer, the peasants' method is used in which up to 2 *
   Log base 2 of Y multiplies of powers of X are done to compute the
   result. The Modulo process is performed after each multiply to
   prevent the intermediate results from becoming large. If Y is not an
   exact integer, the result is computed by Exp(Y * Ln(X)) Mod FMB. If
   FMB is not on the list, it is added to the list with a value of zero.
   If FMB is zero, the Modulo is not performed. An error message is
   generated in three cases: 1) X is < 0 and Y is not an integer. 2) X =
   0 and Y is < 0. 3) X = 0 and Y = 0.
   
   RN(X) = RandomNumber(Seed=X):
   
   Random number function. RN(X) evaluates to a random number between
   zero and 1.0. This number will never have more than 35 decimal
   digits. Theoretically the random number generator will cycle after 10
   ** 35 numbers, but the earth will not last that long. The fractional
   part of the argument of the function is taken as the seed of the
   random number generator. For a consecutive set of random numbers, the
   argument X should be the previous random number generated. The items
   RNA and RNC are put on the list by the random number function. The
   equation used is: RN(X) = (RNA * X * 10^35 + RNC) mod (10^35) /
   10^35, where RNA and RNC are 35 digit integers.
   
   Sin(X) = Sine(X):
   
   Trigonometric Sine function, error if |X| is very large.
   
   SinH(X) = HyperbolicSine(X)
   
   Hyperbolic Sine function.
   
   Sq(X) = X Squared:
   
   The square function, X times X.
   
   SqRt(X) = SquareRoot(X):
   
   The positive square root function, error if X < 0.
   
   Tan(X) = Tangent(X):
   
   Trigonometric Tangent function, error if |X| is very large. It is
   also an error if X is equivalent to plus or minus 90 degrees.
   
   TanH(X) = HyperbolicTangent(X):
   
   Hyperbolic Tangent function.
   
   ToDeg(X) = RadiansToDegrees(X):
   
   Converts radians to degrees. Evaluates to X multiplied by 180/Pi.
   
   ToRad(X) = DegreesToRadians(X):
   
   Converts degrees to radians. Evaluates to X multiplied by Pi/180.
   
   -X = Negative of X, 0 - X:
   
   Negative inverse of X. The -, +, and ! functions do not require the
   parentheses so they also can be considered as unary or monadic
   operators.
   
   +X = Positive of X, 0 + X:
   
   The identity operator, +X = X.
   
   !X = Not X, 0 -> 1 else 0:
   
   Logical Not operator. Not X (!!X) will leave 0.0 alone and will
   change all other values to 1.0 (True).
   
   If, GoTo, GoUpTo, Label, Continuation lines -
   
   The following commands are primarily for use in VPCalc code files,
   but can be used from the Command: prompt line.
   
   If Command:
   
   The If command is the first word of an If statement. The syntax of
   the If statement is:
   
   If <expression> Then <statements> Else <statements>
   
   The expression following the If is evaluated and if it is True, i.e.,
   not zero, all statements on the same line following the next Else are
   deleted and execution continues with the statements following the
   Then. If the expression evaluates to zero (False), all statements
   following the expression up to the next Else are deleted and
   execution continues with the statements following the next Else. The
   Then key word is optional, the Then <statements> is optional and the
   Else <statements> is optional.
   
   The equivalent of a case statement can be constructed for example
   like:
   
   If A=1 B=3 Else If A=2 B=5 Else If A=3 B=7 Else B=0
   
   If A is an integer, this is equivalent to:
   
   B=0 If (1 <= A) & (A <= 3) Then B=2*A+1
   
   GoTo Command:
   
   The GoTo <label> command will skip all statements following the GoTo
   until <label>: is found and then start executing the state- ments
   following the <label>:. If the GoTo command is in a VPCalc code file,
   lines of input also will be skipped until the <label>: is found or
   until an end-of-file. If the line containing the GoTo is from the
   Command: prompt line, only statements on the current line will be
   skipped. It is not an error if the <label>: is not found, but a GoTo
   end-of-file or end-of-line will be performed in this case.
   
   GoUpTo Command:
   
   The GoUpTo <label> command will skip all statements following the
   start of the current line until <label>: is found and then start
   executing the statements following the <label>:. If the <label>: is
   not found on the current line and the GoUpTo command is in a VPCalc
   code file, the file will be reset to the first line of the file and
   lines of input will be skipped until the <label>: is found or until
   an end-of-file. If the line containing the GoUpTo is from the
   Command: prompt line, only statements on the current line will be
   skipped. It is not an error if the <label>: is not found, but a GoTo
   end-of-file or end-of-line will be performed in this case.
   
   Labels:
   
   A label is a name followed by a colon (:). When encountered as a
   command, a label is a no-op. When searching for where to go from a
   GoTo <label> or from a GoUpTo <label> command, the <label>: is used
   to determine where to restart execution. If duplicate labels are on a
   command line or in a code file, the first one encountered is the one
   that is effective.
   
   Continuation lines:
   
   Continuation lines are indicated by the last non-blank character of
   the line being a + or - character. A + says, this line is to be
   continued by adding the next line, but a blank character should be
   included between them if it is needed to separate fields. A - says,
   this line is to be continued by adding the next line, but no blank
   character should be included between them.
   
   Batch Commands (Echo, @Echo, Pause, and Rem) -
   
   The following commands are primarily for use in VPCalc code files,
   but can be used from the Command: prompt line.
   
   Echo Command:
   
   Normally, commands from a VPCalc code file are displayed on the
   screen as they are executed. This can be turned off by the Echo off
   command and turned on by the Echo on command. If something other than
   or more than on or off follow the word Echo, it is considered a
   message and is output to the screen.
   
   @Echo Command:
   
   The @Echo command is the same as the Echo command except that, if it
   is the first command on a line, it is executed before the command
   line is echoed to the screen. Thus, an @Echo off at the beginning of
   a line will do an Echo off without the command being echoed to the
   screen.
   
   Pause Command:
   
   The pause command will output the following message to the screen and
   wait for operator input of any key:
   
   Strike a key when ready . . . _
   
   Everything on the line following the word Pause is considered a
   remark and is skipped. VPCalc code file processing can be interrupted
   by pressing the ESC key and can be terminated by pressing the ESC key
   twice.
   
   Rem Command:
   
   The syntax of the Rem command is Rem <remark>. It is a no-op command
   and everything on the line following the word Rem is skipped.
   
   Transcendental Function Evaluation -
   
   All transcendental functions, Sin(X), Cos(X), ASin(X), ACos(X),
   Tan(X), ATan(X), Exp(X), ExpL(X), Ln(X), LnL(X), Log(X), SinH(X),
   CosH(X), TanH(X), ASinH(X), ACosH(X), ATanH(X), and ATan2(Y' X), when
   they are evaluated, ends up using one of the four basic
   transcendental functions, Sin(X), ATan(X), ExpL(X), and LnL(X). The
   methods used by these four functions are quite similar: 1) For F(X),
   reduce the given argument X to a related argument f. 2) Further
   reduce f, NN times in a recursive loop to produce an argument g much
   smaller than f. 3) Evaluate the Taylor series for the argument g. 4)
   Reconstruct F(f) from F(g) by a recursive process executed NN times.
   5) Reconstruct the desired function value F(X) from F(f).
   
   The number NN in steps 2) and 4) is computed by a heuristic equation
   of the form NN = a + b * SqRt(M) where a and b are constants and M is
   the current max decimal digits in a mantissa. The best value of NN is
   the value that produces the smallest total execution time. After step
   4) a best value of NN is computed and output by estimating a value of
   NN that would have made the running time of step 3) equal the sum of
   the running time of steps 2) and 4). Best NN = NN * SqRt(T3 / (T2 +
   T4)). Where Tn is the time to execute step n). This equation is based
   on T2 and T4 being proportional to NN and T3 being inversely
   proportional to NN.
   
   If the operator wants to control the value on NN, he can enter a
   value on the list for item MSinNN, MATanNN, MExpLNN, MLnLNN to
   control the value used for NN in the Sin(X), ATan(X), ExpL(X), and
   LnL(X) functions respectively.
   
   The recursive method used to reduce the argument for Sin(X) is based
   on the equation: Sin(X) = Sin(X/3) * (3 - 4 * Sq(Sin(X/3))). In step
   2) f is divided by 3, NN times to produce g. In step 4) the
   recursion: S = S * (3 - 4 * Sq(S)), is performed NN times, where S is
   initially the value of Sin(g) produced in step 3) and the final value
   is Sin(f).
   
   The recursive method used to reduce the argument for ATan(X) is based
   on the equation: Tan(X/2) = Tan(X) / (1 + SqRt(1+Sq(Tan(X))). In step
   2) the recursion: T = T / (1 + SqRt(1 + Sq(T))), is performed NN
   times, where T is initially the value of f from step 1) and the final
   value of T is the value of g for step 3). In step 4) the angle value,
   A = ATan(g), produced in step 3) is multiplied by 2, NN times to
   produce ATan(f).
   
   The recursive method used to reduce the argument for ExpL(X) is based
   on the equation: Exp(X) = Sq(Exp(X/2). In step 2) f is divided by 2,
   NN times to produce g. In step 4) the recursion: A = A * (2 + A), is
   performed NN times, where A is initially the value of ExpL(g)
   produced in step 3) and the final value is ExpL(f). The recursion A =
   A * (2 + A) is equivalent to, but more accurate than, the recursion E
   = Sq(E), where E = A + 1;
   
   The recursive method used to reduce the argument for LnL(Y) is based
   on the equation: Ln(X) = 2 * Ln(SqRt(X)). In step 2) the recursion: Y
   = Y / (1 + SqRt(1 + Y)), is performed NN times, where Y is initially
   the value of f from step 1) and the final value of Y is the value of
   g for step 3). In step 4) the log value L = LnL(g) produced in step
   3) is multiplied by 2, NN times to produce LnL(f). The recursion Y =
   Y / (1 + SqRt(1 + Y)) is equivalent to, but more accurate than, the
   recursion X = SqRt(X), where Y = X - 1;
   
   If the diagnostic mode is on, the values computed for NN in the four
   subroutines MSin, MATan, MExpL, and MLnL are displayed, for example,
   as:
   
           MExpL: NN = 22.299
           MExpL: NN = 21
           Best   NN = 21.935 +/- 1.633

   In this example the MExpL subroutine estimated NN to be 22.299. A
   value of NN = 21 was actually used (this is not 22 because the number
   being worked on was less than 3, the base number used to generate the
   heuristic equation). Based on the actual timing of the run, the best
   value for NN is computed to be 21.935. Due to the uncertainty of the
   timing, the Best NN could be off by + or - 1.633.
   
   The Taylor series used for Sin(X) is: Sin(X) = X - X^3 / 3! + X^5 /
   5! ...
   
   The Taylor series used for ATan(X) is: ATan(X) = X - X^3 / 3 + X^5 /
   5 ...
   
   The Taylor series used for ExpL(X) is: ExpL(X) = X + X^2 / 2! + X^3 /
   3! ...
   
   The Taylor series used for LnL(Y) is: LnL(y) = Ln(1+y) =
   Ln((1+z)/(1-z)) = 2 * (z + z^3/3 + z^5/5 ...) Where x = 1+y = (1+z) /
   (1-z), y = x-1 = 2 * z / (1-z), z = (x-1) / (x+1) = y / (2+z).
   
   Other equations used to produce the transcendental functions:
   
   Cos(X) = Sin(X + Pi/2).
   
   Tan(X) = Sin(X) / SqRt(1 - Sq(Sin(x)), and change sign of Tan(X) if
   in 2nd or 3rd quadrant, but error if X is equivalent to plus or minus
   90 degrees.
   
   ASin(S) = ATan2(S, SqRt(1 - Sq(S)), but error if |S| > 1.
   
   ACos(C) = ATan2(SqRt(1 - Sq(C), C), but error if |C| > 1.
   
   Log(X) = Ln(X) / Ln(10), but error if X <= 0.
   
   For X >= 0.1, SinH(X) = (Y - 1/Y) / 2, where Y = Exp(X), for X < 0.1,
   SinH(X) = Y / (2 * SqRt(Y+1)), where Y = ExpL(2*X), and SinH(-X) =
   -SinH(X).
   
   CosH(X) = (Y + 1/Y) / 2, where Y = Exp(|X|).
   
   TanH(X) = Y / (Y + 2), where Y = ExpL(2 * X), and TanH(-X) =
   -TanH(X).
   
   For X >= 0.1, ASinH(X) = Ln(X + SqRt(1 + Sq(X))), for X < 0.1,
   ASinH(X) = LnL(X + Sq(X) / SqRt(1 + Sq(X))), and ASinH(-X) =
   -ASinH(X).
   
   ACosH(X) = Ln(X + SqRt(Sq(X) - 1)), but error if X < 1.
   
   ATanH(X) = LnL(2 * X / (1 - X)), but error if |X| >= 1, and ATanH(-X)
   = -ATanH(X).
   
   Error reports -
   
   There are many different error reports like
   
   Cannot divide by zero, continuing...
   
   that are a result of directly or indirectly requesting an operation
   that cannot be performed. Another type of error is the syntax error,
   where a command cannot be interpreted. The syntax errors are:
   
          Error in function's argument: <name>(|<string>
          Error in function's 2nd argument: <name>(...'|<string>
          Exponent expected: ^<sign>|<string>
          Expression expected: (IF |<string>
          Expression expected: (|<string>
          Expression expected: <name>(|<string>
          Factor expected: <op>|<string>
          Input line continuation too long: |<string>
          Simple Expression expected: <op>|<string>
          Term expected: <op>|<string>
          Unknown function: |<name>(<string>
          Unknown operation, Command line discarded: |<string>
          ( expected: <name>|<string>
          "File name expected: <name>(|<string>

   The vertical bar | always shows the start of the string of characters
   that cannot be interpreted.
   
   The end -
   
   Report any errors by sending me a letter or call me at my home voice
   phone (408) 741-0406 evenings or weekends.
   
                              Harry J. Smith
                            19628 Via Monte Dr.
                            Saratoga, CA 95070