Dyadic Operators


Common Error Reports

Multiple errors elicit but one report. If an error report in the following list is issued, then the ones preceding it do not apply. Five reports are common to all dyadic operators:

Definitions of Dyadic Operators

Inner Product y f.g x

   Arguments and Result
There are three inner products in A+: +., .+,  and .+. The arguments y and x must be nonscalars, and 1y must equal 1x. The shape of the result is (1y),1x.
   Definition
For matrices y and x, the function g is applied to row vectors of y on the left and column vectors of x on the right, in all combinations; f/ is applied to each these results. That is:
      (y f.g x)[i;j]  f/y[i;]g x[;j]
for all scalar indices i and j. The general definition of +. is:
     y (pdt@1 1 0)(1x)x
where
     a pdt b:+/ab
The function pdt must be applied to vectors along the last axis of y and vectors along the first axis of x, in all combinations. In order to do this with the Rank operator, the vectors along the first axis of x must be moved to the last axis. The expression (1x)x has the effect of moving the first axis of x to the last, while leaving all other axes in their original order.

Analogous definitions hold for .+ and .+.

As pointed out in "Operators and Derived Functions", Inner Product is not in the strictest sense an operator, but for most purposes it can be regarded as one.

   Additional Error Reports
Each of the following reports is issued only if there is no parse or value error report (see "Common Error Reports") - the token report preceding the value report -, and none of the reports preceding it on this list applies:

   Example
     (2 3)+.(3 4)
 20 23 26 29
 56 68 80 92

Outer Product 1   y .f x

   Arguments and Result
f can be one of +, , -, , , , |, <, , =, , >, , and *. The arguments y and x are any arrays whose elements are suitable left and right arguments of f, respectively. The shape of the result is (y),(x).
   Definition
The function f is applied to all combinations of scalars from y and x. In particular, for vectors x and y:
     (y.f x)[i;j]  y[i]f x[j]
for all scalar indices i and j. Similar relations hold for arrays of other ranks. In general, y.f x is equivalent to y(f@0 0 0)x.

As pointed out in the "Operators and Derived Functions", Outer Product is not in the strictest sense an operator, but for most purposes it can be regarded as one.

   Additional Error Reports
If there is no error reported as a parse error, then a similar error may be reported:

The following report is issued only if there is no parse, token, or value error (see "Common Error Reports"):

   Example

     1 10 100.1.2 3 98.2 5
   1.2   3     98.2    5
  12    30    982     50
 120   300   9820    500

Rank f@n x and y f@n x

(Just as for all operators, f cannot be Assignment.) Rank's derivation of monadic functions and its derivation of dyadic functions are covered in separate sections below. First, however, you should understand how the operator decomposes arrays, and the implications for its handling of empty arrays.

   Rank Operator uses Frames and Cells

The Rank operator  (f@n x and y f@n x)  splits an array into equal-shaped cells held in a frame and applies its function to each cell. The frame's shape consists of zero or more leading dimensions of the array and the cells' shape consists of the remaining zero or more trailing dimensions. (Cf. "Dimension, Shape, and Rank".) Rank deriving dyadic splits each argument separately.

For example, a function applied to an array of shape 3 4 5 using the Rank operator may be applied to:

Rank allows specification of the rank of either the cells (a positive number in n) or the frame (a negative number in n, whose magnitude is used). For example, to have the Rank operator apply a function to rank-2 cells in a 3-dimensional array, you can use either 2 (for the rank of each cell) or -1 (for a frame rank of 1).

If |n exceeds the rank of an argument to which it is applied, it is treated as if it equaled that rank. Thus you can specify both extreme cases in a way independent of rank: to allot all the axes to the frame, you specify cell rank to be 0, of course; to give all axes to the cells, you specify cell rank to be 9, the limit on ranks.

   The Rank Operator and Empty Arguments

