Initial documentation commit

initial python arrayfire documentation with overview and tutorial.
This includes tests for all snippets used in the documentation.

Author: michaeleg21

dev-requirements.txt

@@ -18,3 +18,7 @@ pytest-cov>=5.0.0
 # Allows codecov to generate coverage reports
 coverage[toml]>=6.4
 codecov>=2.1.12
+
+# Allows documentation
+sphinx>=7.3.7
+sphinxawesome_theme>=5.2.0

docs/__init__.py

@@ -0,0 +1,8 @@
+a {
+    color: blue; /* Set the color of links to blue */
+    text-decoration: underline; /* Underline links */
+}
+
+a:hover {
+    color: darkblue; /* Change link color to dark blue on hover */
+}

docs/_static/custom.css

@@ -0,0 +1,24 @@
+# [jit-snippet]
+
+# As JIT is automatically enabled in ArrayFire, this version of the function
+# forces each expression to be evaluated. If the eval() function calls are
+# removed, then the execution of this code would be equivalent to the
+# following function.
+
+def pi_no_jit(x, y, temp, samples):
+    temp = x * x
+    temp.eval()
+    temp += y * y
+    temp.eval()
+    temp = sqrt(temp)
+    temp.eval()
+    temp = temp < 1
+    temp.eval()
+    return 4.0 * sum(temp) / samples
+
+def pi_jit(x, y, temp, samples):
+    temp = sqrt(x * x + y * y) < 1
+    temp.eval()
+    return 4.0 * sum(temp) / samples
+
+# [jit-endsnippet]

docs/afjit.py

@@ -0,0 +1,142 @@
+# [manipulation1-snippet]
+
+import arrayfire as af
+
+# Creates a 3x3 array filled with random numbers between [0, 1)
+a = af.randu((3, 3))
+
+# Flattens the array 'a' into a 1-dimensional column vector
+flat_a = af.flat(a)
+
+# Display the original array 'a'
+print(a)
+
+# [manipulation1-endsnippet]
+
+
+# [manipulation2-snippet]
+
+
+import arrayfire as af
+
+# Generate a 5x2 array of uniformly distributed random numbers between [0, 1)
+a = af.randu((5, 2))
+
+# Print the original array 'a'
+print("Original array 'a' [5 2 1 1]")
+print(a)
+
+# Flip the array 'a' along both axes (rows and columns)
+flip_a = af.flip(a)
+
+# Print the flipped array 'flip_a'
+print("\nFlipped array 'flip_a' [5 2 1 1]")
+print(flip_a)
+
+# [manipulation2-endsnippet]
+
+
+# [manipulation3-snippet]
+
+import arrayfire as af
+
+# Generate a 1-dimensional array 'a' of size 5 filled with uniformly distributed random numbers between [0, 1)
+a = af.randu((5,))
+
+# Print the original array 'a'
+print("Original array 'a' [5 1 1 1]")
+print(a)
+
+# Join the array 'a' with itself along axis 0
+a_join = af.join(0, a, a)
+
+# Print the joined array 'a_join'
+print("\nJoined array 'a_join' [10 1 1 1]")
+print(a_join)
+# [manipulation3-endsnippet]
+
+
+# [manipulation4-snippet]
+
+import arrayfire as af
+
+a = af.randu((8,))
+
+print(a)
+
+moddims_a = af.moddims(a,(2,4))
+
+print(moddims_a)
+
+moddims_b = af.moddims(a,(len(a),))
+print(moddims_b)
+
+# [manipulation4-endsnippet]
+
+
+# [manipulation5-snippet]
+
+
+import arrayfire as af
+
+a = af.randu((2,2,3,1))
+
+print(a)
+
+a_reorder = af.reorder(a,())
+# [manipulation5-endsnippet]
+
+# [manipulation6-snippet]
+
+import arrayfire as af
+
+a = af.randu((3,5))
+print(a)
+
+a_shift = af.shift(a,(0,2))
+print(a_shift)
+
+a_shift1 = af.shift(a,(-1,2))
+print(a_shift1)
+
+# [manipulation6-endsnippet]
+
+
+# [manipulation7-snippet]
+
+import arrayfire as af
+
+a = af.randu((3,)) #[3,1,1,1]
+
+print (a)
+
+a_tile = af.tile(a,(2,)) 
+print(a_tile)
+
+a_tile1 = af.tile(a,(2,2))
+print(a_tile1)
+
+a_tile2 = af.tile(a,(1,2,3)) 
+print(a_tile2)
+# [manipulation7-endsnippet]
+
+
+# [manipulation8-snippet]
+
+import arrayfire as af
+
+a = af.randu((3,3))
+print(a)  #[3 3 1 1]
+
+''' 0.3949     0.8465     0.3709
+    0.3561     0.9399     0.2751
+    0.6097     0.6802     0.2720'''
+    
+
+a_transpose = af.transpose(a)
+print(a_transpose) #[3 3 1 1]
+
+''' 0.3949     0.3561     0.6097
+        0.8465     0.9399     0.6802
+        0.3709     0.2751     0.2720'''
+# [manipulation8-endsnippet]

