Added descriptions to more functions and examples

Author: edwinsolisf

docs/README.md

@@ -1,13 +1,15 @@
-Documentation
+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 [requirements.txt](../requirements.txt)
+1. Install the required sphinx packages and extensions from the [dev-requirements.txt](../dev-requirements.txt)
 ```sh
-pip install -r requirements.txt # install sphinx and its extensions
+pip install -r dev-requirements.txt # install sphinx and its extensions
 ```
 2. Build docs using sphinx
 ```sh

docs/configuringarrayfireenvironment.rst

@@ -6,4 +6,9 @@ Environment Variables
 =====================
 The following are useful environment variable that can be used with ArrayFire.
 
-
+* `AF_VERBOSE_LOADS`
+* `AF_CUDA_DEFAULT_DEVICE`
+* `AF_OPENCL_DEFAULT_DEVICE`
+* `AF_ONEAPI_DEFAULT_DEVICE`
+* `AF_TRACE`
+* `AF_PRINT_ERRORS`

docs/examples.rst

@@ -2,6 +2,40 @@ Examples
 ========
 
 
-TO DO
------
-ADD LIST OF EXAMPLES
+.. collapse:: Getting Started
+
+    .. list-table::
+
+        * - :doc:`intro.py`
+            - Shows how to set a device, initialize arrays, and do some array operations
+        * - :doc:`convolve.py`
+            - Shows how to do convolutions on 2D images
+
+.. collapse:: Linear Algebra
+
+    .. list-table::
+
+        * - :doc:`cholesky.py`
+            - Shows Cholesky decomposition in/out of place
+        * - :doc:`lu.py`
+            - Shows LU factorization in/out of place
+        * - :doc:`qr.py`
+            - Shows QR factorization in/out of place
+
+.. collapse:: Financial
+
+    .. list-table::
+
+        * - :doc:`black_scholes_options.py`
+            - Recreates black scholes options model utilizing ArrayFire's random and vectorization operations
+        * - :doc:`heston_model.py`
+            - Recreates heston model simultation utilizing ArrayFire's random and vectorization operations
+        * - :doc:`monte_carlo_options.py`
+            - Simulates monte carlo options model utilizing ArrayFire's random and vectorization operations
+
+.. collapse:: Benchmarks
+
+    .. list-table::
+
+        * - :doc:`monte_carlo_pi.py`
+            - Recreates a monte carlo method of calculating the digits of pi ArrayFire's random and vectorization operations

docs/functions.rst

@@ -22,6 +22,12 @@ Documentation grouped by category:
             - Creates an array filled with zeros.
         * - :doc:`af.ones() <functions/ones>`
             - Creates an array filled with ones.
+        * - :doc:`af.constant() <functions/constant>`
+            - Creates an array filled with a scalar value.
+        * - :doc:`af.range() <functions/range>`
+            - Creates an array filled with a range of linear indices along a dimension.
+        * - :doc:`af.iota() <functions/iota>`
+            - Creates an array filled with a range of linear indices along multiple dimensions
         * - :doc:`af.randu() <functions/randu>`
             - Creates an array with random uniform values.
         * - :doc:`af.randn() <functions/randn>`
@@ -54,6 +60,8 @@ Documentation grouped by category:
             - Computes the square root of each element.
         * - :doc:`af.matmul() <functions/matmul>`
             - Matrix multiplication.
+        * - :doc:`af.gemm() <functions/gemm>`
+            - General matrix multiplication.
         * - :doc:`af.inv() <functions/inv>`
             - Computes the inverse of a matrix.
         * - :doc:`af.det() <functions/det>`
@@ -80,6 +88,10 @@ Documentation grouped by category:
             - Matrix multiplication.
         * - :doc:`af.set_device() <functions/set_device>`
             - Gets the current device.
+        * - :doc:`af.set_backend() <functions/set_backend>`
+            - Sets the current backend.
+        * - :doc:`af.get_backend() <functions/get_backend>`
+            - Gets the current backend.
         * - :doc:`af.get() <functions/get>`
             - Copies data from the GPU to the CPU.
         * - :doc:`af.min() <functions/min>`

docs/functions/constant.rst

@@ -0,0 +1,31 @@
+constant
+========
+The 'af.constant()' function in the ArrayFire library is used to create arrays filled with a specific scalar value. 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.constant()`
+    - Python interface to create a multi-dimensional array filled with a constant value.
+
+Detailed Description
+--------------------
+The 'af.constant()' function creates an ArrayFire array where every element is initialized to the scalar (integer, floating point, or complex) value specified. 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.constant()
+
+    Syntax:
+        af.constant(scalar, dims, dtype)
+    
+    Parameters:
+        'scalar': value that will be used to initialize 
+        'dims': List of 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, etc.
+        'dtype': type that will be used to store the value internally. For example, af.int64 for signed 64-bit integer, af.float32 for 32-bit floating-point, and af.float64 for 64-bit floating-point
+
+    Returns:
+        An ArrayFire array with the specified dimensions and data type, where all elements are initialized to a scalar value.
+
+

