FCALCULATOR

implements a reverse polish calculator on elements of data files.

<LABEL>     - Label for the output file.
<param 1:N> - Parameters for the fcalc function.

Evaluates the expression contained in the list of <variables/operators/files>
entries and stores the answer(s) in the output file(s). Reverse Polish Notation
is used (just like most HP calculators). The NeXtMidas version of calculator
extends the syntax to allow multiple outputs per calculation. If this syntax
is not used, it assumes the 1st argument is the name of the single output file
as in the X-Midas version. This version also allows results or expressions
to be recomputed as the files are processed by using the /MON switch.

If multiple input files are given with different lengths, the computations
will stop after then end of the shortest file is reached. The resulting output
file will have the same size as the *shortest* input file.

Though at least one input for an operator needs to be a file, there is no restriction on order.
(As of 3.5.1 there is no longer a requirement that the first input be a file)

3 input operators can have 2 of their 3 inputs be constants (as of 3.5.1).

Note1: Since NeXtMidas 2.5.0, the string infinity can be used in computations.
Note2: Since NeXtMidas 2.6.0, the LOG, LN, and DB operators may return NaN
       (Not a Number) for negative arguments, and also treat zero arguments as
       if they were very small positive values, in order to avoid returning
       -infinity for log(0.0).  The old pre 2.6.0 backwards compatible behavior
       (incoming arguments were bounded at 1.0e-12 and the absolute value was
       always taken) is available via the LOG/B, LN/B, and DB/B operators.
Note3: Note that at the start of each JVM session, the initial seed value is set
       to 12345678 and this seed is used for the uniformly distributed RANDOM
       number generation. This consistent non-random setting of seed allows for
       consistent random data generation for testing across repeated session.
       SETSEED must be used if a truly random seed is required for each session.
       Since NeXtMidas 3.1.1: The RANDOM/P are RANDOM/S operators provide
       alternative random number generation that always are with a random seed.