docs/arrayandmatrixmanipulation.py

@@ -0,0 +1,144 @@
+Array and Matrix Manipulation
+=============================
+ArrayFire provides several different methods for manipulating arrays and matrices. The functionality includes:
+
+* moddims() - change the dimensions of an array without changing the data
+* array() - create a (shallow) copy of an array with different dimensions.
+* flat() - flatten an array to one dimension
+* flip() - flip an array along a dimension
+* join() - join up to 4 arrays
+* reorder() - changes the dimension order within the array
+* shift() - shifts data along a dimension
+* tile() - repeats an array along a dimension
+* transpose() - performs a matrix transpose
+* T() - transpose a matrix or vector (shorthand notation)
+* H() - Hermitian Transpose (conjugate-transpose) a matrix
+
+Below we provide several examples of these functions and their use.
+
+flat()
+======
+The **flat()** function flattens an array to one dimension:
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation1-snippet]
+    :end-before: [manipulation1-endsnippet]
+
+The **flat** function can be called from Python as follows:
+
+.. admonition:: Function
+
+   af.flat(array) - Python function for flattening an array
+
+flip()
+======
+The **flip()** 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:
+
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation2-snippet]
+    :end-before: [manipulation2-endsnippet]
+
+The **flip** function can be called from Python as follows:
+
+.. admonition:: Function
+
+   af.flip(array) - Python function for flipping an array
+
+
+join()
+======
+
+The **join()** function joins arrays along a specific dimension. The C++ interface can join up to four arrays whereas the C interface supports up to 10 arrays. Here is an example of how to use join an array to itself:
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation3-snippet]
+    :end-before: [manipulation3-endsnippet]
+
+
+The **join** function can be called from Python as follows:
+
+.. admonition:: Function
+
+   af.join(0, array, array1) - Python function for joining arrays along a specified axis
+
+moddims()
+=========
+
+The **moddims()** 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:
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation4-snippet]
+    :end-before: [manipulation4-endsnippet]
+
+The moddims function has a single form in the Python API:
+
+.. admonition:: Function
+
+   af.moddims(array, (3,2)) - Python function for modifying dimensions of an array
+
+
+reorder()
+=========
+The **reorder()** 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.
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation5-snippet]
+    :end-before: [manipulation5-endsnippet]
+
+shift()
+=======
+The **shift()** function shifts data in a circular buffer fashion along a chosen dimension. Consider the following example:
+
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation6-snippet]
+    :end-before: [manipulation6-endsnippet]
+
+The shift function can be called from Python as follows:
+.. admonition:: Function
+
+   af.shift(array, (3,2)) - Python function for shifting arrays along specified dimension
+
+tile()
+======
+The **tile()** 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:
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation7-snippet]
+    :end-before: [manipulation7-endsnippet]
+
+.. admonition:: Function
+
+   af.tile(array, (3,2)) - Python function that tiles arrays along specified dimensions
+
+
+transpose()
+===========
+The **transpose()** function performs a standard matrix transpose. The input array must have the dimensions of a 2D-matrix.
+
+.. literalinclude:: arrayandmatrixmanipulation.py 
+    :language: python 
+    :start-after: [manipulation8-snippet]
+    :end-before: [manipulation8-endsnippet]
+
+    
+The python interface for transpose is as follows:
+
+.. admonition:: Function
+
+   af.transpose(array) - Python function to transpose matrix in place
+        
+
+
+array()
+=======
+**array()** can be used to create a (shallow) copy of a matrix with different dimensions. The total number of elements must remain the same. This function is a wrapper over the moddims() function discussed earlier.
+

