cdfmath −− do point by point mathematics on common data format grids
cdfmath ’expression’
Cdfmath expects a Candis common data format file on the standard input and writes a modified file to the standard output. The modifications are the result of point by point math operations on existing or new fields, and are controlled by the reverse Polish notation expression on the command line. For instance, the expression ’a b * 3 + log c =’ multiplies the fields "a" and "b" together on a point by point basis, adds 3, takes the natural logarithm, and stores the result in the field "c". The fields "a", "b," and "c" may or may not exist. If they don’t, they will be created in the variable slice section of the output file. Generally, new fields should only be created if they are being assigned a value. The dimensionality of new fields is the union of the dimensionalities of the fields previously indicated in the expression.
More formally, an expression is made up of a sequence of elements, separated by one or more spaces, each element being one of four types, "field", "constant", "function", or "operator". Any constant expressible in "d", "f", or "g" format (C language) may be used. Functions have the same name and operation as those in the C language math library. Those currently available are "exp", "sin", "cos", "log", "log10", "pow", "atan2", "mod", and "abs". Available operators are "+", "−", "*", "/", ">", "<", "?", and "=". Sine and cosine arguments are in degrees rather than radians, and atan2 returns degrees in the range 0 to 360.
All operations occur on a stack. The occurence of a variable or a constant pushes the corresponding value onto the stack. The six arithmetic operators pop the top two stack values, perform the operation, and push the result onto the stack. The assignment operator, "=", stores the value second from top on the stack in the field represented by the top entry. Functions pop the appropriate number of arguments off the stack, perform the action, and push the result back on the stack. For multi−argument functions, the order that fields occur in the expression is the same as the order in which they are given to the function. Any bad data values in the calculation result in a bad data value result. Cdfmath tries to protect against failures due to inappropriate math operations, e. g., logarithm of a negative number or dividing by zero. In these cases the result is silently given a bad data value.
The "<", ">", and "?" operators deserve special comment. The expression "a b > c =" means that the value of a is stored in c if a > b. Otherwise the bad data value is stored. The elements a and b may be either fields or constants, but c must be a field. Note that "a b > c =" is different from "b a < c =" −− the latter expression stores the value of b in c rather than the value of a. The "?" operator has three arguments. If the first argument is bad, then the third argument is returned. Otherwise the second argument is returned. Thus, the combination "a 0 > b c ? d =" puts the value of b into d if a > 0, and puts the value of c into d otherwise.
Cdfmath performs all calculations over all dimensions over which the input fields are defined. The index fields are used to define the available space of grid points, so index fields for each exercised dimensions must exist. If a particular field doesn’t vary in a particular dimension, its values in that dimension are simply assumed to be constant. If an existing field that is being assigned to is of lower dimension than the calculation, just the first instances of the unavailable dimensions will be assigned.
Certain consistency checks are made. Trying to pop more entries off the stack than exist results in a syntax error. The assignment operation must leave the stack empty. No more than 50 elements may occur in a single expression, but multiple calculations may be done in sequence, e. g., ’a b + c = d f − exp a =’.
Input may come from either the static or the current variable slice, but assignment may only be done to the variable slice. Assignment to the static slice is done after that slice is written, and so has no effect on the output. However, such assignment will affect the next calculation using that field.
More than four index fields on input result in failure.
If dimension names in fields occur in a different order than the corresponding index fields in the static slice, cdfmath will fail with an error message. The ordering of index fields and dimensions can be changed using cdforder.