[qv]<IDL>Manual>APPENDIXE.BRAVO!1

As mentioned in Chapter 3, IDL redefines the Lisp arithmetic and comparison functions in order to substitute functions with the appropriate extensions. However, the Lisp arithmetic and comparison functions are still available as functions of the form fn.LISP for some renamed function fn. The functions whose definitions have been changed are: PLUS, TIMES, DIFFERENCE, QUOTIENT, SQRT, EXPT, LOG, SIN, COS, TAN, ARCSIN, ARCCOS, ARCTAN, ARCTAN2, EQP, GREATERP, LESSP, REMAINDER, MAX, MIN, MINUS, MINUSP, ABS, GCD.

A possible difficulty that faces the user who intermixes IDL and Lisp functions in a program is that IDL scalars may not be Lisp numbers. That is, if V is a vector, V@’(3) may be neither FIXP nor FLOATP, but an object of type ARRAYFRAME. These objects will be handled correctly by all Lisp’s arithmetic functions (even those that have not been redefined), but FIXP, FLOATP, SMALLP, and NUMBERP will not be true of them. SCALARP will be true of them, however. The equivalent of NUMBERP is (AND (SCALARP X) (NOT (EQP X NIL))). Note also that what appears to be a small integer might actually be a pointer to a large number box, so that EQ tests should be used cautiously.

The efficiency gained by following these principles will ordinarily be negligible for very small objects (under, say, a hundred elements), but will grow to significant levels as larger arrays are processed.

1.Use EAPPLY and ELAMBDA to avoid generating intermediate results. Consider the example, discussed in section 8.4.1, of computing x2 for two arrays O and E by using the expression ((O–E)↑2)/E. This generates the array O–E and then (O–E)↑2, before producing the result. If instead, the formula is expressed as an ELAMBDA function which expects scalars, and this is then applied to the arrays O and E, no unnecessary results will be computed.

EAPPLY provides a mechanism for "splitting up" arrays that are too big (i.e., of too great dimensionality) for a function to handle; calling the function once for each split piece; and "pasting together" the returned values from the function calls into a result array. Its exact operation is quite complex, and some notation has to be introduced to make a precise specification possible.

Say an extended function has N arguments, numbered from left to right as 1, ..., i, ..., N. For each argument i, call the number of dimensions the function expects in that position ai, and call the number of dimensions of the argument actually supplied, bi. If ai is NIL (i.e., the function will accept any argument), EAPPLY will ignore this argument and pass it to the extended function, without change, on every call. If ai is ARRAY (i.e., the decomposition is to be controlled entirely by the keeps), then set ai equal to bi. If the number of kept dimensions on the ith argument exceeds bi-ai (i.e., the user is forcing the argument to be broken down into smaller pieces than the function expects), then set ai to bi minus the number of dimensions kept. The effective dimension discrepancy, di, is bi-ai. If this is non-positive, for any argument, that argument will be passed to the extended function without change on every call. The remainder of this discussion applies only to arguments that have positive discrepancy.

First, the shape vector of each argument with positive di is reordered so that any kept dimensions come first, in the order in which they were kept, followed by any unkept dimensions, in their natural order. Thus, for a 4-dimensional object A with shape [6 2 4 3], (KEEP A 4 1 3) results in the reordered shape vector [3 6 4 2].

The leftmost argument of greatest di is called the controlling argument. Let it be the cth argument. All the other arguments must match it in their "excess shapes". That is, for each argument i, the first di of its reordered subscripts must have the same extents as the first di of the controlling argument.

The operation now proceeds as follows. The controlling argument is enumerated in terms of sub-arrays of size ac. The enumeration is of the reordered set of subscripts in row-major order. For example, if the controlling argument has shape [3 4 2] and the third and first dimensions are kept, its reordered shape vector is [2 3 4]. If the extended function expects vectors (i.e., ac is 1), then the function will be called 3*2 times, each time with a 4-vector arg@[-,-,ALL] in the controlling argument position.

The subscripts of the other arguments are enumerated in parrallel with the subscripts of the controlling argument as follows. For the ith argument, the di leading subscripts in its reordered list are matched with the first di in the controlling argument’s reordered subscript list (hence the conformability requirement stated above). For example, if the controlling argument is as above, and another argument, i, for which a vector is expected, has reordered shape [2 6], then di is 1. Note that the first extent, 2, matches that for the controlling argument. Each time the function is called, a 6-vector will be supplied by EAPPLY for the ith argument position; it will be matched with the controlling argument as follows:

The results of these applications of the extended function to the split-down arguments are put back together into an array that is an image of the decomposition of the controlling argument into pieces of dimensionality ac. That is, the first dc of its reordered subscripts are kept, but are sorted back into their original order to define the first dc dimensions of the shape of the result. The last dimensions of the result shape are taken from the shape of the function’s returned value. So if the function in our example returned a [8 4]-matrix, the result of EAPPLY would be an array of shape [3 2 8 4]: the dc leading dimensions of the controlling argument in their original order [3 2], followed by [8 4].