From 7faf96746f2d9a051c048b312480583494b5ee7b Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Sat, 13 Nov 2021 15:37:14 -0500 Subject: Add multidimensional Join to docs --- docs/doc/join.html | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) (limited to 'docs/doc/join.html') diff --git a/docs/doc/join.html b/docs/doc/join.html index 220c6631..56975907 100644 --- a/docs/doc/join.html +++ b/docs/doc/join.html @@ -60,10 +60,11 @@ ↗️
    1↓∾' '∾¨"time"‿"to"‿"join"‿"some"‿"words"
 "time to join some words"
-

Join requires each element of its argument to be an array, and their ranks to match exactly. No rank extension is performed.

-↗️
    ∾"abc"‿'d'‿"ef"  # Includes an atom
-ERROR
-    ∾"abc"‿(<'d')‿"ef"  # Includes a unit
+
Join also extends the rank of a unit element (including an atom) to allow it to fit into the list. The highest-rank element determines the rank of the result.

+↗️
    ∾"abc"‿'d'‿"ef"‿(<'g')
+"abcdefg"
+
+    ∾"abcd"  # Result has to be rank 0, impossible
 ERROR
 

 
However, Join has higher-dimensional uses as well. Given a rank-m array of rank-n arrays (requiring m≤n), it will merge arrays along their first m axes. For example, if the argument is a matrix of matrices representing a block matrix, Join will give the corresponding unblocked matrix as its result.

@@ -86,5 +87,30 @@
   3 3 3 3 4 4 5 5 5 5 5  
                         ┘
-

Join has fairly strict requirements on the shapes of its argument elements—although less strict than those of Merge, which requires they all have identical shape. Suppose the argument to Join has rank m. Each of its elements must have the same rank, n, which is at least m. The trailing shapes m↓⟜≢¨𝕩 must all be identical (the trailing shape m↓≢∾𝕩 of the result will match these shapes as well). The other entries in the leading shapes need not be the same, but the shape of an element along a particular axis must depend only on the location of the element along that axis in the full array. For a list argument this imposes no restriction, since the one leading shape element is allowed to depend on position along the only axis. But for higher ranks the structure quickly becomes more rigid.

-

To state this requirement more formally in BQN, we say that there is some list s of lists of lengths, so that (≢¨s)≡≢𝕩. We require element i⊑𝕩 to have shape i⊑¨s. Then the first m axes of the result are +´¨s.

+

Axes with length 1 in the argument can also be left out, if it's done consistently for all elements in that position. One use of this is to add borders to an array, as in the multiplication table below.

+↗️
    ⊢ n ← 2‿4‿6 ×{⟨𝕗,𝕩⟩≍⟨𝕨,𝕨𝔽⌜𝕩⟩} 5‿6‿7‿8
+┌─                           
+╵ ×         ⟨ 5 6 7 8 ⟩      
+  ⟨ 2 4 6 ⟩ ┌─               
+            ╵ 10 12 14 16    
+              20 24 28 32    
+              30 36 42 48    
+                          ┘  
+                            ┘
+
+    ≢¨ n  # Different ranks but compatible shapes
+┌─               
+╵ ⟨⟩    ⟨ 4 ⟩    
+  ⟨ 3 ⟩ ⟨ 3 4 ⟩  
+                ┘
+
+    ∾ n
+┌─               
+╵ × 5  6  7  8   
+  2 10 12 14 16  
+  4 20 24 28 32  
+  6 30 36 42 48  
+                ┘
+
+

Even with the extension, Join has fairly strict requirements on the shapes of its argument elements—although less strict than those of Merge, which requires they all have identical shape. Suppose the argument to Join has rank m. The highest element rank (call it n) must be at least m. The trailing shapes (-n-m)↑⟜≢¨𝕩 must all be identical (the trailing shape (-n-m)↑≢∾𝕩 of the result will match these shapes as well). The other entries in the leading shapes need not be the same, but the shape of an element along a particular axis must depend only on the location of the element along that axis in the full array. For a list argument this imposes no restriction, since the one leading shape element is allowed to depend on position along the only axis. But for higher ranks the structure quickly becomes more rigid.

+

To state this requirement more formally in BQN, we say that there is some list s of lists of lengths, so that (≢¨s)≡≢𝕩. We require element i⊑𝕩 to have shape i⊑¨s. Then the first m axes of the result are +´¨s. To handle omitted axes, we change s to contain lists of length 0 or 1 instead of lengths, and require i⊑𝕩 to have shape ∾i⊑¨s instead. In the result, an omitted axis behaves exactly like a length-1 axis, so the result can be found using shapes derived from 1⊣´¨¨s.

-- cgit v1.2.3