docs/arrayandmatrixmanipulation.rst

@@ -0,0 +1,45 @@
+ArrayFire JIT Code Generation
+=============================
+The ArrayFire library offers JIT (Just In Time) compiling for elementwise arithmetic operations. This includes trigonometric functions, comparisons, and element-wise operations.
+
+At runtime, ArrayFire aggregates these function calls using an Abstract Syntax Tree (AST) data structure such that whenever a JIT-supported function is called, it is added into the AST for a given variable instance. The AST of the variable is computed if one of the following conditions is met:
+
+* an explication evaluation is required by the programmer using the eval function, or
+* the variable is required to compute a different variable that is not JIT-supported.
+
+When the above occurs, and the variable needs to be evaluated, the functions and variables in the AST data structure are used to create a single kernel. This is done by creating a customized kernel on-the-fly that is made up of all the functions in the AST. The customized function is then executed.
+
+This JIT compilation technique has multiple benefits:
+
+* A reduced number of kernel calls – a kernel call can be a significant overhead for small data sets.
+* Better cache performance – there are many instances in which the memory required by a single element in the array can be reused multiple times, or the temporary value of a computation can be stored in the cache and reused by future computations.
+* Temporary memory allocation and write-back can be reduced – when multiple expressions are evaluated and stored into temporary arrays, these arrays need to be allocated and the results written back to main memory.
+* Avoid computing elements that are not used – there are cases in which the AST is created for a variable; however, the expression is not used later in the computation. Thus, its evaluation can be avoided.
+* Better performance – all the above can help reduce the total execution time.
+
+.. literalinclude:: afjit.py
+    :language: python 
+    :start-after: [jit-snippet]
+    :end-before: [jit-endsnippet]
+
+
+The above code computes the value of π using a Monte-Carlo simulation where points are randomly generated within the unit square. Each point is tested to see if it is within the unit circle. The ratio of points within the circle and square approximate the value π. The accuracy of π improves as the number of samples is increased, which motivates using additional samples.
+
+There are two implementations above:
+
+1. an implementation that does not benefit from the JIT (pi_no_jit), and
+2. an implementation that takes advantage of the JIT feature (pi_jit).
+
+Specifically, as JIT is an integral feature of the ArrayFire library, it cannot simply be turned on and off. The only way for a programmer to sidestep the JIT operations is to manually force the evaluation of expressions. This is done in the non-JIT-supported implementation.
+
+Timing these two implementations results in the following performance benchmark:
+
+**Add Picture**
+
+The above figure depicts the execution time (abscissa) as a function of the number of samples (ordinate) for the two implementations discussed above.
+
+When the number of samples is small, the execution time of pi_no_jit is dominated by the launch of multiple kernels and the execution time pi_jit is dominated by on-the-fly compilation of the JIT code required to launch a single kernel. Even with this JIT compilation time, pi_jit outperforms pi_no_jit by 1.4-2.0X for smaller sample sizes.
+
+When the number of samples is large, both the kernel launch overhead and the JIT code creation are no longer the limiting factors – the kernel’s computational load dominates the execution time. Here, the pi_jit outperforms pi_no_jit by 2.0-2.7X.
+
+The number of applications that benefit from the JIT code generation is significant. The actual performance benefits are also application-dependent.