Skip to content

Commit 2673c9f

Browse files
9prady99prady9
committed
Change documentation generation workflow
Earlier to this change, documentation was generated using the command `cargo doc`. However, this has one drawback - when external markdown files were used, additional set of commands had to be run using `rustdoc` tool to generate the html files corresponding to the md files. With this change, `generate_docs.sh` bash script will handle those intricacies of running `cargo doc` followed by execution of `rustdoc` for external md files. This change adds the following tutorials to the documetation. * Getting Started with ArrayFire * Introduction to Vectorization * Array and Matrix Manipulation * Indexing * Configure ArrayFire Environment
1 parent 4e0e6da commit 2673c9f

8 files changed

+1011
-0
lines changed

‎doc/array_and_matrix_manipulation.md

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
% Array and Matrix Manipulation
2+
3+
ArrayFire provides several different methods for manipulating arrays and matrices.
4+
The functionality includes:
5+
6+
* [moddims()](#moddims) - change the dimensions of an array without changing the data
7+
* [flat()](#flat) - flatten an array to one dimension
8+
* [flip()](#flip) - flip an array along a dimension
9+
* [join()](#join) - join up to 4 arrays
10+
* [reorder()](#reorder) - changes the dimension order within the array
11+
* [shift()](#shift) - shifts data along a dimension
12+
* [tile()](#tile) - repeats an array along a dimension
13+
* [transpose()](#transpose) - performs a matrix transpose
14+
15+
Below we provide several examples of these functions and their use.
16+
17+
### moddims()
18+
19+
The [moddims](./fn.moddims.html) function changes the dimensions of an array without
20+
changing its data or order. Note that this function modifies only the _metadata_
21+
associated with the array. It does not modify the content of the array.
22+
Here is an example of moddims() converting an 8x1 array into a 2x4 and then
23+
back to a 8x1:
24+
25+
```rust
26+
a [8 1 1 1]
27+
1.0000
28+
2.0000
29+
1.0000
30+
2.0000
31+
1.0000
32+
2.0000
33+
1.0000
34+
2.0000
35+
36+
let new_dims = Dim4::new(&[2, 4, 1, 1]);
37+
moddims(&a, new_dims)
38+
[2 4 1 1]
39+
1.0000 1.0000 1.0000 1.0000
40+
2.0000 2.0000 2.0000 2.0000
41+
42+
let out = moddims(&a, a.elements(), 1, 1, 1);
43+
[8 1 1 1]
44+
1.0000
45+
2.0000
46+
1.0000
47+
2.0000
48+
1.0000
49+
2.0000
50+
1.0000
51+
2.0000
52+
```
53+
54+
### flat()
55+
56+
The [flat](./fn.flat.html) function flattens an array to one dimension:
57+
58+
```
59+
a [3 3 1 1]
60+
1.0000 4.0000 7.0000
61+
2.0000 5.0000 8.0000
62+
3.0000 6.0000 9.0000
63+
64+
flat(&a)
65+
[9 1 1 1]
66+
1.0000
67+
2.0000
68+
3.0000
69+
4.0000
70+
5.0000
71+
6.0000
72+
7.0000
73+
8.0000
74+
9.0000
75+
```
76+
77+
### flip()
78+
79+
The [flip](./fn.flip.html) function flips the contents of an array along a
80+
chosen dimension. In the example below, we show the 5x2 array flipped
81+
along the zeroth (i.e. within a column) and first (e.g. across rows) axes:
82+
83+
```rust
84+
a [5 2 1 1]
85+
1.0000 6.0000
86+
2.0000 7.0000
87+
3.0000 8.0000
88+
4.0000 9.0000
89+
5.0000 10.0000
90+
91+
flip(a, 0) [5 2 1 1]
92+
5.0000 10.0000
93+
4.0000 9.0000
94+
3.0000 8.0000
95+
2.0000 7.0000
96+
1.0000 6.0000
97+
98+
flip(a, 1) [5 2 1 1]
99+
6.0000 1.0000
100+
7.0000 2.0000
101+
8.0000 3.0000
102+
9.0000 4.0000
103+
10.0000 5.0000
104+
```
105+
106+
### join()
107+
108+
The [join](./fn.join.html), [join_many](./fn.join_many.html) functions can be
109+
used to join arrays along a specific dimension.
110+
111+
Here is an example of how to use join an array to itself:
112+
113+
```rust
114+
a [5 1 1 1]
115+
1.0000
116+
2.0000
117+
3.0000
118+
4.0000
119+
5.0000
120+
121+
join(0, a, a) [10 1 1 1]
122+
1.0000
123+
2.0000
124+
3.0000
125+
4.0000
126+
5.0000
127+
1.0000
128+
2.0000
129+
3.0000
130+
4.0000
131+
5.0000
132+
133+
join(1, a, a) [5 2 1 1]
134+
1.0000 1.0000
135+
2.0000 2.0000
136+
3.0000 3.0000
137+
4.0000 4.0000
138+
5.0000 5.0000
139+
```
140+
141+
### reorder()
142+
143+
The [reorder](./fn.reorder.html) function modifies the order of data within an array by
144+
exchanging data according to the change in dimensionality. The linear ordering
145+
of data within the array is preserved.
146+
147+
```rust
148+
a [2 2 3 1]
149+
1.0000 3.0000
150+
2.0000 4.0000
151+
152+
1.0000 3.0000
153+
2.0000 4.0000
154+
155+
1.0000 3.0000
156+
2.0000 4.0000
157+
158+
159+
reorder(&a, 1, 0, 2)
160+
[2 2 3 1] //equivalent to a transpose
161+
1.0000 2.0000
162+
3.0000 4.0000
163+
164+
1.0000 2.0000
165+
3.0000 4.0000
166+
167+
1.0000 2.0000
168+
3.0000 4.0000
169+
170+
171+
reorder(&a, 2, 0, 1)
172+
[3 2 2 1]
173+
1.0000 2.0000
174+
1.0000 2.0000
175+
1.0000 2.0000
176+
177+
3.0000 4.0000
178+
3.0000 4.0000
179+
3.0000 4.0000
180+
```
181+
182+
### shift()
183+
184+
The [shift](./fn.shift.html) function shifts data in a circular buffer fashion along a
185+
chosen dimension. Consider the following example:
186+
187+
```rust
188+
a [3 5 1 1]
189+
0.0000 0.0000 0.0000 0.0000 0.0000
190+
3.0000 4.0000 5.0000 1.0000 2.0000
191+
3.0000 4.0000 5.0000 1.0000 2.0000
192+
193+
shift(&a, 0, 2 )
194+
[3 5 1 1]
195+
0.0000 0.0000 0.0000 0.0000 0.0000
196+
1.0000 2.0000 3.0000 4.0000 5.0000
197+
1.0000 2.0000 3.0000 4.0000 5.0000
198+
199+
shift(&a, -1, 2 )
200+
[3 5 1 1]
201+
1.0000 2.0000 3.0000 4.0000 5.0000
202+
1.0000 2.0000 3.0000 4.0000 5.0000
203+
0.0000 0.0000 0.0000 0.0000 0.0000
204+
```
205+
206+
### tile()
207+
208+
The [tile](./fn.tile.html) function repeats an array along the specified dimension.
209+
For example below we show how to tile an array along the zeroth and first
210+
dimensions of an array:
211+
212+
```rust
213+
a [3 1 1 1]
214+
1.0000
215+
2.0000
216+
3.0000
217+
218+
// Repeat array a twice in the zeroth dimension
219+
tile(&a, 2)
220+
[6 1 1 1]
221+
1.0000
222+
2.0000
223+
3.0000
224+
1.0000
225+
2.0000
226+
3.0000
227+
228+
// Repeat array a twice along both the zeroth and first dimensions
229+
tile(&a, 2, 2)
230+
[6 2 1 1]
231+
1.0000 1.0000
232+
2.0000 2.0000
233+
3.0000 3.0000
234+
1.0000 1.0000
235+
2.0000 2.0000
236+
3.0000 3.0000
237+
238+
// Repeat array a twice along the first and three times along the second
239+
// dimension.
240+
let tile_dims = Dim4::new(&[1, 2, 3, 1]);
241+
tile(a, tile_dims) [3 2 3 1]
242+
1.0000 1.0000
243+
2.0000 2.0000
244+
3.0000 3.0000
245+
246+
1.0000 1.0000
247+
2.0000 2.0000
248+
3.0000 3.0000
249+
250+
1.0000 1.0000
251+
2.0000 2.0000
252+
3.0000 3.0000
253+
```
254+
255+
### transpose()
256+
257+
The [transpose](./fn.transpose.html) function performs a standard matrix transpose. The input
258+
array must have the dimensions of a 2D-matrix.
259+
260+
```rust
261+
a [3 3 1 1]
262+
1.0000 3.0000 3.0000
263+
2.0000 1.0000 3.0000
264+
2.0000 2.0000 1.0000
265+
266+
transpose(&a, False) //Second parameter to be used for conjugate transpose
267+
[3 3 1 1]
268+
1.0000 2.0000 2.0000
269+
3.0000 1.0000 2.0000
270+
3.0000 3.0000 1.0000
271+
```

0 commit comments

Comments
 (0)