From 7fa325f583a59a1999cd8ce093a49f8048a3e05c Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Fri, 8 Jul 2022 22:06:05 -0400 Subject: Simplify and update Couple/Merge docs --- docs/doc/couple.html | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs/doc/couple.html') diff --git a/docs/doc/couple.html b/docs/doc/couple.html index d5325de5..86d8434a 100644 --- a/docs/doc/couple.html +++ b/docs/doc/couple.html @@ -59,7 +59,11 @@ β‰’ > a ⟨ 2 3 5 ⟩ -

Merge serves as a generalization of Solo and Couple, since Solo is {>βŸ¨π•©βŸ©} and Couple is {>βŸ¨π•¨,π•©βŸ©}. Since ≍ works on the "list" of arguments, it can only add one dimension, but > can take any number of dimensions as its input.

+

If 𝕩 is empty, but has a fill element, then its shape is used for the inner shape. If it doesn't have a fill, the inner shape is assumed to be empty, so that the result is 𝕩 with no changes.

+

Merge serves as a generalization of Solo and Couple, since Solo is {>βŸ¨π•©βŸ©} and Couple is {>βŸ¨π•¨,π•©βŸ©}. These can be combined with Pair, giving >β‹ˆ for both. Since the result of β‹ˆ has rank 1, it can only add one dimension, but > can take any number of dimensions as its input.

+

Coupling units

+

A note on the topic of Solo and Couple applied to units. As always, one axis will be added, so that the result is a list (strangely, J's laminate differs from Couple in this one case, as it adds an axis to get a shape 2β€Ώ1 result). Solo on a unit is interchangeable with Deshape (β₯Š), and either primitive might be chosen for stylistic reasons. Couple on units is equivalent to Join-to (∾), but this is an irregular form of Join-to because it is the only case where Join-to adds an axis to both arguments instead of just one. Couple should be preferred in this case.

+

As a consequence, Pair (β‹ˆ) can be written ≍○<, while ≍ is >βˆ˜β‹ˆ as discussed above. This gives the neat (but not useful) identities ≍ ←→ >βˆ˜β‰β—‹<, and β‹ˆ ←→ >βˆ˜β‹ˆβ—‹<, which have the same form because adding β—‹< commutes with adding >∘.

Merge and array theory

In all cases, what these functions do is more like reinterpreting existing data than creating new information. In fact, if we ignore the shape and look at the deshaped arrays involved in a call to Merge, we find that it just joins them together. Essentially, Merge is a request to ensure that the inner arrays make up a homogeneous (not "ragged") array, and then to consider them to be such an array. It's the same thing Rank does to combine the result cells from its operand into a single array.

↗️
    β₯Š > a
@@ -70,7 +74,7 @@
     ∾ β₯Š β₯ŠΒ¨ a
 "ABrstABuvwABxyzCDrstCDuvwCDxyz"
-

Somewhat like Table ⌜, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or unit arrays are somewhat special. They are the identity value of a function with Table, and Enclose (<), which creates a unit, is a right inverse to Merge. Enclose is needed because Merge can't produce a rank 0 array on its own. Merge has another catch as well: it can't produce arrays with a 0 in the shape, except at the end, without relying on a fill element.

+

Somewhat like Table ⌜, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or unit arrays are somewhat special. They are the identity value of a function with Table, and Enclose (<), which creates a unit, is a right inverse to Merge. Enclose is needed because Merge can't produce a rank 0 array on its own. Merge has another catch as well: it can't produce arrays with a 0 in the shape, except at the end, without relying on a fill element.

↗️
    ⊒ e ← ⟨⟩¨ ↕3
 ⟨ ⟨⟩ ⟨⟩ ⟨⟩ ⟩
     β‰’ > e
@@ -79,9 +83,6 @@
 ⟨ 3 0 ⟩

Above we start with a list of three empty arrays. After merging once we get a shape 3β€Ώ0 array, sure, but what happens next? The shape added by another merge is the shared shape of that array's elementsβ€”and there aren't any! If the nested list kept some type information around then we might know, but extra type information is essentially how lists pretend to be arrays. True dynamic lists simply can't represent multidimensional arrays with a 0 in the middle of the shape. In this sense, arrays are a richer model than nested lists.

-

Coupling units

-

A note on the topic of Solo and Couple applied to units. As always, one axis will be added, so that the result is a list (strangely, J's laminate differs from Couple in this one case, as it will add an axis to get a shape 2β€Ώ1 result). For Solo, this is interchangeable with Deshape (β₯Š), and either primitive might be chosen for stylistic reasons. For Couple, it is equivalent to Join-to (∾), but this is an irregular form of Join-to because it is the only case where Join-to adds an axis to both arguments instead of just one. Couple should be preferred in this case.

-

The function Pair (β‹ˆ) can be written ≍○<, while ≍ in either valence is >βˆ˜β‹ˆ. As an interesting consequence, ≍ ←→ >βˆ˜β‰β—‹<, and β‹ˆ ←→ >βˆ˜β‹ˆβ—‹<. These two identities have the same form because adding β—‹< commutes with adding >∘.

Definitions

-

As discussed above, ≍ is equivalent to >{βŸ¨π•©βŸ©;βŸ¨π•¨,π•©βŸ©} or >β‹ˆ. To complete the picture we should describe Merge fully. Merge is defined on an array argument 𝕩 such that there's some shape s satisfying ∧´β₯Š(s≑≒)¨𝕩. If 𝕩 is empty then any shape satisfies this expression; s should be chosen based on known type information for 𝕩 or otherwise assumed to be ⟨⟩. If s is empty then 𝕩 is allowed to contain atoms as well as unit arrays, and these will be implicitly promoted to arrays by the βŠ‘ indexing used later. We construct the result by combining the outer and inner axes of the argument with Table; since the outer axes come first they must correspond to the left argument and the inner axes must correspond to the right argument. 𝕩 is a natural choice of left argument, and because no concrete array can be used, the right argument will be ↕s, the array of indices into any element of 𝕩. To get the appropriate element corresponding to a particular choice of index and element of 𝕩 we should select using that index. The result of Merge is π•©βŠ‘ΛœβŒœβ†•s.

-

Given this definition we can also describe Rank (βŽ‰) in terms of Each (Β¨) and the simpler monadic function Enclose-Rank <βŽ‰k. We assume effective ranks j for 𝕨 (if present) and k for 𝕩 have been computed. Then the correspondence is 𝕨FβŽ‰k𝕩 ←→ >(<βŽ‰j𝕨)FΒ¨(<βŽ‰k𝕩).

+

We can define ≍ as >β‹ˆ. To complete the picture we should describe Merge fully. Merge is defined on an array argument 𝕩 such that there's some shape s satisfying ∧´β₯Š(s≑≒)¨𝕩. If 𝕩 is empty then any shape satisfies this expression; s is then the shape of the fill if there is one, or otherwise ⟨⟩.

+

Then the result of Merge is π•©βŠ‘ΛœβŒœβ†•s. Here, Table is a nice way of combining outer and inner axes to produce the result; since the outer axes come first they should go on the left and the inner axes on the right. 𝕩 is a natural choice of left argument, and because no concrete array can be used, the right argument is ↕s, the array of indices into any element of 𝕩. Then Pick selects all the elements. If s is empty, then 𝕩 is allowed to contain atoms as well as unit arrays. Pick will implicitly treat them as arrays.

-- cgit v1.2.3