# Difference between revisions of "Leading axis agreement"

(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 | + | '''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
```

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
```

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
```

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
```

## Aligning axes using the Rank operator

When using the Rank operator for dyadic functions as in `X (f⍤m 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
```

APL features [edit]
| |
---|---|

Built-ins | Primitive function ∙ Primitive operator ∙ Quad name |

Array model | Shape ∙ Rank ∙ Depth ∙ Bound ∙ Index (Indexing) ∙ Axis ∙ Ravel ∙ Ravel order ∙ Element ∙ Scalar ∙ Vector ∙ Matrix ∙ Simple scalar ∙ Simple array ∙ Nested array ∙ Cell ∙ Major cell ∙ Subarray ∙ Empty array ∙ Prototype |

Data types | Number (Boolean, Complex number) ∙ Character (String) ∙ Box ∙ Namespace |

Concepts and paradigms | Leading axis theory ∙ Scalar extension ∙ Conformability ∙ Leading axis agreement ∙ Scalar function ∙ Pervasion ∙ Glyph ∙ Identity element ∙ Complex floor ∙ Total array ordering |

Errors | LIMIT ERROR ∙ RANK ERROR ∙ SYNTAX ERROR ∙ DOMAIN ERROR ∙ LENGTH ERROR ∙ INDEX ERROR ∙ VALUE ERROR |