The shape of the result of the derived function is always determined in the same way (with any additional axes on the right produced by the operand function), whether the arguments are empty or not. The type of the result, however, is a different matter. In the absence of an empty frame, the type is determined by the operand function, for the empty cells. On the other hand, if a frame is empty, the Rank operator never calls this function. For a primitive function, Rank uses its result type, or at least its default result type. For a nonprimitive function, it uses null. These examples show this type selection:
     y f x:x      A simple function to be used as an operand.
     2(f@1)0    Scalar frames, empty-vector cells (left argument is made
 `int             to conform to right). An empty integer vector is returned
                  to Rank by f.
     2(f@0)0    An empty-vector frame (from right argument); no (scalar)
 `null            cells for f, so no call. Rank makes the result type null.
     2(+@1)0    Like the first example.
 `int             +0 is integer.
     2(+@0)0    Rank doesn't apply Add to anything, but does use the type
 `int             implied by Add: the Add result type for integers is integer,
                  if the result can be so represented.
     (0) @0 0  Rank passes fake args (the usual zeros, unhappily)
 : domain        to the operand function to determine the size and
                  type of the result. Divide is not amused.

   Rank Deriving Monadic f@n x

The rank specification n is a one-element integer array. For conformity with the discussion of Rank deriving dyadic, assume n is a vector. Then if n is nonnegative, Rank applies f to cells of rank jn[0]x within a frame of shape (-j)x.

If n is negative, Rank applies f to cells of rank k0(x)-|n[0] within a frame of shape (-k)x.

   Additional Error Reports
Each of the following reports is issued for Rank deriving monadic only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

   Examples
     (+/@1) 2 310 20 30 1 2 3  The data operand must be separated
 60 6               from the left argument of Reshape: parentheses used.
     @1 2 3 4    The frame is of rank 1, so the cells are of rank 2.
  8  9 10 11         is called twice, with matrices as arguments,
  4  5  6  7        so the items whose order is reversed by
  0  1  2  3         are rows.

 20 21 22 23
 16 17 18 19
 12 13 14 15
     @1 2 3 4     The cells are of rank 1, so the frame is of rank 2.
  3  2  1  0         is called six times, with rows as arguments,
  7  6  5  4        so the items whose order is reversed by
 11 10  9  8         are scalars.

 15 14 13 12
 19 18 17 16
 23 22 21 20
     @3 2 3 4     The cells are of rank 3, so the frame is scalar.
 12 13 14 15         is called just once, with a rank-3 array as arg,
 16 17 18 19        so the items whose order is reversed by
 20 21 22 23         are matrices.
                    @3 2 3 4 is equivalent to 2 3 4
  0  1  2  3
  4  5  6  7
  8  9 10 11

   Rank Deriving Dyadic y f@n x

The rank specification n must be an integer array with one, two, or three elements. For convenience, assume n is a vector throughout this description.

There are three behaviors for Rank deriving dyadic, depending upon n;

If n has one element and is nonnegative, Rank applies f to cells of rank jn[0]x within a frame of shape (-j)x on x and to cells of rank kn[0]y within a frame of shape (-k)y on y.

If n has one element and is negative , Rank applies f to cells of rank j0(x)-|n[0] within a frame of shape (-j)x on x and to cells of rank k0(y)-|n[0] within a frame of shape (-k)y on y. A common case is f@1 (which pairs items from both arguments and applies the function f to each pair).

If n has two elements, then the first element of n is used for y and the second element is used for x, each interpreted in the same way as when n has one element.

When n has three elements, the first two are used in the manner just stated. The third element of n breaks the frame into two subframes, leading and trailing. It specifies the number of trailing axes in the frames of x and y in which cells will be paired with corresponding cells, and in which, therefore, mismatched dimensions are forbidden. Any leading dimensions present in one trailing subframe and absent in the other - which must in this case be a whole frame -, are supplied by replicating the latter subframe. Any remaining (leading) axes of the frames are used to create subframes whose members are paired in all possible ways, in the manner of an outer product. Again, n can be excessive; any excess is dealt with as described in the next paragraphs.

Assume, just for convenience, that the first two elements of n are positive. Set
cyn[0]y and cxn[1]x (cell ranks), tyn[2](y)-cy and txn[2](x)-cx (ranks of the trailing parts of the frames), and ly0(y)-cy+ty and lx0(x)-cx+tx (ranks of the leading parts of the frames).

That is, the cell specifications are honored to the extent possible, then the trailing subframe specification is honored to the extent possible, and the leading subframes are whatever is left. The function f is applied to pairs of cells of rank cy and cx taken from y and x respectively, using all combinations of subscripts for the first ly and lx axes and corresponding subscripts for the next tytx axes (after possible replication of one trailing subframe to make these subframes match).

Whether the cells match is the responsibility of the operand function. The two leading subframes have no compatibility requirement. The two trailing subframes must match only as far as they both exist: specifically,

     (-tytx)(-cy)y    (-tytx)(-cx)x.
Clearly, if ty is less than tx (and so the trailing subframe for y is replicated to match the shape of the trailing subframe for x), then ly is zero, and if tx is less than ty, then lx is zero.

Note that:
if n has only one element, y (f@n) x is equivalent to y (f@ n,n) x
        which is equivalent to y (f@ n,n,9) x
and if n has exactly two elements, y (f@n) x is equivalent to y (f@ n,9) x.
When n has fewer than three elements, the trailing subframes are simply the frames.
   Additional Error Reports
Each of the following reports is issued for Rank deriving dyadic only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

   Examples
     '-->' ,@1 4!'abcdABCD'  Rank 1 cell (rank 0 frame) vs. rank 1
 -->abcd                      cell (rank 1 frame). The scalar left
 -->ABCD                      frame is treated as a 2-element vector.

     '01' ,@1 4!'abcdABCD'  Rank 1 frame (rank 0 cell) vs. rank 1
 0abcd                        frame (rank 1 cell).
 1ABCD

     (3)(,@0 1)2 3 4        Rank 0 cell (rank 1 frame) vs. rank 1
   0  0  1  2  3              cell (rank 2 frame). The vector left
   1  4  5  6  7              frame is treated as a 2 by 3 matrix: the
   2  8  9 10 11              "missing" dimension is supplied.

   0 12 13 14 15
   1 16 17 18 19
   2 20 21 22 23

     (1990+2)(,@0 1 0)2 3   Both left argument scalars vs.
 1990    0    1    2          both right argument vectors. Cells left
 1990    3    4    5          rank 0, right rank 1; rank 0 trailing
                              subframes and rank 1 leading subframes
 1991    0    1    2          for both.
 1991    3    4    5

     (2 3 4),@1 1 2(2 3 9)  Vector vs. vector, rank 0 leading
   0  1  2  3  0  1  2  3  4  5  6  7  8   subframes. The
   4  5  6  7  9 10 11 12 13 14 15 16 17   1 1 2 operand
   8  9 10 11 18 19 20 21 22 23 24 25 26    could as well be
                                           1 1
  12 13 14 15 27 28 29 30 31 32 33 34 35
  16 17 18 19 36 37 38 39 40 41 42 43 44
  20 21 22 23 45 46 47 48 49 50 51 52 53

Now vector cells, from corresponding rows, both planes vs. both planes (rank 1 cells, rank 1 trailing subframes, and rank 1 leading subframes for both). The arguments are:
     2 3 3"my you it  t hedog"
my
you
 it

  t
 he
dog

and

     2 3 4"hat  did is win rs  's  "
hat
 did
 is

win
rs
's
Applying ,@1 1 1 to them yields
     (2 3 3"my you it  t hedog")(,@1 1 1
*     )2 3 4"hat  did is win rs  's  "
my hat
you did
 it is
my win
yours
 it's


  that
 he did
dog is

  twin
 hers
dog's
      Errors
Errors may be reported by either the operator or an operand:

     (2 4 4),@1 1(2 3 9)   One trailing subframe a vector of length
,@1: mismatch                four, the other a vector of length three.
*                           Rank notes the discrepancy in lengths.

     (24)(+@0)23
+@0: mismatch                Rank can't pair scalar cells for Add.
*     

     (24)(+@1)23           Rank can pair vector cells for Add,
 +: length                   but Add can't pair scalar items.
*      
      Inner and Outer Products
If there is no Outer Product for f, f@0 0 0 may be used.
Sine, cosine, tangent of 0 45 90 ... 360 degrees, with the result doctored to show Inf:
     8.4 1 2 3 @0 0 0 .259
  0.0000  0.7071  1.0000  0.7071  0.0000 -0.7071 -1.0000 -0.7071  0.0000
  1.0000  0.7071  0.0000 -0.7071 -1.0000 -0.7071  0.0000  0.7071  1.0000
  0.0000  1.0000     Inf -1.0000  0.0000  1.0000    Inf -1.0000  0.0000
If there is no Inner Product for f and g, f/@(y) x g@0 1 y may be used (if there is no Reduction for f a defined reduction operator may be used). For (2 12)^.<12 24:
     ^/@2 (2 12) <@0 1 12 24
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1

doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.