ConvertBot: implements a reverse polish calculator on elements of data files.

2020-04-27T22:05:10Z

implements a reverse polish calculator on elements of data files.

New page

implements a reverse polish calculator on elements of data files.
<pre>
<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

</pre>

[[Category:NXM_Explain]]

FCALCULATOR - Revision history

ConvertBot: implements a reverse polish calculator on elements of data files.