Many of the SDDS toolkit programs employ a common Reverse Polish Notation (RPN) calculator module for equation evaluation. This module is based on the rpn programmable calculator program. It is also available in a commandline version called rpnl for use in shell scripts. This manual page discusses the programs rpn and rpnl, and indicates how the rpn expression evaluator is used in SDDS tools.
rpn is a program that places the user in a Reverse Polish Notation calculator shell. Commands to rpn consist of generally of expressions in terms of built-in functions, user-defined variables, and user-defined functions. Built-in functions include mathematical operations, logic operations, string operations, and file operations. User-defined functions and variables may be defined ``on the fly'' or via files containing rpn commands.
The command rpn filename invokes the rpn shell with filename as a initial command file. Typically, this file would contain instructions for a computation. Prior to execution of any files named the commandline, rpn first executes the instructions in the file named by the environment variable RPN_DEFNS, if it is defined. This file can be used to store commonly-used variable and function definitions in order to customize the rpn shell. This same file is read by rpnl and all of the SDDS toolkit programs that use the rpn calculator module. An example of such a file is included with the code.
As with any RPN system, rpn uses stacks. Separate stacks are maintained for numerical, logical, string data, and command files.
rpnl is essentially equivalent to executing rpn, typing a single command, then exiting. However, rpnl has the advantage that it evaluates the command and prints the result to the screen without any need for user input. Thus, it can be used to provide floating point arithmetic in shell scripts. Because of the wide variety of operations supported by the rpn module and the availability of user-defined functions, this is a very powerful feature even for command shells that include floating point arithmetic.
Built-in commands may be divided into four broad categories: mathematical operations, logical operations, string operations, and file operations. (There are also a few specialized commands such as creating and listing user-defined functions and variables; these will be addressed in the next section). Any of these commands may be characterized by the number of items it uses from and places on the various stacks.
For example, 1 sto one would create a variable called one and store the value 1 in it. To recall the value, one simply uses the variable name. E.g., one could enter 3.1415925 sto pi and later enter pi to retrieve the value of .
With the exception of sum, these operations all take two values from the numeric stack and push one result onto the numeric stack. For example, 5 2 - would push 5 onto the stack, push 2 onto the stack, then push the result (3) onto the stack.
sum is used to sum the top n items on the stack, exclusive of the top of the stack, which gives the number of items to sum. For example, 2 4 6 8 4 sum would put the value 20 on the stack.
With the exception of atan2 and pow, these operations all take one item from the numeric stack and push one result onto that stack.
sin and cos are the sine and cosine functions, while asin, acos, and atan are inverse trigonometic functins. atan2 is the two-argument inverse tangent: x y atan2 pushes the value with the result being in the interval .
sqrt returns the positive square-root of nonnegative values. sqr returns the square of a value. pow returns a general power of a number: x y pow pushes onto the stack. Note that if y is nonintegral, then x must be nonnegative.
exp and ln are the base-e exponential and logarithm functions.
cei1 and cei2 are the 1st and 2nd complete elliptic integrals. The argument is the modulus k, as seen in
the following equations (the functions K and E are those used by Abramowitz).
erf and erfc are the error function and complementary error function. By definition,
is unity. However, for large x, x erf 1 - will return 0 while x erfc will return a small, nonzero value.
The error function is defined as:
gamP and gamQ are, respectively, the incomplete gamma function and its complement
lngam is the natural log of the gamma function. For integer arguments, x lngam is
. The gamma function is defined as:
] is the memory store operator. A sequence of the form value index addr ] results in
value being stored in the index position of address addr. value, index, and addr are consumed in this operation. Indices start from 0.
Similarly, index addr [ value pushes the value in the index position of address addr onto the stack. index and addr are consumed in this operation.
int returns the integer part of the top value on the stack by truncating the noninteger part.
! && < == > ? $ vlog ||
&& || !
&&returns the logical and of the top two values, while || returns the logical or. ! is the logical negation operator.
Suppose we are running in the rpn shell and that the quantity 4 is initially pushed onto the stack. The command ``
0 < ? -1 : 1 $ '' that accomplishes the sign test will be executed as follows.
command stack logical stack 0 0 stack empty 4 < 0 false <-- new value 4 ? 1 : -1 $ 1 stack empty 0 4
0 < pop pop ? -1 : 1 $'', where the pop commands would eliminate the 0 and 4 from the stack before the conditional is executed.
If the command is executed with rpnl command in a C-shell, then the $
character has to be followed by a blank space to prevent the shell
from interperting the $ as part of variable:
"4 0 < pop pop ? -1 : 1 $ "
If the command is executed in a C-shell sddsprocess command to create
a new column, then we write:
sddsprocess <infile> <outfile> \ -def=col,NewColumn,"OldColumn 0 < pop pop ? -1 : 1 $ "
If the sddsprocess command is run in a tcl/tk shell, the $ character can be escaped with a backslash as well as with a blank space:
sddsprocess <infile> <outfile> \ "-def=col,NewColumn,OldColumn 0 < pop pop ? -1 : 1 \$"
Example: "commands.rpn,s" @ would silently execute the rpn commands in the file commands.rpn.
clos consumes the top of the numeric stack, and uses it as the number of a file to close.
gets consumes the top of the numeric stack to get a file number from which to read. It reads a line of input from the given file, and pushes it onto the string stack. The trailing newline is removed. If successful, gets pushes true onto the logic stack, otherwise it pushes false.
puts consumes the top of the string stack to get a string to output, and the top of the numeric stack to get a file number. Unlike the C routine of the same name, a newline is not generated. Both puts and fprf accept C-style escape sequences for including newlines and other such characters.