docs/functions/gemm.rst

@@ -0,0 +1,31 @@
+gemm
+======
+The 'af.matmul()' function in ArrayFire performs general matrix multiplication. General Matrix multiplication is a fundamental operation in linear algebra and is widely used in various neural networks, scientific and engineering computations.
+
+Function
+--------
+:literal:`af.gemm()`
+    - Python interface used to perform general matrix multiplication
+
+Detailed Description
+--------------------
+The af.gemm() function computes the general matrix product of various input arrays. General Matrix multiplication is defined for three matrices A, B, C and two scalars alpha and beta as the operation alpha * A * B + beta * C where the number of columns in A is equal to the number of rows in B, while C has the same number of columns as B and same number of rows as A. The result is that is a weighted average of the matrix multiplication between A and B, and the accumulator matrix C.
+
+Function Documentation
+----------------------
+.. sidebar:: af.gemm()
+
+    Syntax:
+        af.matmul(A, B, alpha=alpha, beta=beta, accum=C, lhs_opts=lhs_opts, rhs_opts=rhs_opts)
+
+    Parameters:
+        'A': The first input array (matrix) to be multiplied.
+        'B': The second input array (matrix) to be multiplied.
+        'alpha': scalar that will be multiplied with the matrix multiplication. If not specified, this is taken to be one and the output is the same as 'matmul'
+        'beta': scalar that will be multiplied with the accumulator. If not specified, this is taken to be zero and the output is the same as 'matmul'
+        'C': The accumulator input array that will be added to the matrix multiplication. If not specified, this behaves as array full of zeros and the output is the same as 'matmul'
+        'lhs_opts': specifies any type of transpose operation should be executed on 'A' prior to the matrix multiplication
+        'rhs_opts': specifies any type of transpose operation should be executed on 'B' prior to the matrix multiplication
+
+    Returns:
+        An ArrayFire array representing the result of the general matrix multiplication:

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.

docs/functions/iota.rst

@@ -0,0 +1,28 @@
+iota
+=======
+The 'af.iota()' function in ArrayFire generates a multi-dimensional ArrayFire array with values populated based on their linear index within the array, optionally tiling the result to create larger arrays. 
+
+Function
+--------
+:literal:`af.iota()`
+    - Python interface used to generate linear indices with optional tiling
+
+Detailed Description
+--------------------
+The 'af.iota()' function is used to generate array of a sequence of indices starting at 0 and ending at (exclusive) the size of the 'shape' dimensions specified, filling the array in column major ordering to the 'shape' specified that it is then duplicated as specified by the 'tile_shape'.
+
+Function Documentation
+----------------------
+.. sidebar:: af.iota()
+
+    Syntax:
+        af.iota(shape, tile_shape, dtype)
+    
+    Parameters:
+        'shape': List of Integers specifying the dimensions for which the sequence of integers is generated.
+        'tile_shape': List of integers specifying the number of times the indices should be tiled in each dimension.
+        'dtype': type that will be used to store the value internally. For example, af.int64 for signed 64-bit integer, af.float32 for 32-bit floating-point, and af.float64 for 64-bit floating-point
+
+    Returns:
+        An ArrayFire array of linear indices with the dimensions 'shape * tile_shape'
+

docs/functions/range.rst

@@ -0,0 +1,29 @@
+range
+=======
+The 'af.range()' function in ArrayFire generates a multi-dimensional ArrayFire array of linear indices using the length of a dimension as a range, tiling the indices on the other dimensions.
+
+Function
+--------
+:literal:`af.range()`
+    - Python interface used to generate a range in one dimension while tiling other dimensions
+
+Detailed Description
+--------------------
+The 'af.range()' function is used to generate array of a sequence of indices starting at 0 and ending at (exclusive) the size of the length of the dimension specified, then it is duplicated on the remaining dimensions specified by 'shape'.
+
+Function Documentation
+----------------------
+.. sidebar:: af.range()
+
+    Syntax:
+        af.range(shape, tile_shape, dtype)
+    
+    Parameters:
+        'shape': List of Integers specifying the dimensions for which the sequence of integers is generated.
+        'axis': Integer from 0 to 3 (by default 0) specifying the dimension to use to generate the linear index range
+        'dtype': type that will be used to store the value internally. For example, af.int64 for signed 64-bit integer, af.float32 for 32-bit floating-point, and af.float64 for 64-bit floating-point
+
+    Returns:
+        An ArrayFire array of linear indices along 'axis' with the dimensions of 'shape'
+
+

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