Operators:
   +   : addition                        -   : subtraction
   *   : multiplication                  /   : division
   ~   : conjugate of complex            ~*  : complex conjugate multiplication
   ~/  : complex conjugate division
   **  : power

   Comparators:
   -----------
   EQ : equal to
   LT : less than                      GT : greater than
   LE : less than or equal to          GE : greater than or equal to

   Trigonometric and Angle Functions:
   ---------------------------------
   COS : radians                       ACOS  : principal value (radians)
   SIN : radians                       ASIN  : principal value (radians)
   TAN : radians                       ATAN  : principal value (radians)
                                       ATAN2 : principal value (radians)
   POLAR : complex rect to polar       RECT  : complex polar to rect
   PHASE : phase of complex

   All functions dealing with angles are by default in radians.
   To express in degrees, append a D to the operator.
   To express in cycles, append a C to the operator.
   This applies to SIN,COS,TAN,ASIN,ACOS,ATAN,ATAN2,PHASE,POLAR,RECT

   COMPLEX NUMBERS
   ---------------
   ADDC        : Alias for ~+
   CMPLX       : Convert a real number <r> into a complex number (<r>,0)
   CONJ        : Alias for ~
   DIVC        : Alias for ~/
   MULC        : Alias for ~*
   REAL, IMAG  : Get the REAL or IMAGINARY part of a complex number
   SUBC        : Alias for ~-

   Bit Manipulations:
   -----------------
   BOR  : bitwise OR         BAND : bitwise AND
   BXOR : Exclusive OR       BNOT : Complement

   Miscellaneous (in alphabetical order):
   -------------------------------------
   ADD     : Alias for +
   ABS     : absolute value
   CEIL    : Get the closest fixed point number above given real number
   CLIP    : CLIP value to within a MAX,MIN range, i.e. MIN (b, MAX(c,a)) where
               a=value, b=maximum, c=minimum
   DB      : Convert number to DB (precise)
   DB/B    : Convert number to DB (precise & bounded - see Note2 above)
   DBF     : Convert number to DB (fast, less precise)
   DEMUX   : demux complex into 2 scalars
   DIV     : Alias for /
   DOT     : dot product of two vectors
   EXP     : natural exponential
   FIX     : real to integer truncation
   FLOOR   : Get the closest fixed point number below given real number
   LOG     : base 10 logarithm
   LOG/B   : Base 10 logarithm (bounded - see Note2 above)
   LN      : natural logarithm
   LN/B    : Natural logarithm (bounded - see Note2 above)
   MAG     : magnitude of complex
   MAG2    : magnitude squared
   MAX     : maximum of 2 values (Alias is MAXIMUM)
   MIN     : minimum of 2 values (Alias is MINIMUM)
   MUL     : Alias for *
   MUX     : mux 2 scalars into complex
   MOD     : Same as MOD/T
   MOD/E   : Euclidean Modulo function (always positive)
   MOD/F   : Floored Modulo function (sign follows divisor)
   MOD/T   : Truncation Modulo function (Java % operator)
   POW     : Alias for **
   POWER2  : Gets the power of 2 number >= given number
   RANDOM  : Pseudo-random number (0, 1). See Note3 above.
   RANDOM/P: Pseudo-random number [0, 1) (see java.util.Random - Since 3.1.1)
   RANDOM/S: Cryptographically secure-random number using [0, 1)
             (see java.security.SecureRandom - Since 3.1.1)
   ROUND   : real to integer rounding
   SQRT    : square root
   SQUARE  : Square a number
   SUB     : Alias for -
   VMUX    : mux 3 scalars into vector
   VDEMUX  : Demux vector into 3 scalars
   WRAP    : Wrap data to a range (usually phase to -180 to 180)
   UNWRAP  : UnWrap data from a range (usually phase to -180 to 180)

   Stack Operations:
   ----------------
   PUSH : push top of stack (duplicate)
   POP  : pop the top of stack (discard)
   <>   : swaps the top two values on the stack
   ?:   : compare top of stack to zero and select top-1 if > or top-2
          if not "D=(C>0)?A:B"

   >name : pops the top of the stack to the named output file
   <name : pushes contents of named input file onto the stack

  All entries are treated first as operators.  If the entry does not match any
  of the supported operators, it is tested to be a results parameter. If it can
  not be evaluated as a result, it is assumed to be a file name. Therefore, the
  operators identified above cannot be used as variable names.  The <name form
  for input files avoids trying to parse them as operators or constants.

  NOTE: When using in-line file trimming the <name input file form may be
  necessary to avoid generating errors while trying to parse them as constants
  or operators.

  The conversion of each numeric input parameter is handled by the Convert.s2o()
  routine. Thus, in-line calculations can be used within a parameter even though
  that argument is treated using reverse polish by the rest of the fcalculator
  command.

  NOTE: FIX and ROUND do NOT convert the file format to fixed point. Use the
        /type switch to alter the output file format.

  NOTE: Operations are defined in the Operators.cnf file. New operators may be
        added and defined in this file and the code is generated with the
        command:
          nM> GENERATE OPER ALL

Examples:
 1. Standard form:
      fcalc/type=l outfile infile1 infile2 + infile3 *

 2. Explicit form (for 1st difference):
      fcalc <infile1 <infile1(1:) - >outfile

 3. Explicit form multiple output:
      fcalc <infile push 2 / >outfile1 10 * >outfile2

 4. Code snippet to show how this command can be used in a pipe and results and
    expressions. In this example, the output of fcalc changes as the Multiplier
    control (gc.multiplier) is changed (see nxm.sys.test.test_fcalculator for
    a detailed implementation of this example).

      ...
      pipe on
        panel/setup/controls=gc
        gcontrol lval multiplier "Multiplier" 2 1 10 1
        ...
        waveform,OUT=_wave,FORM=SF,ELEM=5e9,SHAPE=CONST,AMP=1
        fcalc/mon _out _wave gc.multiplier.value-1 *
      pipe off

Switches:
  /MON        - Treat results and expressions as variables that can be changed
                as the file(s) are processed. Usually used in a pipe section.
  /TL         - The number of elements to be read each process loop [DEF=1024]
  /TYPE=D|F|L - Data type for calculations (defaults to F)


SEE ALSO: CALCULATOR, nxm.sys.libm.Operators.cnf, nxm.sys.libm.ArgStack.java,
SEE ALSO: nxm.sys.test.test_fcalculator.mm