diff --git a/.gitignore b/.gitignore index f1a00b9..8019809 100644 --- a/.gitignore +++ b/.gitignore @@ -40,8 +40,7 @@ coverage.xml .pytest_cache/ # documentation build artifacts - -docs/*.md docs/api site/ mkdocs.yml +output-docs/ \ No newline at end of file diff --git a/arrayfire/__init__.py b/arrayfire/__init__.py index e5f2079..7a5c4a3 100755 --- a/arrayfire/__init__.py +++ b/arrayfire/__init__.py @@ -72,6 +72,8 @@ __all__ += [ "constant", + "zeros", + "ones", "diag", "identity", "iota", @@ -89,6 +91,7 @@ "flip", "join", "moddims", + "reshape", "reorder", "replace", "select", @@ -100,6 +103,8 @@ from arrayfire.library.array_functions import ( constant, + zeros, + ones, copy_array, diag, eval, @@ -114,6 +119,7 @@ lookup, lower, moddims, + reshape, pad, range, reorder, diff --git a/arrayfire/array_object.py b/arrayfire/array_object.py index d44ee29..9b715b1 100755 --- a/arrayfire/array_object.py +++ b/arrayfire/array_object.py @@ -869,8 +869,8 @@ def T(self) -> Array: Note ---- - - The array instance must be two-dimensional. If the array instance is not two-dimensional, an error - should be raised. + - The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised. + """ if self.ndim < 2: raise TypeError(f"Array should be at least 2-dimensional. Got {self.ndim}-dimensional array") @@ -881,6 +881,24 @@ def T(self) -> Array: @property @afarray_as_array def H(self) -> Array: + """ + Hermitian Conjugate of the array. + + Returns + ------- + Array + Two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to + original array with its elements complex conjugated. The returned array must have the same data type as the original array. + + Note + ---- + - The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised. + + """ + if self.ndim < 2: + raise TypeError(f"Array should be at least 2-dimensional. Got {self.ndim}-dimensional array") + + # TODO add check if out.dtype == self.dtype return cast(Array, wrapper.transpose(self._arr, True)) @property @@ -1096,6 +1114,39 @@ def device_pointer(self) -> int: def is_locked_array(self) -> bool: return wrapper.is_locked_array(self._arr) + @afarray_as_array + def reshape(self, shape) -> Array: + """ + Return a copy of this array with the specified shape without changing the data layout. + + Parameters + ---------- + shape : tuple of int + The desired shape of the output array. It should be a tuple of integers + representing the dimensions of the output array. The product of these + dimensions must match the total number of elements in the input array. + + Returns + ------- + out : af.Array + - An array containing the same data as `array` with the specified shape. + - The total number of elements in `array` must match the product of the dimensions specified in the `shape` tuple. + + Raises + ------ + ValueError + If the total number of elements in the input array does not match the + product of the dimensions specified in the `shape` tuple. + + Notes + ----- + This function modifies the shape of the input array without changing the + data layout. The resulting array will have the same data, but with a + different shape as specified by the `shape` parameter. + """ + # TODO add examples to doc + return cast(Array, wrapper.moddims(self._arr, shape)) + def lock_array(self) -> None: return wrapper.lock_array(self._arr) diff --git a/arrayfire/library/array_functions.py b/arrayfire/library/array_functions.py index e8028e5..ba78c5a 100644 --- a/arrayfire/library/array_functions.py +++ b/arrayfire/library/array_functions.py @@ -1,5 +1,7 @@ __all__ = [ "constant", + "zeros", + "ones", "diag", "identity", "iota", @@ -17,6 +19,7 @@ "flip", "join", "moddims", + "reshape", "reorder", "replace", "select", @@ -70,6 +73,59 @@ def constant(scalar: int | float | complex, shape: tuple[int, ...] = (1,), dtype """ return cast(Array, wrapper.create_constant_array(scalar, shape, dtype)) +def zeros(shape: tuple[int, ...], dtype: Dtype = float32) -> Array: + """ + Create a multi-dimensional array filled with zeros + + Parameters + ---------- + shape : tuple[int, ...], optional, default: (1,) + The shape of the constant array. + + dtype : Dtype, optional, default: float32 + Data type of the array. + + Returns + ------- + Array + A multi-dimensional ArrayFire array filled zeros + + Notes + ----- + The shape parameter determines the dimensions of the resulting array: + - If shape is (x1,), the output is a 1D array of size (x1,). + - If shape is (x1, x2), the output is a 2D array of size (x1, x2). + - If shape is (x1, x2, x3), the output is a 3D array of size (x1, x2, x3). + - If shape is (x1, x2, x3, x4), the output is a 4D array of size (x1, x2, x3, x4). + """ + return constant(0, shape, dtype) + +def ones(shape: tuple[int, ...], dtype: Dtype = float32) -> Array: + """ + Create a multi-dimensional array filled with ones + + Parameters + ---------- + shape : tuple[int, ...], optional, default: (1,) + The shape of the constant array. + + dtype : Dtype, optional, default: float32 + Data type of the array. + + Returns + ------- + Array + A multi-dimensional ArrayFire array filled ones + + Notes + ----- + The shape parameter determines the dimensions of the resulting array: + - If shape is (x1,), the output is a 1D array of size (x1,). + - If shape is (x1, x2), the output is a 2D array of size (x1, x2). + - If shape is (x1, x2, x3), the output is a 3D array of size (x1, x2, x3). + - If shape is (x1, x2, x3, x4), the output is a 4D array of size (x1, x2, x3, x4). + """ + return constant(1, shape, dtype) @afarray_as_array def diag(array: Array, /, *, diag_index: int = 0, extract: bool = True) -> Array: @@ -255,8 +311,7 @@ def lower(array: Array, /, *, is_unit_diag: bool = False) -> Array: Notes ----- - The function does not alter the elements above the main diagonal; it simply does not include them in the output. - - This function can be useful for mathematical operations that require lower triangular matrices, such as certain - types of matrix factorizations. + - This function can be useful for mathematical operations that require lower triangular matrices, such as certain types of matrix factorizations. Examples -------- @@ -312,8 +367,7 @@ def upper(array: Array, /, *, is_unit_diag: bool = False) -> Array: Notes ----- - The function does not alter the elements below the main diagonal; it simply does not include them in the output. - - This function can be useful for mathematical operations that require upper triangular matrices, such as certain - types of matrix factorizations. + - This function can be useful for mathematical operations that require upper triangular matrices, such as certain types of matrix factorizations. Examples -------- @@ -818,6 +872,40 @@ def moddims(array: Array, shape: tuple[int, ...], /) -> Array: # TODO add examples to doc return cast(Array, wrapper.moddims(array.arr, shape)) +def reshape(array: Array, shape: tuple[int, ...], /) -> Array: + """ + Modify the shape of the array without changing the data layout. + + Parameters + ---------- + array : af.Array + Multi-dimensional array to be reshaped. + + shape : tuple of int + The desired shape of the output array. It should be a tuple of integers + representing the dimensions of the output array. The product of these + dimensions must match the total number of elements in the input array. + + Returns + ------- + out : af.Array + - An array containing the same data as `array` with the specified shape. + - The total number of elements in `array` must match the product of the + dimensions specified in the `shape` tuple. + + Raises + ------ + ValueError + If the total number of elements in the input array does not match the + product of the dimensions specified in the `shape` tuple. + + Notes + ----- + This function modifies the shape of the input array without changing the + data layout. The resulting array will have the same data, but with a + different shape as specified by the `shape` parameter. + """ + return moddims(array, shape) @afarray_as_array def reorder(array: Array, /, *, shape: tuple[int, ...] = (1, 0, 2, 3)) -> Array: diff --git a/arrayfire/library/computer_vision.py b/arrayfire/library/computer_vision.py index 95f25d4..2e6de41 100644 --- a/arrayfire/library/computer_vision.py +++ b/arrayfire/library/computer_vision.py @@ -53,7 +53,7 @@ def gloh( A tuple containing two elements: - `Features`: An object holding the detected features, including their locations and scales. - `Array`: An ArrayFire array containing the GLOH descriptors for the detected features, with each descriptor - having 272 elements. + having 272 elements. Note ---- @@ -164,8 +164,7 @@ def sift( tuple[Features, Array] A tuple containing: - An ArrayFire Features object encapsulating the detected keypoints. - - An ArrayFire Array containing the corresponding descriptors for each keypoint. The descriptors are - 128-dimensional vectors describing the local appearance around each keypoint. + - An ArrayFire Array containing the corresponding descriptors for each keypoint. The descriptors are 128-dimensional vectors describing the local appearance around each keypoint. Note ---- diff --git a/dev-requirements.txt b/dev-requirements.txt index 31e4b98..7c3e0e6 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -18,3 +18,8 @@ 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 +sphinx_collapse>=0.1.3 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3fd2f2f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +Documentation (WIP) +========== + +**This documentation is a work in progress and may not contain all currently supported operations. Please check the functions signature and description for more info on it** + +We use [`Sphinx`](https://www.sphinx-doc.org/en/master/index.html) for presenting our documentation. + +To build the docs follow these steps: + +1. Install the required sphinx packages and extensions from the [dev-requirements.txt](../dev-requirements.txt) +```sh +pip install -r dev-requirements.txt # install sphinx and its extensions +pip install -r requirements.txt # install arrayfire-binary-python-wrapper +``` +2. Build docs using sphinx +```sh +sphinx-build -M html docs/ output-docs/ # builds docs as html files stored in output-docs +``` +3. Explore the docs starting at `output-docs/index.html` + diff --git a/docs/TODO b/docs/TODO new file mode 100644 index 0000000..f80a47d --- /dev/null +++ b/docs/TODO @@ -0,0 +1,7 @@ +TODO +===== + +- Add docstring to function image processing +- Change to where the Restructured Files for the undocumented functions point to (currently some point to docs in the arrayfire-binary-python-wrapper) +- Add more detail to the constants and classes +- Add more information in the python installation section \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..0ba166f --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,13 @@ +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 */ +} + +.responsive-img { + max-width: 100%; + height: auto; +} \ No newline at end of file diff --git a/docs/afjit.py b/docs/afjit.py new file mode 100644 index 0000000..de40c05 --- /dev/null +++ b/docs/afjit.py @@ -0,0 +1,50 @@ +# [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. + +import arrayfire as af +import time + +samples = int(9e8) +x = af.randu((samples)) +y = af.randu((samples)) + +def pi_no_jit(x, y, samples): + temp = x * x + af.eval(temp) + temp += y * y + af.eval(temp) + temp = af.sqrt(temp) + af.eval(temp) + temp = temp < 1 + af.eval(temp) + return 4.0 * af.sum(temp) / samples + +def pi_jit(x, y, samples): + temp = af.sqrt(x * x + y * y) < 1 + af.eval(temp) + return 4.0 * af.sum(temp) / samples + +# Print device info +af.info() + +# Time JIT code +start = time.perf_counter() +res = pi_jit(x, y, samples) +af.sync() +end = time.perf_counter() + +print("jit:", end - start, res) +af.device_gc() + +# Time no JIT code +start = time.perf_counter() +res = pi_no_jit(x, y, samples) +af.sync() +end = time.perf_counter() +print("no jit:", end - start, res) + +# [jit-endsnippet] \ No newline at end of file diff --git a/docs/array_creation_functions.rst b/docs/array_creation_functions.rst new file mode 100644 index 0000000..aaef83d --- /dev/null +++ b/docs/array_creation_functions.rst @@ -0,0 +1,50 @@ +Array Creation Functions +========================== + +Functions in this category are used to initialize arrays with specific values or patterns. + +.. list-table:: Functions + + * - :doc:`af.cast() ` + - Cast an array from one type to another. + * - :doc:`af.constant() ` + - Create an array from a scalar input value. + * - :doc:`af.copy_array() ` + - Performs a deep copy of the array. + * - :doc:`af.cplx() ` + - Creates complex arrays from real and imaginary parts + * - :doc:`af.diag() ` + - Extract the diagonal from an array. + * - :doc:`af.eval() ` + - Evaluate an expression (nonblocking). + * - :doc:`af.gaussian_kernel() ` + - Creates a Gaussian Kernel. + * - :doc:`af.identity() ` + - Generate an identity matrix. + * - :doc:`af.iota() ` + - Generate an array with [0, n-1] values modified to specified dimensions and tiling. + * - :doc:`af.isinf() ` + - Check if values are infinite. + * - :doc:`af.isnan() ` + - Check if values are NaN. + * - :doc:`af.iszero() ` + - Check if values are zero. + * - :doc:`af.lookup() ` + - Lookup values of an array by indexing with another array. + * - :doc:`af.lower() ` + - Return the lower triangular matrix from an input array. + - Find maximum value from a window. + * - :doc:`af.ones() ` + - Creates an array filled with ones.\ + * - :doc:`af.randn() ` + - Create a random array sampled from normal distribution. + * - :doc:`af.randu() ` + - Create a random array sampled from uniform distribution. + * - :doc:`af.range() ` + - Generate an array with [0, n-1] values along the a specified dimension and tiled across other dimensions. + * - :doc:`af.upper() ` + - Return the upper triangular matrix from an input array. + * - :doc:`af.where() ` + - Locate the indices of the non-zero values in an array. + * - :doc:`af.zeros() ` + - Creates an array filled with zeros. \ No newline at end of file diff --git a/docs/array_manipulation_functions.rst b/docs/array_manipulation_functions.rst new file mode 100644 index 0000000..73fbf76 --- /dev/null +++ b/docs/array_manipulation_functions.rst @@ -0,0 +1,55 @@ +Array Manipulation +=================== + +These functions help modify the structure or arrangement of arrays. + +.. list-table:: Functions + + * - :doc:`af.approx1() ` + - Interpolation across a single dimension. + * - :doc:`af.approx1_uniform() ` + - Interpolation across a single dimension in uniform steps + * - :doc:`af.approx2() ` + - Interpolation along two dimensions. + * - :doc:`af.approx2_uniform() ` + - Interpolation along two dimensions in uniform steps + * - :doc:`af.flat() ` + - Flatten an array. + * - :doc:`af.flip() ` + - Flip the input along a specified dimension. + * - :doc:`af.join() ` + - Join up to 4 arrays along specified dimension. + * - :doc:`af.pad() ` + - Pad an array. + * - :doc:`af.reorder() ` + - Reorder an array. + * - :doc:`af.replace() ` + - Replace elements of an array with elements of another array. + * - :doc:`af.reshape() ` + - Modify the dimensions of an array without changing the order of its elements + * - :doc:`af.resize() ` + - Resize an input image. + * - :doc:`af.rotate() ` + - Rotate an input image or array. + * - :doc:`af.scale() ` + - Scale an input image. + * - :doc:`af.select() ` + - Select elements based on a conditional array. + * - :doc:`af.set_intersect() ` + - Evaluate the intersection of two arrays + * - :doc:`af.set_union() ` + - Evaluate the union of two arrays + * - :doc:`af.set_unique() ` + - Return the unique values in an array + * - :doc:`af.shift() ` + - Shift an array. + * - :doc:`af.sort() ` + - Sort an array over a given dimension + * - :doc:`af.tile() ` + - Generate a tiled array by repeating an array's contents along a specified dimension. + * - :doc:`af.transpose() ` + - Transpose a matrix. + * - :doc:`af.unwrap() ` + - Rearrange windowed sections of an array into columns (or rows) + * - :doc:`af.wrap() ` + - Performs the opposite of af::unwrap(). \ No newline at end of file diff --git a/docs/arrayandmatrixmanipulation.py b/docs/arrayandmatrixmanipulation.py new file mode 100644 index 0000000..55d5f77 --- /dev/null +++ b/docs/arrayandmatrixmanipulation.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] diff --git a/docs/arrayandmatrixmanipulation.rst b/docs/arrayandmatrixmanipulation.rst new file mode 100644 index 0000000..fbc0fc2 --- /dev/null +++ b/docs/arrayandmatrixmanipulation.rst @@ -0,0 +1,145 @@ +Array and Matrix Manipulation +============================= +ArrayFire provides several different methods for manipulating arrays and matrices. The functionality includes: + +* :doc:`moddims() ` - change the dimensions of an array without changing the data +* :doc:`Array() ` - create a (shallow) copy of an array with different dimensions. +* :doc:`flat() ` - flatten an array to one dimension +* :doc:`flip() ` - flip an array along a dimension +* :doc:`join() ` - join up to 4 arrays +* :doc:`reorder() ` - changes the dimension order within the array +* :doc:`shift() ` - shifts data along a dimension +* :doc:`tile() ` - repeats an array along a dimension +* :doc:`transpose() ` - performs a matrix transpose +* :doc:`Array property T ` - transpose a matrix or vector (shorthand notation) +* :doc:`Array property 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 another Array with dimensions different to the original. +The total number of elements must remain the same. This function is a wrapper over the moddims() function discussed earlier. + diff --git a/docs/arrayfirejitcodegeneration.rst b/docs/arrayfirejitcodegeneration.rst new file mode 100644 index 0000000..b09315c --- /dev/null +++ b/docs/arrayfirejitcodegeneration.rst @@ -0,0 +1,48 @@ +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: + +.. image:: images/afjit_benchmark.png + :alt: Benchmark Results + :align: center + :class: responsive-img + +The above figure depicts the execution time as a function of the number of samples for the two implementations discussed above. + +When the number of samples is small (less than 100k samples), 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 (more than 1 million samples), 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 3-25X. + +The number of applications that benefit from the JIT code generation is significant. The actual performance benefits are also application-dependent. \ No newline at end of file diff --git a/docs/classes/Features.rst b/docs/classes/Features.rst new file mode 100644 index 0000000..b977887 --- /dev/null +++ b/docs/classes/Features.rst @@ -0,0 +1,4 @@ +Features +========== + +.. autoclass:: arrayfire.library.features.Features \ No newline at end of file diff --git a/docs/classes/RandomEngine.rst b/docs/classes/RandomEngine.rst new file mode 100644 index 0000000..e44f2c6 --- /dev/null +++ b/docs/classes/RandomEngine.rst @@ -0,0 +1,7 @@ +Random Engine +============== + +.. autoclass:: arrayfire.library.random.RandomEngine + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/classes/array.rst b/docs/classes/array.rst new file mode 100644 index 0000000..75339ad --- /dev/null +++ b/docs/classes/array.rst @@ -0,0 +1,37 @@ +Array +===== + +The 'af.Array()' class provides a powerful framework for performing high-performance numerical computations. It is designed to create an ArrayFire array from various data structures, such as Python lists or other iterable collections. + +Function +-------- +:literal:`af.Array()` + - Python interface to form an array. + + +Detailed Description +-------------------- +The 'af.Array()' object allows you to convert a data structure, such as a Python list or tuple, into an ArrayFire array. This conversion is essential for leveraging ArrayFire's optimized computational capabilities. By creating an array from a list or another iterable, you can perform efficient mathematical operations, matrix manipulations, and other numerical computations using ArrayFire's APIs. + +It supports multiple data types and can handle multi-dimensional arrays. The ability to create an ArrayFire array from native Python structures makes it easier to integrate ArrayFire into Python-based workflows. + +Function Documentation +---------------------- +.. sidebar:: af.Array() + + Syntax: + af.Array(data) + + Parameters: + 'data': A list, tuple, or another iterable containing the elements to be converted into an ArrayFire array. The data should be in a format that ArrayFire can interpret, such as nested lists for multi-dimensional arrays. + + Returns: + An ArrayFire array containing the elements from the input data structure. + +.. autoclass:: arrayfire.Array + :members: + :undoc-members: + :show-inheritance: + + + diff --git a/docs/classes/index.rst b/docs/classes/index.rst new file mode 100644 index 0000000..0fa4715 --- /dev/null +++ b/docs/classes/index.rst @@ -0,0 +1,10 @@ +:orphan: + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Classes List: + + Features + RandomEngine + array diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..ca827f1 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,48 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +import sys +import os +sys.path.insert(0, os.path.abspath('..')) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'ArrayFire' +copyright = '2025, ArrayFire' +author = 'ArrayFire' +release = '' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.mathjax', + 'sphinx_collapse', +] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinxawesome_theme' +html_static_path = ['_static'] +html_permalinks = False +html_theme_options = { + "logo_light": "_static/../images/arrayfire_icon.png", + "logo_dark": "_static/../images/arrayfire_icon.png" +} + +# -- Suppress specific warnings -------------------------------------------- + +suppress_warnings = [ + 'ref.include_missing', +] diff --git a/docs/configuringarrayfireenvironment.rst b/docs/configuringarrayfireenvironment.rst new file mode 100644 index 0000000..80ee50b --- /dev/null +++ b/docs/configuringarrayfireenvironment.rst @@ -0,0 +1,254 @@ +Configuring ArrayFire Environment +================================= +This page lists environment and runtime configurations that will help enhance your experience with ArrayFire. +The following are useful environment variable that can be used with ArrayFire. + +For Device Execution +#################### + +`AF_CUDA_DEFAULT_DEVICE` +************************ + +Use this variable to set the default CUDA device. Valid values for this +variable are the device identifiers shown when af::info is run. + +.. code-block:: bash + + AF_CUDA_DEFAULT_DEVICE=1 python myprogram_cuda.py + + +`AF_ONEAPI_DEFAULT_DEVICE` +*************************** + +Use this variable to set the default oneAPI device. Valid values for this +variable are the device identifiers shown when af::info is run. + +.. code-block:: bash + + AF_ONEAPI_DEFAULT_DEVICE=1 python myprogram_oneapi.py + + +Note: af::setDevice call in the source code will take precedence over this +variable. + +`AF_OPENCL_DEFAULT_DEVICE` +************************** + +Use this variable to set the default OpenCL device. Valid values for this +variable are the device identifiers shown when af::info is run. + +.. code-block:: bash + + AF_OPENCL_DEFAULT_DEVICE=1 python myprogram_opencl.py + + +Note: af::setDevice call in the source code will take precedence over this +variable. + +`AF_OPENCL_DEFAULT_DEVICE_TYPE` +******************************* + +Use this variable to set the default OpenCL device type. Valid values for this +variable are: CPU, GPU, ACC (Accelerators). + +When set, the first device of the specified type is chosen as default device. + +.. code-block:: bash + + AF_OPENCL_DEFAULT_DEVICE_TYPE=CPU python myprogram_opencl.py + + +Note: `AF_OPENCL_DEFAULT_DEVICE` and af::setDevice takes precedence over this variable. + +`AF_OPENCL_DEVICE_TYPE` +*********************** + +Use this variable to only choose OpenCL devices of specified type. Valid values for this +variable are: + +- ALL: All OpenCL devices. (Default behavior). +- CPU: CPU devices only. +- GPU: GPU devices only. +- ACC: Accelerator devices only. + +When set, the remaining OpenCL device types are ignored by the OpenCL backend. + +.. code-block:: bash + + AF_OPENCL_DEVICE_TYPE=CPU python myprogram_opencl.py + + +`AF_OPENCL_CPU_OFFLOAD` +************************ + +When ArrayFire runs on devices with unified memory with the host (ie. +`CL_DEVICE_HOST_UNIFIED_MENORY` is true for the device) then certain functions +are offloaded to run on the CPU using mapped buffers. + +ArrayFire takes advantage of fast libraries such as MKL while spending no time +copying memory from device to host. The device memory is mapped to a host +pointer which can be used in the offloaded functions. + +This functionality can be disabled by using the environment variable +`AF_OPENCL_CPU_OFFLOAD=0`. + +The default bevaior of this has changed in version 3.4. + +Prior to v3.4, CPU Offload functionality was used only when the user set +`AF_OPENCL_CPU_OFFLOAD=1` and disabled otherwise. + +From v3.4 onwards, CPU Offload is enabled by default and is disabled only when +`AF_OPENCL_CPU_OFFLOAD=0` is set. + +For Debugging +############# + +`AF_VERBOSE_LOADS` +******************* + +The arrayfire binary python wrapper (`arrayfire_wrapper` package) searches for default locations where +the arrayfire binaries may be located for loading. When set to 1, ArrayFire will print the locations +where the backend binaries are being searched and if loading the library at the location was successful. + +.. code-block:: bash + + AF_VERBOSE_LOADS=1 python myprogram.py + +`AF_PRINT_ERRORS` +****************** + +When AF_PRINT_ERRORS is set to 1, the exceptions thrown are more verbose and +detailed. This helps in locating the exact failure. + +.. code-block:: bash + + AF_PRINT_ERRORS=1 python myprogram.py + + +`AF_TRACE` +********** +This is a comma separated +list of modules to trace. If enabled, ArrayFire will print relevant information +to stdout. Currently the following modules are supported: + +- all: All trace outputs +- jit: Logs kernel fetch & respective compile options and any errors. +- mem: Memory management allocation, free and garbage collection information +- platform: Device management information +- unified: Unified backend dynamic loading information + +Tracing displays the information that could be useful when debugging or +optimizing your application. Here is how you would use this variable: + +.. code-block:: bash + + AF_TRACE=mem,unified python myprogram.py + +This will print information about memory operations such as allocations, +deallocations, and garbage collection. + +All trace statements printed to the console have a suffix with the following +pattern. + +:literal:`[category][Seconds since Epoch][Thread Id][source file relative path] \` + +`AF_OPENCL_SHOW_BUILD_INFO` +*************************** + +This variable is useful when debugging OpenCL kernel compilation failures. When +this variable is set to 1, and an error occurs during a OpenCL kernel +compilation, then the log and kernel are printed to screen. + +`AF_MEM_DEBUG` +************** + +When AF_MEM_DEBUG is set to 1 (or anything not equal to 0), the caching +mechanism in the memory manager is disabled. The device buffers are allocated +using native functions as needed and freed when going out of scope. + +When the environment variable is not set, it is treated to be zero. + +.. code-block:: + + AF_MEM_DEBUG=1 python myprogram.py + +`AF_MAX_BUFFERS` +***************** + +When AF_MAX_BUFFERS is set, this environment variable specifies the maximum +number of buffers allocated before garbage collection kicks in. + +Please note that the total number of buffers that can exist simultaneously can +be higher than this number. This variable tells the garbage collector that it +should free any available buffers immediately if the treshold is reached. + +When not set, the default value is 1000. + +`AF_OPENCL_MAX_JIT_LEN` +************************* + +When set, this environment variable specifies the maximum height of the OpenCL +JIT tree after which evaluation is forced. + +The default value, as of v3.4, is 50 on OSX, 100 everywhere else. This value was +20 for older versions. + +`AF_CUDA_MAX_JIT_LEN` +********************* + +When set, this environment variable specifies the maximum height of the CUDA JIT +tree after which evaluation is forced. + +The default value, as of v3.4, 100. This value was 20 for older versions. + +`AF_CPU_MAX_JIT_LEN` +******************** + +When set, this environment variable specifies the maximum length of the CPU JIT +tree after which evaluation is forced. + +The default value, as of v3.4, 100. This value was 20 for older versions. + +`AF_BUILD_LIB_CUSTOM_PATH` +************************** + +When set, this environment variable specifies a custom path along which the +symbol manager will search for dynamic (shared library) backends to load. This +is useful for specialized build configurations that use the unified backend and +build shared libraries separately. + +By default, no additional path will be searched for an empty value. + + +`AF_JIT_KERNEL_TRACE` +********************** + +When set, this environment variable has to be set to one of the following +three values: + +- stdout : generated kernels will be printed to standard output +- stderr : generated kernels will be printed to standard error stream +- absolute path to a folder on the disk where generated kernels will be stored + +CUDA backend kernels are stored in files with cu file extension. + +OpenCL backend kernels are stored in files with cl file extension. + +`AF_JIT_KERNEL_CACHE_DIRECTORY` +******************************* + +This variable sets the path to the ArrayFire cache on the filesystem. If set +ArrayFire will write the kernels that are compiled at runtime to this directory. +If the path is not writeable, the default path is used. + +This path is different from AF_JIT_KERNEL_TRACE which stores strings. These +kernels will store binaries and the content will be dependent on the +backend and platforms used. + +The default path is determined in the following order: + Unix: + 1. $HOME/.arrayfire + 2. /tmp/arrayfire + Windows: + 1. ArrayFire application Temp folder(Usually + C:\\Users\\\\\AppData\\Local\\Temp\\ArrayFire) \ No newline at end of file diff --git a/docs/constants/BinaryOperator.rst b/docs/constants/BinaryOperator.rst new file mode 100644 index 0000000..3cc695f --- /dev/null +++ b/docs/constants/BinaryOperator.rst @@ -0,0 +1,7 @@ +BinaryOperator Enum +==================== + +.. autoclass:: arrayfire_wrapper.lib.BinaryOperator + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/constants/CSpace.rst b/docs/constants/CSpace.rst new file mode 100644 index 0000000..84bfea7 --- /dev/null +++ b/docs/constants/CSpace.rst @@ -0,0 +1,7 @@ +CSpace Enum +============ + +.. autoclass:: arrayfire_wrapper.lib.CSpace + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/CannyThreshold.rst b/docs/constants/CannyThreshold.rst new file mode 100644 index 0000000..1929d9a --- /dev/null +++ b/docs/constants/CannyThreshold.rst @@ -0,0 +1,7 @@ +CannyThreshold Enum +==================== + +.. autoclass:: arrayfire_wrapper.lib.CannyThreshold + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/constants/Connectivity.rst b/docs/constants/Connectivity.rst new file mode 100644 index 0000000..045165b --- /dev/null +++ b/docs/constants/Connectivity.rst @@ -0,0 +1,7 @@ +Connectivity Enum +================== + +.. autoclass:: arrayfire_wrapper.lib.Connectivity + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/ConvDomain.rst b/docs/constants/ConvDomain.rst new file mode 100644 index 0000000..e7032ca --- /dev/null +++ b/docs/constants/ConvDomain.rst @@ -0,0 +1,7 @@ +ConvDomain Enum +================ + +.. autoclass:: arrayfire_wrapper.lib.ConvDomain + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/ConvGradient.rst b/docs/constants/ConvGradient.rst new file mode 100644 index 0000000..32d7680 --- /dev/null +++ b/docs/constants/ConvGradient.rst @@ -0,0 +1,7 @@ +ConvGradient Enum +================== + +.. autoclass:: arrayfire_wrapper.lib.ConvGradient + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/ConvMode.rst b/docs/constants/ConvMode.rst new file mode 100644 index 0000000..73465fa --- /dev/null +++ b/docs/constants/ConvMode.rst @@ -0,0 +1,7 @@ +ConvMode Enum +============== + +.. autoclass:: arrayfire_wrapper.lib.ConvMode + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Diffusion.rst b/docs/constants/Diffusion.rst new file mode 100644 index 0000000..1d594c7 --- /dev/null +++ b/docs/constants/Diffusion.rst @@ -0,0 +1,7 @@ +Diffusion Enum +=============== + +.. autoclass:: arrayfire_wrapper.lib.Diffusion + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Dtype.rst b/docs/constants/Dtype.rst new file mode 100644 index 0000000..a1f6200 --- /dev/null +++ b/docs/constants/Dtype.rst @@ -0,0 +1,28 @@ +Supported Data Types +===================== + +.. autodata:: arrayfire_wrapper.b8 + +.. autodata:: arrayfire_wrapper.u8 + +.. autodata:: arrayfire_wrapper.u16 + +.. autodata:: arrayfire_wrapper.u32 + +.. autodata:: arrayfire_wrapper.u64 + +.. autodata:: arrayfire_wrapper.s16 + +.. autodata:: arrayfire_wrapper.s32 + +.. autodata:: arrayfire_wrapper.s64 + +.. autodata:: arrayfire_wrapper.f16 + +.. autodata:: arrayfire_wrapper.f32 + +.. autodata:: arrayfire_wrapper.f64 + +.. autodata:: arrayfire_wrapper.c32 + +.. autodata:: arrayfire_wrapper.c64 \ No newline at end of file diff --git a/docs/constants/Flux.rst b/docs/constants/Flux.rst new file mode 100644 index 0000000..ff66c20 --- /dev/null +++ b/docs/constants/Flux.rst @@ -0,0 +1,7 @@ +Flux Enum +========== + +.. autoclass:: arrayfire_wrapper.lib.Flux + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/ImageFormat.rst b/docs/constants/ImageFormat.rst new file mode 100644 index 0000000..6d704bc --- /dev/null +++ b/docs/constants/ImageFormat.rst @@ -0,0 +1,7 @@ +ImageFormat Enum +================= + +.. autoclass:: arrayfire_wrapper.lib.ImageFormat + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Interp.rst b/docs/constants/Interp.rst new file mode 100644 index 0000000..63d40bc --- /dev/null +++ b/docs/constants/Interp.rst @@ -0,0 +1,7 @@ +Interp Enum +============ + +.. autoclass:: arrayfire_wrapper.lib.Interp + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/IterativeDeconv.rst b/docs/constants/IterativeDeconv.rst new file mode 100644 index 0000000..bab1a17 --- /dev/null +++ b/docs/constants/IterativeDeconv.rst @@ -0,0 +1,7 @@ +IterativeDeconv Enum +===================== + +.. autoclass:: arrayfire_wrapper.lib.IterativeDeconv + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/MatProp.rst b/docs/constants/MatProp.rst new file mode 100644 index 0000000..8c0e693 --- /dev/null +++ b/docs/constants/MatProp.rst @@ -0,0 +1,7 @@ +MatProp Enum +============= + +.. autoclass:: arrayfire_wrapper.lib.MatProp + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Match.rst b/docs/constants/Match.rst new file mode 100644 index 0000000..0802fd0 --- /dev/null +++ b/docs/constants/Match.rst @@ -0,0 +1,7 @@ +Match Enum +=========== + +.. autoclass:: arrayfire_wrapper.lib.Match + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Norm.rst b/docs/constants/Norm.rst new file mode 100644 index 0000000..7b96d28 --- /dev/null +++ b/docs/constants/Norm.rst @@ -0,0 +1,7 @@ +Norm Enum +========== + +.. autoclass:: arrayfire_wrapper.lib.Norm + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/Pad.rst b/docs/constants/Pad.rst new file mode 100644 index 0000000..fdf2b4c --- /dev/null +++ b/docs/constants/Pad.rst @@ -0,0 +1,7 @@ +Pad Enum +========= + +.. autoclass:: arrayfire_wrapper.lib.Pad + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/RandomEngineType.rst b/docs/constants/RandomEngineType.rst new file mode 100644 index 0000000..4091fdb --- /dev/null +++ b/docs/constants/RandomEngineType.rst @@ -0,0 +1,7 @@ +RandomEngineType Enum +====================== + +.. autoclass:: arrayfire.library.random.RandomEngineType + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/TopK.rst b/docs/constants/TopK.rst new file mode 100644 index 0000000..3f51fcc --- /dev/null +++ b/docs/constants/TopK.rst @@ -0,0 +1,7 @@ +TopK Enum +========== + +.. autoclass:: arrayfire_wrapper.lib.TopK + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/VarianceBias.rst b/docs/constants/VarianceBias.rst new file mode 100644 index 0000000..6b1c13c --- /dev/null +++ b/docs/constants/VarianceBias.rst @@ -0,0 +1,7 @@ +VarianceBias Enum +================== + +.. autoclass:: arrayfire_wrapper.lib.VarianceBias + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/YCCStd.rst b/docs/constants/YCCStd.rst new file mode 100644 index 0000000..0041f55 --- /dev/null +++ b/docs/constants/YCCStd.rst @@ -0,0 +1,7 @@ +YCCStd Enum +============ + +.. autoclass:: arrayfire_wrapper.lib.YCCStd + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/constants/index.rst b/docs/constants/index.rst new file mode 100644 index 0000000..d0f6e51 --- /dev/null +++ b/docs/constants/index.rst @@ -0,0 +1,28 @@ +:orphan: + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Constants List: + + BinaryOperator + CSpace + CannyThreshold + Connectivity + ConvDomain + ConvGradient + ConvMode + Diffusion + Dtype + Flux + ImageFormat + Interp + IterativeDeconv + MatProp + Match + Norm + Pad + RandomEngineType + TopK + VarianceBias + YCCStd diff --git a/docs/data_reduction_functions.rst b/docs/data_reduction_functions.rst new file mode 100644 index 0000000..7544ce6 --- /dev/null +++ b/docs/data_reduction_functions.rst @@ -0,0 +1,41 @@ +Data Reduction +=============== + +Functions for aggregating and reducing data to summarize or condense information. + +.. list-table:: + + * - :doc:`af.accum() ` + - Evaluate the cumulative sum (inclusive) along a given dimension. + * - :doc:`af.all_true() ` + - Check if all values along a given dimension are true. + * - :doc:`af.any_true() ` + - Check if any values along a given dimension are true. + * - :doc:`af.count() ` + - Count non-zero values in an array along a given dimension. + * - :doc:`af.dot() ` + - Compute the dot product. + * - :doc:`af.imax() ` + - Finds the maximum value. + * - :doc:`af.imin() ` + - Finds the minimum value. + * - :doc:`af.max() ` + - Return the maximum along a given dimension. + * - :doc:`af.maxof() ` + - Elementwise maximum between two arrays + * - :doc:`af.mean() ` + - Find the mean of values in the input. + * - :doc:`af.median() ` + - Find the median of values in the input. + * - :doc:`af.min() ` + - Return the minimum along a given dimension. + * - :doc:`af.minof() ` + - Elementwise minimum between two arrays + * - :doc:`af.product() ` + - Multiply array elements over a given dimension. + * - :doc:`af.scan() ` + - Scan an array (generalized) over a given dimension. + * - :doc:`af.sttdev() ` + - Find the standard deviation of values in the input. + * - :doc:`af.sum() ` + - Sum array elements over a given dimension. \ No newline at end of file diff --git a/docs/debuggingarrayfirecode.rst b/docs/debuggingarrayfirecode.rst new file mode 100644 index 0000000..c87c7d4 --- /dev/null +++ b/docs/debuggingarrayfirecode.rst @@ -0,0 +1,71 @@ +Debugging ArrayFire Issues +========================== + +Using Exceptions +################# + +When an error is encountered (incorrect arguments or some calculation error), ArrayFire will raise an exception. This exception +contains a stacktrace on which arrayfire function is raising the error and what is the cause for it. For example, this code will raise +an print an exception: + +.. code-block:: python + + import arrayfire as af + x = af.randu(10) + y = af.randu(5) + + try: + # Arrays have non-broadcastable shapes + res = x + y + catch Exception as e: + print(e) + +This may produce the following output + +.. code-block:: bash + + In function arithOpBroadcast + In file src\api\c\binary.cpp:81 + Invalid dimension for argument 1 + Expected: ((lshape[d] == rshape[d]) || (lshape[d] == 1 && rshape[d] > 1) || (lshape[d] > 1 && rshape[d] == 1)) + 0# af::exception::~exception in afcuda + 1# af_bilateral in afcuda + 2# af_bilateral in afcuda + 3# af_add in afcuda + 4# ffi_prep_go_closure in libffi_8 + 5# ffi_call_go in libffi_8 + 6# ffi_call in libffi_8 + 7# 0x00007FFCD2833C05 in _ctypes + 8# 0x00007FFCD2832ACA in _ctypes + 9# 0x00007FFCD28326C8 in _ctypes + + +Using ArrayFire Debug/Utility Functions +######################################## + +For issues with specific devices or memory limitations, ArrayFire provides functions to inform the user the current +device and allocations. + +For checking device information we have the functions: + +* :doc:`get_device() ` and :doc:`get_device_count()` gets the devices on the current backend +* :doc:`get_dbl_support(device_id)` and :doc:`get_half_support(device_id)` provides information for f64 and f16 type support +* :doc:`device_info(device_id)`, :doc:`info()`, :doc:`info_string()` provides backend, vendor, and version of device +* :doc:`device_gc()` forces garbage collection of unused arrays on current device +* :doc:`get_mem_step_size()` and :doc:`set_mem_step_size(mem_size)` allows getting and setting the size of allocation groups +* :doc:`print_mem_info(prepend_message, device_id)`: Print table of memory used by ArrayFire on the selected device + +Using ArrayFire's environment variables +####################################### + +For internal information related to the kernels generated by the JIT, allocation triggers, and extra information, ArrayFire +provides environment variables that enable extra tracing information that will be printed into stdout. + +Please check the section of +:doc:`Debugging Environment Variables in Configuring ArrayFire Environment` +for a list of all the debug variables and their usage. + +Further Reading +############### +For outstanding issues related to ArrayFire, you may visit the Github Issues in `ArrayFire Python `_ +and `ArrayFire C/C++ Libraries `_ \ No newline at end of file diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..cae41e7 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,40 @@ +Examples +======== + +.. collapse:: Getting Started + + .. list-table:: + + * - :download:`intro.py <../examples/getting_started/intro.py>` + - Shows how to set a device, initialize arrays, and do some array operations + * - :download:`convolve.py <../examples/getting_started/convolve.py>` + - Shows how to do convolutions on 2D images + +.. collapse:: Linear Algebra + + .. list-table:: + + * - :download:`cholesky.py <../examples/linear_algebra/cholesky.py>` + - Shows Cholesky decomposition in/out of place + * - :download:`lu.py <../examples/linear_algebra/lu.py>` + - Shows LU factorization in/out of place + * - :download:`qr.py <../examples/linear_algebra/qr.py>` + - Shows QR factorization in/out of place + +.. collapse:: Financial + + .. list-table:: + + * - :download:`black_scholes_options.py <../examples/financial/black_scholes_options.py>` + - Recreates black scholes options model utilizing ArrayFire's random and vectorization operations + * - :download:`heston_model.py <../examples/financial/heston_model.py>` + - Recreates heston model simultation utilizing ArrayFire's random and vectorization operations + * - :download:`monte_carlo_options.py <../examples/financial/monte_carlo_options.py>` + - Simulates monte carlo options model utilizing ArrayFire's random and vectorization operations + +.. collapse:: Benchmarks + + .. list-table:: + + * - :download:`monte_carlo_pi.py <../examples/benchmarks/monte_carlo_pi.py>` + - Recreates a monte carlo method of calculating the digits of pi ArrayFire's random and vectorization operations \ No newline at end of file diff --git a/docs/fourier_transforms_functions.rst b/docs/fourier_transforms_functions.rst new file mode 100644 index 0000000..4e72042 --- /dev/null +++ b/docs/fourier_transforms_functions.rst @@ -0,0 +1,41 @@ +Fourier Transform +=================== + +Functions for performing Fourier analysis, essential for signal processing and frequency analysis. + +.. list-table:: Functions + + * - :doc:`af.fast() ` + - FAST feature detector. + * - :doc:`af.fft() ` + - Fast Fourier Transform. + * - :doc:`af.fft2() ` + - Fast Fourier Transform. + * - :doc:`af.fft2_c2r() ` + - Fast fourier transform on two dimensional real signals producing complex output + * - :doc:`af.fft2_r2c() ` + - Fast fourier transform on two dimensional real signals producing complex output + * - :doc:`af.fft3() ` + - Fast Fourier Transform. + * - :doc:`af.fft3_c2r() ` + - Fast fourier transform on three dimensional real signals producing complex output + * - :doc:`af.fft3_r2c() ` + - Fast fourier transform on three dimensional real signals producing complex output + * - :doc:`af.fft_c2r() ` + - Fast fourier transform on complex signals producing real output + * - :doc:`af.fft_convolve1() ` + - FFT-based convolution for one dimensional signals + * - :doc:`af.fft_convolve2() ` + - FFT-based convolution for two dimensional signals + * - :doc:`af.fft_convolve3() ` + - FFT-based convolution for three dimensional signals + * - :doc:`af.fft_r2c() ` + - Fast fourier transform on real signals producing complex output + * - :doc:`af.ifft() ` + - Fast Fourier Transform. + * - :doc:`af.ifft2() ` + - Fast Fourier Transform. + * - :doc:`af.ifft3() ` + - Fast Fourier Transform. + * - :doc:`af.set_fft_plan_cache_size() ` + - Sets fft plan cache size \ No newline at end of file diff --git a/docs/functions.rst b/docs/functions.rst new file mode 100644 index 0000000..0655771 --- /dev/null +++ b/docs/functions.rst @@ -0,0 +1,589 @@ +Functions +========= + +.. include:: classes/index +.. include:: functions/index +.. include:: constants/index + +.. toctree:: + :hidden: + + array_creation_functions + array_manipulation_functions + fourier_transforms_functions + data_reduction_functions + linear_algebra_functions + mathematical_operations_functions + special_functions + statistics_functions + utilities_functions + +Documentation grouped by category: + + +.. collapse:: ArrayFire Classes + + .. list-table:: + + * - :doc:`af.Array ` + - Represents an ArrayFire array + * - :doc:`af.library.random.RandomEngine ` + - Reperesents an ArrayFire custom random engine + * - :doc:`af.library.features.Features ` + - Represents an ArrayFire Feature Extraction class + + +.. collapse:: ArrayFire Functions + + .. list-table:: + + * - :doc:`af.abs() ` + - Calculate the absolute value. + * - :doc:`af.accum() ` + - Evaluate the cumulative sum (inclusive) along a given dimension. + * - :doc:`af.acos() ` + - Evaluate the inverse cosine function (arc cosine). + * - :doc:`af.acosh() ` + - Evaluate the inverse hyperbolic cosine function (area hyperbolic cosine). + * - :doc:`af.add() ` + - Elementwise addition. + * - :doc:`af.all_true() ` + - Check if all values along a given dimension are true. + * - :doc:`af.alloc_device() ` + - Allocate memory on device + * - :doc:`af.alloc_host() ` + - Allocate memory on host. + * - :doc:`af.alloc_pinned() ` + - Allocate pinned memory on device. + * - :doc:`af.anisotropic_diffusion() ` + - Anisotropic Smoothing Filter. + * - :doc:`af.any_true() ` + - Check if any values along a given dimension are true. + * - :doc:`af.approx1() ` + - Interpolation across a single dimension. + * - :doc:`af.approx1_uniform() ` + - Interpolation across a single dimension in uniform steps + * - :doc:`af.approx2() ` + - Interpolation along two dimensions. + * - :doc:`af.approx2_uniform() ` + - Interpolation along two dimensions in uniform steps + * - :doc:`af.arg() ` + - Calculate the phase angle (in radians) of a complex array. + * - :doc:`af.asin() ` + - Evaluate the inverse sine function (arc sine). + * - :doc:`af.asinh() ` + - Evaluate the inverse hyperbolic sine function (area hyperbolic sine). + * - :doc:`af.atan() ` + - Evaluate the inverse tangent function (arc tangent). + * - :doc:`af.atan2() ` + - Evaluate the inverse tangent function (arc tangent). + * - :doc:`af.atanh() ` + - Evaluate the inverse hyperbolic tangent function (area hyperbolic tangent). + * - :doc:`af.bilateral() ` + - Bilateral Filter. + * - :doc:`af.bitand() ` + - Evaluate the bitwise AND of two arrays. + * - :doc:`af.bitnot() ` + - Evaluate the bitwise NOT of an array. + * - :doc:`af.bitor() ` + - Evaluate the bitwise OR of two arrays. + * - :doc:`af.bitshiftl() ` + - Shift the bits of integer arrays left. + * - :doc:`af.bitshiftr() ` + - Shift the bits of integer arrays right. + * - :doc:`af.bitxor() ` + - Evaluate the bitwise XOR of two arrays. + * - :doc:`af.canny() ` + - Canny Edge Detector. + * - :doc:`af.cast() ` + - Cast an array from one type to another. + * - :doc:`af.cbrt() ` + - Evaluate the cube root. + * - :doc:`af.ceil() ` + - Rounds up to the least integer greater than or equal to x. + * - :doc:`af.cholesky() ` + - Perform Cholesky decomposition. + * - :doc:`af.clamp() ` + - Clamp an array between an upper and a lower limit. + * - :doc:`af.color_space() ` + - Colorspace conversion function. + * - :doc:`af.confidence_cc() ` + - Segment image based on similar pixel characteristics. + * - :doc:`af.conjg() ` + - Evaluate the complex conjugate of an input array. + * - :doc:`af.constant() ` + - Create an array from a scalar input value. + * - :doc:`af.convolve1() ` + - Convolution Integral for one dimensional data. + * - :doc:`af.convolve2() ` + - Convolution Integral for two dimensional data. + * - :doc:`af.convolve2_gradient_nn() ` + - Version of convolution that is consistent with the machine learning formulation that will spatially convolve a filter on 2-dimensions against a signal. + * - :doc:`af.convolve2_nn() ` + - Version of convolution that is consistent with the machine learning formulation that will spatially convolve a filter on 2-dimensions against a signal. + * - :doc:`af.convolve2_separable() ` + - Faster equivalent of the canonical 2D convolution for filters/kernels that can be decomposed into two separate spatial vectors. + * - :doc:`af.convolve3() ` + - Convolution Integral for three dimensional data. + * - :doc:`af.copy_array() ` + - Performs a deep copy of the array. + * - :doc:`af.cos() ` + - Evaluate the cosine function. + * - :doc:`af.cosh() ` + - Evaluate the hyperbolic cosine function. + * - :doc:`af.count() ` + - Count non-zero values in an array along a given dimension. + * - :doc:`af.cplx() ` + - Creates complex arrays from real and imaginary parts + * - :doc:`af.cublas_set_math_mode() ` + - Sets the cuBLAS math mode for the internal handle + * - :doc:`af.delete_image_memory() ` + - Delete memory created by saveImageMem + * - :doc:`af.det() ` + - Find the determinant of a matrix. + * - :doc:`af.device_gc() ` + - Call the garbage collection routine + * - :doc:`af.device_info() ` + - Gets the information about device and platform as strings. + * - :doc:`af.device_mem_info() ` + - Gets information about the memory manager + * - :doc:`af.diag() ` + - Extract the diagonal from an array. + * - :doc:`af.diff1() ` + - Calculate the first order difference in an array over a given dimension. + * - :doc:`af.diff2() ` + - Calculate the second order difference in an array over a given dimension. + * - :doc:`af.dilate() ` + - Dilation(morphological operator) for images. + * - :doc:`af.div() ` + - Elementwise division. + * - :doc:`af.dog() ` + - Difference of Gaussians. + * - :doc:`af.dot() ` + - Compute the dot product. + * - :doc:`af.eq() ` + - Equal to, an elementwise comparison of two arrays. + * - :doc:`af.erf() ` + - Evaluate the error function. + * - :doc:`af.erfc() ` + - Evaluate the complementary error function. + * - :doc:`af.erode() ` + - Erosion(morphological operator) for images. + * - :doc:`af.eval() ` + - Evaluate an expression (nonblocking). + * - :doc:`af.exp() ` + - Evaluate the exponential function. + * - :doc:`af.expm1() ` + - Evaluate the exponential function of an array minus 1, exp(in) - 1. + * - :doc:`af.factorial() ` + - Evaluate the factorial. + * - :doc:`af.fast() ` + - FAST feature detector. + * - :doc:`af.fft() ` + - Fast Fourier Transform. + * - :doc:`af.fft2() ` + - Fast Fourier Transform. + * - :doc:`af.fft2_c2r() ` + - Fast fourier transform on two dimensional real signals producing complex output + * - :doc:`af.fft2_r2c() ` + - Fast fourier transform on two dimensional real signals producing complex output + * - :doc:`af.fft3() ` + - Fast Fourier Transform. + * - :doc:`af.fft3_c2r() ` + - Fast fourier transform on three dimensional real signals producing complex output + * - :doc:`af.fft3_r2c() ` + - Fast fourier transform on three dimensional real signals producing complex output + * - :doc:`af.fft_c2r() ` + - Fast fourier transform on complex signals producing real output + * - :doc:`af.fft_convolve1() ` + - FFT-based convolution for one dimensional signals + * - :doc:`af.fft_convolve2() ` + - FFT-based convolution for two dimensional signals + * - :doc:`af.fft_convolve3() ` + - FFT-based convolution for three dimensional signals + * - :doc:`af.fft_r2c() ` + - Fast fourier transform on real signals producing complex output + * - :doc:`af.fir() ` + - This function implements a Finite Impulse Filter. + * - :doc:`af.flat() ` + - Flatten an array. + * - :doc:`af.flip() ` + - Flip the input along a specified dimension. + * - :doc:`af.floor() ` + - Rounds down to the greatest integer less than or equal to x. + * - :doc:`af.free_device() ` + - Free memory allocated on device internally by ArrayFire. + * - :doc:`af.free_host() ` + - Free memory allocated on host internally by ArrayFire. + * - :doc:`af.free_pinned() ` + - Free pinned memory allocated by ArrayFire's memory manager. + * - :doc:`af.gaussian_kernel() ` + - Creates a Gaussian Kernel. + * - :doc:`af.ge() ` + - Greater than or equal to, an elementwise comparison of two arrays. + * - :doc:`af.gemm() ` + - General matrix multiplication. + * - :doc:`af.get_backend() ` + - Gets the backend enum for the active backend. + * - :doc:`af.get_dbl_support() ` + - Gets if the device supports double floating point + * - :doc:`af.get_device() ` + - Get the current device ID. + * - :doc:`af.get_device_count() ` + - Gets the number of compute devices on the system. + * - :doc:`af.get_half_support() ` + - Gets if the device supports half floating point + * - :doc:`af.get_kernel_cache_directory() ` + - Returns directory where ArrayFire JIT kernels are being stored + * - :doc:`af.get_mem_step_size() ` + - Get the minimum memory chunk size. + * - :doc:`af.get_native_id() ` + - Get the native device id of the CUDA device with id in ArrayFire context + * - :doc:`af.get_stream() ` + - Returns the current cuda stream + * - :doc:`af.gloh() ` + - SIFT feature detector and GLOH descriptor extractor. + * - :doc:`af.gradient() ` + - Calculate the gradients of the input + * - :doc:`af.gray2rgb() ` + - Grayscale to RGB colorspace converter. + * - :doc:`af.gt() ` + - Greater than comparison, an elementwise comparison of two arrays. + * - :doc:`af.hamming_matcher() ` + - Calculates Hamming distances between two 2-dimensional arrays + * - :doc:`af.harris() ` + - Harris corner detector. + * - :doc:`af.hist_equal() ` + - Histogram equalization of input image. + * - :doc:`af.histogram() ` + - Histogram of input data. + * - :doc:`af.hsv2rgb() ` + - HSV to RGB colorspace converter. + * - :doc:`af.hypot() ` + - Evaluate the length of the hypotenuse of two inputs. + * - :doc:`af.identity() ` + - Generate an identity matrix. + * - :doc:`af.ifft() ` + - Fast Fourier Transform. + * - :doc:`af.ifft2() ` + - Fast Fourier Transform. + * - :doc:`af.ifft3() ` + - Fast Fourier Transform. + * - :doc:`af.iir() ` + - This function implements a Infinite Impulse Filter. + * - :doc:`af.imag() ` + - Returns the imaginary part of a complex array. + * - :doc:`af.imax() ` + - Finds the maximum value. + * - :doc:`af.imin() ` + - Finds the minimum value. + * - :doc:`af.info() ` + - Display ArrayFire and device info. + * - :doc:`af.info_string() ` + - Returns a string with information of current device and backend + * - :doc:`af.init() ` + - Initializes ArrayFire + * - :doc:`af.inv() ` + - Computes the inverse of a matrix. + * - :doc:`af.inverse() ` + - Invert a matrix. + * - :doc:`af.inverse_deconv() ` + - Inverse Deconvolution using linear algebra (non-iterative) methods + * - :doc:`af.iota() ` + - Generate an array with [0, n-1] values modified to specified dimensions and tiling. + * - :doc:`af.is_image_io_available() ` + - Checks if Image IO is available + * - :doc:`af.is_lapack_available() ` + - Check if lapack runtimes are available + * - :doc:`af.isinf() ` + - Check if values are infinite. + * - :doc:`af.isnan() ` + - Check if values are NaN. + * - :doc:`af.iszero() ` + - Check if values are zero. + * - :doc:`af.iterative_deconv() ` + - Inverse Deconvolution using iterative methods + * - :doc:`af.join() ` + - Join up to 4 arrays along specified dimension. + * - :doc:`af.le() ` + - Less than or equal to, an elementwise comparison of two arrays. + * - :doc:`af.lgamma() ` + - Evaluate the logarithm of the absolute value of the gamma function. + * - :doc:`af.load_image() ` + - Load an image from disk to an array + * - :doc:`af.load_image_memory() ` + - Load an image from memory which is stored as a FreeImage stream + * - :doc:`af.load_image_native() ` + - Load an image as is original type. + * - :doc:`af.log() ` + - Evaluate the natural logarithm. + * - :doc:`af.log10() ` + - Evaluate the base 10 logarithm. + * - :doc:`af.log1p() ` + - Evaluate the natural logarithm of 1 + input, ln(1+in). + * - :doc:`af.log2() ` + - Evaluate the base 2 logarithm. + * - :doc:`af.logical_and() ` + - Evaluate the logical and between two arrays + * - :doc:`af.logical_not() ` + - Evaluate the logical not of an array + * - :doc:`af.logical_or() ` + - Evaluate the logical or between two arrays + * - :doc:`af.lookup() ` + - Lookup values of an array by indexing with another array. + * - :doc:`af.lower() ` + - Return the lower triangular matrix from an input array. + * - :doc:`af.lt() ` + - Less than, an elementwise comparison of two arrays. + * - :doc:`af.lu() ` + - Perform LU decomposition. + * - :doc:`af.matmul() ` + - Matrix multiplication. + * - :doc:`af.max() ` + - Return the maximum along a given dimension. + * - :doc:`af.maxfilt() ` + - Find maximum value from a window. + * - :doc:`af.maxof() ` + - Elementwise maximum between two arrays + * - :doc:`af.mean() ` + - Find the mean of values in the input. + * - :doc:`af.mean_shift() ` + - Edge-preserving smoothing filter commonly used in object tracking and image segmentation. + * - :doc:`af.medfilt() ` + - Median Filter. + * - :doc:`af.medfilt1() ` + - 1D Median Filter. + * - :doc:`af.medfilt2() ` + - 2D Median Filter. + * - :doc:`af.median() ` + - Find the median of values in the input. + * - :doc:`af.min() ` + - Return the minimum along a given dimension. + * - :doc:`af.minfilt() ` + - Find minimum value from a window. + * - :doc:`af.minof() ` + - Elementwise minimum between two arrays + * - :doc:`af.mod() ` + - Calculate the modulus. + * - :doc:`af.moddims() ` + - Modify the dimensions of an array without changing the order of its elements. + * - :doc:`af.mul() ` + - Elementwise multiply. + * - :doc:`af.nearest_neighbour() ` + - Calculates which points in the train are nearest to each other point + * - :doc:`af.neg() ` + - Negate an array. + * - :doc:`af.neq() ` + - Not equal to, an elementwise comparison of two arrays. + * - :doc:`af.norm() ` + - Find the norm of a matrix. + * - :doc:`af.ones() ` + - Creates an array filled with ones. + * - :doc:`af.orb() ` + - ORB Feature descriptor. + * - :doc:`af.pad() ` + - Pad an array. + * - :doc:`af.pinverse() ` + - Pseudo-invert (Moore-Penrose) a matrix. + * - :doc:`af.pow() ` + - Raise a base to a power (or exponent). + * - :doc:`af.pow2() ` + - Raise 2 to a power (or exponent). + * - :doc:`af.print_mem_info() ` + - Prints buffer details from the ArrayFire Device Manager + * - :doc:`af.product() ` + - Multiply array elements over a given dimension. + * - :doc:`af.qr() ` + - Perform QR decomposition. + * - :doc:`af.randn() ` + - Create a random array sampled from normal distribution. + * - :doc:`af.randu() ` + - Create a random array sampled from uniform distribution. + * - :doc:`af.range() ` + - Generate an array with [0, n-1] values along the a specified dimension and tiled across other dimensions. + * - :doc:`af.rank() ` + - Find the rank of a matrix. + * - :doc:`af.read_array() ` + - Load an array from a file. + * - :doc:`af.real() ` + - Returns the real part of a complex array. + * - :doc:`af.regions() ` + - Find blobs in given image. + * - :doc:`af.rem() ` + - Calculate the remainder of a division. + * - :doc:`af.reorder() ` + - Reorder an array. + * - :doc:`af.replace() ` + - Replace elements of an array with elements of another array. + * - :doc:`af.reshape() ` + - Modify the dimensions of an array without changing the order of its elements + * - :doc:`af.resize() ` + - Resize an input image. + * - :doc:`af.rgb2gray() ` + - RGB to Grayscale colorspace converter. + * - :doc:`af.rgb2hsv() ` + - RGB to HSV colorspace converter. + * - :doc:`af.rgb2ycbcr() ` + - RGB to YCbCr colorspace converter. + * - :doc:`af.root() ` + - Evaluate the nth root. + * - :doc:`af.rotate() ` + - Rotate an input image or array. + * - :doc:`af.round() ` + - Round numbers to the nearest integer. + * - :doc:`af.rsqrt() ` + - Evaluate the reciprocal square root. + * - :doc:`af.sat() ` + - Summed Area Tables. + * - :doc:`af.save_array() ` + - Save an array to a binary file + * - :doc:`af.save_image() ` + - Save an array to disk as an image + * - :doc:`af.save_image_memory() ` + - Save an array to memory as an image using FreeImage stream + * - :doc:`af.save_image_native() ` + - Save an image as is original type. + * - :doc:`af.scale() ` + - Scale an input image. + * - :doc:`af.scan() ` + - Scan an array (generalized) over a given dimension. + * - :doc:`af.select() ` + - Select elements based on a conditional array. + * - :doc:`af.set_backend() ` + - Set the current backend + * - :doc:`af.set_device() ` + - Change current device to specified device. + * - :doc:`af.set_fft_plan_cache_size() ` + - Sets fft plan cache size + * - :doc:`af.set_intersect() ` + - Evaluate the intersection of two arrays + * - :doc:`af.set_kernel_cache_directory() ` + - Sets the directory for JIT kernel caching + * - :doc:`af.set_mem_step_size() ` + - Get the minimum memory chunk size. + * - :doc:`af.set_native_id() ` + - Set the CUDA device with given native id as the active device for ArrayFire + * - :doc:`af.set_union() ` + - Evaluate the union of two arrays + * - :doc:`af.set_unique() ` + - Return the unique values in an array + * - :doc:`af.shift() ` + - Shift an array. + * - :doc:`af.sift() ` + - SIFT feature detector and descriptor extractor. + * - :doc:`af.sign() ` + - Return the sign of elements in an array. + * - :doc:`af.sin() ` + - Evaluate the sine function. + * - :doc:`af.sinh() ` + - Evaluate the hyperbolic sine function. + * - :doc:`af.skew() ` + - Skew an input image. + * - :doc:`af.sobel_operator() ` + - Perform a 2-D spatial gradient measurement on an image + * - :doc:`af.solve() ` + - Solve a system of equations. + * - :doc:`af.sort() ` + - Sort an array over a given dimension. + * - :doc:`af.sqrt() ` + - Evaluate the square root. + * - :doc:`af.sttdev() ` + - Find the standard deviation of values in the input. + * - :doc:`af.sub() ` + - Elementwise subtraction. + * - :doc:`af.sum() ` + - Sum array elements over a given dimension. + * - :doc:`af.susan() ` + - SUSAN corner detector. + * - :doc:`af.svd() ` + - Perform singular value decomposition. + * - :doc:`af.sync() ` + - Blocks until all operations on device are finished. + * - :doc:`af.tan() ` + - Evaluate the tangent function. + * - :doc:`af.tanh() ` + - Evaluate the hyperbolic tangent function. + * - :doc:`af.tgamma() ` + - Evaluate the gamma function. + * - :doc:`af.tile() ` + - Generate a tiled array by repeating an array's contents along a specified dimension. + * - :doc:`af.transform() ` + - Transform an input image. + * - :doc:`af.transform_coordinates() ` + - Transform input coordinates to perspective. + * - :doc:`af.translate() ` + - Translate an input image. + * - :doc:`af.transpose() ` + - Transpose a matrix. + * - :doc:`af.trunc() ` + - Truncate numbers to nearest integer. + * - :doc:`af.unwrap() ` + - Rearrange windowed sections of an array into columns (or rows) + * - :doc:`af.upper() ` + - Return the upper triangular matrix from an input array. + * - :doc:`af.where() ` + - Locate the indices of the non-zero values in an array. + * - :doc:`af.wrap() ` + - Performs the opposite of af::unwrap(). + * - :doc:`af.zeros() ` + - Creates an array filled with zeros. + + +.. collapse:: ArrayFire Functions by Category + + .. list-table:: + + * - :doc:`Array Creation ` + - Functions in this category are used to initialize arrays with specific values or patterns. + * - :doc:`Array Manipulation ` + - These functions help modify the structure or arrangement of arrays. + * - :doc:`Mathematical Operations ` + - Functions for performing fundamental arithmetic and mathematical operations on arrays. + * - :doc:`Linear Algebra ` + - Functions for performing linear algebra operations, essential in many scientific and engineering tasks. + * - :doc:`Fourier Transforms ` + - Functions for performing Fourier analysis, essential for signal processing and frequency analysis. + * - :doc:`Statistics ` + - Functions for computing statistical metrics and analyzing data distributions. + * - :doc:`Data Reduction ` + - Functions for aggregating and reducing data to summarize or condense information. + * - :doc:`Utilities ` + - General-purpose functions for managing arrays and devices. + * - :doc:`Special Functions ` + - Functions for convolutions, creating and applying specific types of filters, commonly used in signal processing and analysis. + +.. collapse:: ArrayFire Constants + + .. list-table:: + + * - :doc:`af.BinaryOperator ` + * - :doc:`af.CannyThreshold ` + * - :doc:`af.Connectivity ` + * - :doc:`af.ConvDomain ` + * - :doc:`af.ConvGradient ` + * - :doc:`af.CSpace ` + * - :doc:`af.Diffusion ` + * - :doc:`af.Dtype ` + - ArrayFire supported datatypes + * - :doc:`af.Flux ` + * - :doc:`af.ImageFormat ` + * - :doc:`af.Interp ` + * - :doc:`af.IterativeDeconv ` + * - :doc:`af.Match ` + * - :doc:`af.MatProp ` + * - :doc:`af.Norm ` + * - :doc:`af.Pad ` + * - :doc:`af.RandomEngineType ` + * - :doc:`af.TopK ` + * - :doc:`af.VarianceBias ` + * - :doc:`af.YCCStd ` + +.. collapse:: Graphics (Coming Soon) + + .. list-table:: + + * - **Rendering Function** + - Rendering Function to draw images, plots etc + * - **Window Function** + - Window Creation, modification and destruction of functions + diff --git a/docs/functions/abs.rst b/docs/functions/abs.rst new file mode 100644 index 0000000..db018f8 --- /dev/null +++ b/docs/functions/abs.rst @@ -0,0 +1,4 @@ +abs +=== + +.. autofunction:: arrayfire_wrapper.lib.abs_ diff --git a/docs/functions/accum.rst b/docs/functions/accum.rst new file mode 100644 index 0000000..b2d634a --- /dev/null +++ b/docs/functions/accum.rst @@ -0,0 +1,4 @@ +accum +===== + +.. autofunction:: arrayfire.accum \ No newline at end of file diff --git a/docs/functions/acos.rst b/docs/functions/acos.rst new file mode 100644 index 0000000..ab5b3ee --- /dev/null +++ b/docs/functions/acos.rst @@ -0,0 +1,4 @@ +acos +==== + +.. autofunction:: arrayfire_wrapper.lib.acos diff --git a/docs/functions/acosh.rst b/docs/functions/acosh.rst new file mode 100644 index 0000000..ce00baa --- /dev/null +++ b/docs/functions/acosh.rst @@ -0,0 +1,4 @@ +acosh +===== + +.. autofunction:: arrayfire_wrapper.lib.acosh diff --git a/docs/functions/add.rst b/docs/functions/add.rst new file mode 100644 index 0000000..05d70fa --- /dev/null +++ b/docs/functions/add.rst @@ -0,0 +1,30 @@ +add +=== +The 'af.add()' function in ArrayFire is used to perform element-wise addition between arrays. This function enables you to add corresponding elements of two arrays or an array and a scalar, resulting in a new array where each element is the sum of the respective elements from the input arrays or the scalar. + + +Function +-------- +:literal:`af.add()` + - Python interface used to perform element-wise addition. + +Detailed Description +-------------------- +The 'af.add()' function computes the sum of two arrays or an array and a scalar, element by element. When adding two arrays, both must have the same dimensions, or be broadcastable to a common shape. For array-scalar addition, the scalar value is added to each element of the array. This function is particularly useful for operations requiring element-wise arithmetic. + +Function Documentation +---------------------- +.. sidebar:: af.add() + + Syntax: + af.add(array1, array2) + af.add(array, scalar) + + Parameters: + 'array1': The first ArrayFire array in the addition operation. + 'array2': The second ArrayFire array with the same dimensions as 'array1', or compatible for broadcasting. + 'array': An ArrayFire array to which the scalar is added. + 'scalar': A scalar value to be added to each element of 'array'. + + Returns: + An ArrayFire array containing the element-wise sum of the inputs. diff --git a/docs/functions/all_true.rst b/docs/functions/all_true.rst new file mode 100644 index 0000000..1006674 --- /dev/null +++ b/docs/functions/all_true.rst @@ -0,0 +1,4 @@ +all_true +======== + +.. autofunction:: arrayfire.all_true \ No newline at end of file diff --git a/docs/functions/alloc_device.rst b/docs/functions/alloc_device.rst new file mode 100644 index 0000000..2078927 --- /dev/null +++ b/docs/functions/alloc_device.rst @@ -0,0 +1,4 @@ +alloc_device +============= + +.. autofunction:: arrayfire_wrapper.lib.alloc_device \ No newline at end of file diff --git a/docs/functions/alloc_host.rst b/docs/functions/alloc_host.rst new file mode 100644 index 0000000..187a2cc --- /dev/null +++ b/docs/functions/alloc_host.rst @@ -0,0 +1,4 @@ +alloc_host +============ + +.. autofunction:: arrayfire_wrapper.lib.alloc_host \ No newline at end of file diff --git a/docs/functions/alloc_pinned.rst b/docs/functions/alloc_pinned.rst new file mode 100644 index 0000000..80538fc --- /dev/null +++ b/docs/functions/alloc_pinned.rst @@ -0,0 +1,4 @@ +alloc_pinned +============== + +.. autofunction:: arrayfire_wrapper.lib.alloc_pinned \ No newline at end of file diff --git a/docs/functions/anisotropic_diffusion.rst b/docs/functions/anisotropic_diffusion.rst new file mode 100644 index 0000000..28435ba --- /dev/null +++ b/docs/functions/anisotropic_diffusion.rst @@ -0,0 +1,4 @@ +anisotropic_diffusion +===================== + +.. autofunction:: arrayfire_wrapper.lib.anisotropic_diffusion diff --git a/docs/functions/any_true.rst b/docs/functions/any_true.rst new file mode 100644 index 0000000..8341323 --- /dev/null +++ b/docs/functions/any_true.rst @@ -0,0 +1,4 @@ +any_true +======== + +.. autofunction:: arrayfire.any_true \ No newline at end of file diff --git a/docs/functions/approx1.rst b/docs/functions/approx1.rst new file mode 100644 index 0000000..de44fd7 --- /dev/null +++ b/docs/functions/approx1.rst @@ -0,0 +1,4 @@ +approx1 +======= + +.. autofunction:: arrayfire_wrapper.lib.approx1 diff --git a/docs/functions/approx1_uniform.rst b/docs/functions/approx1_uniform.rst new file mode 100644 index 0000000..2b60e2a --- /dev/null +++ b/docs/functions/approx1_uniform.rst @@ -0,0 +1,4 @@ +approx1_uniform +=============== + +.. autofunction:: arrayfire_wrapper.lib.approx1_uniform diff --git a/docs/functions/approx2.rst b/docs/functions/approx2.rst new file mode 100644 index 0000000..eb9c87d --- /dev/null +++ b/docs/functions/approx2.rst @@ -0,0 +1,4 @@ +approx2 +======= + +.. autofunction:: arrayfire_wrapper.lib.approx2 diff --git a/docs/functions/approx2_uniform.rst b/docs/functions/approx2_uniform.rst new file mode 100644 index 0000000..c821dc1 --- /dev/null +++ b/docs/functions/approx2_uniform.rst @@ -0,0 +1,4 @@ +approx2_uniform +=============== + +.. autofunction:: arrayfire_wrapper.lib.approx2_uniform diff --git a/docs/functions/arg.rst b/docs/functions/arg.rst new file mode 100644 index 0000000..aa373ca --- /dev/null +++ b/docs/functions/arg.rst @@ -0,0 +1,4 @@ +arg +=== + +.. autofunction:: arrayfire_wrapper.lib.arg diff --git a/docs/functions/asin.rst b/docs/functions/asin.rst new file mode 100644 index 0000000..883e5f3 --- /dev/null +++ b/docs/functions/asin.rst @@ -0,0 +1,4 @@ +asin +==== + +.. autofunction:: arrayfire_wrapper.lib.asin diff --git a/docs/functions/asinh.rst b/docs/functions/asinh.rst new file mode 100644 index 0000000..1d4b092 --- /dev/null +++ b/docs/functions/asinh.rst @@ -0,0 +1,4 @@ +asinh +===== + +.. autofunction:: arrayfire_wrapper.lib.asinh diff --git a/docs/functions/atan.rst b/docs/functions/atan.rst new file mode 100644 index 0000000..18b856a --- /dev/null +++ b/docs/functions/atan.rst @@ -0,0 +1,4 @@ +atan +==== + +.. autofunction:: arrayfire_wrapper.lib.atan diff --git a/docs/functions/atan2.rst b/docs/functions/atan2.rst new file mode 100644 index 0000000..a393936 --- /dev/null +++ b/docs/functions/atan2.rst @@ -0,0 +1,4 @@ +atan2 +===== + +.. autofunction:: arrayfire_wrapper.lib.atan2 diff --git a/docs/functions/atanh.rst b/docs/functions/atanh.rst new file mode 100644 index 0000000..5c75a98 --- /dev/null +++ b/docs/functions/atanh.rst @@ -0,0 +1,4 @@ +atanh +===== + +.. autofunction:: arrayfire_wrapper.lib.atanh diff --git a/docs/functions/bilateral.rst b/docs/functions/bilateral.rst new file mode 100644 index 0000000..a60a023 --- /dev/null +++ b/docs/functions/bilateral.rst @@ -0,0 +1,4 @@ +bilateral +========= + +.. autofunction:: arrayfire_wrapper.lib.bilateral diff --git a/docs/functions/bitand.rst b/docs/functions/bitand.rst new file mode 100644 index 0000000..f016416 --- /dev/null +++ b/docs/functions/bitand.rst @@ -0,0 +1,4 @@ +bitand +====== + +.. autofunction:: arrayfire_wrapper.lib.bitand diff --git a/docs/functions/bitnot.rst b/docs/functions/bitnot.rst new file mode 100644 index 0000000..db9ce61 --- /dev/null +++ b/docs/functions/bitnot.rst @@ -0,0 +1,4 @@ +bitnot +====== + +.. autofunction:: arrayfire_wrapper.lib.bitnot diff --git a/docs/functions/bitor.rst b/docs/functions/bitor.rst new file mode 100644 index 0000000..2f829eb --- /dev/null +++ b/docs/functions/bitor.rst @@ -0,0 +1,4 @@ +bitor +===== + +.. autofunction:: arrayfire_wrapper.lib.bitor diff --git a/docs/functions/bitshiftl.rst b/docs/functions/bitshiftl.rst new file mode 100644 index 0000000..8478a1e --- /dev/null +++ b/docs/functions/bitshiftl.rst @@ -0,0 +1,4 @@ +bitshiftl +========= + +.. autofunction:: arrayfire_wrapper.lib.bitshiftl diff --git a/docs/functions/bitshiftr.rst b/docs/functions/bitshiftr.rst new file mode 100644 index 0000000..fb17b29 --- /dev/null +++ b/docs/functions/bitshiftr.rst @@ -0,0 +1,4 @@ +bitshiftr +========= + +.. autofunction:: arrayfire_wrapper.lib.bitshiftr diff --git a/docs/functions/bitxor.rst b/docs/functions/bitxor.rst new file mode 100644 index 0000000..a37c252 --- /dev/null +++ b/docs/functions/bitxor.rst @@ -0,0 +1,4 @@ +bitxor +====== + +.. autofunction:: arrayfire_wrapper.lib.bitxor diff --git a/docs/functions/canny.rst b/docs/functions/canny.rst new file mode 100644 index 0000000..da62faf --- /dev/null +++ b/docs/functions/canny.rst @@ -0,0 +1,4 @@ +canny +===== + +.. autofunction:: arrayfire_wrapper.lib.canny diff --git a/docs/functions/cast.rst b/docs/functions/cast.rst new file mode 100644 index 0000000..3fa1c16 --- /dev/null +++ b/docs/functions/cast.rst @@ -0,0 +1,4 @@ +cast +===== + +.. autofunction:: arrayfire.cast \ No newline at end of file diff --git a/docs/functions/cbrt.rst b/docs/functions/cbrt.rst new file mode 100644 index 0000000..384f506 --- /dev/null +++ b/docs/functions/cbrt.rst @@ -0,0 +1,4 @@ +cbrt +==== + +.. autofunction:: arrayfire_wrapper.lib.cbrt diff --git a/docs/functions/ceil.rst b/docs/functions/ceil.rst new file mode 100644 index 0000000..d738a7a --- /dev/null +++ b/docs/functions/ceil.rst @@ -0,0 +1,4 @@ +ceil +==== + +.. autofunction:: arrayfire_wrapper.lib.ceil diff --git a/docs/functions/cholesky.rst b/docs/functions/cholesky.rst new file mode 100644 index 0000000..464ebd5 --- /dev/null +++ b/docs/functions/cholesky.rst @@ -0,0 +1,4 @@ +cholesky +======== + +.. autofunction:: arrayfire_wrapper.lib.cholesky diff --git a/docs/functions/clamp.rst b/docs/functions/clamp.rst new file mode 100644 index 0000000..b1d0559 --- /dev/null +++ b/docs/functions/clamp.rst @@ -0,0 +1,4 @@ +clamp +===== + +.. autofunction:: arrayfire_wrapper.lib.clamp diff --git a/docs/functions/color_space.rst b/docs/functions/color_space.rst new file mode 100644 index 0000000..965e591 --- /dev/null +++ b/docs/functions/color_space.rst @@ -0,0 +1,4 @@ +color_space +=========== + +.. autofunction:: arrayfire_wrapper.lib.color_space diff --git a/docs/functions/confidence_cc.rst b/docs/functions/confidence_cc.rst new file mode 100644 index 0000000..2a9d51a --- /dev/null +++ b/docs/functions/confidence_cc.rst @@ -0,0 +1,4 @@ +confidence_cc +============= + +.. autofunction:: arrayfire_wrapper.lib.confidence_cc diff --git a/docs/functions/conjg.rst b/docs/functions/conjg.rst new file mode 100644 index 0000000..2fbc710 --- /dev/null +++ b/docs/functions/conjg.rst @@ -0,0 +1,4 @@ +conjg +===== + +.. autofunction:: arrayfire_wrapper.lib.conjg diff --git a/docs/functions/constant.rst b/docs/functions/constant.rst new file mode 100644 index 0000000..180c6fb --- /dev/null +++ b/docs/functions/constant.rst @@ -0,0 +1,4 @@ +constant +======== + +.. autofunction:: arrayfire.constant \ No newline at end of file diff --git a/docs/functions/convolve1.rst b/docs/functions/convolve1.rst new file mode 100644 index 0000000..cfb9cdb --- /dev/null +++ b/docs/functions/convolve1.rst @@ -0,0 +1,4 @@ +convolve1 +========= + +.. autofunction:: arrayfire_wrapper.lib.convolve1 diff --git a/docs/functions/convolve2.rst b/docs/functions/convolve2.rst new file mode 100644 index 0000000..d88c7ad --- /dev/null +++ b/docs/functions/convolve2.rst @@ -0,0 +1,4 @@ +convolve2 +========= + +.. autofunction:: arrayfire_wrapper.lib.convolve2 diff --git a/docs/functions/convolve2_gradient_nn.rst b/docs/functions/convolve2_gradient_nn.rst new file mode 100644 index 0000000..2f0e302 --- /dev/null +++ b/docs/functions/convolve2_gradient_nn.rst @@ -0,0 +1,4 @@ +convolve2_gradient_nn +====================== + +.. autofunction:: arrayfire_wrapper.lib.convolve2_gradient_nn \ No newline at end of file diff --git a/docs/functions/convolve2_nn.rst b/docs/functions/convolve2_nn.rst new file mode 100644 index 0000000..c8027a3 --- /dev/null +++ b/docs/functions/convolve2_nn.rst @@ -0,0 +1,4 @@ +convolve2_nn +============ + +.. autofunction:: arrayfire_wrapper.lib.convolve2_nn diff --git a/docs/functions/convolve2_separable.rst b/docs/functions/convolve2_separable.rst new file mode 100644 index 0000000..0c97f55 --- /dev/null +++ b/docs/functions/convolve2_separable.rst @@ -0,0 +1,4 @@ +convolve2_separable +=================== + +.. autofunction:: arrayfire_wrapper.lib.convolve2_sep diff --git a/docs/functions/convolve3.rst b/docs/functions/convolve3.rst new file mode 100644 index 0000000..1bd2276 --- /dev/null +++ b/docs/functions/convolve3.rst @@ -0,0 +1,4 @@ +convolve3 +========= + +.. autofunction:: arrayfire_wrapper.lib.convolve3 diff --git a/docs/functions/copy_array.rst b/docs/functions/copy_array.rst new file mode 100644 index 0000000..437c947 --- /dev/null +++ b/docs/functions/copy_array.rst @@ -0,0 +1,4 @@ +copy_array +========== + +.. autofunction:: arrayfire.copy_array diff --git a/docs/functions/cos.rst b/docs/functions/cos.rst new file mode 100644 index 0000000..daf981e --- /dev/null +++ b/docs/functions/cos.rst @@ -0,0 +1,4 @@ +cos +=== + +.. autofunction:: arrayfire_wrapper.lib.cos diff --git a/docs/functions/cosh.rst b/docs/functions/cosh.rst new file mode 100644 index 0000000..258646a --- /dev/null +++ b/docs/functions/cosh.rst @@ -0,0 +1,4 @@ +cosh +==== + +.. autofunction:: arrayfire_wrapper.lib.cosh diff --git a/docs/functions/count.rst b/docs/functions/count.rst new file mode 100644 index 0000000..1ec2cde --- /dev/null +++ b/docs/functions/count.rst @@ -0,0 +1,4 @@ +count +===== + +.. autofunction:: arrayfire.count \ No newline at end of file diff --git a/docs/functions/cplx.rst b/docs/functions/cplx.rst new file mode 100644 index 0000000..07ac775 --- /dev/null +++ b/docs/functions/cplx.rst @@ -0,0 +1,4 @@ +cplx +==== + +.. autofunction:: arrayfire_wrapper.lib.cplx diff --git a/docs/functions/cublas_set_math_mode.rst b/docs/functions/cublas_set_math_mode.rst new file mode 100644 index 0000000..a9418e0 --- /dev/null +++ b/docs/functions/cublas_set_math_mode.rst @@ -0,0 +1,4 @@ +cublas_set_math_mode +==================== + +.. autofunction:: arrayfire_wrapper.lib.cublas_set_math_mode diff --git a/docs/functions/delete_image_memory.rst b/docs/functions/delete_image_memory.rst new file mode 100644 index 0000000..7926cf4 --- /dev/null +++ b/docs/functions/delete_image_memory.rst @@ -0,0 +1,4 @@ +delete_image_memory +=================== + +.. autofunction:: arrayfire_wrapper.lib.delete_image_memory diff --git a/docs/functions/det.rst b/docs/functions/det.rst new file mode 100644 index 0000000..f2acfda --- /dev/null +++ b/docs/functions/det.rst @@ -0,0 +1,25 @@ +det +=== +The 'af.det()' function in ArrayFire computes the determinant of a square matrix. The determinant is a scalar value that provides important properties of the matrix, such as whether it is invertible. It is a fundamental operation in linear algebra with applications in areas such as system of equations, matrix inversion, and eigenvalue problems. + +Function +-------- +:literal:`af.det()` + - Python interface to find determinant of a square matrix. + +Detailed Description +-------------------- +The 'af.det()' function calculates the determinant of a square matrix. The matrix must be square, meaning the number of rows must be equal to the number of columns. The determinant of a matrix is a scalar that can provide information about the matrix, such as its invertibility. If the determinant is zero, the matrix is singular (non-invertible); if it is non-zero, the matrix is invertible. + +Function Documentation +---------------------- +.. sidebar:: af.det() + + Syntax: + af.det(matrix) + + Parameters: + 'matrix': A 2D ArrayFire array (matrix) whose determinant is to be calculated. The matrix must be square, i.e., the number of rows must be equal to the number of columns. + + Returns: + A scalar value representing the determinant of the input matrix. The type of the result will be the same as the input matrix data type. diff --git a/docs/functions/device_gc.rst b/docs/functions/device_gc.rst new file mode 100644 index 0000000..d9a885d --- /dev/null +++ b/docs/functions/device_gc.rst @@ -0,0 +1,4 @@ +device_gc +=========== + +.. autofunction:: arrayfire_wrapper.lib.device_gc \ No newline at end of file diff --git a/docs/functions/device_info.rst b/docs/functions/device_info.rst new file mode 100644 index 0000000..2ccc64f --- /dev/null +++ b/docs/functions/device_info.rst @@ -0,0 +1,4 @@ +device_info +============ + +.. autofunction:: arrayfire_wrapper.lib.device_info \ No newline at end of file diff --git a/docs/functions/device_mem_info.rst b/docs/functions/device_mem_info.rst new file mode 100644 index 0000000..b4a9c3d --- /dev/null +++ b/docs/functions/device_mem_info.rst @@ -0,0 +1,4 @@ +device_mem_info +=============== + +.. autofunction:: arrayfire_wrapper.lib.device_mem_info diff --git a/docs/functions/diag.rst b/docs/functions/diag.rst new file mode 100644 index 0000000..3958e84 --- /dev/null +++ b/docs/functions/diag.rst @@ -0,0 +1,4 @@ +diag +==== + +.. autofunction:: arrayfire.diag \ No newline at end of file diff --git a/docs/functions/diff1.rst b/docs/functions/diff1.rst new file mode 100644 index 0000000..862f2cc --- /dev/null +++ b/docs/functions/diff1.rst @@ -0,0 +1,4 @@ +diff1 +===== + +.. autofunction:: arrayfire.diff1 \ No newline at end of file diff --git a/docs/functions/diff2.rst b/docs/functions/diff2.rst new file mode 100644 index 0000000..723e367 --- /dev/null +++ b/docs/functions/diff2.rst @@ -0,0 +1,4 @@ +diff2 +===== + +.. autofunction:: arrayfire.diff2 \ No newline at end of file diff --git a/docs/functions/dilate.rst b/docs/functions/dilate.rst new file mode 100644 index 0000000..7d5f07b --- /dev/null +++ b/docs/functions/dilate.rst @@ -0,0 +1,4 @@ +dilate +====== + +.. autofunction:: arrayfire_wrapper.lib.dilate diff --git a/docs/functions/div.rst b/docs/functions/div.rst new file mode 100644 index 0000000..fa086a5 --- /dev/null +++ b/docs/functions/div.rst @@ -0,0 +1,4 @@ +div +=== + +.. autofunction:: arrayfire_wrapper.lib.div diff --git a/docs/functions/dog.rst b/docs/functions/dog.rst new file mode 100644 index 0000000..dfe52e0 --- /dev/null +++ b/docs/functions/dog.rst @@ -0,0 +1,4 @@ +dog +=== + +.. autofunction:: arrayfire.dog \ No newline at end of file diff --git a/docs/functions/dot.rst b/docs/functions/dot.rst new file mode 100644 index 0000000..5717259 --- /dev/null +++ b/docs/functions/dot.rst @@ -0,0 +1,4 @@ +dot +=== + +.. autofunction:: arrayfire.dot \ No newline at end of file diff --git a/docs/functions/eq.rst b/docs/functions/eq.rst new file mode 100644 index 0000000..1b9c67e --- /dev/null +++ b/docs/functions/eq.rst @@ -0,0 +1,4 @@ +eq +== + +.. autofunction:: arrayfire_wrapper.lib.eq diff --git a/docs/functions/erf.rst b/docs/functions/erf.rst new file mode 100644 index 0000000..5c29a27 --- /dev/null +++ b/docs/functions/erf.rst @@ -0,0 +1,4 @@ +erf +=== + +.. autofunction:: arrayfire_wrapper.lib.erf diff --git a/docs/functions/erfc.rst b/docs/functions/erfc.rst new file mode 100644 index 0000000..f816b96 --- /dev/null +++ b/docs/functions/erfc.rst @@ -0,0 +1,4 @@ +erfc +==== + +.. autofunction:: arrayfire_wrapper.lib.erfc diff --git a/docs/functions/erode.rst b/docs/functions/erode.rst new file mode 100644 index 0000000..56277a2 --- /dev/null +++ b/docs/functions/erode.rst @@ -0,0 +1,4 @@ +erode +===== + +.. autofunction:: arrayfire_wrapper.lib.erode diff --git a/docs/functions/eval.rst b/docs/functions/eval.rst new file mode 100644 index 0000000..a380b16 --- /dev/null +++ b/docs/functions/eval.rst @@ -0,0 +1,4 @@ +eval +==== + +.. autofunction:: arrayfire.eval diff --git a/docs/functions/exp.rst b/docs/functions/exp.rst new file mode 100644 index 0000000..5d06ec0 --- /dev/null +++ b/docs/functions/exp.rst @@ -0,0 +1,32 @@ +exp +=== +The 'af.exp()' function in ArrayFire computes the element-wise exponential of an array. This function calculates the exponential of each element in the input array, using the base of the natural logarithm (e ≈ 2.71828). It is commonly used in scientific computing, machine learning, and numerical analysis where exponential transformations are required. + +Function +-------- +:literal:`af.exp()` + - Python interface used to compute the exponential of each element in an array. + +Detailed Description +-------------------- +The af.exp() function performs the exponential operation on each element of the input array. If +𝑥 is an element in the array, then exp⁡(𝑥) computes 𝑒𝑥, where 𝑒 is the base of the natural logarithm. + +This function supports: + +- **Element-wise Operations:** Applying the exponential function to each element of the array independently. +- **Broadcasting:** Automatically handling arrays of different shapes for operations where applicable. + +Function Documentation +---------------------- +.. sidebar:: af.exp() + + Syntax: + af.exp(array) + + Parameters: + 'array': An ArrayFire array (1D, 2D, or higher-dimensional) for which the exponential is to be computed. + + Returns: + An ArrayFire array with the same shape as the input array, where each element is the exponential of the corresponding element in the input array. + diff --git a/docs/functions/expm1.rst b/docs/functions/expm1.rst new file mode 100644 index 0000000..6f1a5d6 --- /dev/null +++ b/docs/functions/expm1.rst @@ -0,0 +1,4 @@ +expm1 +===== + +.. autofunction:: arrayfire_wrapper.lib.expm1 diff --git a/docs/functions/factorial.rst b/docs/functions/factorial.rst new file mode 100644 index 0000000..679fe1e --- /dev/null +++ b/docs/functions/factorial.rst @@ -0,0 +1,4 @@ +factorial +========= + +.. autofunction:: arrayfire_wrapper.lib.factorial diff --git a/docs/functions/fast.rst b/docs/functions/fast.rst new file mode 100644 index 0000000..f0b1bb2 --- /dev/null +++ b/docs/functions/fast.rst @@ -0,0 +1,4 @@ +fast +==== + +.. autofunction:: arrayfire.fast \ No newline at end of file diff --git a/docs/functions/fft.rst b/docs/functions/fft.rst new file mode 100644 index 0000000..e648438 --- /dev/null +++ b/docs/functions/fft.rst @@ -0,0 +1,41 @@ +fft +=== +The 'af.fft()' function in ArrayFire computes the Fast Fourier Transform (FFT) of an array. The FFT is an efficient algorithm to compute the discrete Fourier transform (DFT) and its inverse. The function is used to transform signals from the time domain to the frequency domain, which is essential in signal processing, image analysis, and many other fields. + +Function +-------- +:literal:`af.fft()` + - Python interface for transforming signals from the time domain to the frequency domain. + +Detailed Description +-------------------- +The 'af.fft()' function performs a discrete Fourier transform of the input array. The FFT is commonly used for: + +- Signal Processing: Analyzing the frequency components of a signal. +- Image Processing: Transforming images to the frequency domain for various processing tasks. +- Numerical Analysis: Solving differential equations and other problems where Fourier methods are applicable. + +The function supports: + +- 1D FFT: Transforming 1D arrays (vectors). +- 2D FFT: Transforming 2D arrays (matrices). +- 3D FFT: Transforming 3D arrays (volumes). +- Multi-dimensional FFTs: Transforming arrays of higher dimensions. + +The FFT can be computed along specified dimensions or all dimensions of the input array. + +Function Documentation +---------------------- +.. sidebar:: af.fft() + + Syntax: + af.fft(array, dim=None, is_inverse=False) + + Parameters: + - array: The ArrayFire array (1D, 2D, or higher-dimensional) to transform. + - dim (optional): The dimension along which to compute the FFT. If not specified, the FFT is computed along all dimensions. + - is_inverse (optional): A boolean flag indicating whether to compute the inverse FFT. If True, the function computes the inverse FFT; otherwise, it computes the forward FFT. + + Returns: + An ArrayFire array of the same shape as the input array containing the FFT of the input array. + diff --git a/docs/functions/fft2.rst b/docs/functions/fft2.rst new file mode 100644 index 0000000..bea70a3 --- /dev/null +++ b/docs/functions/fft2.rst @@ -0,0 +1,4 @@ +fft2 +==== + +.. autofunction:: arrayfire_wrapper.lib.fft2 diff --git a/docs/functions/fft2_c2r.rst b/docs/functions/fft2_c2r.rst new file mode 100644 index 0000000..9403a4e --- /dev/null +++ b/docs/functions/fft2_c2r.rst @@ -0,0 +1,4 @@ +fft2_c2r +======== + +.. autofunction:: arrayfire_wrapper.lib.fft2_c2r diff --git a/docs/functions/fft2_r2c.rst b/docs/functions/fft2_r2c.rst new file mode 100644 index 0000000..c11fca4 --- /dev/null +++ b/docs/functions/fft2_r2c.rst @@ -0,0 +1,4 @@ +fft2_r2c +======== + +.. autofunction:: arrayfire_wrapper.lib.fft2_r2c diff --git a/docs/functions/fft3.rst b/docs/functions/fft3.rst new file mode 100644 index 0000000..7fd90a5 --- /dev/null +++ b/docs/functions/fft3.rst @@ -0,0 +1,4 @@ +fft3 +==== + +.. autofunction:: arrayfire_wrapper.lib.fft3 diff --git a/docs/functions/fft3_c2r.rst b/docs/functions/fft3_c2r.rst new file mode 100644 index 0000000..4a0cb97 --- /dev/null +++ b/docs/functions/fft3_c2r.rst @@ -0,0 +1,4 @@ +fft3_c2r +======== + +.. autofunction:: arrayfire_wrapper.lib.fft3_c2r diff --git a/docs/functions/fft3_r2c.rst b/docs/functions/fft3_r2c.rst new file mode 100644 index 0000000..c1d053a --- /dev/null +++ b/docs/functions/fft3_r2c.rst @@ -0,0 +1,4 @@ +fft3_r2c +======== + +.. autofunction:: arrayfire_wrapper.lib.fft3_r2c diff --git a/docs/functions/fft_c2r.rst b/docs/functions/fft_c2r.rst new file mode 100644 index 0000000..834a43a --- /dev/null +++ b/docs/functions/fft_c2r.rst @@ -0,0 +1,4 @@ +fft_c2r +======= + +.. autofunction:: arrayfire_wrapper.lib.fft_c2r diff --git a/docs/functions/fft_convolve1.rst b/docs/functions/fft_convolve1.rst new file mode 100644 index 0000000..ad3277f --- /dev/null +++ b/docs/functions/fft_convolve1.rst @@ -0,0 +1,4 @@ +fft_convolve1 +============= + +.. autofunction:: arrayfire_wrapper.lib.fft_convolve1 diff --git a/docs/functions/fft_convolve2.rst b/docs/functions/fft_convolve2.rst new file mode 100644 index 0000000..11dfe0a --- /dev/null +++ b/docs/functions/fft_convolve2.rst @@ -0,0 +1,4 @@ +fft_convolve2 +============= + +.. autofunction:: arrayfire_wrapper.lib.fft_convolve2 diff --git a/docs/functions/fft_convolve3.rst b/docs/functions/fft_convolve3.rst new file mode 100644 index 0000000..6d18162 --- /dev/null +++ b/docs/functions/fft_convolve3.rst @@ -0,0 +1,4 @@ +fft_convolve3 +============= + +.. autofunction:: arrayfire_wrapper.lib.fft_convolve3 diff --git a/docs/functions/fft_r2c.rst b/docs/functions/fft_r2c.rst new file mode 100644 index 0000000..448b15a --- /dev/null +++ b/docs/functions/fft_r2c.rst @@ -0,0 +1,4 @@ +fft_r2c +======= + +.. autofunction:: arrayfire_wrapper.lib.fft_r2c diff --git a/docs/functions/fir.rst b/docs/functions/fir.rst new file mode 100644 index 0000000..dc5ac6c --- /dev/null +++ b/docs/functions/fir.rst @@ -0,0 +1,4 @@ +fir +=== + +.. autofunction:: arrayfire_wrapper.lib.fir diff --git a/docs/functions/flat.rst b/docs/functions/flat.rst new file mode 100644 index 0000000..cee1184 --- /dev/null +++ b/docs/functions/flat.rst @@ -0,0 +1,4 @@ +flat +==== + +.. autofunction:: arrayfire.flat diff --git a/docs/functions/flip.rst b/docs/functions/flip.rst new file mode 100644 index 0000000..bb75af6 --- /dev/null +++ b/docs/functions/flip.rst @@ -0,0 +1,4 @@ +flip +==== + +.. autofunction:: arrayfire.flip diff --git a/docs/functions/floor.rst b/docs/functions/floor.rst new file mode 100644 index 0000000..349486a --- /dev/null +++ b/docs/functions/floor.rst @@ -0,0 +1,4 @@ +floor +===== + +.. autofunction:: arrayfire_wrapper.lib.floor diff --git a/docs/functions/free_device.rst b/docs/functions/free_device.rst new file mode 100644 index 0000000..7d842f9 --- /dev/null +++ b/docs/functions/free_device.rst @@ -0,0 +1,4 @@ +free_device +=========== + +.. autofunction:: arrayfire_wrapper.lib.free_device diff --git a/docs/functions/free_host.rst b/docs/functions/free_host.rst new file mode 100644 index 0000000..da0b090 --- /dev/null +++ b/docs/functions/free_host.rst @@ -0,0 +1,4 @@ +free_host +========= + +.. autofunction:: arrayfire_wrapper.lib.free_host diff --git a/docs/functions/free_pinned.rst b/docs/functions/free_pinned.rst new file mode 100644 index 0000000..16095b7 --- /dev/null +++ b/docs/functions/free_pinned.rst @@ -0,0 +1,4 @@ +free_pinned +=========== + +.. autofunction:: arrayfire_wrapper.lib.free_pinned diff --git a/docs/functions/gaussian_kernel.rst b/docs/functions/gaussian_kernel.rst new file mode 100644 index 0000000..92a3bef --- /dev/null +++ b/docs/functions/gaussian_kernel.rst @@ -0,0 +1,4 @@ +gaussian_kernel +=============== + +.. autofunction:: arrayfire_wrapper.lib.gaussian_kernel diff --git a/docs/functions/ge.rst b/docs/functions/ge.rst new file mode 100644 index 0000000..9c7d803 --- /dev/null +++ b/docs/functions/ge.rst @@ -0,0 +1,4 @@ +ge +== + +.. autofunction:: arrayfire_wrapper.lib.ge diff --git a/docs/functions/gemm.rst b/docs/functions/gemm.rst new file mode 100644 index 0000000..0e53480 --- /dev/null +++ b/docs/functions/gemm.rst @@ -0,0 +1,4 @@ +gemm +====== + +.. autofunction:: arrayfire.gemm \ No newline at end of file diff --git a/docs/functions/get.rst b/docs/functions/get.rst new file mode 100644 index 0000000..f7d8956 --- /dev/null +++ b/docs/functions/get.rst @@ -0,0 +1,31 @@ +get +=== +The af.get() function in ArrayFire is used to retrieve data from an ArrayFire array and copy it into a standard Python data structure, such as a NumPy array or a Python list. This function is useful for accessing and manipulating the data stored in ArrayFire arrays within the Python environment. + +Function +-------- +:literal:`af.get()` + - Python interface used to retrieve data from an ArrayFire array and copy it into a standard Python data structure. + +Detailed Description +-------------------- +The 'af.get()' function is used to copy the data from an ArrayFire array into a standard Python data structure. This function is typically used when you need to work with the data in a format that is compatible with other Python libraries or for further analysis and manipulation in Python. + +Key Points: + +- Conversion to NumPy Arrays: You can convert ArrayFire arrays to NumPy arrays for use with libraries that do not support ArrayFire arrays directly. +- Conversion to Python Lists: You can convert ArrayFire arrays to Python lists for ease of use in general Python code. + +Function Documentation +---------------------- +.. sidebar:: af.get() + + Syntax: + af.get(array) + + + Parameters: + 'array': The ArrayFire array from which to retrieve data. + + Returns: + A standard Python data structure (e.g., NumPy array or Python list) containing the data from the ArrayFire array. diff --git a/docs/functions/get_backend.rst b/docs/functions/get_backend.rst new file mode 100644 index 0000000..2608d13 --- /dev/null +++ b/docs/functions/get_backend.rst @@ -0,0 +1,25 @@ +get_backend +=========== +The 'af.get_backend()' function in ArrayFire is used to retrieve the BackendType object associated with the ArrayFire context. This function provides information about the current active backend. It is useful for managing and querying the status of a compute backend in a multi-device environment. + +Function +-------- +:literal:`af.get_backend()` + - Python interface used to retrieve the BackendType object associated with the ArrayFire context. + +Detailed Description +-------------------- +The 'af.get_backend()' function provides access to the BackendType object in ArrayFire. The possible return values are BackendType.cpu, BackendType.opencl, BackendType.cuda, BackendType.oneapi. This function is particularly useful in environments where multiple devices are available and you need to query or manage backend-specific information. + +Function Documentation +---------------------- +.. sidebar:: af.get_backend() + + Syntax: + device = af.get_backend() + + Parameters: + This function does not take any parameters. + + Returns: + An ArrayFire device object representing the current active backend in the ArrayFire context. diff --git a/docs/functions/get_dbl_support.rst b/docs/functions/get_dbl_support.rst new file mode 100644 index 0000000..65965d9 --- /dev/null +++ b/docs/functions/get_dbl_support.rst @@ -0,0 +1,4 @@ +get_dbl_support +=============== + +.. autofunction:: arrayfire_wrapper.lib.get_dbl_support diff --git a/docs/functions/get_device.rst b/docs/functions/get_device.rst new file mode 100644 index 0000000..8e64928 --- /dev/null +++ b/docs/functions/get_device.rst @@ -0,0 +1,4 @@ +get_device +========== + +.. autofunction:: arrayfire_wrapper.lib.get_device diff --git a/docs/functions/get_device_count.rst b/docs/functions/get_device_count.rst new file mode 100644 index 0000000..d42362a --- /dev/null +++ b/docs/functions/get_device_count.rst @@ -0,0 +1,4 @@ +get_device_count +================ + +.. autofunction:: arrayfire_wrapper.lib.get_device_count diff --git a/docs/functions/get_half_support.rst b/docs/functions/get_half_support.rst new file mode 100644 index 0000000..5befef1 --- /dev/null +++ b/docs/functions/get_half_support.rst @@ -0,0 +1,4 @@ +get_half_support +================ + +.. autofunction:: arrayfire_wrapper.lib.get_half_support diff --git a/docs/functions/get_kernel_cache_directory.rst b/docs/functions/get_kernel_cache_directory.rst new file mode 100644 index 0000000..e6e4123 --- /dev/null +++ b/docs/functions/get_kernel_cache_directory.rst @@ -0,0 +1,4 @@ +get_kernel_cache_directory +========================== + +.. autofunction:: arrayfire_wrapper.lib.get_kernel_cache_directory diff --git a/docs/functions/get_mem_step_size.rst b/docs/functions/get_mem_step_size.rst new file mode 100644 index 0000000..94156a3 --- /dev/null +++ b/docs/functions/get_mem_step_size.rst @@ -0,0 +1,4 @@ +get_mem_step_size +================= + +.. autofunction:: arrayfire_wrapper.lib.get_mem_step_size diff --git a/docs/functions/get_native_id.rst b/docs/functions/get_native_id.rst new file mode 100644 index 0000000..b0ff2e8 --- /dev/null +++ b/docs/functions/get_native_id.rst @@ -0,0 +1,4 @@ +get_native_id +============= + +.. autofunction:: arrayfire_wrapper.lib.get_native_id diff --git a/docs/functions/get_stream.rst b/docs/functions/get_stream.rst new file mode 100644 index 0000000..cb6d152 --- /dev/null +++ b/docs/functions/get_stream.rst @@ -0,0 +1,4 @@ +get_stream +========== + +.. autofunction:: arrayfire_wrapper.lib.get_stream diff --git a/docs/functions/gloh.rst b/docs/functions/gloh.rst new file mode 100644 index 0000000..a0c4009 --- /dev/null +++ b/docs/functions/gloh.rst @@ -0,0 +1,4 @@ +gloh +==== + +.. autofunction:: arrayfire.gloh \ No newline at end of file diff --git a/docs/functions/gradient.rst b/docs/functions/gradient.rst new file mode 100644 index 0000000..22ffaed --- /dev/null +++ b/docs/functions/gradient.rst @@ -0,0 +1,4 @@ +gradient +======== + +.. autofunction:: arrayfire.gradient \ No newline at end of file diff --git a/docs/functions/gray2rgb.rst b/docs/functions/gray2rgb.rst new file mode 100644 index 0000000..2b61659 --- /dev/null +++ b/docs/functions/gray2rgb.rst @@ -0,0 +1,4 @@ +gray2rgb +======== + +.. autofunction:: arrayfire_wrapper.lib.gray2rgb diff --git a/docs/functions/gt.rst b/docs/functions/gt.rst new file mode 100644 index 0000000..03a4eea --- /dev/null +++ b/docs/functions/gt.rst @@ -0,0 +1,4 @@ +gt +== + +.. autofunction:: arrayfire_wrapper.lib.gt diff --git a/docs/functions/hamming_matcher.rst b/docs/functions/hamming_matcher.rst new file mode 100644 index 0000000..a4b5747 --- /dev/null +++ b/docs/functions/hamming_matcher.rst @@ -0,0 +1,4 @@ +hamming_matcher +=============== + +.. autofunction:: arrayfire.hamming_matcher \ No newline at end of file diff --git a/docs/functions/harris.rst b/docs/functions/harris.rst new file mode 100644 index 0000000..32e5ef6 --- /dev/null +++ b/docs/functions/harris.rst @@ -0,0 +1,4 @@ +harris +====== + +.. autofunction:: arrayfire.harris \ No newline at end of file diff --git a/docs/functions/hist_equal.rst b/docs/functions/hist_equal.rst new file mode 100644 index 0000000..5ac088e --- /dev/null +++ b/docs/functions/hist_equal.rst @@ -0,0 +1,4 @@ +hist_equal +========== + +.. autofunction:: arrayfire_wrapper.lib.hist_equal diff --git a/docs/functions/histogram.rst b/docs/functions/histogram.rst new file mode 100644 index 0000000..bb5018a --- /dev/null +++ b/docs/functions/histogram.rst @@ -0,0 +1,4 @@ +histogram +========= + +.. autofunction:: arrayfire_wrapper.lib.histogram diff --git a/docs/functions/hsv2rgb.rst b/docs/functions/hsv2rgb.rst new file mode 100644 index 0000000..28a0317 --- /dev/null +++ b/docs/functions/hsv2rgb.rst @@ -0,0 +1,4 @@ +hsv2rgb +======= + +.. autofunction:: arrayfire_wrapper.lib.hsv2rgb diff --git a/docs/functions/hypot.rst b/docs/functions/hypot.rst new file mode 100644 index 0000000..4a641fc --- /dev/null +++ b/docs/functions/hypot.rst @@ -0,0 +1,4 @@ +hypot +===== + +.. autofunction:: arrayfire_wrapper.lib.hypot diff --git a/docs/functions/identity.rst b/docs/functions/identity.rst new file mode 100644 index 0000000..e297bb6 --- /dev/null +++ b/docs/functions/identity.rst @@ -0,0 +1,4 @@ +identity +========= + +.. autofunction:: arrayfire.identity \ No newline at end of file diff --git a/docs/functions/ifft.rst b/docs/functions/ifft.rst new file mode 100644 index 0000000..991576c --- /dev/null +++ b/docs/functions/ifft.rst @@ -0,0 +1,27 @@ +ifft +==== +The 'af.ifft()' function in ArrayFire computes the inverse Fast Fourier Transform (IFFT) of an array. The IFFT is used to transform data from the frequency domain back to the time domain, which is crucial in many signal processing, image analysis, and scientific computing applications. + +Function +-------- +:literal:`af.ifft()` + - Python interface used to compute the inverse Fast Fourier Transform of an array. + +Detailed Description +-------------------- +The 'af.ifft()' function performs an inverse discrete Fourier transform of the input array. It is essentially the reverse operation of the Fast Fourier Transform (FFT), converting frequency domain data back into the time domain. + +Function Documentation +---------------------- +.. sidebar:: af.ifft() + + Syntax: + af.ifft(array, dim=None) + + Parameters: + 'array': The ArrayFire array (1D, 2D, or higher-dimensional) to which the inverse FFT is to be applied. + 'dim (optional)'': The dimension along which to compute the inverse FFT. If not specified, the IFFT is computed along all dimensions. + + Returns: + An ArrayFire array of the same shape as the input array containing the result of the inverse FFT. + diff --git a/docs/functions/ifft2.rst b/docs/functions/ifft2.rst new file mode 100644 index 0000000..98a0149 --- /dev/null +++ b/docs/functions/ifft2.rst @@ -0,0 +1,4 @@ +ifft2 +===== + +.. autofunction:: arrayfire_wrapper.lib.ifft2 diff --git a/docs/functions/ifft3.rst b/docs/functions/ifft3.rst new file mode 100644 index 0000000..20081dc --- /dev/null +++ b/docs/functions/ifft3.rst @@ -0,0 +1,4 @@ +ifft3 +===== + +.. autofunction:: arrayfire_wrapper.lib.ifft3 diff --git a/docs/functions/iir.rst b/docs/functions/iir.rst new file mode 100644 index 0000000..2c38fd2 --- /dev/null +++ b/docs/functions/iir.rst @@ -0,0 +1,4 @@ +iir +=== + +.. autofunction:: arrayfire_wrapper.lib.iir diff --git a/docs/functions/imag.rst b/docs/functions/imag.rst new file mode 100644 index 0000000..6c39fe5 --- /dev/null +++ b/docs/functions/imag.rst @@ -0,0 +1,4 @@ +imag +==== + +.. autofunction:: arrayfire_wrapper.lib.imag diff --git a/docs/functions/imax.rst b/docs/functions/imax.rst new file mode 100644 index 0000000..c84a23a --- /dev/null +++ b/docs/functions/imax.rst @@ -0,0 +1,4 @@ +imax +===== + +.. autofunction:: arrayfire.imax \ No newline at end of file diff --git a/docs/functions/imin.rst b/docs/functions/imin.rst new file mode 100644 index 0000000..642af25 --- /dev/null +++ b/docs/functions/imin.rst @@ -0,0 +1,4 @@ +imin +==== + +.. autofunction:: arrayfire.imin \ No newline at end of file diff --git a/docs/functions/index.rst b/docs/functions/index.rst new file mode 100644 index 0000000..d674e06 --- /dev/null +++ b/docs/functions/index.rst @@ -0,0 +1,253 @@ +:orphan: + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Function List: + + abs + accum + acos + acosh + add + all_true + alloc_device + alloc_host + alloc_pinned + anisotropic_diffusion + any_true + approx1 + approx1_uniform + approx2 + approx2_uniform + arg + asin + asinh + atan + atan2 + atanh + bilateral + bitand + bitnot + bitor + bitshiftl + bitshiftr + bitxor + canny + cast + cbrt + ceil + cholesky + clamp + color_space + confidence_cc + conjg + constant + convolve1 + convolve2 + convolve2_gradient_nn + convolve2_nn + convolve2_separable + convolve3 + copy_array + cos + cosh + count + cplx + cublas_set_math_mode + delete_image_memory + det + device_gc + device_info + device_mem_info + diag + diff1 + diff2 + dilate + div + dog + dot + eq + erf + erfc + erode + eval + exp + expm1 + factorial + fast + fft + fft2 + fft2_c2r + fft2_r2c + fft3 + fft3_c2r + fft3_r2c + fft_c2r + fft_convolve1 + fft_convolve2 + fft_convolve3 + fft_r2c + fir + flat + flip + floor + free_device + free_host + free_pinned + gaussian_kernel + ge + gemm + get + get_backend + get_dbl_support + get_device + get_device_count + get_half_support + get_kernel_cache_directory + get_mem_step_size + get_native_id + get_stream + gloh + gradient + gray2rgb + gt + hamming_matcher + harris + hist_equal + histogram + hsv2rgb + hypot + identity + ifft + ifft2 + ifft3 + iir + imag + imax + imin + info + info_string + init + inv + inverse + inverse_deconv + iota + is_image_io_available + is_lapack_available + isinf + isnan + iszero + iterative_deconv + join + le + lgamma + load_image + load_image_memory + load_image_native + log + log10 + log1p + log2 + logical_and + logical_not + logical_or + lookup + lower + lt + lu + matmul + max + maxfilt + maxof + mean + mean_shift + medfilt + medfilt1 + medfilt2 + median + min + minfilt + minof + mod + moddims + mul + nearest_neighbour + neg + neq + norm + ones + orb + pad + pinverse + pow + pow2 + print_mem_info + product + qr + randn + randu + range + rank + read_array + real + regions + rem + reorder + replace + reshape + resize + rgb2gray + rgb2hsv + rgb2ycbcr + root + rotate + round + rsqrt + sat + save_array + save_image + save_image_memory + save_image_native + scale + scan + select + set_backend + set_device + set_fft_plan_cache_size + set_intersect + set_kernel_cache_directory + set_mem_step_size + set_native_id + set_union + set_unique + shift + sift + sign + sin + sinh + skew + sobel_operator + solve + sort + sqrt + sttdev + sub + sum + susan + svd + sync + tan + tanh + tgamma + tile + transform + transform_coordinates + translate + transpose + trunc + unwrap + upper + where + wrap + zeros diff --git a/docs/functions/info.rst b/docs/functions/info.rst new file mode 100644 index 0000000..5aa50f8 --- /dev/null +++ b/docs/functions/info.rst @@ -0,0 +1,4 @@ +info +==== + +.. autofunction:: arrayfire_wrapper.lib.info diff --git a/docs/functions/info_string.rst b/docs/functions/info_string.rst new file mode 100644 index 0000000..6d8c14a --- /dev/null +++ b/docs/functions/info_string.rst @@ -0,0 +1,4 @@ +info_string +=========== + +.. autofunction:: arrayfire_wrapper.lib.info_string diff --git a/docs/functions/init.rst b/docs/functions/init.rst new file mode 100644 index 0000000..e72fb38 --- /dev/null +++ b/docs/functions/init.rst @@ -0,0 +1,4 @@ +init +==== + +.. autofunction:: arrayfire_wrapper.lib.init diff --git a/docs/functions/inv.rst b/docs/functions/inv.rst new file mode 100644 index 0000000..37969b1 --- /dev/null +++ b/docs/functions/inv.rst @@ -0,0 +1,30 @@ +inv +=== +The 'af.inv()' function in ArrayFire computes the inverse of a square matrix. Matrix inversion is a fundamental operation in linear algebra with applications in solving systems of linear equations, optimization problems, and various computational tasks. + +Function +-------- +:literal:`af.inv()` + - Python interface used to find inverse of a square matrix. + +Detailed Description +-------------------- +The af.inv() function calculates the inverse of a given square matrix. For a matrix +𝐴, the inverse is denoted as 𝐴−1, and it satisfies the following property: + +A⋅A−1=I +where I is the identity matrix. The matrix A must be square (i.e., the number of rows must be equal to the number of columns) for its inverse to exist. + +Function Documentation +---------------------- +.. sidebar:: af.inv() + + Syntax: + af.inv(matrix) + + Parameters: + 'matrix:'' A 2D ArrayFire array representing the square matrix for which the inverse is to be computed. The matrix must be square. + + Returns: + An ArrayFire array of the same shape as the input matrix, containing the inverse of the input matrix. + diff --git a/docs/functions/inverse.rst b/docs/functions/inverse.rst new file mode 100644 index 0000000..3a5d08e --- /dev/null +++ b/docs/functions/inverse.rst @@ -0,0 +1,4 @@ +inverse +======= + +.. autofunction:: arrayfire_wrapper.lib.inverse diff --git a/docs/functions/inverse_deconv.rst b/docs/functions/inverse_deconv.rst new file mode 100644 index 0000000..5d0eb48 --- /dev/null +++ b/docs/functions/inverse_deconv.rst @@ -0,0 +1,4 @@ +inverse_deconv +============== + +.. autofunction:: arrayfire_wrapper.lib.inverse_deconv diff --git a/docs/functions/iota.rst b/docs/functions/iota.rst new file mode 100644 index 0000000..fc11731 --- /dev/null +++ b/docs/functions/iota.rst @@ -0,0 +1,4 @@ +iota +======= + +.. autofunction:: arrayfire.iota \ No newline at end of file diff --git a/docs/functions/is_image_io_available.rst b/docs/functions/is_image_io_available.rst new file mode 100644 index 0000000..c4ad9a2 --- /dev/null +++ b/docs/functions/is_image_io_available.rst @@ -0,0 +1,4 @@ +is_image_io_available +===================== + +.. autofunction:: arrayfire_wrapper.lib.is_image_io_available diff --git a/docs/functions/is_lapack_available.rst b/docs/functions/is_lapack_available.rst new file mode 100644 index 0000000..ef214e7 --- /dev/null +++ b/docs/functions/is_lapack_available.rst @@ -0,0 +1,4 @@ +is_lapack_available +=================== + +.. autofunction:: arrayfire_wrapper.lib.is_lapack_available diff --git a/docs/functions/isinf.rst b/docs/functions/isinf.rst new file mode 100644 index 0000000..a6dc653 --- /dev/null +++ b/docs/functions/isinf.rst @@ -0,0 +1,4 @@ +isinf +===== + +.. autofunction:: arrayfire.isinf \ No newline at end of file diff --git a/docs/functions/isnan.rst b/docs/functions/isnan.rst new file mode 100644 index 0000000..36720ab --- /dev/null +++ b/docs/functions/isnan.rst @@ -0,0 +1,4 @@ +isnan +===== + +.. autofunction:: arrayfire.isnan diff --git a/docs/functions/iszero.rst b/docs/functions/iszero.rst new file mode 100644 index 0000000..bec2a9a --- /dev/null +++ b/docs/functions/iszero.rst @@ -0,0 +1,4 @@ +iszero +====== + +.. autofunction:: arrayfire.iszero diff --git a/docs/functions/iterative_deconv.rst b/docs/functions/iterative_deconv.rst new file mode 100644 index 0000000..0650593 --- /dev/null +++ b/docs/functions/iterative_deconv.rst @@ -0,0 +1,4 @@ +iterative_deconv +================ + +.. autofunction:: arrayfire_wrapper.lib.iterative_deconv diff --git a/docs/functions/join.rst b/docs/functions/join.rst new file mode 100644 index 0000000..18906f7 --- /dev/null +++ b/docs/functions/join.rst @@ -0,0 +1,27 @@ +join +==== +The 'af.join()' function in ArrayFire is used to concatenate multiple arrays along a specified dimension. This operation is useful for combining data from different arrays into a single array, which can be particularly useful in data processing, machine learning, and numerical analysis. + + + +Function +-------- +:literal:`af.join` + - Python interface used to concatenate multiple arrays along a specified dimension. + +Detailed Description +-------------------- +The 'af.join()' function allows you to concatenate multiple arrays along a specified dimension. The arrays being concatenated must have compatible shapes along all dimensions except for the dimension along which concatenation is performed. + +Function Documentation +---------------------- +.. sidebar:: af.join() + + Syntax: + af.join(dim, \*arrays) + + Parameters: + 'dim': The dimension along which the arrays will be concatenated. This is an integer indicating the axis along which the join operation will take place. + '\*arrays': The arrays to be concatenated. These can be 1D, 2D, or higher-dimensional arrays, and they must be compatible in all dimensions except the specified dimension. + Returns: + An ArrayFire array that is the result of concatenating the input arrays along the specified dimension. diff --git a/docs/functions/le.rst b/docs/functions/le.rst new file mode 100644 index 0000000..180d7b3 --- /dev/null +++ b/docs/functions/le.rst @@ -0,0 +1,4 @@ +le +== + +.. autofunction:: arrayfire_wrapper.lib.le diff --git a/docs/functions/lgamma.rst b/docs/functions/lgamma.rst new file mode 100644 index 0000000..35ea774 --- /dev/null +++ b/docs/functions/lgamma.rst @@ -0,0 +1,4 @@ +lgamma +====== + +.. autofunction:: arrayfire_wrapper.lib.lgamma diff --git a/docs/functions/load_image.rst b/docs/functions/load_image.rst new file mode 100644 index 0000000..3ac5153 --- /dev/null +++ b/docs/functions/load_image.rst @@ -0,0 +1,4 @@ +load_image +========== + +.. autofunction:: arrayfire_wrapper.lib.load_image diff --git a/docs/functions/load_image_memory.rst b/docs/functions/load_image_memory.rst new file mode 100644 index 0000000..c6f4cfe --- /dev/null +++ b/docs/functions/load_image_memory.rst @@ -0,0 +1,4 @@ +load_image_memory +================= + +.. autofunction:: arrayfire_wrapper.lib.load_image_memory diff --git a/docs/functions/load_image_native.rst b/docs/functions/load_image_native.rst new file mode 100644 index 0000000..eb62645 --- /dev/null +++ b/docs/functions/load_image_native.rst @@ -0,0 +1,4 @@ +load_image_native +================= + +.. autofunction:: arrayfire_wrapper.lib.load_image_native diff --git a/docs/functions/log.rst b/docs/functions/log.rst new file mode 100644 index 0000000..3477898 --- /dev/null +++ b/docs/functions/log.rst @@ -0,0 +1,26 @@ +log +=== +The 'af.log()' function in ArrayFire computes the natural logarithm (base 𝑒) of each element in the input array. This function is commonly used in mathematical and scientific computing for transformations, normalization, and statistical analysis. + +Function +-------- +:literal:`af.log()` + - Python interface used to compute the natural logarithm of each base element in the input array. + +Detailed Description +-------------------- +The af.log() function applies the natural logarithm operation element-wise to the input array. The natural logarithm is the logarithm to the base +𝑒, where 𝑒 is approximately equal to 2.71828. The function operates on each element of the array independently. + +Function Documentation +---------------------- +.. sidebar:: af.log() + + Syntax: + af.log(array) + + Parameters: + 'array': An ArrayFire array (1D, 2D, or higher-dimensional) containing the values for which the natural logarithm is to be computed. + + Returns: + An ArrayFire array of the same shape as the input array, with each element replaced by its natural logarithm. diff --git a/docs/functions/log10.rst b/docs/functions/log10.rst new file mode 100644 index 0000000..5ebc650 --- /dev/null +++ b/docs/functions/log10.rst @@ -0,0 +1,4 @@ +log10 +===== + +.. autofunction:: arrayfire_wrapper.lib.log10 diff --git a/docs/functions/log1p.rst b/docs/functions/log1p.rst new file mode 100644 index 0000000..5f5727e --- /dev/null +++ b/docs/functions/log1p.rst @@ -0,0 +1,4 @@ +log1p +===== + +.. autofunction:: arrayfire_wrapper.lib.log1p diff --git a/docs/functions/log2.rst b/docs/functions/log2.rst new file mode 100644 index 0000000..d3e5540 --- /dev/null +++ b/docs/functions/log2.rst @@ -0,0 +1,4 @@ +log2 +==== + +.. autofunction:: arrayfire_wrapper.lib.log2 diff --git a/docs/functions/logical_and.rst b/docs/functions/logical_and.rst new file mode 100644 index 0000000..1bba235 --- /dev/null +++ b/docs/functions/logical_and.rst @@ -0,0 +1,4 @@ +logical_and +=========== + +.. autofunction:: arrayfire_wrapper.lib.and_ diff --git a/docs/functions/logical_not.rst b/docs/functions/logical_not.rst new file mode 100644 index 0000000..4001ea2 --- /dev/null +++ b/docs/functions/logical_not.rst @@ -0,0 +1,4 @@ +logical_not +=========== + +.. autofunction:: arrayfire_wrapper.lib.not_ diff --git a/docs/functions/logical_or.rst b/docs/functions/logical_or.rst new file mode 100644 index 0000000..c469538 --- /dev/null +++ b/docs/functions/logical_or.rst @@ -0,0 +1,4 @@ +logical_or +========== + +.. autofunction:: arrayfire_wrapper.lib.or_ diff --git a/docs/functions/lookup.rst b/docs/functions/lookup.rst new file mode 100644 index 0000000..0f3ac72 --- /dev/null +++ b/docs/functions/lookup.rst @@ -0,0 +1,4 @@ +lookup +====== + +.. autofunction:: arrayfire.lookup diff --git a/docs/functions/lower.rst b/docs/functions/lower.rst new file mode 100644 index 0000000..2250b9d --- /dev/null +++ b/docs/functions/lower.rst @@ -0,0 +1,4 @@ +lower +====== + +.. autofunction:: arrayfire.lower \ No newline at end of file diff --git a/docs/functions/lt.rst b/docs/functions/lt.rst new file mode 100644 index 0000000..d67e727 --- /dev/null +++ b/docs/functions/lt.rst @@ -0,0 +1,4 @@ +lt +== + +.. autofunction:: arrayfire_wrapper.lib.lt diff --git a/docs/functions/lu.rst b/docs/functions/lu.rst new file mode 100644 index 0000000..530f3fc --- /dev/null +++ b/docs/functions/lu.rst @@ -0,0 +1,4 @@ +lu +==== + +.. autofunction:: arrayfire_wrapper.lib.lu \ No newline at end of file diff --git a/docs/functions/matmul.rst b/docs/functions/matmul.rst new file mode 100644 index 0000000..40329d3 --- /dev/null +++ b/docs/functions/matmul.rst @@ -0,0 +1,4 @@ +matmul +====== + +.. autofunction:: arrayfire.matmul \ No newline at end of file diff --git a/docs/functions/max.rst b/docs/functions/max.rst new file mode 100644 index 0000000..091719a --- /dev/null +++ b/docs/functions/max.rst @@ -0,0 +1,31 @@ +max +=== +The 'af.max()' function in ArrayFire is used to find the maximum value within an array or along a specific dimension. It can also return the indices of the maximum values if requested. + + + +Function +-------- +:literal:`af.max()` + - Python interface used to find the maximum value within an array or specific dimension. + +Detailed Description +-------------------- +The af.max() function performs one of the following operations: + +- Finds the maximum value in the entire array. +- Finds the maximum value along a specified dimension. +- Returns both the maximum values and their indices if requested. + +Function Documentation +---------------------- +.. sidebar:: af.max() + + Syntax: + af.max(array) + + Parameters: + 'array': The ArrayFire array from which to find the maximum values. + + Returns: + An ArrayFire array containing the maximum element from the input data structure. diff --git a/docs/functions/maxfilt.rst b/docs/functions/maxfilt.rst new file mode 100644 index 0000000..a256e56 --- /dev/null +++ b/docs/functions/maxfilt.rst @@ -0,0 +1,4 @@ +maxfilt +======= + +.. autofunction:: arrayfire_wrapper.lib.maxfilt diff --git a/docs/functions/maxof.rst b/docs/functions/maxof.rst new file mode 100644 index 0000000..b9f1caa --- /dev/null +++ b/docs/functions/maxof.rst @@ -0,0 +1,4 @@ +maxof +===== + +.. autofunction:: arrayfire_wrapper.lib.maxof diff --git a/docs/functions/mean.rst b/docs/functions/mean.rst new file mode 100644 index 0000000..a900ee0 --- /dev/null +++ b/docs/functions/mean.rst @@ -0,0 +1,27 @@ +mean +==== +The 'af.mean()' function in ArrayFire computes the mean (average) value of elements in an array or along a specified dimension. It is a fundamental statistical operation used in various data analysis and processing tasks. + +Function +-------- +:literal:`af.mean()` + - Python interface used to compute the average value of elements in an array or specified dimension. + +Detailed Description +-------------------- +The 'af.mean()' function calculates the average value of elements in the input array. The mean is computed by summing all elements and dividing by the number of elements. The function can compute the mean over the entire array or along a specified dimension. + +Function Documentation +---------------------- +.. sidebar:: af.mean() + + Syntax: + af.mean(array) + + + Parameters: + 'array': The ArrayFire array for which the mean is to be computed. + + Returns: + An ArrayFire array containing the mean values. If 'axis' is specified, the result will have the specified dimension reduced. + diff --git a/docs/functions/mean_shift.rst b/docs/functions/mean_shift.rst new file mode 100644 index 0000000..ba07d9f --- /dev/null +++ b/docs/functions/mean_shift.rst @@ -0,0 +1,4 @@ +mean_shift +========== + +.. autofunction:: arrayfire_wrapper.lib.mean_shift diff --git a/docs/functions/medfilt.rst b/docs/functions/medfilt.rst new file mode 100644 index 0000000..1339e5a --- /dev/null +++ b/docs/functions/medfilt.rst @@ -0,0 +1,4 @@ +medfilt +======= + +.. autofunction:: arrayfire_wrapper.lib.medfilt diff --git a/docs/functions/medfilt1.rst b/docs/functions/medfilt1.rst new file mode 100644 index 0000000..580beff --- /dev/null +++ b/docs/functions/medfilt1.rst @@ -0,0 +1,4 @@ +medfilt1 +======== + +.. autofunction:: arrayfire_wrapper.lib.medfilt1 diff --git a/docs/functions/medfilt2.rst b/docs/functions/medfilt2.rst new file mode 100644 index 0000000..2e0bb5f --- /dev/null +++ b/docs/functions/medfilt2.rst @@ -0,0 +1,4 @@ +medfilt2 +======== + +.. autofunction:: arrayfire_wrapper.lib.medfilt2 diff --git a/docs/functions/median.rst b/docs/functions/median.rst new file mode 100644 index 0000000..4ee1417 --- /dev/null +++ b/docs/functions/median.rst @@ -0,0 +1,27 @@ +median +====== +The af.median() function in ArrayFire computes the median value of elements in an array or along a specified dimension. The median is a measure of central tendency that provides a robust statistic by identifying the middle value in a sorted list of numbers. + +Function +-------- +:literal:`af.median()` + - Python interface used to compute the median value of elements in an array or specified dimension. + +Detailed Description +-------------------- +The 'af.median()' function finds the median value of elements in the input array. The median is defined as the middle value in a sorted sequence of numbers. If the number of elements is even, it is the average of the two middle numbers. The function can compute the median over the entire array or along a specified dimension. + +Function Documentation +---------------------- +.. sidebar:: af.median() + + Syntax: + af.median(array) + + + Parameters: + 'array': The ArrayFire array for which the median is to be computed. + + Returns: + An ArrayFire array containing the median values. If 'axis' is specified, the result will have the specified dimension reduced. + diff --git a/docs/functions/min.rst b/docs/functions/min.rst new file mode 100644 index 0000000..6ee6556 --- /dev/null +++ b/docs/functions/min.rst @@ -0,0 +1,25 @@ +min +=== +The af.min() function in ArrayFire is used to compute the minimum value within an array or along a specific dimension. This operation helps in identifying the smallest value in a dataset or reducing multi-dimensional arrays to a lower dimension based on the minimum values. + +Function +-------- +:literal:`af.min()` + - Python interface used to compute the minimum value within an array or specified dimension. + +Detailed Description +-------------------- +The 'af.min()' function finds the minimum value of elements in the input array. The minimum value is the smallest element in the array. The function can compute the minimum over the entire array or along a specified dimension. + +Function Documentation +---------------------- +.. sidebar:: af.min() + + Syntax: + af.min(array) + + Parameters: + 'array': The ArrayFire array from which to find the minimum values. + + Returns: + An ArrayFire array containing the minimum values from the input data structure. diff --git a/docs/functions/minfilt.rst b/docs/functions/minfilt.rst new file mode 100644 index 0000000..67ed57f --- /dev/null +++ b/docs/functions/minfilt.rst @@ -0,0 +1,4 @@ +minfilt +======= + +.. autofunction:: arrayfire_wrapper.lib.minfilt diff --git a/docs/functions/minof.rst b/docs/functions/minof.rst new file mode 100644 index 0000000..ab3e338 --- /dev/null +++ b/docs/functions/minof.rst @@ -0,0 +1,4 @@ +minof +===== + +.. autofunction:: arrayfire_wrapper.lib.minof diff --git a/docs/functions/mod.rst b/docs/functions/mod.rst new file mode 100644 index 0000000..85f8148 --- /dev/null +++ b/docs/functions/mod.rst @@ -0,0 +1,4 @@ +mod +=== + +.. autofunction:: arrayfire.mod \ No newline at end of file diff --git a/docs/functions/moddims.rst b/docs/functions/moddims.rst new file mode 100644 index 0000000..bb1b23d --- /dev/null +++ b/docs/functions/moddims.rst @@ -0,0 +1,4 @@ +moddims +======= + +.. autofunction:: arrayfire.moddims diff --git a/docs/functions/mul.rst b/docs/functions/mul.rst new file mode 100644 index 0000000..31ac3f4 --- /dev/null +++ b/docs/functions/mul.rst @@ -0,0 +1,4 @@ +mul +=== + +.. autofunction:: arrayfire_wrapper.lib.mul diff --git a/docs/functions/nearest_neighbour.rst b/docs/functions/nearest_neighbour.rst new file mode 100644 index 0000000..a617e53 --- /dev/null +++ b/docs/functions/nearest_neighbour.rst @@ -0,0 +1,4 @@ +nearest_neighbour +================= + +.. autofunction:: arrayfire.nearest_neighbour \ No newline at end of file diff --git a/docs/functions/neg.rst b/docs/functions/neg.rst new file mode 100644 index 0000000..546ff47 --- /dev/null +++ b/docs/functions/neg.rst @@ -0,0 +1,4 @@ +neg +=== + +.. autofunction:: arrayfire_wrapper.lib.neg diff --git a/docs/functions/neq.rst b/docs/functions/neq.rst new file mode 100644 index 0000000..f577cd6 --- /dev/null +++ b/docs/functions/neq.rst @@ -0,0 +1,4 @@ +neq +=== + +.. autofunction:: arrayfire_wrapper.lib.neq diff --git a/docs/functions/norm.rst b/docs/functions/norm.rst new file mode 100644 index 0000000..f90124b --- /dev/null +++ b/docs/functions/norm.rst @@ -0,0 +1,4 @@ +norm +==== + +.. autofunction:: arrayfire_wrapper.lib.norm diff --git a/docs/functions/ones.rst b/docs/functions/ones.rst new file mode 100644 index 0000000..fbf78af --- /dev/null +++ b/docs/functions/ones.rst @@ -0,0 +1,26 @@ +ones +==== +The 'af.ones()' function in the ArrayFire library is used to create arrays where every element is initialized to one. This function is useful for various numerical and scientific computing tasks where you need an array filled with ones, such as initializing weights in machine learning algorithms or setting up identity matrices. + +Function +-------- +:literal:`af.ones()` + - Pyhton interface to create an array filled with ones. + +Detailed Description +-------------------- +The 'af.ones()' function creates an ArrayFire array in which all the elements are set to one. This function is versatile and can create arrays of different shapes and data types. By default, the function creates arrays with single precision floating-point numbers (float), but you can specify different data types as needed. + +The dimensions of the array are specified as arguments to the function, allowing you to create both one-dimensional and multi-dimensional arrays. + +Function Documentation +---------------------- +.. sidebar:: af.ones() + + Syntax: + af.ones(dim0, dim1) + + Parameters: + 'dim0, dim1': Integers representing the dimensions of the array. You can provide multiple dimensions to create multi-dimensional arrays. For instance, 'dim0' represents the number of rows, and 'dim1' represents the number of columns for a 2D array. + Returns: + An ArrayFire array with the specified dimensions and data type, where all elements are initialized to one. diff --git a/docs/functions/orb.rst b/docs/functions/orb.rst new file mode 100644 index 0000000..4b671bc --- /dev/null +++ b/docs/functions/orb.rst @@ -0,0 +1,4 @@ +orb +=== + +.. autofunction:: arrayfire.orb \ No newline at end of file diff --git a/docs/functions/pad.rst b/docs/functions/pad.rst new file mode 100644 index 0000000..b89fe9c --- /dev/null +++ b/docs/functions/pad.rst @@ -0,0 +1,4 @@ +pad +=== + +.. autofunction:: arrayfire.pad \ No newline at end of file diff --git a/docs/functions/pinverse.rst b/docs/functions/pinverse.rst new file mode 100644 index 0000000..5cca53a --- /dev/null +++ b/docs/functions/pinverse.rst @@ -0,0 +1,4 @@ +pinverse +======== + +.. autofunction:: arrayfire_wrapper.lib.pinverse diff --git a/docs/functions/pow.rst b/docs/functions/pow.rst new file mode 100644 index 0000000..62e6c07 --- /dev/null +++ b/docs/functions/pow.rst @@ -0,0 +1,4 @@ +pow +=== + +.. autofunction:: arrayfire_wrapper.lib.pow diff --git a/docs/functions/pow2.rst b/docs/functions/pow2.rst new file mode 100644 index 0000000..0903c95 --- /dev/null +++ b/docs/functions/pow2.rst @@ -0,0 +1,4 @@ +pow2 +==== + +.. autofunction:: arrayfire_wrapper.lib.pow2 diff --git a/docs/functions/print_mem_info.rst b/docs/functions/print_mem_info.rst new file mode 100644 index 0000000..e520947 --- /dev/null +++ b/docs/functions/print_mem_info.rst @@ -0,0 +1,4 @@ +print_mem_info +============== + +.. autofunction:: arrayfire_wrapper.lib.print_mem_info diff --git a/docs/functions/product.rst b/docs/functions/product.rst new file mode 100644 index 0000000..99a4efe --- /dev/null +++ b/docs/functions/product.rst @@ -0,0 +1,4 @@ +product +======= + +.. autofunction:: arrayfire.product \ No newline at end of file diff --git a/docs/functions/qr.rst b/docs/functions/qr.rst new file mode 100644 index 0000000..f6315b0 --- /dev/null +++ b/docs/functions/qr.rst @@ -0,0 +1,4 @@ +qr +===== + +.. autofunction:: arrayfire_wrapper.lib.qr \ No newline at end of file diff --git a/docs/functions/randn.rst b/docs/functions/randn.rst new file mode 100644 index 0000000..43ff957 --- /dev/null +++ b/docs/functions/randn.rst @@ -0,0 +1,26 @@ +randn +===== +The 'af.randn()' function in the ArrayFire library is used to generate arrays filled with random numbers drawn from a normal (Gaussian) distribution with mean 0 and standard deviation 1. This is useful in statistical simulations, machine learning, and other applications where normally distributed random values are required. + +Function +-------- +:literal:`af.python()` + - Python interface to form an array filled with numbers. + +Detailed Description +-------------------- +The 'af.randn()' function creates an ArrayFire array where each element is a random number sampled from a standard normal distribution, also known as a Gaussian distribution. The distribution has a mean of 0 and a standard deviation of 1. This function allows you to specify the dimensions of the array and optionally the data type. By default, the function generates numbers in single precision floating-point format (float), but other data types can be specified if needed. + +Function Documentation +---------------------- +.. sidebar:: af.randn() + + Syntax: + af.randn(dim0, dim1) + + + Parameters: + 'dim0, dim1': Integers representing the dimensions of the array. You can specify multiple dimensions to create multi-dimensional arrays. For example, dim0 represents the number of rows, and dim1 represents the number of columns for a 2D array. + + Returns: + An ArrayFire array with the specified dimensions and data type, where all elements are initialized with random values sampled from a normal distribution with mean 0 and standard deviation 1. diff --git a/docs/functions/randu.rst b/docs/functions/randu.rst new file mode 100644 index 0000000..16de0df --- /dev/null +++ b/docs/functions/randu.rst @@ -0,0 +1,29 @@ +randu +===== +The af.randu() function in ArrayFire is used to generate arrays with uniformly distributed random numbers. The numbers are drawn from a uniform distribution in the interval +[0,1). This function is useful for initializing random data for simulations, stochastic processes, or for testing algorithms that require random inputs. + +Function +-------- +:literal:`af.randu()` + - Python interface for making a rray with random units. + +Detailed Description +-------------------- +The 'af.randu()' function creates an ArrayFire array filled with random numbers that follow a uniform distribution between 0 and 1 (excluding 1). This function allows you to specify the dimensions of the array and optionally the data type. By default, the generated numbers are single-precision floating-point values (float), but other data types can be specified if needed. + +Random number generation is a fundamental aspect of many computational tasks, and 'af.randu()' provides an efficient way to create random datasets with uniform distribution. + +Function Documentation +---------------------- +.. sidebar:: af.randu() + + Syntax: + af.randu(dim0, dim1) + + Parameters: + 'dim0, dim1': Integers representing the dimensions of the array. You can provide multiple dimensions to create multi-dimensional arrays. For example, dim0 represents the number of rows, and dim1 represents the number of columns for a 2D array. + + Returns: + An ArrayFire array with the specified dimensions and data type, where all elements are initialized with random values uniformly distributed between 0 and 1. + diff --git a/docs/functions/range.rst b/docs/functions/range.rst new file mode 100644 index 0000000..57448e0 --- /dev/null +++ b/docs/functions/range.rst @@ -0,0 +1,4 @@ +range +======= + +.. autofunction:: arrayfire.range \ No newline at end of file diff --git a/docs/functions/rank.rst b/docs/functions/rank.rst new file mode 100644 index 0000000..58ab15e --- /dev/null +++ b/docs/functions/rank.rst @@ -0,0 +1,4 @@ +rank +==== + +.. autofunction:: arrayfire_wrapper.lib.rank diff --git a/docs/functions/read_array.rst b/docs/functions/read_array.rst new file mode 100644 index 0000000..f3c6fce --- /dev/null +++ b/docs/functions/read_array.rst @@ -0,0 +1,8 @@ +read_array +========== + +When using with keys: +.. autofunction:: arrayfire_wrapper.lib.read_array_key + +When using with indices: +.. autofunction:: arrayfire_wrapper.lib.read_array_index diff --git a/docs/functions/real.rst b/docs/functions/real.rst new file mode 100644 index 0000000..3369b5a --- /dev/null +++ b/docs/functions/real.rst @@ -0,0 +1,4 @@ +real +==== + +.. autofunction:: arrayfire_wrapper.lib.real diff --git a/docs/functions/regions.rst b/docs/functions/regions.rst new file mode 100644 index 0000000..e42f466 --- /dev/null +++ b/docs/functions/regions.rst @@ -0,0 +1,4 @@ +regions +======= + +.. autofunction:: arrayfire_wrapper.lib.regions diff --git a/docs/functions/rem.rst b/docs/functions/rem.rst new file mode 100644 index 0000000..13bb279 --- /dev/null +++ b/docs/functions/rem.rst @@ -0,0 +1,4 @@ +rem +=== + +.. autofunction:: arrayfire_wrapper.lib.rem diff --git a/docs/functions/reorder.rst b/docs/functions/reorder.rst new file mode 100644 index 0000000..d51f9a8 --- /dev/null +++ b/docs/functions/reorder.rst @@ -0,0 +1,27 @@ +reorder +======= +The 'af.reorder()' function in ArrayFire is used to rearrange the dimensions of an array. This is useful for changing the order of dimensions to align with the requirements of different operations or to facilitate certain types of computations. + +Function +-------- +:literal:`af.reorder()` + - Python interface used to rearrange the dimensions of an array. + +Detailed Description +-------------------- +The 'af.reorder()' function changes the order of dimensions of the input array. It is often used in conjunction with other functions that require specific data layouts. Reordering dimensions can help optimize performance or compatibility with other libraries and tools. + +Function Documentation +---------------------- +.. sidebar:: af.reorder() + + Syntax: + af.reorder(array, \*order) + + Parameters: + 'array': The ArrayFire array whose dimensions are to be reordered. + '\*order': The new order of dimensions specified as a sequence of integers. Each integer represents the index of the dimension in the new order. + + Returns: + An ArrayFire array with the dimensions reordered according to the specified order. + diff --git a/docs/functions/replace.rst b/docs/functions/replace.rst new file mode 100644 index 0000000..1b3a2fd --- /dev/null +++ b/docs/functions/replace.rst @@ -0,0 +1,4 @@ +replace +======= + +.. autofunction:: arrayfire.replace diff --git a/docs/functions/reshape.rst b/docs/functions/reshape.rst new file mode 100644 index 0000000..8f9ec78 --- /dev/null +++ b/docs/functions/reshape.rst @@ -0,0 +1,25 @@ +reshape +======= +The 'af.reshape()' function in ArrayFire is used to change the shape of an array. This function allows you to rearrange the dimensions of an array while keeping the underlying data intact. It is particularly useful for preparing data for operations that require specific shapes or for transforming data between different formats. + +Function +-------- +:literal:`af.reshape()` + - Python interface used to change the shape of an array. + +Detailed Description +-------------------- +The 'af.reshape()' function changes the shape of an existing array to a new shape specified by the user. The total number of elements in the original array must match the total number of elements in the reshaped array. The function does not alter the data but reinterprets it under a new shape. + +Function Documentation +---------------------- +.. sidebar:: af.reshape() + + Syntax: + af.reshape(array,\*new_shape) + + Parameters: + 'array': The ArrayFire array to be reshaped. + '\*new_shape': The new shape for the array, specified as a sequence of integers. The product of these dimensions must equal the total number of elements in the original array. + Returns: + An ArrayFire array with the specified new shape. \ No newline at end of file diff --git a/docs/functions/resize.rst b/docs/functions/resize.rst new file mode 100644 index 0000000..bc9b7bd --- /dev/null +++ b/docs/functions/resize.rst @@ -0,0 +1,4 @@ +resize +====== + +.. autofunction:: arrayfire_wrapper.lib.resize diff --git a/docs/functions/rgb2gray.rst b/docs/functions/rgb2gray.rst new file mode 100644 index 0000000..3d48ab1 --- /dev/null +++ b/docs/functions/rgb2gray.rst @@ -0,0 +1,4 @@ +rgb2gray +======== + +.. autofunction:: arrayfire_wrapper.lib.rgb2gray diff --git a/docs/functions/rgb2hsv.rst b/docs/functions/rgb2hsv.rst new file mode 100644 index 0000000..7ef5061 --- /dev/null +++ b/docs/functions/rgb2hsv.rst @@ -0,0 +1,4 @@ +rgb2hsv +======= + +.. autofunction:: arrayfire_wrapper.lib.rgb2hsv diff --git a/docs/functions/rgb2ycbcr.rst b/docs/functions/rgb2ycbcr.rst new file mode 100644 index 0000000..4f33c04 --- /dev/null +++ b/docs/functions/rgb2ycbcr.rst @@ -0,0 +1,4 @@ +rgb2ycbcr +========= + +.. autofunction:: arrayfire_wrapper.lib.rgb2ycbcr diff --git a/docs/functions/root.rst b/docs/functions/root.rst new file mode 100644 index 0000000..d073378 --- /dev/null +++ b/docs/functions/root.rst @@ -0,0 +1,4 @@ +root +==== + +.. autofunction:: arrayfire_wrapper.lib.root diff --git a/docs/functions/rotate.rst b/docs/functions/rotate.rst new file mode 100644 index 0000000..8671fab --- /dev/null +++ b/docs/functions/rotate.rst @@ -0,0 +1,4 @@ +rotate +====== + +.. autofunction:: arrayfire_wrapper.lib.rotate diff --git a/docs/functions/round.rst b/docs/functions/round.rst new file mode 100644 index 0000000..cc28ad9 --- /dev/null +++ b/docs/functions/round.rst @@ -0,0 +1,4 @@ +round +===== + +.. autofunction:: arrayfire_wrapper.lib.round_ diff --git a/docs/functions/rsqrt.rst b/docs/functions/rsqrt.rst new file mode 100644 index 0000000..cc8d01e --- /dev/null +++ b/docs/functions/rsqrt.rst @@ -0,0 +1,4 @@ +rsqrt +===== + +.. autofunction:: arrayfire_wrapper.lib.rsqrt diff --git a/docs/functions/sat.rst b/docs/functions/sat.rst new file mode 100644 index 0000000..5851285 --- /dev/null +++ b/docs/functions/sat.rst @@ -0,0 +1,4 @@ +sat +=== + +.. autofunction:: arrayfire_wrapper.lib.sat diff --git a/docs/functions/save_array.rst b/docs/functions/save_array.rst new file mode 100644 index 0000000..4203a2c --- /dev/null +++ b/docs/functions/save_array.rst @@ -0,0 +1,4 @@ +save_array +========== + +.. autofunction:: arrayfire_wrapper.lib.save_array diff --git a/docs/functions/save_image.rst b/docs/functions/save_image.rst new file mode 100644 index 0000000..8a5e04b --- /dev/null +++ b/docs/functions/save_image.rst @@ -0,0 +1,4 @@ +save_image +========== + +.. autofunction:: arrayfire_wrapper.lib.save_image diff --git a/docs/functions/save_image_memory.rst b/docs/functions/save_image_memory.rst new file mode 100644 index 0000000..d5a9b77 --- /dev/null +++ b/docs/functions/save_image_memory.rst @@ -0,0 +1,4 @@ +save_image_memory +================= + +.. autofunction:: arrayfire_wrapper.lib.save_image_memory diff --git a/docs/functions/save_image_native.rst b/docs/functions/save_image_native.rst new file mode 100644 index 0000000..94489b6 --- /dev/null +++ b/docs/functions/save_image_native.rst @@ -0,0 +1,4 @@ +save_image_native +================= + +.. autofunction:: arrayfire_wrapper.lib.save_image_native diff --git a/docs/functions/scale.rst b/docs/functions/scale.rst new file mode 100644 index 0000000..f8837f0 --- /dev/null +++ b/docs/functions/scale.rst @@ -0,0 +1,4 @@ +scale +===== + +.. autofunction:: arrayfire_wrapper.lib.scale diff --git a/docs/functions/scan.rst b/docs/functions/scan.rst new file mode 100644 index 0000000..8e5070d --- /dev/null +++ b/docs/functions/scan.rst @@ -0,0 +1,4 @@ +scan +===== + +.. autofunction:: arrayfire.scan \ No newline at end of file diff --git a/docs/functions/select.rst b/docs/functions/select.rst new file mode 100644 index 0000000..86224b5 --- /dev/null +++ b/docs/functions/select.rst @@ -0,0 +1,4 @@ +select +====== + +.. autofunction:: arrayfire.select diff --git a/docs/functions/set_backend.rst b/docs/functions/set_backend.rst new file mode 100644 index 0000000..cfe3e49 --- /dev/null +++ b/docs/functions/set_backend.rst @@ -0,0 +1,26 @@ +set_backend +=========== +The 'af.set_backend()' function in ArrayFire is used to specify which backend will be used for subsequent ArrayFire operations. This is useful when working with multiple devices or GPUs to ensure that computations are directed to the desired hardware and software libraries. + +Function +-------- +:literal:`af.set_backend()` + - Python interface used to specify which backend will be used for subsequent arrayfire operations. + +Detailed Description +-------------------- +The 'af.set_backend()' function sets the backend for ArrayFire operations. By default, ArrayFire uses the first available backend in order of priority: 'cuda', 'opencl', 'oneapi', 'cpu' from highest to lowest priority. When you have multiple GPUs or devices, you can use this function to select which backend ArrayFire should use for subsequent operations. +Note that previous instantiated af.Array's or results from functions before the backend has been set will not be migrated to the new backend and device. + +Function Documentation +---------------------- +.. sidebar:: af.set_backend() + + Syntax: + af.set_backend(backend) + + Parameters: + 'backend': af.BackendType value that corresponds to the ArrayFire backend to be set. Available values are af.BackendType.cuda, af.BackendType.opencl, af.BackendType.oneapi, and af.BackendType.cpu + + Returns: + None diff --git a/docs/functions/set_device.rst b/docs/functions/set_device.rst new file mode 100644 index 0000000..de199c0 --- /dev/null +++ b/docs/functions/set_device.rst @@ -0,0 +1,4 @@ +set_device +========== + +.. autofunction:: arrayfire_wrapper.lib.set_device diff --git a/docs/functions/set_fft_plan_cache_size.rst b/docs/functions/set_fft_plan_cache_size.rst new file mode 100644 index 0000000..3ddf2a6 --- /dev/null +++ b/docs/functions/set_fft_plan_cache_size.rst @@ -0,0 +1,4 @@ +set_fft_plan_cache_size +======================= + +.. autofunction:: arrayfire_wrapper.lib.set_fft_plan_cache_size diff --git a/docs/functions/set_intersect.rst b/docs/functions/set_intersect.rst new file mode 100644 index 0000000..da03b64 --- /dev/null +++ b/docs/functions/set_intersect.rst @@ -0,0 +1,4 @@ +set_intersect +============== + +.. autofunction:: arrayfire.set_intersect \ No newline at end of file diff --git a/docs/functions/set_kernel_cache_directory.rst b/docs/functions/set_kernel_cache_directory.rst new file mode 100644 index 0000000..0263993 --- /dev/null +++ b/docs/functions/set_kernel_cache_directory.rst @@ -0,0 +1,4 @@ +set_kernel_cache_directory +========================== + +.. autofunction:: arrayfire_wrapper.lib.set_kernel_cache_directory diff --git a/docs/functions/set_mem_step_size.rst b/docs/functions/set_mem_step_size.rst new file mode 100644 index 0000000..e6d1009 --- /dev/null +++ b/docs/functions/set_mem_step_size.rst @@ -0,0 +1,4 @@ +set_mem_step_size +================= + +.. autofunction:: arrayfire_wrapper.lib.set_mem_step_size diff --git a/docs/functions/set_native_id.rst b/docs/functions/set_native_id.rst new file mode 100644 index 0000000..0aa9a3f --- /dev/null +++ b/docs/functions/set_native_id.rst @@ -0,0 +1,4 @@ +set_native_id +============= + +.. autofunction:: arrayfire_wrapper.lib.set_native_id diff --git a/docs/functions/set_union.rst b/docs/functions/set_union.rst new file mode 100644 index 0000000..21fc129 --- /dev/null +++ b/docs/functions/set_union.rst @@ -0,0 +1,4 @@ +set_union +========= + +.. autofunction:: arrayfire.set_union \ No newline at end of file diff --git a/docs/functions/set_unique.rst b/docs/functions/set_unique.rst new file mode 100644 index 0000000..d1b72e6 --- /dev/null +++ b/docs/functions/set_unique.rst @@ -0,0 +1,4 @@ +set_unique +========== + +.. autofunction:: arrayfire.set_unique \ No newline at end of file diff --git a/docs/functions/shift.rst b/docs/functions/shift.rst new file mode 100644 index 0000000..d2ee410 --- /dev/null +++ b/docs/functions/shift.rst @@ -0,0 +1,4 @@ +shift +===== + +.. autofunction:: arrayfire.shift diff --git a/docs/functions/sift.rst b/docs/functions/sift.rst new file mode 100644 index 0000000..9f6ab86 --- /dev/null +++ b/docs/functions/sift.rst @@ -0,0 +1,4 @@ +sift +==== + +.. autofunction:: arrayfire.sift \ No newline at end of file diff --git a/docs/functions/sign.rst b/docs/functions/sign.rst new file mode 100644 index 0000000..217a041 --- /dev/null +++ b/docs/functions/sign.rst @@ -0,0 +1,4 @@ +sign +==== + +.. autofunction:: arrayfire_wrapper.lib.sign diff --git a/docs/functions/sin.rst b/docs/functions/sin.rst new file mode 100644 index 0000000..6d16d7d --- /dev/null +++ b/docs/functions/sin.rst @@ -0,0 +1,4 @@ +sin +=== + +.. autofunction:: arrayfire_wrapper.lib.sin diff --git a/docs/functions/sinh.rst b/docs/functions/sinh.rst new file mode 100644 index 0000000..ee4170c --- /dev/null +++ b/docs/functions/sinh.rst @@ -0,0 +1,4 @@ +sinh +==== + +.. autofunction:: arrayfire_wrapper.lib.sinh diff --git a/docs/functions/skew.rst b/docs/functions/skew.rst new file mode 100644 index 0000000..079d161 --- /dev/null +++ b/docs/functions/skew.rst @@ -0,0 +1,4 @@ +skew +==== + +.. autofunction:: arrayfire_wrapper.lib.skew diff --git a/docs/functions/sobel_operator.rst b/docs/functions/sobel_operator.rst new file mode 100644 index 0000000..561ed51 --- /dev/null +++ b/docs/functions/sobel_operator.rst @@ -0,0 +1,4 @@ +sobel_operator +============== + +.. autofunction:: arrayfire_wrapper.lib.sobel_operator diff --git a/docs/functions/solve.rst b/docs/functions/solve.rst new file mode 100644 index 0000000..e2e8999 --- /dev/null +++ b/docs/functions/solve.rst @@ -0,0 +1,4 @@ +solve +===== + +.. autofunction:: arrayfire_wrapper.lib.solve diff --git a/docs/functions/sort.rst b/docs/functions/sort.rst new file mode 100644 index 0000000..3860c0b --- /dev/null +++ b/docs/functions/sort.rst @@ -0,0 +1,4 @@ +sort +===== + +.. autofunction:: arrayfire.sort \ No newline at end of file diff --git a/docs/functions/sqrt.rst b/docs/functions/sqrt.rst new file mode 100644 index 0000000..4fb397f --- /dev/null +++ b/docs/functions/sqrt.rst @@ -0,0 +1,25 @@ +sqrt +==== +The 'af.sqrt()' function in ArrayFire is used to compute the square root of each element in an array. This is a common mathematical operation used in various computational tasks, including normalization, scaling, and feature extraction. + +Function +-------- +:literal:`af.sqrt()` + - Python interface used to compute the square root of each element in an array. + +Detailed Description +-------------------- +The 'af.sqrt()' function calculates the square root of every element in the input array. The result is an array of the same shape, where each element is the square root of the corresponding element in the input array. + +Function Documentation +---------------------- +.. sidebar:: af.sqrt() + + Syntax: + af.sqrt(array) + + Parameters: + 'array': The ArrayFire array for which the square root will be computed. + + Returns: + An ArrayFire array where each element is the square root of the corresponding element in the input array. diff --git a/docs/functions/sttdev.rst b/docs/functions/sttdev.rst new file mode 100644 index 0000000..11fb80e --- /dev/null +++ b/docs/functions/sttdev.rst @@ -0,0 +1,26 @@ +stdev +===== +The 'af.stdev()' function in ArrayFire computes the standard deviation of elements in an array. The standard deviation is a measure of the amount of variation or dispersion in a set of values. This function can compute the standard deviation across all elements or along a specified dimension of the array. + +Function +-------- +:literal:`af.stdev()` + - Python interface used to compute the standard deviation of elements in an array. + +Detailed Description +-------------------- +The 'af.stdev()' function calculates the standard deviation of the values in an array. It can operate over all elements of the array or along a specified dimension. This function helps in understanding the spread or variability of data points. + +Function Documentation +---------------------- +.. sidebar:: af.stdev() + + Syntax: + af.stdev(array) + + + Parameters: + 'array': The ArrayFire array for which the standard deviation will be computed. + + Returns: + An ArrayFire array containing the computed standard deviation. diff --git a/docs/functions/sub.rst b/docs/functions/sub.rst new file mode 100644 index 0000000..a43c7bc --- /dev/null +++ b/docs/functions/sub.rst @@ -0,0 +1,4 @@ +sub +=== + +.. autofunction:: arrayfire_wrapper.lib.sub diff --git a/docs/functions/sum.rst b/docs/functions/sum.rst new file mode 100644 index 0000000..13407e5 --- /dev/null +++ b/docs/functions/sum.rst @@ -0,0 +1,26 @@ +sum +=== +The 'af.sum()' function in ArrayFire computes the sum of the elements in an array. This function can perform the summation over all elements or along a specified dimension. It is useful for aggregating data, calculating totals, and summarizing results in numerical computations. + +Function +-------- +:literal:`af.sum()` + - Python interface used to compute the sum of the elements in an array. + +Detailed Description +-------------------- +The 'af.sum()' function calculates the sum of array elements. You can choose to compute the sum across all elements of the array or along a specific dimension. This function supports both reducing the array to a single value and computing sums along specified axes. + +Function Documentation +---------------------- +.. sidebar:: af.sum() + + Syntax: + af.sum(array) + + Parameters: + 'array': The ArrayFire array for which the sum will be computed. + 'dim': An optional integer specifying the dimension along which to compute the sum. By default, it is set to 0, which means the function will sum along the first dimension. + + Returns: + An ArrayFire array containing the sum of the elements. diff --git a/docs/functions/susan.rst b/docs/functions/susan.rst new file mode 100644 index 0000000..f1b5303 --- /dev/null +++ b/docs/functions/susan.rst @@ -0,0 +1,4 @@ +susan +===== + +.. autofunction:: arrayfire.susan \ No newline at end of file diff --git a/docs/functions/svd.rst b/docs/functions/svd.rst new file mode 100644 index 0000000..1b19f90 --- /dev/null +++ b/docs/functions/svd.rst @@ -0,0 +1,4 @@ +svd +==== + +.. autofunction:: arrayfire_wrapper.lib.svd \ No newline at end of file diff --git a/docs/functions/sync.rst b/docs/functions/sync.rst new file mode 100644 index 0000000..59462ba --- /dev/null +++ b/docs/functions/sync.rst @@ -0,0 +1,4 @@ +sync +======== + +.. autofunction:: arrayfire.sync \ No newline at end of file diff --git a/docs/functions/tan.rst b/docs/functions/tan.rst new file mode 100644 index 0000000..c12a06f --- /dev/null +++ b/docs/functions/tan.rst @@ -0,0 +1,4 @@ +tan +=== + +.. autofunction:: arrayfire_wrapper.lib.tan diff --git a/docs/functions/tanh.rst b/docs/functions/tanh.rst new file mode 100644 index 0000000..f6fa790 --- /dev/null +++ b/docs/functions/tanh.rst @@ -0,0 +1,4 @@ +tanh +==== + +.. autofunction:: arrayfire_wrapper.lib.tanh diff --git a/docs/functions/tgamma.rst b/docs/functions/tgamma.rst new file mode 100644 index 0000000..8ef337c --- /dev/null +++ b/docs/functions/tgamma.rst @@ -0,0 +1,4 @@ +tgamma +====== + +.. autofunction:: arrayfire_wrapper.lib.tgamma diff --git a/docs/functions/tile.rst b/docs/functions/tile.rst new file mode 100644 index 0000000..ca8abca --- /dev/null +++ b/docs/functions/tile.rst @@ -0,0 +1,4 @@ +tile +==== + +.. autofunction:: arrayfire.tile diff --git a/docs/functions/transform.rst b/docs/functions/transform.rst new file mode 100644 index 0000000..c30247b --- /dev/null +++ b/docs/functions/transform.rst @@ -0,0 +1,4 @@ +transform +========= + +.. autofunction:: arrayfire_wrapper.lib.transform diff --git a/docs/functions/transform_coordinates.rst b/docs/functions/transform_coordinates.rst new file mode 100644 index 0000000..05e61cf --- /dev/null +++ b/docs/functions/transform_coordinates.rst @@ -0,0 +1,4 @@ +transform_coordinates +===================== + +.. autofunction:: arrayfire_wrapper.lib.transform_coordinates diff --git a/docs/functions/translate.rst b/docs/functions/translate.rst new file mode 100644 index 0000000..a16cda7 --- /dev/null +++ b/docs/functions/translate.rst @@ -0,0 +1,4 @@ +translate +========= + +.. autofunction:: arrayfire_wrapper.lib.translate diff --git a/docs/functions/transpose.rst b/docs/functions/transpose.rst new file mode 100644 index 0000000..5f41466 --- /dev/null +++ b/docs/functions/transpose.rst @@ -0,0 +1,27 @@ +transpose +========= +The 'af.transpose()' function in ArrayFire is used to compute the transpose of a matrix or higher-dimensional array. Transposing a matrix involves swapping its rows and columns. This function is fundamental in linear algebra operations and many computational tasks. + +Function +-------- +:literal:`af.transpose()` + - Python interface used to compute the transpose of a matrix or higher-dimensional array. + +Detailed Description +-------------------- +The 'af.transpose()' function computes the transpose of a given array. For 2D matrices, this means converting rows into columns and columns into rows. For higher-dimensional arrays, the function permutes dimensions according to the specified order. + +Function Documentation +---------------------- +.. sidebar:: af.transpose() + + Syntax: + af.transpose(array, \*permutation) + + Parameters: + 'array': The ArrayFire array to be transposed. + '\*permutation': An optional sequence of integers specifying the new order of dimensions. If not provided, the function defaults to transposing the last two dimensions. + + Returns: + An ArrayFire array that is the transpose of the input array, with dimensions permuted according to the provided permutation. + diff --git a/docs/functions/trunc.rst b/docs/functions/trunc.rst new file mode 100644 index 0000000..783ba23 --- /dev/null +++ b/docs/functions/trunc.rst @@ -0,0 +1,4 @@ +trunc +===== + +.. autofunction:: arrayfire_wrapper.lib.trunc diff --git a/docs/functions/unwrap.rst b/docs/functions/unwrap.rst new file mode 100644 index 0000000..10789f9 --- /dev/null +++ b/docs/functions/unwrap.rst @@ -0,0 +1,4 @@ +unwrap +====== + +.. autofunction:: arrayfire_wrapper.lib.unwrap diff --git a/docs/functions/upper.rst b/docs/functions/upper.rst new file mode 100644 index 0000000..7e8ebc3 --- /dev/null +++ b/docs/functions/upper.rst @@ -0,0 +1,4 @@ +upper +===== + +.. autofunction:: arrayfire.upper \ No newline at end of file diff --git a/docs/functions/where.rst b/docs/functions/where.rst new file mode 100644 index 0000000..45614a0 --- /dev/null +++ b/docs/functions/where.rst @@ -0,0 +1,4 @@ +where +======= + +.. autofunction:: arrayfire.where \ No newline at end of file diff --git a/docs/functions/wrap.rst b/docs/functions/wrap.rst new file mode 100644 index 0000000..e66a277 --- /dev/null +++ b/docs/functions/wrap.rst @@ -0,0 +1,4 @@ +wrap +==== + +.. autofunction:: arrayfire_wrapper.lib.wrap diff --git a/docs/functions/zeros.rst b/docs/functions/zeros.rst new file mode 100644 index 0000000..90ead5f --- /dev/null +++ b/docs/functions/zeros.rst @@ -0,0 +1,28 @@ +zeros +===== +The 'af.zeros()' function in the ArrayFire library is used to create arrays filled with zeros. This is a common operation when initializing arrays that will be updated or manipulated later in numerical computations. The function allows you to specify the dimensions and data type of the array, making it flexible for various use cases. + +Function +-------- +:literal:`af.zeros()` + - Python interface to create array filled with zeros. + +Detailed Description +-------------------- +The 'af.zeros()' function creates an ArrayFire array where every element is initialized to zero. It is particularly useful when you need to allocate space for an array but want to ensure that all values start from zero. This is often used in numerical methods, data processing, and initialization of variables in scientific computing. + +You can specify the dimensions of the array as well as its data type. By default, the function creates arrays with a single precision floating-point type (float), but you can specify other data types if needed. + +Function Documentation +---------------------- +.. sidebar:: af.zero() + + Syntax: + af.zeros(dim0, dim1) + + Parameters: + 'dim0, dim1': Integers representing the dimensions of the array. You can specify multiple dimensions to create multi-dimensional arrays. For example, dim0 is the number of rows, and dim1 is the number of columns for a 2D array. + Returns: + An ArrayFire array with the specified dimensions and data type, where all elements are initialized to zero. + + diff --git a/docs/gettingstarted.py b/docs/gettingstarted.py new file mode 100644 index 0000000..7d6a092 --- /dev/null +++ b/docs/gettingstarted.py @@ -0,0 +1,275 @@ + +# [gettingstarted1-snippet] +# Arrays may be created using the array constructor and dimensioned +# as 1D, 2D, 3D; however, the values in these arrays will be undefined +import arrayfire as af + +array = af.constant(0,(100,)) +array_2d = af.constant(0, (10, 100)) +array_3d = af.constant(0, (10, 10, 10)) +# [gettingstarted1-endsnippet] + + + +# [gettingstarted2-snippet] +import arrayfire as af + +# Generate an array of size three filled with zeros. +# If no data type is specified, ArrayFire defaults to f32. +# The constant function generates the data on the device. +zeroes = af.constant(0,(3,)) + +# Generate a 1x4 array of uniformly distributed [0,1] random numbers +# The randu function generates the data on the device. +rand1 = af.randu((1,4)) + +# Generate a 2x2 array (or matrix, if you prefer) of random numbers +# sampled from a normal distribution. +# The randn function generates data on the device. +rand2 = af.randu((2,2)) + +# Generate a 3x3 identity matrix. The data is generated on the device. +iden = af.identity((3,3)) + +# Lastly, create a 2x1 array (column vector) of uniformly distributed +# 32-bit complex numbers (c32 data type): +randcplx = af.randu((2,1)) +# [gettingstarted2-endsnippet] + + +# [gettingstarted3-snippet] +import arrayfire as af +# Create a six-element array on the host +hA = ([0, 1, 2, 3, 4, 5]) + +# Which can be copied into an ArrayFire Array using the pointer copy +# constructor. Here we copy the data into a 2x3 matrix: +A = af.moddims(af.Array(hA),(2,3)) + + +# ArrayFire provides a convenince function for printing array +# objects in case you wish to see how the data is stored: +print(A) + +#todo how to create complex numbers +# [gettingstarted3-endsnippet] + + + +# [gettingstarted4-snippet] + +import arrayfire as af +import pycuda.driver as cuda +import numpy as np + +# Create an array on the host +host_ptr = af.Array([0, 1, 2, 3, 4, 5]) + + +# Create an ArrayFire array 'a' from host_ptr (2x3 matrix) +A = af.moddims(host_ptr,(2,3)) + +# Allocate CUDA device memory and copy data from host to device +device_ptr = cuda.mem_alloc(host_ptr.nbytes) +cuda.memcpy_htod(device_ptr, host_ptr) + +# Create an ArrayFire array 'b' from CUDA-allocated device memory (2x3 matrix) +b = af.Array(device_ptr, dims=(2, 3), is_device=True) + +# Note: ArrayFire takes ownership of `device_ptr`, so no need to free it manually + +# Clean up CUDA resources (not necessary due to Python's automatic memory management) +# cuda.mem_free(device_ptr) +# [gettingstarted4-endsnippet] + + + +# [gettingstarted5-snippet] + +import arrayfire as af + +# Generate two arrays +a= af.randu((2,2)) # Create a 2x2 array with random numbers between [0, 1] +b = af.constant(1,(2,1)) # Create a 2x1 array filled with constant value 1 + +# Print arrays 'a' and 'b' to the console +print("Array 'a':", a) + +print("Array 'b':",b) + +# Print the results of an expression involving arrays +result = a.col(0) + b + 0.4 # Perform operation: first column of 'a' + 'b' + 0.4 +print("Result of expression (a.col(0) + b + 0.4):") +print(result) +# [gettingstarted5-endsnippet] + + +# [gettingstarted6-snippet] + +import arrayfire as af + +# Create a 4x5x2 array of uniformly distributed random numbers +a = af.randu((4,5,2)) + +# Determine the number of dimensions using the `numdims()` function +print("numdims(a):", a.numdims()) # Print the number of dimensions (should be 3) + +# Print the size of the individual dimensions using the `dims()` function +print("dims =", a.dims()) # Print dimensions as a tuple (4, 5, 2) + +# Alternatively, access dimensions using a dim4 object +dims = a.dims() +print("dims =", dims[0], dims[1]) # Print dimensions separately (4, 5) +# [gettingstarted6-endsnippet] + + +# [gettingstarted7-snippet] + +import arrayfire as af + +# Create an example ArrayFire array 'a' +a = af.randu((4, 5)) # Example array of dtype float32 + +# Get the type stored in the array +print("underlying type:", a.type()) + +# Check if the array contains complex or real values +print("is complex?", a.iscomplex(), " is real?", a.isreal()) + +# Check if the array is a vector, column vector, or row vector +print("is vector?", a.isvector(), " column?", a.iscolumn(), " row?", a.isrow()) + +# Check if the array is empty, and determine its total elements and memory usage +print("empty?", a.isempty(), " total elements:", a.elements(), " bytes:", a.bytes()) +# [gettingstarted7-endsnippet] + + +# [gettingstarted8-snippet] + +import arrayfire as af + +# Generate a 3x3 array of uniformly distributed random numbers +R = af.randu((3, 3)) +print(af.constant(1,( 3, 3)) + af.join(af.sin(R))) # will be c32 + +# Rescale complex values to unit circle +a = af.randn(5) +print(a / af.abs(a)) + +# Calculate L2 norm of vectors +X = af.randn((3, 4)) +print(af.sqrt(af.sum(af.pow(X, 2)))) # norm of every column vector +print(af.sqrt(af.sum(af.pow(X, 2), 0))) # same as above +print(af.sqrt(af.sum(af.pow(X, 2), 1))) # norm of every row vector + +# [gettingstarted8-endsnippet] + + +# [gettingstarted9-snippet] + +import arrayfire as af +import math + +# Generate a 5x5 array of uniformly distributed random numbers +A = af.randu((5, 5)) + +# Set elements in A greater than 0.5 to NaN +A[af.where(A > 0.5)] = af.NaN + +# Generate arrays x and y with 10 million random numbers each +x = af.randu(int(10e6)) +y = af.randu(int(10e6)) + +# Estimate Pi using Monte Carlo method +pi_est = 4 * af.sum(af.hypot(x, y) < 1) / 10e6 + +# Print the estimation error compared to math.pi +print("estimation error:", abs(math.pi - pi_est)) +# [gettingstarted9-endsnippet] + + + +# [gettingstarted10-snippet] + +import arrayfire as af + +# Create an array consisting of 3 random numbers of type f32 (float) +a = af.randu(3) + +# Copy array data from device to host +host_a = a.host_ptr() # Get host pointer +print("host_a[2] =", host_a[2]) # Access host data as a normal array +a.unlock() # Unlock array to allow garbage collection if necessary + +# Access device memory for CUDA kernel +d_cuda = a.device_ptr() # Get device pointer (no need to free) +value = af.sum(d_cuda[2]) # Access device memory data +print("d_cuda[2] =", value) + +# For OpenCL, accessing memory is similar but with a different syntax +# Note: ArrayFire handles these details internally, no explicit OpenCL handling in Python + +# No need to free pointers in ArrayFire Python interface as memory management is automatic +# [gettingstarted10-endsnippet] + + +# [gettingstarted11-snippet] + +import arrayfire as af + +# Create an array consisting of 3 random numbers +a = af.randu(3) + +# Get the scalar value of the array +val = a.scalar() + +# Print the scalar value +print(f"scalar value: {val}") +# [gettingstarted11-endsnippet] + + +# [gettingstarted12-snippet] + +import arrayfire as af + +# Define host arrays +h_A = ([1, 1, 0, 0, 4, 0, 0, 2, 0]) +h_B = ([1, 0, 1, 0, 1, 0, 1, 1, 1]) + +# Create ArrayFire arrays A and B from host arrays +A = af.Array(h_A, dims=(3, 3)) +B = af.Array(h_B, dims=(3, 3)) + +# Print arrays A and B +print(A) +print(B) + +# Perform bitwise operations +A_and_B = A & B +A_or_B = A | B +A_xor_B = A ^ B + +# Print results of bitwise operations +print(A_and_B) +print(A_or_B) +print(A_xor_B) +# [gettingstarted12-endsnippet] + + + +# [gettingstarted13-snippet] + +import arrayfire as af + +def main(): + # Generate random values + a = af.randu(10000, dtype=af.Dtype.f32) + + # Sum all the values + result = af.sum(a) + print(f"sum: {result}\n") + + +# [gettingstarted13-endsnippet] + + diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst new file mode 100644 index 0000000..f199f6b --- /dev/null +++ b/docs/gettingstarted.rst @@ -0,0 +1,162 @@ +Getting Started +=============== + +Introduction +************ + +ArrayFire is a high performance software library for parallel computing with an easy-to-use API. ArrayFire abstracts away much of the details of programming parallel architectures by providing a high-level container object, the array, that represents data stored on a CPU, GPU, FPGA, or other type of accelerator. This abstraction permits developers to write massively parallel applications in a high-level language where they need not be concerned about low-level optimizations that are frequently required to achieve high throughput on most parallel architectures. + +:doc:`Supported data types ` +********************************************** + +ArrayFire provides one generic container object, the array on which functions and mathematical operations are performed. The :literal:`array` can represent one of many different basic data types: + +* f32 real single-precision (:literal:`float`) +* c32 complex single-precision (:literal:`cfloat`) +* f64 real double-precision (:literal:`double`) +* c64 complex double-precision (:literal:`cdouble`) +* f16 real half-precision (:literal:`half_float::half`) +* b8 8-bit boolean values (:literal:`bool`) +* s32 32-bit signed integer (:literal:`int`) +* u32 32-bit unsigned integer (:literal:`unsigned`) +* u8 8-bit unsigned values (:literal:`unsigned char`) +* s64 64-bit signed integer (:literal:`intl`) +* u64 64-bit unsigned integer (:literal:`uintl`) +* s16 16-bit signed integer (:literal:`short`) +* u16 16-bit unsigned integer (:literal:`unsigned short`) + +Most of these data types are supported on all modern GPUs; however, some older devices may lack support for double precision arrays. In this case, a runtime error will be generated when the array is constructed. + +If not specified otherwise, :literal:`array`s are created as single precision floating point numbers (:literal:`f32`). + +Creating and populating an ArrayFire array +****************************************** + +ArrayFire arrays represent memory stored on the device. As such, creation and population of an array will consume memory on the device which cannot freed until the :literal:`array` object goes out of scope. As device memory allocation can be expensive, ArrayFire also includes a memory manager which will re-use device memory whenever possible. + +Arrays can be created using one of the array constructors. Below we show how to create 1D, 2D, and 3D arrays with uninitialized values: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted1-snippet] + :end-before: [gettingstarted1-endsnippet] + + + +However, uninitialized memory is likely not useful in your application. ArrayFire provides several convenient functions for creating arrays that contain pre-populated values including constants, uniform random numbers, uniform normally distributed numbers, and the identity matrix: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted2-snippet] + :end-before: [gettingstarted2-endsnippet] + + +A complete list of ArrayFire functions that automatically generate data on the device may be found on the functions to create arrays page. As stated above, the default data type for arrays is f32 (a 32-bit floating point number) unless specified otherwise. + +ArrayFire arrays may also be populated from data found on the host. For example: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted3-snippet] + :end-before: [gettingstarted3-endsnippet] + +ArrayFire also supports array initialization from memory already on the GPU. For example, with CUDA one can populate an :literal:`array` directly using a call to :literal:`cudaMemcpy`: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted4-snippet] + :end-before: [gettingstarted4-endsnippet] + +Similar functionality exists for OpenCL too. If you wish to intermingle ArrayFire with CUDA or OpenCL code, we suggest you consult the CUDA interoperability or OpenCL interoperability pages for detailed instructions. + +ArrayFire array contents, dimensions, and properties +**************************************************** + +ArrayFire provides several functions to determine various aspects of arrays. This includes functions to print the contents, query the dimensions, and determine various other aspects of arrays. + +The print function can be used to print arrays that have already been generated or any expression involving arrays: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted5-snippet] + :end-before: [gettingstarted5-endsnippet] + +The dimensions of an array may be determined using either a dim4 object or by accessing the dimensions directly using the dims() and numdims() functions: + + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted6-snippet] + :end-before: [gettingstarted6-endsnippet] + + + +In addition to dimensions, arrays also carry several properties including methods to determine the underlying type and size (in bytes). You can even determine whether the array is empty, real/complex, a row/column, or a scalar or a vector: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted7-snippet] + :end-before: [gettingstarted7-endsnippet] + +For further information on these capabilities, we suggest you consult the full documentation on the array. + + +Writing mathematical expressions in ArrayFire +********************************************* + +ArrayFire leverages an advanced Just-In-Time (JIT) compilation engine that optimizes array operations by minimizing the number of CUDA/OpenCL kernels used. In Python, ArrayFire functions operate similarly to a vector library. This means that typical element-wise operations, such as :literal:`c[i] = a[i] + b[i]` in C, can be expressed more succinctly as :literal:`c = a + b`, eliminating the need for explicit indexing. + +When multiple array operations are involved, ArrayFire's JIT engine consolidates them through "kernel fusion". This technique not only reduces the frequency of kernel invocations but also optimizes memory usage by eliminating redundant global memory operations. The JIT functionality extends seamlessly across Python function boundaries, continuing until a non-JIT function is encountered or a synchronization operation is explicitly invoked in the code. + +ArrayFire provides a broad spectrum of functions tailored for element-wise operations. It supports standard arithmetic operators (+, \-, \*, /) as well as a variety of transcendental functions (sin, cos, log, sqrt, etc.). These capabilities empower users to perform complex computations efficiently and effectively. + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted8-snippet] + :end-before: [gettingstarted8-endsnippet] + +To see the complete list of functions please consult the documentation on mathematical, linear algebra, signal processing, and statistics. + +Mathematical constants +********************** + +In Python, ArrayFire provides several platform-independent constants such as Pi, NaN, and Inf. If ArrayFire lacks a specific constant you require, you can create it using the `af.constant` array constructor. + +These constants are universally applicable across all ArrayFire functions. Below, we illustrate their usage in element selection and a mathematical expression: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted9-snippet] + :end-before: [gettingstarted9-endsnippet] + +Please note that our constants may, at times, conflict with macro definitions in standard header files. When this occurs, please refer to our constants using the :literal:`af::` namespace. + +Indexing +******** +Like all functions in ArrayFire, indexing is also executed in parallel on the OpenCL/CUDA devices. Because of this, indexing becomes part of a JIT operation and is accomplished using parentheses instead of square brackets (i.e. as :literal:`A(0)` instead of :literal:`A[0]`). To index :literal:`af::` arrays you may use one or a combination of the following functions: + +* integer scalars +* :literal:`:` representing the entire description +* :literal:`begin:end:step` representing a linear sequence/slice +* :literal:`row(i)` or :literal:`col(i)` specifying a single row/column +* :literal:`rows(first,last)` or :literal:`cols(first,last)` specifying a span of rows or columns + +Please see the indexing page for several examples of how to use these functions. + + +Bitwise operators +***************** +In addition to supporting standard mathematical functions, arrays that contain integer data types also support bitwise operators including and, or, and shift: + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted12-snippet] + :end-before: [gettingstarted12-endsnippet] + +Sample using Python API +~~~~~~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: gettingstarted.py + :language: python + :start-after: [gettingstarted13-snippet] + :end-before: [gettingstarted13-endsnippet] diff --git a/docs/images/afjit_benchmark.png b/docs/images/afjit_benchmark.png new file mode 100644 index 0000000..5529862 Binary files /dev/null and b/docs/images/afjit_benchmark.png differ diff --git a/docs/images/arrayfire_icon.png b/docs/images/arrayfire_icon.png new file mode 100644 index 0000000..a973878 Binary files /dev/null and b/docs/images/arrayfire_icon.png differ diff --git a/docs/images/arrayfire_logo.png b/docs/images/arrayfire_logo.png new file mode 100644 index 0000000..e3368db Binary files /dev/null and b/docs/images/arrayfire_logo.png differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..dfbb295 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,45 @@ +.. image:: images/arrayfire_logo.png + :alt: ArrayFire Logo + :align: center + :class: responsive-img + +Welcome to ArrayFire's documentation! +===================================== + +.. toctree:: + :maxdepth: 1 + :caption: The Basics + + overview + tutorial + installation + gettingstarted + +.. toctree:: + :maxdepth: 1 + :caption: User Guide + + configuringarrayfireenvironment + introductiontovectorization + arrayfirejitcodegeneration + arrayandmatrixmanipulation + indexing + timing_arrayfire + debuggingarrayfirecode + +.. toctree:: + :maxdepth: 1 + :caption: Reference + + functions + examples + genindex + releasenotes + product_support + license + + + + + + diff --git a/docs/indexing.py b/docs/indexing.py new file mode 100644 index 0000000..e5d2364 --- /dev/null +++ b/docs/indexing.py @@ -0,0 +1,129 @@ +# [indexing1-snippet] + +import arrayfire as af + +data = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] + +A = af.Array(data) +A = af.moddims(A,(4,4)) + +# [indexing1-endsnippet] + + +# [indexing2-snippet] + +A[0,0] #Returns an array pointing to the first element + + +A[2,3] #WARN: avoid doing this. Demo only +# [indexing2-endsnippet] + + +# [indexing3-snippet] + +ref0 = A[2,-1] # 14 second row last column +ref1 = A[2,-2] # 10 Second row, second to last(third) column +# [indexing3-endsnippet] + + +# [indexing4-snippet] + +#Returns an array pointing to the third column +A[:,2] +# [indexing4-endsnippet] + + + +# [indexing5-snippet] + +#Returns an array pointing to the second row +A[1, :] +# [indexing5-endsnippet] + + + +# [indexing6-snippet] + + #Returns an array pointing to the first two columns +A[:, 0:2] + +# [indexing6-endsnippet] + + +# [indexing7-snippet] + +reference = A[:, 1] +reference2 = A[0:3, 1] +reference3 = A[0:2, :] +# [indexing7-endsnippet] + + +# [indexing8-snippet] + +copy = A[2, :] +copy2 = A[1:3:2, :] + +hidx = [0, 1, 2] +idx = af.Array(hidx) +copy3 = A[idx, :] + +# [indexing8-endsnippet] + + +# [indexing9-snippet] + +inputA = af.constant(3,(10,10)) +inputB = af.constant(2,(10,10)) +data = af.constant(1,(10,10)) + +#Points to the second column of data. Does not allocate memory +ref = data[:,1] + +# This call does NOT update data. Memory allocated in matmul +ref = af.matmul(inputA, inputB) +# reference does not point to the same memory as the data array + +# [indexing9-endsnippet] + + +# [indexing10-snippet] + +reference = A[:, 2] + +A[:, 2] = 3.14 +# [indexing10-endsnippet] + + +# [indexing11-snippet] + +ref = A[:, 2] + +A[:, 2] = 3.14 +# [indexing11-endsnippet] + + +# [indexing12-snippet] + +hidx = [4, 3, 4, 0] +hvals = [9.0, 8.0, 7.0, 6.0] + +idx = af.Array(hidx) +vals = af.Array(hvals) +# [indexing12-endsnippet] + + +# [indexing13-snippet] + +A = af.Array[1,2,3,4,5,6,7,8,9] +A = af.moddims(A,(3,3)) +# 1.0000 4.0000 7.0000 +# 2.0000 5.0000 8.0000 +# 3.0000 6.0000 9.0000 + +print(A[0,0]) # first element +# 1.0000 + +print(A[0,1]) # first row, second column +# 4.0000 +# [indexing13-endsnippet] + diff --git a/docs/indexing.rst b/docs/indexing.rst new file mode 100644 index 0000000..dd0ca61 --- /dev/null +++ b/docs/indexing.rst @@ -0,0 +1,233 @@ +Indexing +======== +Indexing in ArrayFire is a powerful but easy to abuse feature of the af.Array class. This feature allows you to reference or copy subsections of a larger array and perform operations on only a subset of elements. + +Indexing in ArrayFire can be performed using the parenthesis operator or one of the member functions of the af::array class. These functions allow you to reference one or a range of elements from the original array. + +Here we will demonstrate some of the ways you can use indexing in ArrayFire and discuss ways to minimize the memory and performance impact of these operations. + +Lets start by creating a new 4x4 matrix of floating point numbers: + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing1-snippet] + :end-before: [indexing1-endsnippet] + +ArrayFire is column-major so the resulting A array will look like this: + +.. math:: + + \begin{bmatrix} + 0 & 4 & 8 & 12 \\ + 1 & 5 & 9 & 13 \\ + 2 & 6 & 10 & 14 \\ + 3 & 7 & 11 & 15 + \end{bmatrix} + +In Python, for a two-dimensional array like a matrix, you can access its first element by providing the indices 0, 0 within the indexing operator of the af.Array object. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing2-snippet] + :end-before: [indexing2-endsnippet] + +.. math:: + + + A[0,0] = [0] + + A[2,3] = [14] + +.. note:: + :class: warning + + Normally you want to avoid accessing individual elements of the array like this for performance reasons. + + This is a warning note regarding accessing individual elements of arrays. + + + + +Indexing with negative values will access from the end of the array. For example, the value negative one and negative two(-2) will return the last and second to last element of the array, respectively. ArrayFire provides the end alias for this which also allows you to index the last element of the array. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing3-snippet] + :end-before: [indexing3-endsnippet] + + +Indexing slices and subarrays* +****************************** +You can access regions of the array via the af::seq and af::span objects. The span objects allows you to select the entire set of elements across a particular dimension/axis of an array. For example, we can select the third column of the array by passing span as the first argument and 2 as the second argument to the parenthesis operator. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing4-snippet] + :end-before: [indexing4-endsnippet] + +.. math:: + + A[:, 2]=\begin{bmatrix} + 8 \\ + 9 \\ + 10 \\ + 11 \\ + \end{bmatrix} + +You can read that as saying that you want all values across the first dimension, but only from index 2 of the second dimension. + +You can access the second row by passing [1, :] to the array + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing5-snippet] + :end-before: [indexing5-endsnippet] + +.. math:: + + A[1, :]=\begin{bmatrix} + 1,5,9,13\\ + \end{bmatrix} + +You can use Python's slicing notation to define a range when indexing in **arrayfire**. For example, if you want to get the first two columns of an array, you can access the array by specifying **':'** for the rows (to select all rows), and **0:2** for the columns (to select columns from index 0 to 1). + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing6-snippet] + :end-before: [indexing6-endsnippet] + +.. math:: + + A[:, 0:2]= \begin{bmatrix} + 0 & 4\\ + 1 & 5\\ + 2 & 6\\ + 3 & 7\\ + \end{bmatrix} + + +Indexing using af.Array +*************************** + +In Python with arrayfire, you can also index arrays using other **af.Array** objects. ArrayFire flattens the input and treats the elements inside the array +as column major indices to index the original Array as 1D Array. + +.. code-block:: python + + import arrayfire as af + + x = af.randu((10, 10)) + + # indices 1, 3, 5 + indices = af.range((3)) * 2 + 1 + + # returns entries with indices 1, 3, 5 of x.flat() + y = x[indices] + + +You can also index Arrays using boolean Arrays. ArrayFire will return an Array with length of the number of :literal:`True` elements in the indexing arrays +and entries of in column major order of the elements that correspond to :literal:`True` entries: + +.. code-block:: python + + import arrayfire as af + + # Creates a random array + x = af.randu((10, 10)) + + # returns an array with all the entries of x that contain values greater than 0.5 + y = x[x > 0.5] + +References and copies +********************* +All indexing operations in ArrayFire return **af.Array** objects, which are instances of the array_proxy class. These objects can either be newly created arrays or references to the original array, depending on the type of indexing operation applied to them + +* When an array is indexed using another **af.Array** , a new array is created instead of referencing the original data. +* If an array was indexed using a scalar, **sequential '0:2'** or **span ':'**, then the resulting array will reference the original data IF the first dimension is continuous. The following lines will not allocate additional memory. + +.. note:: + :class: warning + + The new arrays wither references or newly allocated arrays, are independent of the original data. Meaning that any changes to the original array will not propagate to the references. Likewise, any changes to the reference arrays will not modify the original data. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing7-snippet] + :end-before: [indexing7-endsnippet] + +The following code snippet shows some examples of indexing that will allocate new memory. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing8-snippet] + :end-before: [indexing8-endsnippet] + +Even though the copy3 array references continuous memory in the original array, using an **af.Array** for indexing in ArrayFire results in the creation of a new array + +Assignment +********** +In Python with ArrayFire, assigning an **af.Array** replaces the array on the left-hand side of :literal:`=` with the result from the right-hand side. This can lead to changes in type and shape compared to the original array. Notably, assignments do not update arrays previously referenced through indexing operations. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing9-snippet] + :end-before: [indexing9-endsnippet] + + +The :literal:`ref` array is created by indexing into the data array. The initialized :literal:`ref` array points to the data array and does not allocate memory when it is created. After the matmul call, the :literal:`ref` array will not be pointing to the data array. The matmul call will not update the values of the data array. + +You can update the contents of an **af.Array** by assigning with the operator parenthesis. For example, if you wanted to change the third column of the :literal:`A` array you can do that by assigning to :literal:`A[:, 2]`. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing10-snippet] + :end-before: [indexing10-endsnippet] + +.. math:: + + ref= \begin{bmatrix} + 8\\ + 9\\ + 10\\ + 11\\ + \end{bmatrix} A = \begin{bmatrix} + 0 & 4 & 3.14 & 12\\ + 1 & 5 & 3.14 & 13\\ + 2 & 6 & 3.14 & 14\\ + 3 & 7 & 3.14 & 15\\ + \end{bmatrix} + +This will update only the array being modified. If there are arrays that are referring to this array because of an indexing operation, those values will remain unchanged. + +Allocation will only be performed if there are other arrays referencing the data at the point of assignment. In the previous example, an allocation will be performed when assigning to the :literal:`A` array because the :literal:`ref` array is pointing to the original data. Here is another example demonstrating when an allocation will occur: + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing11-snippet] + :end-before: [indexing11-endsnippet] + + +In this example, no allocation will take place because when the :literal:`ref` object is created, it is pointing to :literal:`A`'s data. Once it goes out of scope, no data points to A, therefore when the assignment takes place, the data is modified in place instead of being copied to a new address. + +You can also assign to arrays using another af::arrays as an indexing array. This works in a similar way to the other types of assignment but care must be taken to assure that the indexes are unique. Non-unique indexes will result in a race condition which will cause non-deterministic values. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing12-snippet] + :end-before: [indexing12-endsnippet] + + +Member Functions +********************* + +Check the :doc:`Array Class ` for more details on other functions that the Array object provides. + +Additional examples +******************* +See Assignment & Indexing operation on arrays for the full listing. + +.. literalinclude:: indexing.py + :language: python + :start-after: [indexing13-snippet] + :end-before: [indexing13-endsnippet] + \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..017d733 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,145 @@ +ArrayFire Installer +=================== + +To use ArrayFire-Python you require three things: + +.. list-table:: + + * - :literal:`arrayfire-python` package + - You may install it through pip :literal:`pip install arrayfire-python` or from `building arrayfire-python wheel <../README.md>`_ + + * - :literal:`arrayfire-binary-python-wrapper` + - You may download and install through pip :literal:`pip install arrayfire_binary_python_wrapper-0.8.0+af3.10.0 -f https://arrayfire.com/python/binaries` which will come with ArrayFire C Libraries as well. You may also `build from source `_ without the C Libraries. + + * - :literal:`ArrayFire C/C++ Libraries` + - If you build the binary wrapper from source or wish to program with ArrayFire in C/C++, navigate to https://arrayfire.com/download and download the appropriate installer for the target architecture and operating system. Although ArrayFire can be `built from source `_, the installers conveniently package necessary dependencies. + +Below we detail more on the ArrayFire C Libraries installation procedure. Install the latest device drivers before using ArrayFire. Drivers and runtimes should be downloaded and installed from each device vendor's website. + +Install Instructions for ArrayFire C Libraries +############################################### + +* :ref:`Windows ` +* :ref:`Linux ` +* :ref:`macOs ` + +.. _Windows: + +Windows +******* +Once the ArrayFire has been downloaded, run the installer. + +The installer offers the option to automatically add ArrayFire to the path for all users. If the installer did not do this, simply append :literal:`%AF_PATH%/lib` to the PATH variable so that the loader can find ArrayFire DLLs. + + +.. _Linux: + +Linux +***** + +There are two ways to install ArrayFire on Linux. + +Package Manager +Using the ArrayFire Linux Installer +As of today, approach (1) is only supported for Ubuntu 18.04 and 20.04. Please go through the GitHub wiki `page `_ for detailed instructions. + +For approach (2), once the ArrayFire installer is downloaded, execute the installer from the terminal as shown below. Set the :literal:`--prefix` argument to the target install directory; we recommend :literal:`/opt`. + +.. code-block:: text + + ./ArrayFire_*_Linux_x86_64.sh --include-subdir --prefix=/opt + +Given sudo permissions, the ArrayFire libraries can be added to the path via :literal:`ldconfig` like so: + +.. code-block:: text + + echo /opt/arrayfire/lib64 > /etc/ld.so.conf.d/arrayfire.conf + sudo ldconfig + +Otherwise, the :literal:`LD_LIBRARY_PATH` environment variable can be set so that the shared library loader can find the ArrayFire libraries. + +For more information on using ArrayFire on Linux, visit the following page*. + +Graphics support +~~~~~~~~~~~~~~~~ + +ArrayFire enables high-performance visualizations via the `Forge `_ library. On Linux, there are a few dependencies to install to enable graphics support: + +* FreeImage +* Fontconfig +* GLU (OpenGL Utility Library) + +To install these dependencies on common Linux distributions: + +**Debian, Ubuntu (14.04 and above), and other Debian derivatives** + +.. code-block:: text + + apt install build-essential libfreeimage3 libfontconfig1 libglu1-mesa + + +**Fedora, Redhat, CentOS** + +.. code-block:: text + + yum install freeimage fontconfig mesa-libGLU + + +.. _macOS: + +macOS +***** + +Once the ArrayFire installer has been downloaded, execute the installer by either double-clicking on the ArrayFire :literal:`pkg` file or running the following command: + +.. code-block:: text + + sudo installer -pkg Arrayfire-*_OSX.pkg -target / + +For more information on using ArrayFire on macOS, visit the following page*. + + +NVIDIA Tegra devices +~~~~~~~~~~~~~~~~~~~~ + +ArrayFire is capable of running TX2 devices. + +Before installing ArrayFire, make sure the latest version of JetPack (v2.3 and above) or L4T (v24.2 and above) is installed. + +Tegra prerequisites +~~~~~~~~~~~~~~~~~~~ + +The following dependencies are required for Tegra devices: + +.. code-block:: text + + sudo apt install libopenblas-dev liblapacke-dev + +Testing installation +******************** + +After ArrayFire is finished installing, we recommend building and running a few of the provided examples to verify things are working as expected. + +On Windows, open the CMakeLists.txt file from CMake-GUI. Once the project is configured and generated, build and run the examples from Visual Studio. + +On Linux, run the following commands: + +.. code-block:: text + + cp -r /opt/arrayfire/share/ArrayFire/examples /tmp/examples + cd /tmp/examples + mkdir build + cd build + cmake .. + make + ./helloworld/helloworld_{cpu,cuda,oneapi,opencl} + +Getting help +~~~~~~~~~~~~ + +* Google Groups: https://groups.google.com/forum/#!forum/arrayfire-users +* ArrayFire Services: `Consulting `_ | `Training `_ +* ArrayFire Blogs: http://arrayfire.com/blog/ +* ArrayFire `Contact Us `_ +* Email: support@arrayfire.com + diff --git a/docs/introductiontovectorization.py b/docs/introductiontovectorization.py new file mode 100644 index 0000000..4551d1b --- /dev/null +++ b/docs/introductiontovectorization.py @@ -0,0 +1,163 @@ + +# [vectorization1-snippet] +import arrayfire as af + +# Create an ArrayFire array 'a' using af.range() +a = af.range(10) # Creates an array [0, 1, 2, ..., 9] + +# Loop through the elements of 'a' and increment each element by 1 +for i in range(a.dims()[0]): + a[i] = a[i] + 1 # Increment each element by 1 + +# Print the modified array 'a' +print("Modified array 'a':") +print(a) +# [vectorization1-endsnippet] + + +# [vectorization2-snippet] + +import arrayfire as af + +#[0, 9] +a = af.range(10) + +# [1, 10] +a = a+ 1 +# [vectorization2-endsnippet] + + +# [vectorization3-snippet] + +import arrayfire as af + +# Define the filter coefficients as a list +g_coef = [1, 2, 1, + 2, 4, 2, + 1, 2, 1] + +# Convert the coefficients list to an ArrayFire array and scale it +filter = (1.0 / 16.0) * af.Array(3, 3, g_coef) + +# Generate a random signal array of dimensions WIDTH x HEIGHT x NUM +WIDTH = 100 +HEIGHT = 100 +NUM = 3 +signal = af.randu(WIDTH, HEIGHT, NUM) + +# Perform 2D convolution of signal with filter +conv = af.convolve2(signal, filter) + +# Print the result if needed +print("Convolution result:") +print(conv) +# [vectorization3-endsnippet] + + +# [vectorization4-snippet] + +import arrayfire as af + +# Define dimensions +WIDTH = 256 +HEIGHT = 256 +NUM_IMAGES = 100 + +# Generate an array of 100 WIDTH x HEIGHT images of random numbers +imgs = af.randu((NUM_IMAGES, (WIDTH, HEIGHT))) + +# Rotate all of the images in a single command (rotate by 45 degrees) +rot_imgs = af.rotate(imgs, 45) + +# Print the shape of rot_imgs to verify the result +print("Shape of rotated images:", rot_imgs.shape()) + +# Optionally, print the rotated images +# print(rot_imgs) + +# Optionally, display or further process `rot_imgs` as needed + +# [vectorization4-endsnippet] + + +# [vectorization5-snippet] + +import arrayfire as af + +# Create an ArrayFire array 'a' using af.range() +a = af.range(10) # Creates an array [0, 1, 2, ..., 9] + +# Perform element-wise addition using vectorized operations +a = a + 1 # Increment each element by 1 + +# Print the modified array 'a' +print("Modified array 'a':") +print(a) +# [vectorization5-endsnippet] + +# [vectorization7-snippet] + +import arrayfire as af + +# Calculate accumulative sum along columns of A +B = af.accum(A) + + +# [vectorization7-endsnippet] + + +# [vectorization9-snippet] + +import arrayfire as af + +# Create the filter and weight vectors +filter = af.randu((1, 5)) +weights = af.randu((5, 5)) + +# Apply the filter using a for-loop equivalent +filtered_weights = af.constant(0, (5, 5)) +for i in range(weights.shape[1]): + filtered_weights[:, i] = af.matmul(filter, weights[:, i]) + +# Print the filtered weights array +print("Filtered weights:") +print(filtered_weights) +# [vectorization9-endsnippet] + + +# [vectorization10-snippet] + +import arrayfire as af + +# Create the filter and weight vectors +filter = af.randu((1, 5)) # Shape: 1x5 +weights = af.randu((5, 5)) # Shape: 5x5 + +# Transpose the filter to align dimensions for broadcasting +filter_transposed = filter.T # Shape: 5x1 + +# Element-wise multiplication with broadcasting +filtered_weights = filter_transposed * weights + +# Print the filtered weights array +print("Filtered weights:") +print(filtered_weights) # Incorrect +# [vectorization10-endsnippet] + +# [vectorization11-snippet] + +import arrayfire as af + +# Create the filter and weight vectors +filter = af.randu((1, 5)) # Shape: 1x5 +batched_filter = af.tile(filter, (1, 1, 5)) # batch on the third dimension +weights = af.randu((5, 5)) # Shape: 5x5 + +# Leverage matmul batching +filtered_weights = af.matmul(batched_filter, weights) # shape 1x5x5 +filtered_weights = af.moddims(filtered_weights, (5, 5)) # reshape to 2d 5x5 + +# Print the filtered weights array +print("Filtered weights:") +print(filtered_weights) +# [vectorization11-endsnippet] diff --git a/docs/introductiontovectorization.rst b/docs/introductiontovectorization.rst new file mode 100644 index 0000000..7088427 --- /dev/null +++ b/docs/introductiontovectorization.rst @@ -0,0 +1,96 @@ +Introduction to Vectorization +============================= +Programmers and Data Scientists want to take advantage of fast and parallel computational devices. Writing vectorized code is necessary to get the best performance out of the current generation parallel hardware and scientific computing software. However, writing vectorized code may not be immediately intuitive. ArrayFire provides many ways to vectorize a given code segment. In this tutorial, we present several methods to vectorize code using ArrayFire and discuss 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 the following code: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization1-snippet] + :end-before: [vectorization1-endsnippet] + +Although completely valid, the code is very inefficient as it results in a kernel kernels that operate on one datum. Instead, the developer should have used ArrayFire's overload of the + operator: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization2-snippet] + :end-before: [vectorization2-endsnippet] + +This code will result in a single kernel that operates on all 10 elements of :literal:`a` in parallel. + +Most ArrayFire functions are vectorized. A small subset of these include: + ++---------------------------------------+--------------------------------------------+ +| Operator Category | Functions | ++=======================================+============================================+ +| Arithmetic Operations | +, -, \*, /, %, >, < | ++---------------------------------------+--------------------------------------------+ +| Logical Operations | &&, ||(or), <, >, ==, != etc. | ++---------------------------------------+--------------------------------------------+ +| Numeric functions | abs(), floor(), round(), min(), max(), etc.| ++---------------------------------------+--------------------------------------------+ +| Complex Operations | real(), imag(), conj(), etc. | ++---------------------------------------+--------------------------------------------+ +| Exponential and logarithmic functions | exp(), log(), expm1(), log1p(), etc. | ++---------------------------------------+--------------------------------------------+ +| Logical Operations | sin(), cos(), tan(), etc. | ++---------------------------------------+--------------------------------------------+ +| Hyperbolic Functions | sinh(), cosh(), tanh(), etc. | ++---------------------------------------+--------------------------------------------+ + +In addition to element-wise operations, many other functions are also vectorized in ArrayFire. + +Notice that even that perform some form of aggregation (e.g. :literal:`sum()` or :literal:`min()`), signal processing (like :literal:`convolve()`), and even image processing functions (i.e. :literal:`rotate()`) all support vectorization on different columns or images. For example, if we have :literal:`NUM` images of size :literal:`WIDTH` by :literal:`HEIGHT`, one could convolve each image in a vector fashion as follows: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization3-snippet] + :end-before: [vectorization3-endsnippet] + + +Similarly, one can rotate 100 images by 45 degrees in a single call using code like the following: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization4-snippet] + :end-before: [vectorization4-endsnippet] + +Although most functions in ArrayFire do support vectorization, some do not. Most notably, all linear algebra functions. Even though they are not vectorized linear algebra operations still execute in parallel on your hardware. + +Using the built in vectorized operations should be the first and preferred method of vectorizing any code written with ArrayFire. + +Batching +******** +Consider the following example. Here we create a filter which we would like to apply to each of the weight vectors. The naive solution would be using a for-loop as we have seen previously: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization9-snippet] + :end-before: [vectorization9-endsnippet] + +However, as we have discussed above, this solution will be very inefficient. One may be tempted to implement a vectorized solution as follows: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization10-snippet] + :end-before: [vectorization10-endsnippet] + +However, the dimensions of :literal:`filter` and :literal:`weights` do not match, thus ArrayFire will generate a runtime error. + +The correct solution is to use `batch operations with matmul `_ +By tiling on the third dimension, matmul is done in the first 2 dimensions and batched on the third to obtain the filtered weights: + +.. literalinclude:: introductiontovectorization.py + :language: python + :start-after: [vectorization11-snippet] + :end-before: [vectorization11-endsnippet] + + +Advanced Vectorization +********************** +We have seen the different methods ArrayFire provides to vectorize our code. Tying them all together is a slightly more involved process that needs to consider +data dimensionality and layout, memory usage, nesting order, etc. An excellent example and discussion of these factors can be found on our blog: +`How to write vectorized code `_ (Ignore GFOR section as it is not applicable to Python). diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..ccab0bf --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,69 @@ +License +========== + +Copyright (c) 2014-2025, ArrayFire +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +* Neither the name ArrayFire nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Trademark Policy +################ +The literal mark “ArrayFire” and ArrayFire logos are trademarks of ArrayFire. + +Trademarks are used to identify and distinguish the source of goods of one party from those offered by others. As such, a trademark must be used properly and consistently otherwise the mark risks becoming generic, making it impossible to enforce. The following guidelines govern the use of ArrayFire trademarks whether by ArrayFire or third parties, in order to protect the value of ArrayFire trademarks and provide guidance to users on how they should or should not use ArrayFire marks. Unauthorized use of ArrayFire trademarks, or similarly confusing marks, which do not comply with the guidelines below, is prohibited and may constitute trademark infringement. These guidelines do not interfere with your right to use or modify the underlying ArrayFire open source software as permitted under the applicable software license. + +Throughout this Policy, the word “Marks” refers to the following: + +The literal mark “ArrayFire” +The logos and graphic marks displayed and available for download at http://arrayfire.com/trademark +The slogan “If you want faster code, you’ve come to the right place” +Throughout this Policy "ArrayFire Product" refers to software, source code, services, and training content developed by ArrayFire or otherwise contributed to ArrayFire by third-parties. + +Fair Use +******** + +You may use the Marks without prior written permission to refer to an ArrayFire Product when the Marks are used for the purpose of description or identification of an ArrayFire Product where there is no suggestion of endorsement or sponsorship by the trademark owner or use of the Marks in such a way to confuse the consumer. Such use is generally regarded as "fair use" under trademark law. + +A few examples of use cases that are clearly fair use are: + +To refer to the ArrayFire software in substantially unmodified form. +To identify the ArrayFire software as a distinct component of a software offering where the Mark is not being used in a way which suggests sponsorship or endorsement of the project. +To factually refer to an ArrayFire Product. +Use of the Marks without written permission +Subject to the inclusion of the disclaimer at the bottom of this section, we permit the use of the literal mark, "ArrayFire" to refer to projects, services, or communities outside of ArrayFire Product without written permission in the following contexts: + +When referring to the ArrayFire software that is not substantially unmodified, to say that such software is a “derivative of” or “based on” ArrayFire. +When referring to third-party software that provides interoperability between ArrayFire and a programming language (commonly called "language wrappers"), in the format "ArrayFire.[Language]" or "ArrayFire-[Language]" or [Language] for ArrayFire" -- provided that such use case otherwise compiles with the rest of the Policy. +When referring to a third-party software product and/or service that is interoperable with the ArrayFire software, in the format “[Product Name] for ArrayFire” -- provided that such use otherwise complies with the rest of the Policy. +In the above scenarios, the following disclaimer must be prominently displayed: + +"[Your project name] is not affiliated with or endorsed by ArrayFire. The ArrayFire literal mark is used under a limited license granted by ArrayFire the trademark holder in the United States and other countries." + +Prohibited Use +**************** +You may not use the Marks in the following ways: + +In any way likely to cause confusion as to the identity of an ArrayFire Product, the provenance of its software, or the software's license. +In any way that indicates a greater degree of association between you and the ArrayFire Project or ArrayFire than actually exists. +In any way that implies a designated successor to an ArrayFire Product. +To refer to the ArrayFire software, modified by a third party to the point of inoperability with ArrayFire software in substantially unmodified form. +In any other way that dilutes or otherwise infringes upon the trademark rights of ArrayFire. +In addition, you may not use any of the Marks as a syllable in a new word or as part of a portmanteau (e.g., “ArrayFirepedia”) used as a mark for a third-party product or service without explicit written permission from ArrayFire. For the avoidance of doubt, this provision applies even to third-party marks that use the Marks as a syllable or as part of a portmanteau to refer to a product or service's use of ArrayFire code. + +Reservation of Rights +********************** +ArrayFire reserves the sole right to: + +Determine the compliance with this Policy +Modify the Policy in ways consistent with the mission of protecting the public. +Grant exceptions to this Policy, of any kind and for any reason whatsoever, other clauses notwithstanding. +Questions +If you have any questions regarding this Policy, wish to report any misuse of ArrayFire trademarks, or are unsure on whether you require a trademark license, or wish to obtain a license to use ArrayFire Marks, please contact sales@arrayfire.com. \ No newline at end of file diff --git a/docs/linear_algebra_functions.rst b/docs/linear_algebra_functions.rst new file mode 100644 index 0000000..aeab32f --- /dev/null +++ b/docs/linear_algebra_functions.rst @@ -0,0 +1,35 @@ +Linear Algebra +=============== + +Functions for performing linear algebra operations, essential in many scientific and engineering tasks. + +.. list-table:: Functions + + * - :doc:`af.det() ` + - Find the determinant of a matrix. + * - :doc:`af.dot() ` + - Compute the dot product. + * - :doc:`af.gemm() ` + - General matrix multiplication. + * - :doc:`af.inv() ` + - Computes the inverse of a matrix. + * - :doc:`af.inverse() ` + - Invert a matrix. + * - :doc:`af.is_lapack_available() ` + - Check if lapack runtimes are available + * - :doc:`af.lu() ` + - Perform LU decomposition. + * - :doc:`af.matmul() ` + - Matrix multiplication. + * - :doc:`af.norm() ` + - Find the norm of a matrix. + * - :doc:`af.pinverse() ` + - Pseudo-invert (Moore-Penrose) a matrix. + * - :doc:`af.qr() ` + - Perform QR decomposition. + * - :doc:`af.rank() ` + - Find the rank of a matrix. + * - :doc:`af.solve() ` + - Solve a system of equations. + * - :doc:`af.svd() ` + - Perform singular value decomposition. \ No newline at end of file diff --git a/docs/mathematical_operations_functions.rst b/docs/mathematical_operations_functions.rst new file mode 100644 index 0000000..24b101e --- /dev/null +++ b/docs/mathematical_operations_functions.rst @@ -0,0 +1,147 @@ +Mathematical Operations +======================== + +Functions for performing fundamental arithmetic and mathematical operations on arrays. + +.. list-table:: Functions + + * - :doc:`af.abs() ` + - Calculate the absolute value. + * - :doc:`af.acos() ` + - Evaluate the inverse cosine function (arc cosine). + * - :doc:`af.acosh() ` + - Evaluate the inverse hyperbolic cosine function (area hyperbolic cosine). + * - :doc:`af.add() ` + - Elementwise addition. + * - :doc:`af.arg() ` + - Calculate the phase angle (in radians) of a complex array. + * - :doc:`af.asin() ` + - Evaluate the inverse sine function (arc sine). + * - :doc:`af.asinh() ` + - Evaluate the inverse hyperbolic sine function (area hyperbolic sine). + * - :doc:`af.atan() ` + - Evaluate the inverse tangent function (arc tangent). + * - :doc:`af.atan2() ` + - Evaluate the inverse tangent function (arc tangent). + * - :doc:`af.atanh() ` + - Evaluate the inverse hyperbolic tangent function (area hyperbolic tangent). + * - :doc:`af.bitand() ` + - Evaluate the bitwise AND of two arrays. + * - :doc:`af.bitnot() ` + - Evaluate the bitwise NOT of an array. + * - :doc:`af.bitor() ` + - Evaluate the bitwise OR of two arrays. + * - :doc:`af.bitshiftl() ` + - Shift the bits of integer arrays left. + * - :doc:`af.bitshiftr() ` + - Shift the bits of integer arrays right. + * - :doc:`af.bitxor() ` + - Evaluate the bitwise XOR of two arrays. + * - :doc:`af.cbrt() ` + - Evaluate the cube root. + * - :doc:`af.ceil() ` + - Rounds up to the least integer greater than or equal to x. + * - :doc:`af.clamp() ` + - Clamp an array between an upper and a lower limit. + * - :doc:`af.conjg() ` + - Evaluate the complex conjugate of an input array. + * - :doc:`af.cos() ` + - Evaluate the cosine function. + * - :doc:`af.cosh() ` + - Evaluate the hyperbolic cosine function. + * - :doc:`af.div() ` + - Elementwise division. + * - :doc:`af.dot() ` + - Compute the dot product. + * - :doc:`af.eq() ` + - Equal to, an elementwise comparison of two arrays. + * - :doc:`af.erf() ` + - Evaluate the error function. + * - :doc:`af.erfc() ` + - Evaluate the complementary error function. + * - :doc:`af.exp() ` + - Evaluate the exponential function. + * - :doc:`af.expm1() ` + - Evaluate the exponential function of an array minus 1, exp(in) - 1. + * - :doc:`af.factorial() ` + - Evaluate the factorial. + * - :doc:`af.floor() ` + - Rounds down to the greatest integer less than or equal to x. + * - :doc:`af.ge() ` + - Greater than or equal to, an elementwise comparison of two arrays. + * - :doc:`af.gradient() ` + - Calculate the gradients of the input + * - :doc:`af.gray2rgb() ` + - Grayscale to RGB colorspace converter. + * - :doc:`af.gt() ` + - Greater than comparison, an elementwise comparison of two arrays. + * - :doc:`af.hypot() ` + - Evaluate the length of the hypotenuse of two inputs. + * - :doc:`af.imag() ` + - Returns the imaginary part of a complex array. + * - :doc:`af.imax() ` + - Finds the maximum value. + * - :doc:`af.imin() ` + - Finds the minimum value. + * - :doc:`af.le() ` + - Less than or equal to, an elementwise comparison of two arrays. + * - :doc:`af.lgamma() ` + - Evaluate the logarithm of the absolute value of the gamma function. + * - :doc:`af.log() ` + - Evaluate the natural logarithm. + * - :doc:`af.log10() ` + - Evaluate the base 10 logarithm. + * - :doc:`af.log1p() ` + - Evaluate the natural logarithm of 1 + input, ln(1+in). + * - :doc:`af.log2() ` + - Evaluate the base 2 logarithm. + * - :doc:`af.logical_and() ` + - Evaluate the logical and between two arrays + * - :doc:`af.logical_not() ` + - Evaluate the logical not of an array + * - :doc:`af.logical_or() ` + - Evaluate the logical or between two arrays + * - :doc:`af.lt() ` + - Less than, an elementwise comparison of two arrays. + * - :doc:`af.maxof() ` + - Elementwise maximum between two arrays + * - :doc:`af.minof() ` + - Elementwise minimum between two arrays + * - :doc:`af.mod() ` + - Calculate the modulus. + * - :doc:`af.mul() ` + - Elementwise multiply. + * - :doc:`af.neg() ` + - Negate an array. + * - :doc:`af.neq() ` + - Not equal to, an elementwise comparison of two arrays. + * - :doc:`af.pow() ` + - Raise a base to a power (or exponent). + * - :doc:`af.pow2() ` + - Raise 2 to a power (or exponent). + * - :doc:`af.real() ` + - Returns the real part of a complex array. + * - :doc:`af.rem() ` + - Calculate the remainder of a division. + * - :doc:`af.root() ` + - Evaluate the nth root. + * - :doc:`af.round() ` + - Round numbers to the nearest integer. + * - :doc:`af.rsqrt() ` + - Evaluate the reciprocal square root. + * - :doc:`af.sign() ` + - Return the sign of elements in an array. + * - :doc:`af.sin() ` + - Evaluate the sine function. + * - :doc:`af.sinh() ` + - Evaluate the hyperbolic sine function. + * - :doc:`af.sqrt() ` + - Evaluate the square root. + * - :doc:`af.sub() ` + - Elementwise subtraction. + * - :doc:`af.tan() ` + - Evaluate the tangent function. + * - :doc:`af.tanh() ` + - Evaluate the hyperbolic tangent function. + * - :doc:`af.tgamma() ` + - Evaluate the gamma function. \ No newline at end of file diff --git a/docs/overview.py b/docs/overview.py new file mode 100644 index 0000000..18ee70a --- /dev/null +++ b/docs/overview.py @@ -0,0 +1,16 @@ +import arrayfire as af + +# [pi-example-simple-snippet] +# Monte Carlo estimation of pi +def calc_pi_device(samples) -> float: + # Simple, array based API + # Generate uniformly distributed random numers + x = af.randu(samples) + y = af.randu(samples) + # Supports Just In Time Compilation + # The following line generates a single kernel + within_unit_circle = (x * x + y * y) < 1 + # Intuitive function names + return 4 * af.count(within_unit_circle) / samples +# [pi-example-simple-endsnippet] + diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..593a65b --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,115 @@ +Overview +======== + +About ArrayFire +*************** + +.. image:: images/arrayfire_logo.png + :alt: ArrayFire Logo + :align: center + :class: responsive-img + +`ArrayFire `_ is a high performance library for parallel computing with an easy-to-use API. It enables users to write scientific computing code that is portable across CUDA, OpenCL and CPU devices. This project provides Python bindings for the ArrayFire library. + +Installing ArrayFire +******************** + +Install ArrayFire using either a binary installer for Windows, OSX, or Linux or download it from source: + * `Download and install Binaries `_ + * `Build from source `_ + +Using ArrayFire +*************** + +The array object is beautifully simple. + +Array-based notation effectively expresses computational algorithms in readable math-resembling notation. Expertise in parallel programming is not required to use ArrayFire. + +A few lines of ArrayFire code accomplishes what can take 100s of complicated lines in CUDA, oneAPI, or OpenCL kernels. + +Support for multiple domains +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ArrayFire contains hundreds of functions across various domains including: + +Vector Algorithms +Image Processing +Computer Vision +Signal Processing +Linear Algebra +Statistics +and more. +Each function is hand-tuned by ArrayFire developers with all possible low-level optimizations. + +Support for various data types and sizes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ArrayFire operates on common data shapes and sizes, including vectors, matrices, volumes, and + +It supports common data types, including single and double precision floating point values, complex numbers, booleans, and 32-bit signed and unsigned integers. + +Extending ArrayFire +~~~~~~~~~~~~~~~~~~~ + +ArrayFire can be used as a stand-alone application or integrated with existing CUDA, oneAPI, or OpenCL code. + +With support for x86, ARM, CUDA, oneAPI, and OpenCL devices, ArrayFire supports for a comprehensive list of devices. + +Each ArrayFire installation comes with: + + * a CUDA backend (named 'libafcuda') for `NVIDIA GPUs `_ + * a oneAPI backend (named 'libafoneapi') for `oneAPI devices `_ + * an OpenCL backend (named 'libafopencl') for `OpenCL devices `_, + * a CPU backend (named 'libafcpu') to fall back to when CUDA, oneAPI, or OpenCL devices are unavailable. + +Vectorized and Batched Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ArrayFire supports batched operations on N-dimensional arrays. Batch operations in ArrayFire are run in parallel ensuring an optimal usage of CUDA, oneAPI, or OpenCL devices. + +Best performance with ArrayFire is achieved using vectorization techniques. + +ArrayFire can also execute loop iterations in parallel with the gfor function. + +Just in Time compilation +~~~~~~~~~~~~~~~~~~~~~~~~ +ArrayFire performs run-time analysis of code to increase arithmetic intensity and memory throughput, while avoiding unnecessary temporary allocations. It has an awesome internal JIT compiler to make important optimizations. + +Read more about how ArrayFire JIT. can improve the performance in your application. + + +Simple Example +-------------- + +Here is an example of ArrayFire code that performs a Monte Carlo estimation of PI. + +.. literalinclude:: overview.py + :language: python + :start-after: [pi-example-simple-snippet] + :end-before: [pi-example-simple-endsnippet] + +Product Support +*************** + +Free Community Options +~~~~~~~~~~~~~~~~~~~~~~ + * `ArrayFire Mailing List `_ (recommended) + * `StackOverFlow `_ + +Premium Support +~~~~~~~~~~~~~~~ + * Phone Support - available for purchase(request a quote) + +Contact Us +~~~~~~~~~~ + * If you need to contact us, visit our `Contact Us page `_. + +Email +~~~~~ + * Engineering: technical@arrayfire.com + * Sales: sales@arrayfire.com + +Citations and Acknowledgements +****************************** + +If you redistribute ArrayFire, please follow the terms established in `the license `_. If you wish to cite ArrayFire in an academic publication, please use the following reference: \ No newline at end of file diff --git a/docs/product_support.rst b/docs/product_support.rst new file mode 100644 index 0000000..bcd814a --- /dev/null +++ b/docs/product_support.rst @@ -0,0 +1,9 @@ +Get Help +============ + +* ArrayFire Services: `Consulting `_ | `Support `_ | `Training `_ +* `ArrayFire Blog `_ +* ArrayFire `Contact Us `_ +* Email: support@arrayfire.com +* `Google Groups `_ +* `Slack Group `_ \ No newline at end of file diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst new file mode 100644 index 0000000..c97ec5e --- /dev/null +++ b/docs/releasenotes.rst @@ -0,0 +1,21 @@ +Release Notes +============== + +v0.1.0 +****** +Welcome to the ArrayFire Python Bindings! These are the currently supported features: + +- Support for all backends (cpu, opencl, oneapi, cuda) +- Computer Vision +- Functions to Create and Modify Arrays +- Functions to Work with Internal Array Layout +- Image Processing with Features +- Input and Output Functions +- Interface Functions +- Linear Algebra +- Machine Learning +- Mathematical Functions +- Signal Processing +- Statistics +- Unified API Functions +- Vector Algorithms \ No newline at end of file diff --git a/docs/special_functions.rst b/docs/special_functions.rst new file mode 100644 index 0000000..4e20311 --- /dev/null +++ b/docs/special_functions.rst @@ -0,0 +1,125 @@ +Special Functions +==================== + +Functions for convolutions, creating and applying specific types of filters, commonly used in signal processing and analysis. + +.. list-table:: Functions + + * - :doc:`af.anisotropic_diffusion() ` + - Anisotropic Smoothing Filter. + * - :doc:`af.approx1() ` + - Interpolation across a single dimension. + * - :doc:`af.approx1_uniform() ` + - Interpolation across a single dimension in uniform steps + * - :doc:`af.approx2() ` + - Interpolation along two dimensions. + * - :doc:`af.approx2_uniform() ` + - Interpolation along two dimensions in uniform steps + * - :doc:`af.canny() ` + - Canny Edge Detector. + * - :doc:`af.convolve1() ` + - Convolution Integral for one dimensional data. + * - :doc:`af.convolve2() ` + - Convolution Integral for two dimensional data. + * - :doc:`af.convolve2_gradient_nn() ` + - Version of convolution that is consistent with the machine learning formulation that will spatially convolve a filter on 2-dimensions against a signal. + * - :doc:`af.convolve2_nn() ` + - Version of convolution that is consistent with the machine learning formulation that will spatially convolve a filter on 2-dimensions against a signal. + * - :doc:`af.convolve2_separable() ` + - Faster equivalent of the canonical 2D convolution for filters/kernels that can be decomposed into two separate spatial vectors. + * - :doc:`af.convolve3() ` + - Convolution Integral for three dimensional data. + * - :doc:`af.color_space() ` + - Colorspace conversion function. + * - :doc:`af.confidence_cc() ` + - Segment image based on similar pixel characteristics. + * - :doc:`af.dilate() ` + - Dilation(morphological operator) for images. + * - :doc:`af.fir() ` + - This function implements a Finite Impulse Filter. + * - :doc:`af.gaussian_kernel() ` + - Creates a Gaussian Kernel. + * - :doc:`af.gloh() ` + - SIFT feature detector and GLOH descriptor extractor. + * - :doc:`af.gradient() ` + - Calculate the gradients of the input + * - :doc:`af.gray2rgb() ` + - Grayscale to RGB colorspace converter. + * - :doc:`af.hamming_matcher() ` + - Calculates Hamming distances between two 2-dimensional arrays + * - :doc:`af.harris() ` + - Harris corner detector. + * - :doc:`af.hsv2rgb() ` + - HSV to RGB colorspace converter. + * - :doc:`af.hypot() ` + - Evaluate the length of the hypotenuse of two inputs. + * - :doc:`af.is_image_io_available() ` + - Checks if Image IO is available + * - :doc:`af.iterative_deconv() ` + - Inverse Deconvolution using iterative methods + * - :doc:`af.load_image() ` + - Load an image from disk to an array + * - :doc:`af.load_image_memory() ` + - Load an image from memory which is stored as a FreeImage stream + * - :doc:`af.load_image_native() ` + - Load an image as is original type. + * - :doc:`af.maxfilt() ` + - Find maximum value from a window. + * - :doc:`af.mean_shift() ` + - Edge-preserving smoothing filter commonly used in object tracking and image segmentation. + * - :doc:`af.medfilt() ` + - Median Filter. + * - :doc:`af.medfilt1() ` + - 1D Median Filter. + * - :doc:`af.medfilt2() ` + - 2D Median Filter. + * - :doc:`af.minfilt() ` + - Find minimum value from a window. + * - :doc:`af.nearest_neighbour() ` + - Calculates which points in the train are nearest to each other point + * - :doc:`af.orb() ` + - ORB Feature descriptor. + * - :doc:`af.pad() ` + - Pad an array. + * - :doc:`af.regions() ` + - Find blobs in given image. + * - :doc:`af.resize() ` + - Resize an input image. + * - :doc:`af.rgb2gray() ` + - RGB to Grayscale colorspace converter. + * - :doc:`af.rgb2hsv() ` + - RGB to HSV colorspace converter. + * - :doc:`af.rgb2ycbcr() ` + - RGB to YCbCr colorspace converter. + * - :doc:`af.rotate() ` + - Rotate an input image or array. + * - :doc:`af.sat() ` + - Summed Area Tables. + * - :doc:`af.save_array() ` + - Save an array to a binary file + * - :doc:`af.save_image() ` + - Save an array to disk as an image + * - :doc:`af.save_image_memory() ` + - Save an array to memory as an image using FreeImage stream + * - :doc:`af.save_image_native() ` + - Save an image as is original type. + * - :doc:`af.scale() ` + - Scale an input image. + * - :doc:`af.sift() ` + - SIFT feature detector and descriptor extractor. + * - :doc:`af.sign() ` + - Return the sign of elements in an array. + * - :doc:`af.sin() ` + - Evaluate the sine function. + * - :doc:`af.skew() ` + - Skew an input image. + * - :doc:`af.sobel_operator() ` + - Perform a 2-D spatial gradient measurement on an image + * - :doc:`af.susan() ` + - SUSAN corner detector. + * - :doc:`af.transform() ` + - Transform an input image. + * - :doc:`af.transform_coordinates() ` + - Transform input coordinates to perspective. + * - :doc:`af.translate() ` + - Translate an input image. \ No newline at end of file diff --git a/docs/statistics_functions.rst b/docs/statistics_functions.rst new file mode 100644 index 0000000..59ad5bc --- /dev/null +++ b/docs/statistics_functions.rst @@ -0,0 +1,35 @@ +Statistics +============ + +Functions for computing statistical metrics and analyzing data distributions. + +.. list-table:: Functions + + * - :doc:`af.count() ` + - Count non-zero values in an array along a given dimension. + * - :doc:`af.hist_equal() ` + - Histogram equalization of input image. + * - :doc:`af.histogram() ` + - Histogram of input data. + * - :doc:`af.imax() ` + - Finds the maximum value. + * - :doc:`af.imin() ` + - Finds the minimum value. + * - :doc:`af.max() ` + - Return the maximum along a given dimension. + * - :doc:`af.maxof() ` + - Elementwise maximum between two arrays + * - :doc:`af.mean() ` + - Find the mean of values in the input. + * - :doc:`af.median() ` + - Find the median of values in the input. + * - :doc:`af.min() ` + - Return the minimum along a given dimension. + * - :doc:`af.minfilt() ` + - Find minimum value from a window. + * - :doc:`af.minof() ` + - Elementwise minimum between two arrays + * - :doc:`af.sttdev() ` + - Find the standard deviation of values in the input. + * - :doc:`af.sum() ` + - Sum array elements over a given dimension. \ No newline at end of file diff --git a/docs/timing_arrayfire.rst b/docs/timing_arrayfire.rst new file mode 100644 index 0000000..04b1de7 --- /dev/null +++ b/docs/timing_arrayfire.rst @@ -0,0 +1,62 @@ +Timing ArrayFire +================= + +Preamble +######## + +As shown in other sections, ArrayFire leverages Just-in-Time (JIT) compilation of kernels to speedup many array operations. +This means that after a function is called, the operation may not have finished (or even started) after execution continues +to the next line. Furthermore, the first time an operation is done, as it may be slowed down due to the JIT compilation of +the combined operations; later operations will not have this problem as the compiled kernel is cached. + +So benchmarking ArrayFire is not as straight forward as just wrapping an operation in between timers. + +Setup +####### + +For benchmarking we will utilize two functions: `af.sync()` and `af.eval(arr)`. + +- :doc:`af.sync `: The purpose of this function is to stall the current thread until all awaiting operations have finished and the result is accessable by the host. It synchronizes the host and the device, similar to what cuda.Stream.synchronize() does in cupy. + +- :doc:`af.eval `: This function takes in an array which will be forced to be evaluated immediately. This forces the JIT tree to be cut at the point of this function calls and any later operations will not be considered in this current JIT tree. + + +Using these two function we can make sure that we are benchmarking the correct operations by making sure that no operation is running +before or after we want our timers to measure. + +Example +########## + +The following is an examples of timing how long an addition takes + +.. code-block:: python + + import arrayfire as af + import time + + # Generate a random array + x = af.randn(1000000) + + # Make sure the numbers have been generated before the timing starts + af.eval(x) + af.sync() + + # Start timer + start = time.perf_counter() + y = x + x + + # Make sure the computation has finished before the timing ends + af.eval(y) + af.sync() + + # End timer + end = time.perf_counter() + + print(f"Elapsed time: {end - start:.6f} seconds") + + +Benchmarking JIT vs non-JIT +############################ + +For timing JIT operations against non-JIT operations, please take a look at page on JIT :doc:`arrayfirejitcodegeneration` and +the code in :download:`afjit.py`. \ No newline at end of file diff --git a/docs/tutorial.rst b/docs/tutorial.rst new file mode 100644 index 0000000..36bbcaf --- /dev/null +++ b/docs/tutorial.rst @@ -0,0 +1,14 @@ +Tutorial +======== + +* :doc:`Installation ` +* :doc:`Getting Started ` +* :doc:`Configuring ArrayFire Environment ` +* :doc:`Introduction to Vectorization ` +* :doc:`ArrayFire JIT Code Generation ` +* :doc:`Array and Matrix Manipulation ` +* :doc:`Indexing ` +* OpenCL Interoperability (Coming Soon) +* Forge Visualization (Coming Soon) +* :doc:`Timing ArrayFire ` +* :doc:`Debugging ArrayFire Code ` \ No newline at end of file diff --git a/docs/utilities_functions.rst b/docs/utilities_functions.rst new file mode 100644 index 0000000..6085b21 --- /dev/null +++ b/docs/utilities_functions.rst @@ -0,0 +1,89 @@ +Utilities +=========== + +General-purpose functions for managing arrays and devices. + +.. list-table:: Functions + + * - :doc:`af.alloc_device() ` + - Allocate memory on device + * - :doc:`af.alloc_host() ` + - Allocate memory on host. + * - :doc:`af.alloc_pinned() ` + - Allocate pinned memory on device. + * - :doc:`af.cublas_set_math_mode() ` + - Sets the cuBLAS math mode for the internal handle + * - :doc:`af.delete_image_memory() ` + - Delete memory created by saveImageMem + * - :doc:`af.det() ` + - Find the determinant of a matrix. + * - :doc:`af.device_gc() ` + - Call the garbage collection routine + * - :doc:`af.device_info() ` + - Gets the information about device and platform as strings. + * - :doc:`af.device_mem_info() ` + - Gets information about the memory manager + * - :doc:`af.free_device() ` + - Free memory allocated on device internally by ArrayFire. + * - :doc:`af.free_host() ` + - Free memory allocated on host internally by ArrayFire. + * - :doc:`af.free_pinned() ` + - Free pinned memory allocated by ArrayFire's memory manager. + * - :doc:`af.get_backend() ` + - Gets the backend enum for the active backend. + * - :doc:`af.get_dbl_support() ` + - Gets if the device supports double floating point + * - :doc:`af.get_device() ` + - Get the current device ID. + * - :doc:`af.get_device_count() ` + - Gets the number of compute devices on the system. + * - :doc:`af.get_half_support() ` + - Gets if the device supports half floating point + * - :doc:`af.get_kernel_cache_directory() ` + - Returns directory where ArrayFire JIT kernels are being stored + * - :doc:`af.get_mem_step_size() ` + - Get the minimum memory chunk size. + * - :doc:`af.get_native_id() ` + - Get the native device id of the CUDA device with id in ArrayFire context + * - :doc:`af.get_stream() ` + - Returns the current cuda stream + * - :doc:`af.info() ` + - Display ArrayFire and device info. + * - :doc:`af.info_string() ` + - Returns a string with information of current device and backend + * - :doc:`af.init() ` + - Initializes ArrayFire + * - :doc:`af.is_image_io_available() ` + - Checks if Image IO is available + * - :doc:`af.is_lapack_available() ` + - Check if lapack runtimes are available + * - :doc:`af.load_image() ` + - Load an image from disk to an array + * - :doc:`af.load_image_memory() ` + - Load an image from memory which is stored as a FreeImage stream + * - :doc:`af.load_image_native() ` + - Load an image as is original type. + * - :doc:`af.print_mem_info() ` + - Prints buffer details from the ArrayFire Device Manager + * - :doc:`af.read_array() ` + - Load an array from a file. + * - :doc:`af.save_array() ` + - Save an array to a binary file + * - :doc:`af.save_image() ` + - Save an array to disk as an image + * - :doc:`af.save_image_memory() ` + - Save an array to memory as an image using FreeImage stream + * - :doc:`af.save_image_native() ` + - Save an image as is original type. + * - :doc:`af.set_backend() ` + - Set the current backend + * - :doc:`af.set_device() ` + - Change current device to specified device. + * - :doc:`af.set_fft_plan_cache_size() ` + - Sets fft plan cache size + * - :doc:`af.set_kernel_cache_directory() ` + - Sets the directory for JIT kernel caching + * - :doc:`af.set_mem_step_size() ` + - Get the minimum memory chunk size. + * - :doc:`af.set_native_id() ` + - Set the CUDA device with given native id as the active device for ArrayFire \ No newline at end of file diff --git a/tests/test_documentation/__init__.py b/tests/test_documentation/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_documentation/test_documentation.py b/tests/test_documentation/test_documentation.py new file mode 100644 index 0000000..ddbb0de --- /dev/null +++ b/tests/test_documentation/test_documentation.py @@ -0,0 +1,402 @@ +import pytest +import arrayfire as af +import math + + + + +def test_array_shapes(): + # [gettingstarted1-snippet] + # Arrays may be created using the array constructor and dimensioned + # as 1D, 2D, 3D; however, the values in these arrays will be undefined + import arrayfire as af + + array = af.constant(0, (100,)) + array_2d = af.constant(0, (10, 100)) + array_3d = af.constant(0, (10, 10, 10)) + # [gettingstarted1-endsnippet] + assert array.shape == (100,) # Check shape of 1D array + assert array_2d.shape == (10, 100) # Check shape of 2D array + assert array_3d.shape == (10, 10, 10) # Check shape of 3D array + + + # [pi-example-simple-snippet] + # Monte Carlo estimation of pi +def calc_pi_device(samples) -> float: + # Simple, array based API + # Generate uniformly distributed random numers + x = af.randu(samples) + y = af.randu(samples) + # Supports Just In Time Compilation + # The following line generates a single kernel + within_unit_circle = (x * x + y * y) < 1 + # Intuitive function names + return 4 * af.count(within_unit_circle) / samples + # [pi-example-simple-endsnippet] + +def test_calc_pi_device(): + samples = 100000 + x = af.randu(samples) + y = af.randu(samples) + within_unit_circle = (x * x + y * y) < 1 + result = 4 * af.count(within_unit_circle) / samples + assert isinstance(result, float) + error = abs(result - math.pi) + tolerance = 0.01 + assert error < tolerance, f"Error ({error}) exceeds tolerance ({tolerance})" + + +# [gettingstarted2-snippet] +import arrayfire as af + +# Generate an array of size three filled with zeros. +# If no data type is specified, ArrayFire defaults to f32. +# The constant function generates the data on the device. +zeroes = af.constant(0,(3,)) + +# Generate a 1x4 array of uniformly distributed [0,1] random numbers +# The randu function generates the data on the device. +rand1 = af.randu((1,4)) + +# Generate a 2x2 array (or matrix, if you prefer) of random numbers +# sampled from a normal distribution. +# The randn function generates data on the device. +rand2 = af.randu((2,2)) + +# Generate a 3x3 identity matrix. The data is generated on the device. +iden = af.identity((3,3)) + +# Lastly, create a 2x1 array (column vector) of uniformly distributed +# 32-bit complex numbers (c32 data type): +randcplx = af.randu((2,1)) +# [gettingstarted2-endsnippet] + +import pytest +import arrayfire as af + +def test_arrayfire_operations(): + # Generate an array of size three filled with zeros + zeroes = af.constant(0, (3,)) + assert zeroes.shape == (3,) # Check shape + + # Generate a 1x4 array of uniformly distributed [0,1] random numbers + rand1 = af.randu((1, 4)) + assert rand1.shape == (1, 4) # Check shape + + # Generate a 2x2 array of random numbers sampled from a normal distribution + rand2 = af.randn((2, 2)) + assert rand2.shape == (2, 2) # Check shape + + # Generate a 3x3 identity matrix + iden = af.identity((3,3)) + assert iden.shape == (3, 3) # Check shape + + # Generate a 2x1 array (column vector) of uniformly distributed 32-bit complex numbers + randcplx = af.randu((2, 1)) + assert randcplx.shape == (2, ) # Check shape + +# [gettingstarted3-snippet] +import arrayfire as af +# Create a six-element array on the host +hA = ([0, 1, 2, 3, 4, 5]) + +# Which can be copied into an ArrayFire Array using the pointer copy +# constructor. Here we copy the data into a 2x3 matrix: +A = af.moddims(af.Array(hA),(2,3)) + + +# ArrayFire provides a convenince function for printing array +# objects in case you wish to see how the data is stored: +print(A) + +#todo how to create complex numbers +# [gettingstarted3-endsnippet] + + +def test_arrayfire_conversion(): + # Create a six-element array on the host + hA = ([0, 1, 2, 3, 4, 5]) + + # Copy data from host array to an ArrayFire array and reshape to 2x3 matrix + A = af.moddims(af.Array(hA),(2,3)) + + # Assert that the shape of A is (2, 3) + assert A.shape == (2, 3) + + # Assert that the elements in A match hA + for i in range(2): + for j in range(3): + assert A[i, j] == hA[i * 3 + j] + +# [gettingstarted11-snippet] + +import arrayfire as af + +# Create an array consisting of 3 random numbers +a = af.randu(3) + +# Get the scalar value of the array +val = a.scalar() + +# Print the scalar value +print(f"scalar value: {val}") +# [gettingstarted11-endsnippet] + + +import pytest +import arrayfire as af + +def test_arrayfire_scalar_value(): + # Create an array consisting of 3 random numbers + a = af.randu(3) + + # Get the scalar value of the array + val = a.scalar() + + # Assert that the scalar value is a float + assert isinstance(val, float) + + # Assert that the scalar value is between 0 and 1 (inclusive) + assert 0 <= val <= 1 + +def test_vectorization(): + + # [vectorization2-snippet] + + import arrayfire as af + + #[0, 9] + a = af.range(10) + + # [1, 10] + a = a+ 1 + # [vectorization2-endsnippet] + # Assertion: Verify the elements of the array 'a' + expected_result = af.Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) + assert a == expected_result + +def test_apply_filter(): + # [vectorization9-snippet] + + import arrayfire as af + + # Create the filter and weight vectors + filter = af.randu((1, 5)) + weights = af.randu((5, 5)) + + # Apply the filter using a for-loop equivalent + filtered_weights = af.constant(0, (5, 5)) + for i in range(weights.shape[1]): + filtered_weights[:, i] = af.matmul(filter, weights[:, i]) + + # Print the filtered weights array + print("Filtered weights:") + print(filtered_weights) + # [vectorization9-endsnippet] + assert filtered_weights.shape == (5, 5) + + + + +def test_filtered_weights(): + # [vectorization10-snippet] + + import arrayfire as af + + # Create the filter and weight vectors + filter = af.randu((1, 5)) # Shape: 1x5 + weights = af.randu((5, 5)) # Shape: 5x5 + + # Transpose the filter to align dimensions for broadcasting + filter_transposed = af.transpose(filter) # Shape: 5x1 + + # Element-wise multiplication with broadcasting + filtered_weights = filter_transposed * weights + + expected_shape = (5, 5) # Expected shape of filtered_weights + + # Assertions + assert filtered_weights.shape == expected_shape + + # Print the filtered weights array + print("Filtered weights:") + print(filtered_weights) + # [vectorization10-endsnippet] + +def test_flatten_array(): + # [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] + assert flat_a.shape == (9,) # Check if it's a 1-dimensional array + assert len(flat_a) == 9 # Check if it has 9 elements (3x3 array) + + +def test_flip_array(): + + # [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] + assert flip_a.shape == a.shape + assert af.flip(flip_a) == a + assert af.min(a) >= 0 + assert af.max(a) < 1 + assert af.min(flip_a) >= 0 + assert af.max(flip_a) < 1 + +def test_join_array(): + # [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] + assert a_join.shape == (10,) + + + +def test_moddims_operations(): + # [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] + assert moddims_a.shape == (2, 4) + assert moddims_b.shape == (8,) + assert a == af.moddims(moddims_a, (8,)) + assert a == moddims_b + + + +def test_arrayfire_shift(): + # [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] + + # Check if arrays are equal by comparing element-wise + assert a != a_shift + assert a != a_shift1 + assert a_shift.shape == (3,5) + assert a_shift1.shape == (3,5) + + +def transpose_arrayifre(): + # [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] + # Convert arrays to Python lists for comparison + a_list = a.to_array().tolist() + a_transpose_list = a_transpose.to_array().tolist() + + # Compute the expected transpose manually + expected_a_transpose = list(zip(*a_list)) + + # Check if the transpose operation is correct + assert a_transpose_list == expected_a_transpose + + + + +def test_moddims(): + # [indexing1-snippet] + + import arrayfire as af + + data = [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] + + A = af.Array(data) + A = af.moddims(A,(4,4)) + +# [indexing1-endsnippet] + expected_result = [ + [0, 1, 2, 3], + [4, 5, 6, 7], + [8, 9, 10, 11], + [12, 13, 14, 15] + ] + + dims = A.shape + A_list = [[A[i, j] for j in range(dims[1])] for i in range(dims[0])] + + # Check if the reshaped array matches the expected result + assert A_list == expected_result + + + +