Frame agreement

Frame agreement is a conformability rule which describes the conditions that must be satisfied by the frames of arguments to dyadic functions with rank (either derived and/or, when supported, native). The frames must either be identical, or one must be empty, or, more generally, when supported, one frame must be a prefix of the other.

Empty frame agreement

In SHARP APL and Dyalog, frames agree only if they match, or if one frame is empty. The latter case corresponds to pairing one argument in its entirety with each of the cells of the other argument.

Examples

      x←⍳2
      y←2 3 2⍴⍳12
      x{⍺⍵}⍤99 2⊢y        ⍝ 1-to-n pairing; ⍤99 corresponds to empty frame
┌───┬─────┐
│1 2│1 2  │
│   │3 4  │
│   │5 6  │
├───┼─────┤
│1 2│ 7  8│
│   │ 9 10│
│   │11 12│
└───┴─────┘
      x{⍺⍵}⍤0 2⊢y           ⍝ 1-to-1 pairing; frames match; (,2) ≡ (,2)
┌─┬─────┐
│1│1 2  │
│ │3 4  │
│ │5 6  │
├─┼─────┤
│2│ 7  8│
│ │ 9 10│
│ │11 12│
└─┴─────┘

Works in: Dyalog APL

Frame prefix agreement

In A+, BQN, and J, frames agree if one is a prefix of the other. In J, because every function has associated ranks, frame agreement generalizes leading axis agreement.

Description

A dyadic function with left and right ranks l and r splits its left argument into l-cells, and splits its right argument into r-cells. Each argument's shape is thus split into a frame and a cell shape. Given that one frame must be a prefix of the other, the shorter frame is called the common frame, which may be empty. Here, the generic term "cells" will denote the l-cells (for the left argument) or r-cells (for the right argument). If the frames are identical, the cells are paired 1-to-1 between the arguments. If the frame lengths differ, each cell of the shorter-framed argument is paired with each among the corresponding group of cells of the longer-framed argument. This 1-to-n pairing can be viewed as extending the shorter frame to match the longer frame. The collective results of the individual applications of the function are framed by the longer frame.

Examples

   x=: i.2
   y=: i.2 3 2
   x+"0 1 y
 0  1
 2  3
 4  5

 7  8
 9 10
11 12

Works in: J

The table below shows the pairing of cells from the above example. Here, the notation [cell shape] denotes the cell shape, and | denotes the division between the common frame and the remaining trailing axes.

Argument	Step 1: Frames / Cells	Step 2: Common frame—cells paired
x	2 []	2|[]
y	2 3 [2]	2|3 [2]

The same example, but without considering cell shape:

Argument	Step 1: Frame / Cells	Step 2: Common frame
x	2 C	2|C
y	2 3 C	2|3 C

Based on the ranks 0 1 of the given function, x's frame is ,2 and its cell shape is empty; y's frame is 2 3 and its cell shape is ,2. The shorter of the frames, and thus the common frame, is ,2. Relative to the common frame, each atom of x is paired with the corresponding 3 vectors of y.

The expanded example below uses APL to model frame prefix agreement.

      ⎕IO←0                      ⍝ for comparison with J example
      x←⍳2
      y←2 3 2⍴⍳12
      l r←0 1                    ⍝ the left and right ranks of the function +⍤0 1
      ⊢lf rf←(-l r)↓¨x,⍥(⊂∘⍴)y   ⍝ frames
┌─┬───┐
│2│2 3│
└─┴───┘
      ⊢cf←lf{⍺<⍥≢⍵:⍺ ⋄ ⍵}rf      ⍝ common (i.e. shorter) frame
2
      x{⍺⍵}⍤(-≢cf)⊢y             ⍝ 1st step: the (-≢cf)-cells are paired 1-to-1 between x and y
┌─┬─────┐
│0│0 1  │
│ │2 3  │
│ │4 5  │
├─┼─────┤
│1│ 6  7│
│ │ 8  9│
│ │10 11│
└─┴─────┘
      x{⍺⍵}⍤l r⍤(-≢cf)⊢y         ⍝ 2nd step: the (-≢cf)-cells in each pairing are split into l- and r-cells, and these are paired 1-to-n (or 1-to-1 if the frames are identical)
┌─┬─────┐
│0│0 1  │
├─┼─────┤
│0│2 3  │
├─┼─────┤
│0│4 5  │
└─┴─────┘
┌─┬─────┐
│1│6 7  │
├─┼─────┤
│1│8 9  │
├─┼─────┤
│1│10 11│
└─┴─────┘
      x+⍤0 1⊢y                   ⍝ n-to-m pairing; invalid in APL
RANK ERROR
      x+⍤l r⍤(-≢cf)⊢y            ⍝ matches the result of J's frame agreement
 0  1
 2  3
 4  5

 7  8
 9 10
11 12

Works in: Dyalog APL

Model

In dialects that do not feature frame prefix agreement, it can nevertheless be utilised by the introduction of an explicit operator:

      _FA_←{
           assert←{0≡⍵:'RANK ERROR: one frame must be a prefix of the other' ⎕SIGNAL 4 ⋄ ⍵}
           r←(1↓⌽3⍴⌽⍵⍵)⌊≢∘⍴¨⍺⍵           ⍝ dyadic ranks
           lf rf←(-r)↓∘⍴¨⍺⍵              ⍝ frames
           cf←lf{⍺<⍥≢⍵:⍺ ⋄ ⍵}rf          ⍝ common frame, assuming frames agree
           k←{⍬≡⍵:99 ⋄ -≢⍵}cf            ⍝ relative rank
           assert ⍺∧⍥(cf≡(≢cf)↑⍴)⍵:      ⍝ verify that frames agree
           ⍺ ⍺⍺⍤⍵⍵⍤k⊢⍵
      }
      x+_FA_ 0 1⊢y
 0  1
 2  3
 4  5

 7  8
 9 10
11 12

Works in: Dyalog APL