Difference between revisions of "Leading axis agreement"

From APL Wiki
Jump to navigation Jump to search
(Remove redirect, add basic explanation and examples)
Tag: Removed redirect
(List languages that use it in the intro)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
'''Leading axis agreement''', sometimes called '''prefix agreement''', is a [[conformability]] rule designed for [[leading axis theory]]. It states that a [[dyadic]] [[scalar function]] can be applied between two arrays only if one of their [[Shape|shapes]] is a prefix of the other. The shape of the result is that of the argument with higher rank.
+
'''Leading axis agreement''', sometimes called '''prefix agreement''', is a [[conformability]] rule designed for [[leading axis theory]] and used by [[J]] and [[BQN]]. It states that a [[dyadic]] [[scalar function]] can be applied between two [[array]]s only if one of their [[shape]]s is a [[prefix]] of the other. The shape of the result is that of the [[argument]] with higher [[rank]].
  
 
== Examples ==
 
== Examples ==
Line 20: Line 20:
 
{{Works in|[[J]]}}
 
{{Works in|[[J]]}}
  
as well as when one is a scalar:
+
as well as when one is a [[scalar]]:
  
 
<source lang=j>
 
<source lang=j>
Line 49: Line 49:
  
 
In this case, <source lang=j inline>x</source> has shape <source lang=j inline>2</source> and <source lang=j inline>y</source> has shape <source lang=j inline>2 3</source>. Since the leading axes agree and the rank difference is 1, each atom (or 0-[[cell]]) of <source lang=j inline>x</source> is matched with each row (or 1-cell) of <source lang=j inline>y</source>, and the two rows in the result are the results of <source lang=j inline>10 + 0 1 2</source> and <source lang=j inline>20 + 3 4 5</source>, respectively.
 
In this case, <source lang=j inline>x</source> has shape <source lang=j inline>2</source> and <source lang=j inline>y</source> has shape <source lang=j inline>2 3</source>. Since the leading axes agree and the rank difference is 1, each atom (or 0-[[cell]]) of <source lang=j inline>x</source> is matched with each row (or 1-cell) of <source lang=j inline>y</source>, and the two rows in the result are the results of <source lang=j inline>10 + 0 1 2</source> and <source lang=j inline>20 + 3 4 5</source>, respectively.
 +
 +
== Model ==
 +
 +
In dialects that do not feature leading axis agreement, it can nevertheless be utilised by the introduction of an explicit operator:
 +
<source lang=apl>
 +
      _LA←{⍺ ⍺⍺⍤(-⍺⌊⍥(≢⍴)⍵)⊢⍵}
 +
      ⊢x ← 10 20
 +
10 20
 +
      ⊢y ← 2 3 ⍴ ⍳ 6
 +
0 1 2
 +
3 4 5
 +
      x +_LA y
 +
10 11 12
 +
23 24 25
 +
</source>
 +
{{Works in|Dyalog APL}}
  
 
== Aligning axes using the Rank operator ==
 
== Aligning axes using the Rank operator ==
  
When using the [[Rank (operator)|Rank operator]] for dyadic functions as in <source lang=apl inline>X (f⍤m n) Y</source>, the [[Frame|frames]] of <source lang=apl inline>X</source> and <source lang=apl inline>Y</source> are checked for conformability. Combined with leading axis agreement, the Rank operator can be used to align the axes to be matched.
+
When using the [[Rank (operator)|Rank operator]] for dyadic functions as in <source lang=apl inline>X (f⍤m n) Y</source>, the [[Frame|frames]] of <source lang=apl inline>X</source> and <source lang=apl inline>Y</source> are checked for conformability. Combined with leading axis agreement, the Rank operator can be used to align the [[axis|axes]] to be matched.
  
 
<source lang=j>
 
<source lang=j>
Line 75: Line 91:
 
65 66
 
65 66
 
</source>
 
</source>
 +
 
{{Works in|[[J]]}}
 
{{Works in|[[J]]}}
 +
[[Category:Leading axis theory]][[Category:Function characteristics]][[Category:Conformability]]{{APL features}}

Latest revision as of 19:49, 19 February 2021

Leading axis agreement, sometimes called prefix agreement, is a conformability rule designed for leading axis theory and used by J and BQN. It states that a dyadic scalar function can be applied between two arrays only if one of their shapes is a prefix of the other. The shape of the result is that of the argument with higher rank.

Examples

The following examples use J for demonstration purposes.

A scalar dyadic function works when the two arrays have the same shape:

   ]x =: 2 3 $ 10
10 10 10
10 10 10
   ]y =: 2 3 $ i.6
0 1 2
3 4 5
   x + y
10 11 12
13 14 15
Works in: J

as well as when one is a scalar:

   ]x =: 10
10
   ]y =: 2 3 $ i.6
0 1 2
3 4 5
   x + y
10 11 12
13 14 15
Works in: J

The two cases above are already supported in other APLs in the form of scalar extension. J goes one step further, allowing the lower-rank array argument to have nonzero rank, as long as the leading dimensions match:

   ]x =: 10 20
10 20
   ]y =: 2 3 $ i.6
0 1 2
3 4 5
   x + y
10 11 12
23 24 25
Works in: J

In this case, x has shape 2 and y has shape 2 3. Since the leading axes agree and the rank difference is 1, each atom (or 0-cell) of x is matched with each row (or 1-cell) of y, and the two rows in the result are the results of 10 + 0 1 2 and 20 + 3 4 5, respectively.

Model

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

      _LA{ ⍺⍺(-(≢⍴))}
      x  10 20
10 20
      y  2 3   6
0 1 2
3 4 5
      x +_LA y
10 11 12
23 24 25
Works in: Dyalog APL

Aligning axes using the Rank operator

When using the Rank operator for dyadic functions as in X (fm n) Y, the frames of X and Y are checked for conformability. Combined with leading axis agreement, the Rank operator can be used to align the axes to be matched.

   NB. $x         : 2|3
   NB. $y         :  |3 2
   NB. ------------------
   NB. $x +"1 2 y : 2 3 2
   ]x =: 2 3 $ 10 20 30 40 50 60
10 20 30
40 50 60
   ]y =: 3 2 $ 1 2 3 4 5 6
1 2
3 4
5 6
   x +"1 2 y
11 12
23 24
35 36

41 42
53 54
65 66
Works in: J
APL features [edit]
Built-ins Primitive functionPrimitive operatorQuad name
Array model ShapeRankDepthBoundIndex (Indexing) ∙ AxisRavelRavel orderElementScalarVectorMatrixSimple scalarSimple arrayNested arrayCellMajor cellSubarrayEmpty arrayPrototype
Data types Number (Boolean, Complex number) ∙ Character (String) ∙ BoxNamespace
Concepts and paradigms Leading axis theoryScalar extensionConformabilityLeading axis agreementScalar functionPervasionGlyphIdentity elementComplex floorTotal array ordering
Errors LIMIT ERRORRANK ERRORSYNTAX ERRORDOMAIN ERRORLENGTH ERRORINDEX ERRORVALUE ERROR