Added more functions docs, added classes, constants, implemented reshape

Author: edwinsolisf

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,

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)
 

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:

arrayfire/library/computer_vision.py

@@ -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
     ----

docs/README.md

@@ -10,6 +10,7 @@ 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

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() <functions/cast>`
+            - Cast an array from one type to another.
+        * - :doc:`af.constant() <functions/constant>`
+            - Create an array from a scalar input value.
+        * - :doc:`af.copy_array() <functions/copy_array>`
+            - Performs a deep copy of the array.
+        * - :doc:`af.cplx() <functions/cplx>`
+            - Creates complex arrays from real and imaginary parts
+        * - :doc:`af.diag() <functions/diag>`
+            - Extract the diagonal from an array.
+        * - :doc:`af.eval() <functions/eval>`
+            - Evaluate an expression (nonblocking).
+        * - :doc:`af.gaussian_kernel() <functions/gaussian_kernel>`
+            - Creates a Gaussian Kernel.
+        * - :doc:`af.identity() <functions/identity>`
+            - Generate an identity matrix.
+        * - :doc:`af.iota() <functions/iota>`
+            - Generate an array with [0, n-1] values modified to specified dimensions and tiling.
+        * - :doc:`af.isinf() <functions/isinf>`
+            - Check if values are infinite.
+        * - :doc:`af.isnan() <functions/isnan>`
+            - Check if values are NaN.
+        * - :doc:`af.iszero() <functions/iszero>`
+            - Check if values are zero.
+        * - :doc:`af.lookup() <functions/lookup>`
+            - Lookup values of an array by indexing with another array.
+        * - :doc:`af.lower() <functions/lower>`
+            - Return the lower triangular matrix from an input array.
+            - Find maximum value from a window.
+        * - :doc:`af.ones() <functions/ones>`
+            - Creates an array filled with ones.\
+        * - :doc:`af.randn() <functions/randn>`
+            - Create a random array sampled from normal distribution.
+        * - :doc:`af.randu() <functions/randu>`
+            - Create a random array sampled from uniform distribution.
+        * - :doc:`af.range() <functions/range>`
+            - Generate an array with [0, n-1] values along the a specified dimension and tiled across other dimensions.
+        * - :doc:`af.upper() <functions/upper>`
+            - Return the upper triangular matrix from an input array.
+        * - :doc:`af.where() <functions/where>`
+            - Locate the indices of the non-zero values in an array.
+        * - :doc:`af.zeros() <functions/zeros>`
+            - Creates an array filled with zeros.

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() <functions/approx1>`
+            - Interpolation across a single dimension.
+        * - :doc:`af.approx1_uniform() <functions/approx1_uniform>`
+            - Interpolation across a single dimension in uniform steps
+        * - :doc:`af.approx2() <functions/approx2>`
+            - Interpolation along two dimensions.
+        * - :doc:`af.approx2_uniform() <functions/approx2_uniform>`
+            - Interpolation along two dimensions in uniform steps
+        * - :doc:`af.flat() <functions/flat>`
+            - Flatten an array.
+        * - :doc:`af.flip() <functions/flip>`
+            - Flip the input along a specified dimension.
+        * - :doc:`af.join() <functions/join>`
+            - Join up to 4 arrays along specified dimension.
+        * - :doc:`af.pad() <functions/pad>`
+            - Pad an array.
+        * - :doc:`af.reorder() <functions/reorder>`
+            - Reorder an array.
+        * - :doc:`af.replace() <functions/replace>`
+            - Replace elements of an array with elements of another array.
+        * - :doc:`af.reshape() <functions/reshape>`
+            - Modify the dimensions of an array without changing the order of its elements
+        * - :doc:`af.resize() <functions/resize>`
+            - Resize an input image.
+        * - :doc:`af.rotate() <functions/rotate>`
+            - Rotate an input image or array.
+        * - :doc:`af.scale() <functions/scale>`
+            - Scale an input image.
+        * - :doc:`af.select() <functions/select>`
+            - Select elements based on a conditional array.
+        * - :doc:`af.set_intersect() <functions/set_intersect>`
+            - Evaluate the intersection of two arrays
+        * - :doc:`af.set_union() <functions/set_union>`
+            - Evaluate the union of two arrays
+        * - :doc:`af.set_unique() <functions/set_unique>`
+            - Return the unique values in an array
+        * - :doc:`af.shift() <functions/shift>`
+            - Shift an array.
+        * - :doc:`af.sort() <functions/sort>`
+            - Sort an array over a given dimension
+        * - :doc:`af.tile() <functions/tile>`
+            - Generate a tiled array by repeating an array's contents along a specified dimension.
+        * - :doc:`af.transpose() <functions/transpose>`
+            - Transpose a matrix.
+        * - :doc:`af.unwrap() <functions/unwrap>`
+            - Rearrange windowed sections of an array into columns (or rows)
+        * - :doc:`af.wrap() <functions/wrap>`
+            - Performs the opposite of af::unwrap().