[arrayfire] 33/61: doxygen formatting and reference fixes
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Dec 8 11:55:07 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to branch dfsg-clean
in repository arrayfire.
commit 1ada68e07dc1808fb91c45baf7d40187aeed380a
Author: syurkevi <stefan at arrayfire.com>
Date: Tue Dec 1 14:01:19 2015 -0500
doxygen formatting and reference fixes
---
docs/pages/forge_visualization.md | 122 +++++++++++++++++++++++++++-----------
docs/pages/matrix_manipulation.md | 112 ++++++++++++++++++++++------------
docs/pages/vectorization.md | 90 ++++++++++++++++++----------
3 files changed, 221 insertions(+), 103 deletions(-)
diff --git a/docs/pages/forge_visualization.md b/docs/pages/forge_visualization.md
index 6107fb3..72901dc 100644
--- a/docs/pages/forge_visualization.md
+++ b/docs/pages/forge_visualization.md
@@ -1,12 +1,30 @@
-Visualizing af::arrays with Forge {#forge_visualization}
+Visualizing af::array with Forge {#forge_visualization}
===================
-Arrayfire as a library aims to provide a robust and easy to use platform for high-performance, parallel and GPU computing. The goal of Forge, an OpenGL visualization library, is to provide equally robust visualizations that are interoperable between Arrayfire data-structures and an OpenGL context. Instead of wasting time copying and reformatting data from the GPU to the host and back to the GPU, we can draw directly from GPU-data to GPU-framebuffers! Furthermore, Arrayfire provides wrapp [...]
-# Setup
-Before we can call Forge functions, we need to set up the related "canvas" classes. Forge functions are tied to the af::Window class. First let's create a window:
+Arrayfire as a library aims to provide a robust and easy to use platform for
+high-performance, parallel and GPU computing.
+
+[TOC]
+
+The goal of [Forge](https://github.com/arrayfire/forge), an OpenGL visualization
+library, is to provide equally robust visualizations that are interoperable
+between Arrayfire data-structures and an OpenGL context.
+
+Arrayfire provides wrapper functions that are designed to be a simple interface
+to visualize af::arrays. These functions perform various interop tasks. One in
+particular is that instead of wasting time copying and reformatting data from
+the GPU to the host and back to the GPU, we can draw directly from GPU-data to
+GPU-framebuffers! This saves 2 memory copies.
+
+Let's see exactly what visuals we can illuminate with forge and how Arrayfire
+anneals the data between the two libraries.
+
+# Setup {#setup}
+Before we can call Forge functions, we need to set up the related "canvas" classes.
+Forge functions are tied to the af::Window class. First let's create a window:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-const static int WIDTH = 512, HEIGHT = 512;
-af::Window window(WIDTH, HEIGHT, "2D plot example title");
+const static int width = 512, height = 512;
+af::Window window(width, height, "2D plot example title");
do{
@@ -15,29 +33,41 @@ do{
} while( !window.close() );
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We also added a drawing loop, so now we can use Forge's drawing functions to draw to the window.
+We also added a drawing loop, so now we can use Forge's drawing functions to
+draw to the window.
The drawing functions present in Forge are listed below.
-# af::Window::image
-The af::Window::image() function can be used to plot grayscale or color images. To plot a grayscale image a 2d array should be passed into the function. Let's see this on a static noise example:
+# Rendering Functions {#render_func}
+
+Documentation for rendering functions can be found [here](\ref gfx_func_draw).
+
+## Image {#image}
+The af::Window::image() function can be used to plot grayscale or color images.
+To plot a grayscale image a 2d array should be passed into the function.
+Let's see this on a static noise example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-array img = constant(0, WIDTH, HEIGHT); //make a black image
-array random = randu(WIDTH, HEIGHT); //make random [0,1] distribution
+array img = constant(0, width, height); //make a black image
+array random = randu(width, height); //make random [0,1] distribution
img(random > 0.5) = 1; //set all pixels where distribution > 0.5 to white
window.image(img);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<img src="gfx_docs_images/noise.png" alt="Forge image plot of noise" width="20%" />
-Tweaking the previous example by giving our image a depth of 3 for the RGB values allows us to generate colorful noise:
+Tweaking the previous example by giving our image a depth of 3 for the RGB values
+allows us to generate colorful noise:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-array img = 255 * randu(WIDTH, HEIGHT, 3); //make random [0, 255] distribution
+array img = 255 * randu(width, height, 3); //make random [0, 255] distribution
window.image( img.as(u8) );
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<img src="gfx_docs_images/color_noise.png" alt="Forge image plot of color noise" width="20%" />
-Notice Forge automatically handles any af::array type passed from Arrayfire. In the first example we passed in an image of floats in the range [0, 1]. In the last example we cast our array to an unsigned byte array with the range [0, 255]. The type-handling properties are consistent for all Forge drawing functions.
-
-# af::Window::plot
-The af::Window::plot() function visualizes an array as a 2d-line plot. Let's see a simple example:
+Note that Forge automatically handles any af::array type passed from Arrayfire.
+In the first example we passed in an image of floats in the range [0, 1].
+In the last example we cast our array to an unsigned byte array with the range
+[0, 255]. The type-handling properties are consistent for all Forge drawing functions.
+
+## Plot {#plot}
+The af::Window::plot() function visualizes an array as a 2d-line plot. Let's see
+a simple example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
array X = seq(-af::Pi, af::Pi, 0.01);
array Y = sin(X);
@@ -46,25 +76,30 @@ window.plot(X, Y);
<img src="gfx_docs_images/sin_plot.png" alt="Forge 2d line plot of sin() function" width="30%" />
The plot function has the signature:
-<br> **void plot( const array &X, const array &Y, const char * const title = NULL );**
-<br> Both the x and y coordinates of the points are required to plot. This allows for non-uniform, or parametric plots:
+
+> **void plot( const array &X, const array &Y, const char * const title = NULL );**
+
+Both the x and y coordinates of the points are required to plot. This allows for
+non-uniform, or parametric plots:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
array t = seq(0, 100, 0.01);
-array X = sin(t) * (exp(cos(t)) - 2*cos(4*t) - pow(sin(t/12), 5)); array Y = cos(t) * (exp(cos(t)) - 2*cos(4*t) - pow(sin(t/12), 5));
+array X = sin(t) * (exp(cos(t)) - 2 * cos(4 * t) - pow(sin(t / 12), 5));
+array Y = cos(t) * (exp(cos(t)) - 2 * cos(4 * t) - pow(sin(t / 12), 5));
window.plot(X, Y);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<img src="gfx_docs_images/butterfly_plot.png" alt="Forge 2d line plot of butterfly function" width="30%" />
-# af::Window::plot3
+## Plot3 {#plot3}
The af::Window::plot3() function will plot a curve in 3d-space.
Its signature is:
-<br> **void plot3 (const array &in, const char * title = NULL);**
-<br> The input array expects xyz-triplets in sequential order. The points can be in a flattened one dimensional <i>(3n x 1)</i> array, or in one of the <i>(3 x n),</i> <i>(n x 3)</i> matrix forms.
+> **void plot3 (const array &in, const char * title = NULL);**
+The input array expects xyz-triplets in sequential order. The points can be in a
+flattened one dimensional (*3n x 1*) array, or in one of the (*3 x n*), (*n x 3*) matrix forms.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
array Z = seq(0.1f, 10.f, 0.01);
-array Y = sin(10*Z) / Z;
-array X = cos(10*Z) / Z;
+array Y = sin(10 * Z) / Z;
+array X = cos(10 * Z) / Z;
array Pts = join(1, X, Y, Z);
//Pts can be passed in as a matrix in the from n x 3, 3 x n
@@ -76,8 +111,11 @@ window.plot3(Pts);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<img src="gfx_docs_images/spiral_plot3.png" alt="Forge 3d line plot" width="40%" />
-# af::Window::hist
-The af::Window::hist() function renders an input array as a histogram. In our example, the input array will be created with Arrayfire's histogram() function, which actually counts and bins each sample. The output from histogram() can directly be fed into the af::Window::hist() rendering function.
+## Histogram {#histogram}
+The af::Window::hist() function renders an input array as a histogram.
+In our example, the input array will be created with Arrayfire's histogram()
+function, which actually counts and bins each sample. The output from histogram()
+can directly be fed into the af::Window::hist() rendering function.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
const int BINS = 128; SAMPLES = 9162;
@@ -86,11 +124,15 @@ array hist_arr = histogram(norm, BINS);
win.hist(hist_arr, 0, BINS);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In addition to the histogram array with the number of samples in each bin, the af::Window::hist() function takes two additional parameters -- the minimum and maximum values of all datapoints in the histogram array. This effectively sets the range of the binned data. The full signature of af::Window::hist() is: **void hist(const array & X, const double minval, const double maxval, const char * const title = NULL);**
+In addition to the histogram array with the number of samples in each bin, the
+af::Window::hist() function takes two additional parameters -- the minimum and
+maximum values of all datapoints in the histogram array. This effectively sets
+the range of the binned data. The full signature of af::Window::hist() is:
+> **void hist(const array & X, const double minval, const double maxval, const char * const title = NULL);**
<img src="gfx_docs_images/norm_histogram.png" alt="Forge 3d scatter plot" width="40%" />
-# af::Window::surface
+## Surface {#surface}
The af::Window::surface() function will plot af::arrays as a 3d surface.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
array Z = randu(21, 21);
@@ -98,13 +140,21 @@ window.surface(Z, "Random Surface"); //equal to next function call
//window.surface( seq(-1, 1, 0.1), seq(-1, 1, 0.1), Z, "Random Surface");
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<img src="gfx_docs_images/rand_surface.png" alt="Forge random surface plot" width="30%" />
-There are two overloads for the **af::Window::surface()** function:
-* **void surface (const array & S, const char *const title )** -- accepts a 2d matrix with the z values of the surface
-* **void surface (const array &xVals, const array &yVals, const array &S, const char * const title)** -- accepts additional vectors that define the x,y coordinates for the surface points.
+There are two overloads for the af::Window::surface() function:
+> **void surface (const array & S, const char * const title )**
+> // Accepts a 2d matrix with the z values of the surface
+
+> **void surface (const array &xVals, const array &yVals, const array &S, const char * const title)**
+> // accepts additional vectors that define the x,y coordinates for the surface points.
The second overload has two options for the x, y coordinate vectors. Assuming a surface grid of size **m x n**:
1. Short vectors defining the spacing along each axis. Vectors will have sizes **m x 1** and **n x 1**.
- 2. Vectors containing the coordinates of each and every point. Each of the vectors will have length **mn x 1**. This can be used for completely non-uniform or parametric surfaces.
-
-# Conclusion
-There is a fairly comprehensive collection of methods to visualize data in Arrayfire. Thanks to the high-performance gpu plotting library Forge, the provided Arrayfire functions not only make visualizations as simple as possible, but keep them as robust as the rest of the Arrayfire library.
+ 2. Vectors containing the coordinates of each and every point.
+ Each of the vectors will have length **mn x 1**.
+ This can be used for completely non-uniform or parametric surfaces.
+
+# Conclusion {#conclusion}
+There is a fairly comprehensive collection of methods to visualize data in Arrayfire.
+Thanks to the high-performance gpu plotting library Forge, the provided Arrayfire
+functions not only make visualizations as simple as possible, but keep them as
+robust as the rest of the Arrayfire library.
diff --git a/docs/pages/matrix_manipulation.md b/docs/pages/matrix_manipulation.md
index f0af0a7..8fde488 100644
--- a/docs/pages/matrix_manipulation.md
+++ b/docs/pages/matrix_manipulation.md
@@ -2,6 +2,7 @@ Matrix Manipulation {#matrixmanipulation}
===================
Many different kinds of [matrix manipulation routines](\ref manip_mat) are available:
+
* flat() - flatten an array to one dimension
* flip() - flip an array along a dimension
* join() - join up to 4 arrays
@@ -13,7 +14,7 @@ Many different kinds of [matrix manipulation routines](\ref manip_mat) are avail
* [array()](\ref af::array) to adjust the dimensions of an array
* [transpose](\ref af::array::T) a matrix or vector with shorthand notation
-### flat()
+## flat()
The __flat()__ function flattens an array to one dimension.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [3 3 1 1]
@@ -34,11 +35,14 @@ flat(a) [9 1 1 1]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The flat function has the following overloads:
-* __array af::flat(const array& in)__ -- flatten an array
-* __af_err af_flat(af_array* out, const af_array in)__ -- C interface for flat() function
+> __array af::flat(const array& in)__
+> -- flatten an array
+
+> __af_err af_flat(af_array* out, const af_array in)__
+> -- C interface for flat() function
-### flip()
+## flip()
The __flip()__ function flips the contents of an array along a chosen dimension.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [5 2 1 1]
@@ -63,10 +67,12 @@ flip(a, 1) [5 2 1 1]
10.0000 5.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The flip function has the following overloads:
-* __array af::flip(const array &in, const unsigned dim)__ -- flips an array along a dimension
-* __af_err af_flip(af_array *out, const af_array in, const unsigned dim)__ -- C interface for flip()
+> __array af::flip(const array &in, const unsigned dim)__
+> -- flips an array along a dimension
+> __af_err af_flip(af_array *out, const af_array in, const unsigned dim)__
+> -- C interface for flip()
-### join()
+## join()
The __join()__ function can join up to 4 arrays together.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [5 1 1 1]
@@ -96,17 +102,22 @@ join(1, a, a) [5 2 1 1]
5.0000 5.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The join function has several overloads:
-* __array af::join(const int dim, const array &first, const array &second)__ -- Joins 2 arrays along a dimension
+> __array af::join(const int dim, const array &first, const array &second)__
+> -- Joins 2 arrays along a dimension
-* __array af::join(const int dim, const array &first, const array &second, const array &third)__ -- Joins 3 arrays along a dimension.
+> __array af::join(const int dim, const array &first, const array &second, const array &third)__
+> -- Joins 3 arrays along a dimension.
-* __array af::join(const int dim, const array &first, const array &second, const array &third, const array &fourth)__ -- Joins 4 arrays along a dimension
+> __array af::join(const int dim, const array &first, const array &second, const array &third, const array &fourth)__
+> -- Joins 4 arrays along a dimension
-* __af_err af_join(af_array *out, const int dim, const af_array first, const af_array second)__ -- C interface function to join 2 arrays along a dimension
+> __af_err af_join(af_array *out, const int dim, const af_array first, const af_array second)__
+> -- C interface function to join 2 arrays along a dimension
-* __af_err af_join_many(af_array *out, const int dim, const unsigned n_arrays, const af_array *inputs)__ -- C interface function to join up to 10 arrays along a dimension
+> __af_err af_join_many(af_array *out, const int dim, const unsigned n_arrays, const af_array *inputs)__
+> -- C interface function to join up to 10 arrays along a dimension
-### moddims()
+## moddims()
The __moddims()__ function changes the dimensions of an array without changing its data or order. It is important to remember that the function only modifies the _metadata_ associated with the array and does not actually modify the content of the array.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [8 1 1 1]
@@ -135,13 +146,21 @@ moddims(a, a.elements(), 1, 1, 1) [8 1 1 1]
2.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The moddims function has several overloads:
-* __array af::moddims(const array &in, const unsigned ndims, const dim_t *const dims)__ -- mods number of dimensions to match _ndims_ as specidied in the array _dims_
-* __array af::moddims(const array &in, const dim4 &dims)__ -- mods dimensions as specified by _dims_
-* __array af::moddims(const array &in, const dim_t d0, const dim_t d1=1, const dim_t d2=1, const dim_t d3=1)__ -- mods dimensions of an array
-* __af_err af_moddims(af_array *out, const af_array in, const unsigned ndims, const dim_t *const dims)__ -- C interface to mod dimensions of an array
+> __array af::moddims(const array &in, const unsigned ndims, const dim_t *const dims)__
+> -- mods number of dimensions to match _ndims_ as specidied in the array _dims_
+
+> __array af::moddims(const array &in, const dim4 &dims)__
+> -- mods dimensions as specified by _dims_
+
+> __array af::moddims(const array &in, const dim_t d0, const dim_t d1=1, const dim_t d2=1, const dim_t d3=1)__
+> -- mods dimensions of an array
-### reorder()
-The __reorder()__ function changes the order of the dimensions within the array. This actually alters the underlying data of the array.
+> __af_err af_moddims(af_array *out, const af_array in, const unsigned ndims, const dim_t *const dims)__
+> -- C interface to mod dimensions of an array
+
+## reorder()
+The __reorder()__ function changes the order of the dimensions within the array.
+This actually alters the underlying data of the array.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [2 2 3 1]
1.0000 3.0000
@@ -175,11 +194,13 @@ reorder(a, 2, 0, 1) [3 2 2 1]
3.0000 4.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The reorder function the following several overloads:
-* __array af::reorder(const array &in, const unsigned x, const unsigned y=1, const unsigned z=2, const unsigned w=3)__ -- Reorders dimensions of an array
+> __array af::reorder(const array &in, const unsigned x, const unsigned y=1, const unsigned z=2, const unsigned w=3)__
+> -- Reorders dimensions of an array
-* __af_err af_reorder(af_array *out, const af_array in, const unsigned x, const unsigned y, const unsigned z, const unsigned w)__ -- C interface for reordering function
+> __af_err af_reorder(af_array *out, const af_array in, const unsigned x, const unsigned y, const unsigned z, const unsigned w)__
+> -- C interface for reordering function
-### shift()
+## shift()
The __shift()__ function shifts data in a circular buffer fashion along a chosen dimension.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [3 5 1 1]
@@ -198,11 +219,13 @@ shift(a, -1, 2 ) [3 5 1 1]
0.0000 0.0000 0.0000 0.0000 0.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The shift function has the following overloads:
-* __array af::shift(const array &in, const int x, const int y=0, const int z=0, const int w=0)__ -- Shifts array along specified dimensions
+> __array af::shift(const array &in, const int x, const int y=0, const int z=0, const int w=0)__
+> -- Shifts array along specified dimensions
-* __af_err af_shift(af_array *out, const af_array in, const int x, const int y, const int z, const int w)__ -- C interface for shifting an array
+> __af_err af_shift(af_array *out, const af_array in, const int x, const int y, const int z, const int w)__
+> -- C interface for shifting an array
-### tile()
+## tile()
The __tile()__ function repeats an array along a dimension
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [3 1 1 1]
@@ -242,11 +265,16 @@ tile(a, tile_dims) [3 2 3 1]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The tile function has several overloads:
-* __array af::tile(const array &in, const unsigned x, const unsigned y=1, const unsigned z=1, const unsigned w=1)__ -- Tiles array along specified dimensions
-* __array af::tile(const array &in, const dim4 &dims)__ -- Tile an array according to a dim4 object
-* __af_err af_tile(af_array *out, const af_array in, const unsigned x, const unsigned y, const unsigned z, const unsigned w)__ -- C interface for tiling an array
+> __array af::tile(const array &in, const unsigned x, const unsigned y=1, const unsigned z=1, const unsigned w=1)__
+> -- Tiles array along specified dimensions
+
+> __array af::tile(const array &in, const dim4 &dims)__
+> -- Tile an array according to a dim4 object
+
+> __af_err af_tile(af_array *out, const af_array in, const unsigned x, const unsigned y, const unsigned z, const unsigned w)__
+> -- C interface for tiling an array
-### transpose()
+## transpose()
The __transpose()__ function performs a standard matrix transpose. The input array must have the dimensions of a 2D-matrix.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
a [3 3 1 1]
@@ -261,13 +289,17 @@ transpose(a) [3 3 1 1]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The transpose function has several overloads:
-* __array af::transpose(const array &in, const bool conjugate=false)__ -- Transposes a matrix.
+> __array af::transpose(const array &in, const bool conjugate=false)__
+> -- Transposes a matrix.
-* __void af::transposeInPlace(array &in, const bool conjugate=false)__ -- Transposes a matrix in-place.
+> __void af::transposeInPlace(array &in, const bool conjugate=false)__
+> -- Transposes a matrix in-place.
-* __af_err af_transpose(af_array *out, af_array in, const bool conjugate)__ -- C interface to transpose a matrix.
+> __af_err af_transpose(af_array *out, af_array in, const bool conjugate)__
+> -- C interface to transpose a matrix.
-* __af_err af_transpose_inplace(af_array in, const bool conjugate)__ -- C interface to transpose a matrix in-place.
+> __af_err af_transpose_inplace(af_array in, const bool conjugate)__
+> -- C interface to transpose a matrix in-place.
[array()](\ref af::array) can be used to create a (shallow) copy of a matrix
with different dimensions. The number of elements must remain the same as
@@ -280,8 +312,12 @@ used to form the [matrix or vector transpose](\ref af::array::T) .
\snippet test/matrix_manipulation.cpp ex_matrix_manipulation_transpose
-### Combining re-ordering functions to enumerate grid coordinates
-By using a combination of the array restructuring functions, we can quickly code complex manipulation patterns with a few lines of code. For example, consider generating _(x,y)_ coordinates for a grid where each axis goes from *1 to n*. Instead of using several loops to populate our arrays we can just use a small combination of the above functions.
+# Combining re-ordering functions to enumerate grid coordinates
+By using a combination of the array restructuring functions, we can quickly code
+complex manipulation patterns with a few lines of code. For example, consider
+generating (*x,y*) coordinates for a grid where each axis goes from *1 to n*.
+Instead of using several loops to populate our arrays we can just use a small
+combination of the above functions.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
unsigned n=3;
af::array xy = join(1
@@ -299,5 +335,7 @@ xy [9 2 1 1]
2.0000 3.0000
3.0000 3.0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-### Conclusion
-Functions provided by arrayfire offer ease and flexibility for efficiently manipulating the structure of arrays. The provided functions can be used as building blocks to generate, shift, or prepare data to any form imaginable!
+# Conclusion
+Functions provided by arrayfire offer ease and flexibility for efficiently
+manipulating the structure of arrays. The provided functions can be used as
+building blocks to generate, shift, or prepare data to any form imaginable!
diff --git a/docs/pages/vectorization.md b/docs/pages/vectorization.md
index 2061172..ad51e64 100644
--- a/docs/pages/vectorization.md
+++ b/docs/pages/vectorization.md
@@ -1,50 +1,68 @@
Vectorization {#vectorization}
===================
-Programmers and Data Scientists want to take advantage of fast and parallel computational devices. Writing vectorized code is becoming a necessity to get the best performance out of the current generation parallel hardware and scientific computing software. However, writing vectorized code may not be intuitive immediately. Arrayfire provides many ways to vectorize a given code segment. In this tutorial, we will be presenting various ways to vectorize code using ArrayFire and the benefits [...]
+Programmers and Data Scientists want to take advantage of fast and parallel
+computational devices. Writing vectorized code is becoming a necessity to get
+the best performance out of the current generation parallel hardware and
+scientific computing software. However, writing vectorized code may not be
+intuitive immediately. Arrayfire provides many ways to vectorize a given code
+segment. In this tutorial, we will be presenting various ways to vectorize code
+using ArrayFire and the benefits and drawbacks associated with each method.
# Generic/Default vectorization
-By its very nature, Arrayfire is a vectorized library. Most functions operate on arrays as a whole -- on all elements in parallel. Wherever possible, existing vectorized functions should be used opposed to manually indexing into arrays. For example, consider this valid, yet mislead code that attempts to increment each element of an array:
+By its very nature, Arrayfire is a vectorized library. Most functions operate on
+arrays as a whole -- on all elements in parallel. Wherever possible, existing
+vectorized functions should be used opposed to manually indexing into arrays.
+For example, consider this valid, yet mislead code that attempts to increment
+each element of an array:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-af::array a = af::seq(10); // [0, 9]
-for(int i=0; i<a.dims(0); ++i)
+af::array a = af::range(10); // [0, 9]
+for(int i = 0; i < a.dims(0); ++i)
{
- a(i) = a(i) + 1; // [1, 10]
+ a(i) = a(i) + 1; // [1, 10]
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Instead, the existing vectorized Arrayfire overload of the + operator should have been used:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-af::array a = af::seq(10); // [0, 9]
-a = a + 1; // [1, 10]
+af::array a = af::range(10); // [0, 9]
+a = a + 1; // [1, 10]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some of the vectorized mathematical functions of Arrayfire include:
-Operator Category | Functions
---------------------------------------|--------------------------
-Arithmetic operations | operator+(), operator-(), operator*(), operator/(), operator>>(), operator<<()
-Complex operations | real(), imag(), conjugate(), etc.
-Exponential and logarithmic functions | exp(), log(), expm1(), log1p(), etc.
-Hyperbolic functions | sinh(), cosh(), tanh(), etc.
-Numeric functions | floor(), round(), min(), max(), etc.
-Trigonometric functions | sin(), cos(), tan(), etc.
-Logical operations | &&, \|\|, \|, &, <, >, <=, >=, ==, !
+Operator Category | Functions
+------------------------------------------------------------|--------------------------
+[Arithmetic operations](\ref arith_mat) | [+](\ref arith_func_add), [-](\ref arith_func_sub), [*](\ref arith_func_mul), [/](\ref arith_func_div), [%](\ref arith_func_mod), [>>](\ref arith_func_shiftr), [<<](\ref arith_func_shiftl)
+[Complex operations](\ref complex_mat) | real(), imag(), conj(), etc.
+[Exponential and logarithmic functions](\ref explog_mat) | exp(), log(), expm1(), log1p(), etc.
+[Hyperbolic functions](\ref hyper_mat) | sinh(), cosh(), tanh(), etc.
+[Logical operations](\ref logic_mat) | [&&](\ref arith_func_and), [\|\|](\ref arith_func_or), [<](\ref arith_func_lt), [>](\ref arith_func_gt), [==](\ref arith_func_eq), [!=](\ref arith_func_neq) etc.
+[Numeric functions](\ref numeric_mat) | abs(), floor(), round(), min(), max(), etc.
+[Trigonometric functions](\ref trig_mat) | sin(), cos(), tan(), etc.
# GFOR: Parallel for-loops
Another novel method of vectorization present in Arrayfire is the GFOR loop replacement construct.
-GFOR allows launching all iterations of a loop in parallel on the GPU or device, as long as the iterations are independent. While the standard for-loop performs each iteration sequentially, ArrayFire's gfor-loop performs each iteration at the same time (in parallel). ArrayFire does this by tiling out the values of all loop iterations and then performing computation on those tiles in one pass.
-You can think of gfor as performing auto-vectorization of your code, e.g. you write a gfor-loop that increments every element of a vector but behind the scenes ArrayFire rewrites it to operate on the entire vector in parallel.
+GFOR allows launching all iterations of a loop in parallel on the GPU or device,
+as long as the iterations are independent. While the standard for-loop performs
+each iteration sequentially, ArrayFire's gfor-loop performs each iteration at
+the same time (in parallel). ArrayFire does this by tiling out the values of all
+loop iterations and then performing computation on those tiles in one pass.
+You can think of gfor as performing auto-vectorization of your code, e.g. you
+write a gfor-loop that increments every element of a vector but behind the scenes
+ArrayFire rewrites it to operate on the entire vector in parallel.
We can remedy our first example with GFOR:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-af::array a = af::seq(10);
+af::array a = af::range(10);
gfor(seq i, n)
a(i) = a(i) + 1;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is best to vectorize computation as much as possible to avoid the overhead in both for-loops and gfor-loops.
+It is best to vectorize computation as much as possible to avoid the overhead in
+both for-loops and gfor-loops.
-To see another example, you could run an FFT on every 2D slice of a volume in a for-loop, or you could "vectorize" and simply do it all in one gfor-loop operation:
+To see another example, you could run an FFT on every 2D slice of a volume in a
+for-loop, or you could "vectorize" and simply do it all in one gfor-loop operation:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
for (int i = 0; i < N; ++i)
A(span,span,i) = fft2(A(span,span,i)); // runs each FFT in sequence
@@ -65,10 +83,15 @@ gfor (seq i, 5)
gfor (seq i, 0, 4)
gfor (seq i, 0, 1, 4)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Using GFOR requires following several rules and multiple guidelines for optimal performance. The details of this vectorization method can be found in the <a href="page_gfor.htm">GFOR documentation.</a>
-
-# batchFunc()
-The batchFunc() function allows the broad application of existing Arrayfire functions to multiple sets of data. Effectively, batchFunc() allows Arrayfire functions to execute in "batch processing" mode. In this mode, functions will find a dimension which contains "batches" of data to be processed and will parallelize the procedure.
+Using GFOR requires following several rules and multiple guidelines for optimal performance.
+The details of this vectorization method can be found in the [GFOR documentation](\ref gfor).
+
+# Batching
+The batchFunc() function allows the broad application of existing Arrayfire
+functions to multiple sets of data. Effectively, batchFunc() allows Arrayfire
+functions to execute in "batch processing" mode. In this mode, functions will
+find a dimension which contains "batches" of data to be processed and will
+parallelize the procedure.
Consider the following example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
af::array filter = randn(1, 5);
@@ -86,19 +109,26 @@ However we would like a vectorized solution. The following syntax begs to be use
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
af::array filtered_weights = filter * weights; //fails due to dimension mismatch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-but it fails due to the (5x1), (5x5) dimension mismatch. Wouldn't it be nice if Arrayfire could figure out along which dimension we intend to apply the batch operation? That is exactly what batchFunc() does!
+but it fails due to the (5x1), (5x5) dimension mismatch. Wouldn't it be nice if
+Arrayfire could figure out along which dimension we intend to apply the batch
+operation? That is exactly what batchFunc() does!
The signature of the function is:
-__AFAPI array batchFunc( const array &lhs, const array &rhs, batchFunc_t func );__
+> array batchFunc(const array &lhs, const array &rhs, batchFunc_t func);
where __batchFunc_t__ is a function pointer of the form:
-__typedef array (*batchFunc_t) ( const array &lhs, const array &rhs );__
+`typedef array (*batchFunc_t) (const array &lhs, const array &rhs);`
-So, to use batchFunc(), we need to provide the function we will be applying as a batch operation. Our final batch call is not much more difficult than the ideal syntax we imagined.
+So, to use batchFunc(), we need to provide the function we will be applying as a
+batch operation. Our final batch call is not much more difficult than the ideal
+syntax we imagined.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
af::array filtered_weights = batchFunc(filter, weights, operator* );
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The batch function will work with many previously mentioned vectorized Arrayfire functions. It can even work with a combination of those functions if they are wrapped inside a helper function matching the __batchFunc_t__ signature. Unfortunately, the batch function cannot be used within a gfor() construct at this moment.
+The batch function will work with many previously mentioned vectorized Arrayfire
+functions. It can even work with a combination of those functions if they are
+wrapped inside a helper function matching the __batchFunc_t__ signature. Unfortunately,
+the batch function cannot be used within a gfor() construct at this moment.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/arrayfire.git
More information about the debian-science-commits
mailing list