FCALCULATOR
Jump to navigation
Jump to search
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