-
Notifications
You must be signed in to change notification settings - Fork 59
Add tutorials with examples to Documentation #132
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,271 @@ | ||
| % Array and Matrix Manipulation | ||
|
|
||
| ArrayFire provides several different methods for manipulating arrays and matrices. | ||
| The functionality includes: | ||
|
|
||
| * [moddims()](#moddims) - change the dimensions of an array without changing the data | ||
| * [flat()](#flat) - flatten an array to one dimension | ||
| * [flip()](#flip) - flip an array along a dimension | ||
| * [join()](#join) - join up to 4 arrays | ||
| * [reorder()](#reorder) - changes the dimension order within the array | ||
| * [shift()](#shift) - shifts data along a dimension | ||
| * [tile()](#tile) - repeats an array along a dimension | ||
| * [transpose()](#transpose) - performs a matrix transpose | ||
|
|
||
| Below we provide several examples of these functions and their use. | ||
|
|
||
| ### moddims() | ||
|
|
||
| The [moddims](./fn.moddims.html) function changes the dimensions of an array without | ||
| changing its data or order. Note that this function modifies only the _metadata_ | ||
| associated with the array. It does not modify the content of the array. | ||
| Here is an example of moddims() converting an 8x1 array into a 2x4 and then | ||
| back to a 8x1: | ||
|
|
||
| ```rust | ||
| a [8 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
|
|
||
| let new_dims = Dim4::new(&[2, 4, 1, 1]); | ||
| moddims(&a, new_dims) | ||
| [2 4 1 1] | ||
| 1.0000 1.0000 1.0000 1.0000 | ||
| 2.0000 2.0000 2.0000 2.0000 | ||
|
|
||
| let out = moddims(&a, a.elements(), 1, 1, 1); | ||
| [8 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| ``` | ||
|
|
||
| ### flat() | ||
|
|
||
| The [flat](./fn.flat.html) function flattens an array to one dimension: | ||
|
|
||
| ``` | ||
| a [3 3 1 1] | ||
| 1.0000 4.0000 7.0000 | ||
| 2.0000 5.0000 8.0000 | ||
| 3.0000 6.0000 9.0000 | ||
|
|
||
| flat(&a) | ||
| [9 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
| 4.0000 | ||
| 5.0000 | ||
| 6.0000 | ||
| 7.0000 | ||
| 8.0000 | ||
| 9.0000 | ||
| ``` | ||
|
|
||
| ### flip() | ||
|
|
||
| The [flip](./fn.flip.html) function flips the contents of an array along a | ||
| chosen dimension. In the example below, we show the 5x2 array flipped | ||
| along the zeroth (i.e. within a column) and first (e.g. across rows) axes: | ||
|
|
||
| ```rust | ||
| a [5 2 1 1] | ||
| 1.0000 6.0000 | ||
| 2.0000 7.0000 | ||
| 3.0000 8.0000 | ||
| 4.0000 9.0000 | ||
| 5.0000 10.0000 | ||
|
|
||
| flip(a, 0) [5 2 1 1] | ||
| 5.0000 10.0000 | ||
| 4.0000 9.0000 | ||
| 3.0000 8.0000 | ||
| 2.0000 7.0000 | ||
| 1.0000 6.0000 | ||
|
|
||
| flip(a, 1) [5 2 1 1] | ||
| 6.0000 1.0000 | ||
| 7.0000 2.0000 | ||
| 8.0000 3.0000 | ||
| 9.0000 4.0000 | ||
| 10.0000 5.0000 | ||
| ``` | ||
|
|
||
| ### join() | ||
|
|
||
| The [join](./fn.join.html), [join_many](./fn.join_many.html) functions can be | ||
| used to join arrays along a specific dimension. | ||
|
|
||
| Here is an example of how to use join an array to itself: | ||
|
|
||
| ```rust | ||
| a [5 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
| 4.0000 | ||
| 5.0000 | ||
|
|
||
| join(0, a, a) [10 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
| 4.0000 | ||
| 5.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
| 4.0000 | ||
| 5.0000 | ||
|
|
||
| join(1, a, a) [5 2 1 1] | ||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
| 4.0000 4.0000 | ||
| 5.0000 5.0000 | ||
| ``` | ||
|
|
||
| ### reorder() | ||
|
|
||
| The [reorder](./fn.reorder.html) function modifies the order of data within an array by | ||
| exchanging data according to the change in dimensionality. The linear ordering | ||
| of data within the array is preserved. | ||
|
|
||
| ```rust | ||
| a [2 2 3 1] | ||
| 1.0000 3.0000 | ||
| 2.0000 4.0000 | ||
|
|
||
| 1.0000 3.0000 | ||
| 2.0000 4.0000 | ||
|
|
||
| 1.0000 3.0000 | ||
| 2.0000 4.0000 | ||
|
|
||
|
|
||
| reorder(&a, 1, 0, 2) | ||
| [2 2 3 1] //equivalent to a transpose | ||
| 1.0000 2.0000 | ||
| 3.0000 4.0000 | ||
|
|
||
| 1.0000 2.0000 | ||
| 3.0000 4.0000 | ||
|
|
||
| 1.0000 2.0000 | ||
| 3.0000 4.0000 | ||
|
|
||
|
|
||
| reorder(&a, 2, 0, 1) | ||
| [3 2 2 1] | ||
| 1.0000 2.0000 | ||
| 1.0000 2.0000 | ||
| 1.0000 2.0000 | ||
|
|
||
| 3.0000 4.0000 | ||
| 3.0000 4.0000 | ||
| 3.0000 4.0000 | ||
| ``` | ||
|
|
||
| ### shift() | ||
|
|
||
| The [shift](./fn.shift.html) function shifts data in a circular buffer fashion along a | ||
| chosen dimension. Consider the following example: | ||
|
|
||
| ```rust | ||
| a [3 5 1 1] | ||
| 0.0000 0.0000 0.0000 0.0000 0.0000 | ||
| 3.0000 4.0000 5.0000 1.0000 2.0000 | ||
| 3.0000 4.0000 5.0000 1.0000 2.0000 | ||
|
|
||
| shift(&a, 0, 2 ) | ||
| [3 5 1 1] | ||
| 0.0000 0.0000 0.0000 0.0000 0.0000 | ||
| 1.0000 2.0000 3.0000 4.0000 5.0000 | ||
| 1.0000 2.0000 3.0000 4.0000 5.0000 | ||
|
|
||
| shift(&a, -1, 2 ) | ||
| [3 5 1 1] | ||
| 1.0000 2.0000 3.0000 4.0000 5.0000 | ||
| 1.0000 2.0000 3.0000 4.0000 5.0000 | ||
| 0.0000 0.0000 0.0000 0.0000 0.0000 | ||
| ``` | ||
|
|
||
| ### tile() | ||
|
|
||
| The [tile](./fn.tile.html) function repeats an array along the specified dimension. | ||
| For example below we show how to tile an array along the zeroth and first | ||
| dimensions of an array: | ||
|
|
||
| ```rust | ||
| a [3 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
|
|
||
| // Repeat array a twice in the zeroth dimension | ||
| tile(&a, 2) | ||
| [6 1 1 1] | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
| 1.0000 | ||
| 2.0000 | ||
| 3.0000 | ||
|
|
||
| // Repeat array a twice along both the zeroth and first dimensions | ||
| tile(&a, 2, 2) | ||
| [6 2 1 1] | ||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
|
|
||
| // Repeat array a twice along the first and three times along the second | ||
| // dimension. | ||
| let tile_dims = Dim4::new(&[1, 2, 3, 1]); | ||
| tile(a, tile_dims) [3 2 3 1] | ||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
|
|
||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
|
|
||
| 1.0000 1.0000 | ||
| 2.0000 2.0000 | ||
| 3.0000 3.0000 | ||
| ``` | ||
|
|
||
| ### transpose() | ||
|
|
||
| The [transpose](./fn.transpose.html) function performs a standard matrix transpose. The input | ||
| array must have the dimensions of a 2D-matrix. | ||
|
|
||
| ```rust | ||
| a [3 3 1 1] | ||
| 1.0000 3.0000 3.0000 | ||
| 2.0000 1.0000 3.0000 | ||
| 2.0000 2.0000 1.0000 | ||
|
|
||
| transpose(&a, False) //Second parameter to be used for conjugate transpose | ||
| [3 3 1 1] | ||
| 1.0000 2.0000 2.0000 | ||
| 3.0000 1.0000 2.0000 | ||
| 3.0000 3.0000 1.0000 | ||
| ``` | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Probably a stupid question: but isn't this already in the rust generated docs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That is true, but having these collected set of examples in one location is probably a good place to start for beginners and they can dwell into parameter documentation and additional examples in the hyperlinked function documentation page - at least that is how I picture it in the long run. I do agree that more examples in each function doc page are to be added yet.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yea, good point. Probably helpful as a reference for people getting started (before they have their setup/etc)