Merge remote-tracking branch 'upstream/main' into compile_to_trace

available_configs.json

@@ -1,7 +1,9 @@
 {
     "compiler": [
         "cp38-none-manylinux_2_17_x86_64",
-        "cp310-none-manylinux_2_17_x86_64"
+        "cp39-none-manylinux_2_17_x86_64",
+        "cp310-none-manylinux_2_17_x86_64",
+        "cp311-none-manylinux_2_17_x86_64"
     ],
     "engines": [
         "cp310-none-manylinux_2_17_x86_64"

docker/DockerfileGPUMultiCuda

@@ -60,7 +60,7 @@ SHELL ["/bin/bash", "-c"]
 
 
 RUN python3 multicuda_framework_directory.py $fw &&\
-    jq -r 'to_entries[] | select(.value != [""]) | .key as $dir | .value[] | @sh "/opt/fw/\($dir) \(.)"' requirement_mappings_gpu.json | xargs -I {} sh -c 'printf "Installing %s\n" $2 && pip install --ignore-installed --target $1 $2' sh {}
+    jq -r 'to_entries[] | select(.value != [""]) | .key as $dir | .value[] | @sh "/opt/fw/\($dir) \(.)"' requirement_mappings_gpu.json | xargs -I {} sh -c 'printf "Installing %s\n" $2 && pip install --ignore-installed --target $1 $2 --extra-index-url https://download.pytorch.org/whl/cu118' sh {}
 
 
 

docs/overview/contributing/setting_up.rst

@@ -10,6 +10,8 @@ Setting Up
 .. _`miniconda`: https://docs.conda.io/en/latest/miniconda.html
 .. _`venv`: https://docs.python.org/3/library/venv.html
 .. _`ivy/run_tests_CLI`: https://github.com/unifyai/ivy/tree/f71a414417646e1dfecb5de27fb555f80333932c/run_tests_CLI
+.. _`platform compatibility tags`: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/
+.. _`logging level`: https://docs.python.org/3/library/logging.html#logging.Logger.setLevel
 
 We're really happy you'd like to learn how to contribute towards Ivy 🙂
 
@@ -835,6 +837,49 @@ The steps are as following to setup testing on VS Code when using a new Codespac
 
 Note: Currently you do not need to comment out the :code:`conftest.py` file in the :code:`array_api_tests` directory.
 
+
+The Binaries
+------------
+
+Some features in :code:`ivy` are served as compiled binaries, such as the transpiler.
+These binaries aren't maintained in the :code:`ivy` repository directly, but on a separate :code:`binaries` repository.
+All the binaries that are required to make use of the full potential of :code:`ivy` are recorded in the :code:`binaries.json`.
+The supported configurations (Python version - OS - Architecture) are recorded in the :code:`available_configs.json`.
+
+The format of representing a configuration is based on PyPI's `platform compatibility tags`_,
+meaning :code:`cp310-none-manylinux_2_17_x86_64` represents a configuration that can be used in a Python 3.10 environment on a linux system with x86-64.
+We continue to add support to many more supported configurations to our binaries to work with various python versions, OS and architecture.
+
+On installing :code:`ivy` with :code:`pip install -e .` all the required binaries with a supported configuration to your system get downloaded.
+Just to have another check on whether all binaries are present, there's a warning that gets thrown when you :code:`import ivy` if any binaries are missing of the form,
+
+.. code-block:: none
+
+   WARNING:root:   Some binaries seem to be missing in your system. This could be either because we don't have compatible binaries for your system or that newer binaries were available.
+                   In the latter case, calling ivy.utils.cleanup_and_fetch_binaries() should fetch the binaries binaries. Feel free to create an issue on https://github.com/unifyai/ivy.git in case of the former
+
+   WARNING:root:
+   Following are the supported configurations :
+   compiler : cp38-none-manylinux_2_17_x86_64, cp310-none-manylinux_2_17_x86_64
+   engines : cp310-none-manylinux_2_17_x86_64
+
+   WARNING:root:   /workspaces/ivy/ivy/compiler/_compiler.so not found.
+
+In case there are no supported binaries for your configuration, then feel free to create an issue on the :code:`ivy` repo asking for adding support to the same.
+Feel free to ignore the warning in the meantime, set a `logging level`_ to avoid receiving the warning.
+In case the you are using a supported configuration and still receiving this warning, it indicates that you are yet to do a :code:`pip install -e .` as mentioned in the previous sections.
+Running a :code:`pip install -e .` is sufficient to download the binaries if they're supported but the :func:`ivy.utils.cleanup_and_fetch_binaries` function is provided just in case you want to download the binaries without a local installation.
+
+.. code-block:: python
+
+   import ivy
+
+   ivy.utils.cleanup_and_fetch_binaries()
+
+
+.. note:: Bear in mind that the binaries are **not** required for working on the open tasks for the most part, so it's totally fine to not have the binaries downloaded on your system for working on any of the open tasks.
+
+
 **Video**
 
 .. raw:: html

ivy/compiler/compiler.py

@@ -1,14 +1,4 @@
-from typing import Callable, Optional, List, Union, Iterable, Tuple, Any
-
-
-# TODO: create meaningful types for Graph and LazyGraph,
-# will probably need a seperate file for that
-class Graph:
-    pass
-
-
-class LazyGraph:
-    pass
+from typing import Callable, Optional, List, Union, Iterable, Tuple
 
 
 def trace_graph(
@@ -26,27 +16,27 @@ def trace_graph(
     mode: Optional[str] = None,
     graph_caching: bool = False,
     args: Optional[Tuple] = None,
-    kwargs: Optional[dict] = None,
-) -> Union[Graph, LazyGraph]:
+    kwargs: Optional[dict] = None
+):
     """
-    Take `fn` and traces it into a more efficient composition of backend operations.
+    Takes `fn` and traces it into a more efficient composition of backend operations.
 
     Parameters
     ----------
     objs
         callable(s) to trace and create a graph of
     stateful
-        list of instances to be considered stateful during the graph compilation
+        list of instances to be considered stateful during the graph tracing
     arg_stateful_idxs
-        positional arguments to be considered stateful during the graph compilation
+        positional arguments to be considered stateful during the graph tracing
     kwarg_stateful_idxs
-        keyword arguments to be considered stateful during the graph compilation
+        keyword arguments to be considered stateful during the graph tracing
     include_generators
         include array creation/generation functions as part of the graph
     array_caching
         cache the constant arrays that appear as arguments to the functions in the graph
     backend_compile
-        whether to apply the native compilers, i.e. tf.function, after ivy's compilation
+        whether to apply the native compilers, i.e. tf.function, after ivy's tracing
     static_argnums
         for jax's jit compilation
     static_argnames
@@ -67,7 +57,7 @@ def trace_graph(
     Examples
     --------
     >>> import ivy, time
-    >>> from ivy import compile
+    >>> from ivy import trace_graph
     >>> ivy.set_backend("torch")
     >>> x = ivy.array([1.])
 
@@ -98,7 +88,8 @@ def trace_graph(
     >>> print(time.time() - start)
     0.0001785755157470703
     """
-    from ._compiler import compile as _trace_graph
+
+    from ._compiler import trace_graph as _trace_graph
 
     return _trace_graph(
         *objs,
@@ -133,10 +124,10 @@ def transpile(
     arg_stateful_idxs: Optional[List] = None,
     kwarg_stateful_idxs: Optional[List] = None,
     args: Optional[Tuple] = None,
-    kwargs: Optional[Any] = None,
+    kwargs: Optional[dict] = None,
     params_v=None,
-    v=None,  # Make this cleaner
-) -> Union[Graph, LazyGraph]:
+    v=None
+):
     """
     Transpiles Callable objects passed as arguments. If args and kwargs are specified,
     transpilation is performed eagerly, otherwise, transpilation will happen lazily.
@@ -158,6 +149,7 @@ def transpile(
     -------
     Either a transpiled Graph or a non-initialized LazyGraph.
     """
+
     from ._compiler import transpile as _transpile
 
     return _transpile(
@@ -187,8 +179,8 @@ def unify(
     args: Optional[Tuple] = None,
     kwargs: Optional[dict] = None,
     with_numpy: bool = True,
-    **transpile_kwargs,
-) -> Callable:
+    **transpile_kwargs
+):
     from ._compiler import unify as _unify
 
     return _unify(

ivy/data_classes/array/elementwise.py

@@ -1438,6 +1438,27 @@ def log2(self: ivy.Array, *, out: Optional[ivy.Array] = None) -> ivy.Array:
             an array containing the evaluated base ``2`` logarithm for each element
             in ``self``. The returned array must have a real-valued floating-point
             data type determined by :ref:`type-promotion`.
+
+        Examples
+        --------
+        Using :code:`ivy.Array` instance method:
+
+        >>> x = ivy.array([5.0, 1, -0.0, -6.0])
+        >>> y = ivy.log2(x)
+        >>> print(y)
+        ivy.array([2.32, 0., -inf, nan])
+
+        >>> x = ivy.array([float('nan'), -5.0, -0.0, 1.0, 5.0, float('+inf')])
+        >>> y = x.log2()
+        >>> print(y)
+        ivy.array([nan, nan, -inf, 0., 2.32, inf])
+
+        >>> x = ivy.array([[float('nan'), 1, 5.0, float('+inf')],\
+                            [+0, -2.0, -5, float('-inf')]])
+        >>> y = x.log2()
+        >>> print(y)
+        ivy.array([[nan, 0., 2.32, inf],
+                   [-inf, nan, nan, nan]])
         """
         return ivy.log2(self._data, out=out)
 

ivy/data_classes/array/experimental/activations.py

@@ -337,3 +337,26 @@ def hardtanh(
         ivy.array([-1., 1., 1.])
         """
         return ivy.hardtanh(self._data, min_val=min_val, max_val=max_val, out=out)
+
+    def tanhshrink(self: ivy.Array, /, *, out: Optional[ivy.Array] = None) -> ivy.Array:
+        """
+        ivy.Array instance method variant of ivy.tanhshrink. This method simply wraps
+        the function, and so the docstring for ivy.tanhshrink also applies to this
+        method with minimal changes.
+
+        Parameters
+        ----------
+        self
+            input array.
+        out
+            optional output array, for writing the result to. It must have a shape
+            that the inputs broadcast to.
+
+        Examples
+        --------
+        >>> x = ivy.array([-1., 0., 1.])
+        >>> y = x.tanhshrink()
+        >>> print(y)
+        ivy.array([-0.23840582,  0.        ,  0.23840582])
+        """
+        return ivy.tanhshrink(self._data, out=out)

ivy/data_classes/array/linear_algebra.py

@@ -759,6 +759,19 @@ def qr(
             is 'complete', the array must have shape (..., M, N). If mode is 'reduced',
             the array must have shape (..., K, N), where K = min(M, N). The first
             x.ndim-2 dimensions must have the same size as those of the input x.
+
+        Examples
+        --------
+        >>> x = ivy.array([[1.,2.,3.],[4.,5.,6.],[7.,8.,9.]])
+        >>> q, r = x.qr(mode='reduced')
+        >>> print(q)
+        ivy.array([[-0.12309149,  0.90453403,  0.40824829],
+            [-0.49236596,  0.30151134, -0.81649658],
+            [-0.86164044, -0.30151134,  0.40824829]])
+        >>> print(r)
+        ivy.array([[-8.12403841e+00,-9.60113630e+00, -1.10782342e+01],
+            [ 0.00000000e+00,  9.04534034e-01,  1.80906807e+00],
+            [ 0.00000000e+00,  0.00000000e+00, -8.88178420e-16]])
         """
         return ivy.qr(self._data, mode=mode, out=out)
 

ivy/data_classes/container/elementwise.py

@@ -5167,6 +5167,21 @@ def _static_log2(
             a container containing the evaluated base ``2`` logarithm for
             each element in ``x``. The returned array must have a real-valued
             floating-point data type determined by :ref:`type-promotion`.
+
+        Examples
+        --------
+        Using :code:`ivy.Container` input:
+
+        >>> x = ivy.Container(a=ivy.array([0.0, float('nan')]),\
+                              b=ivy.array([-0., -4.9, float('+inf')]),\
+                              c=ivy.array([8.9, 2.1, 1.]))
+        >>> y = ivy.Container.static_log2(x)
+        >>> print(y)
+        {
+            a: ivy.array([-inf, nan]),
+            b: ivy.array([-inf, nan, inf]),
+            c: ivy.array([3.15, 1.07, 0.])
+        }
         """
         return ContainerBase.cont_multi_map_in_function(
             "log2",
@@ -5217,6 +5232,21 @@ def log2(
             a container containing the evaluated base ``2`` logarithm for each
             element in ``self``. The returned array must have a real-valued
             floating-point data type determined by :ref:`type-promotion`.
+
+        Examples
+        --------
+        Using :code:`ivy.Container` instance method:
+
+        >>> x = ivy.Container(a=ivy.array([0.0, float('nan')]),
+        ...                   b=ivy.array([-0., -5.9, float('+inf')]),
+        ...                   c=ivy.array([8.9, 2.1, 1.]))
+        >>> y = ivy.log2(x)
+        >>> print(y)
+        {
+            a: ivy.array([-inf, nan]),
+            b: ivy.array([-inf, nan, inf]),
+            c: ivy.array([3.15, 1.07, 0.])
+        }
         """
         return self._static_log2(
             self,