-
As always, you can find more information about [Ivy as a framework in
the
@@ -437,7 +380,7 @@ expected. :sweat_smile:
``` bash
git clone https://github.com/unifyai/ivy.git
-cd ivy
+cd ivy
pip install --user -e .
```
@@ -1526,7 +1469,7 @@ device = "cuda:0" if ivy.gpu_is_available() else "cpu"
# training hyperparams
optimizer= ivy.Adam(1e-4)
-batch_size = 64
+batch_size = 64
num_epochs = 20
num_classes = 10
@@ -1600,7 +1543,7 @@ def train(images, classes, epochs, model, device, num_classes=10, batch_size=32)
f.writerows(metrics)
-# assuming the dataset(images and classes) are already prepared in a folder
+# assuming the dataset(images and classes) are already prepared in a folder
train(images, classes, num_epochs, model, device, num_classes = num_classes, batch_size = batch_size)
```
diff --git a/automation_tools/checklists/frontend_checklist.md b/automation_tools/checklists/frontend_checklist.md
index ecfe3226b0dc7..53fc5f25e99b1 100644
--- a/automation_tools/checklists/frontend_checklist.md
+++ b/automation_tools/checklists/frontend_checklist.md
@@ -6,7 +6,7 @@ The [Ivy Docs](https://unify.ai/docs/ivy/) represent the ground truth for the ta
Please note that the contributor is not expected to understand everything in the checklist. It's mainly here for the reviewer to make sure everything has been done correctly 🙂
#### LEGEND 🗺:
-- ❌ : Check item is not completed.
+- ❌ : Check item is not completed.
- ✅ : Check item is ready for review.
- 🆘 : Stuck/Doubting implementation (PR author should add comments explaining why).
- ⏩ : Check is not applicable to function (skip).
@@ -24,15 +24,15 @@ Please note that the contributor is not expected to understand everything in the
2. - [ ] ❌: A ToDo comment has been added prompting to pass the frontend argument to the ivy function whose behavior is to be extended.
6. - [ ] ❌: In case a frontend function is being added:
1. - [ ] ❌: It is a composition of ivy functions.
- 2. - [ ] ❌: In case the needed composition is long (using numerous ivy functions), a `Missing Function Suggestion` issue has been opened to suggest a new ivy function should be added to shorten the frontend implementation.
+ 2. - [ ] ❌: In case the needed composition is long (using numerous ivy functions), a `Missing Function Suggestion` issue has been opened to suggest a new ivy function should be added to shorten the frontend implementation.
3. - [ ] ❌: `@to_ivy_arrays_and_back` has been added to the function.
7. - [ ] ❌: In case a frontend method is being added:
- 1. - [ ] ❌: It is composed of existing frontend functions or methods.
+ 1. - [ ] ❌: It is composed of existing frontend functions or methods.
2. - [ ] ❌: If a required frontend function has not yet been added, the method may be implemented as a composition of ivy functions, making sure that:
- [ ] ❌: `@to_ivy_arrays_and_back` has been added to the method.
- [ ] ❌: A ToDo comment has been made prompting to remove the decorator and update the implementation as soon as the missing function has been added.
8. - [ ] ❌: The function/method's test has been added (except in the alias case mentioned in <2>):
- 1. - [ ] ❌: All supported arguments are being generated in `handle_frontend_test`/`handle_frontend_method` and passed to `test_frontend_function`/`test_frontend_method`.
+ 1. - [ ] ❌: All supported arguments are being generated in `handle_frontend_test`/`handle_frontend_method` and passed to `test_frontend_function`/`test_frontend_method`.
2. - [ ] ❌: The argument generation covers all possible supported values. Array sizes, dimensions, and axes adhere to the full supported set of the original function/method.
3. - [ ] ❌: The `available_dtypes` parameter passed to the helper generating the function/method's input array is set to `helpers.get_dtypes("valid")`. If there are unsupported dtypes that cause the test to fail, they should be handled by adding `@with_supported_dtypes`/`@with_unsupported_dtype` to the function/method.
9. - [ ] ❌: The PR is not introducing any test failures.
diff --git a/automation_tools/checklists/reformat_checklist.md b/automation_tools/checklists/reformat_checklist.md
index d3b185224f6fd..0e40e9804211a 100644
--- a/automation_tools/checklists/reformat_checklist.md
+++ b/automation_tools/checklists/reformat_checklist.md
@@ -4,7 +4,7 @@
The [Ivy Docs](https://unify.ai/docs/ivy/) represent the ground truth for the task descriptions and this checklist should only be used as a supplementary item to aid with the review process.
#### LEGEND 🗺:
-- ❌ : Check item is not completed.
+- ❌ : Check item is not completed.
- ✅ : Check item is ready for review.
- 🆘 : Stuck/Doubting implementation (PR author should add comments explaining why).
- ⏩ : Check is not applicable to function (skip).
@@ -16,7 +16,7 @@ The [Ivy Docs](https://unify.ai/docs/ivy/) represent the ground truth for the ta
- [ ] ❌: [ivy/functional/backends/numpy/{{ .category_name }}.py](https://github.com/unifyai/ivy/tree/main/ivy/functional/backends/numpy/{{ .category_name }}.py).
- [ ] ❌: [ivy/functional/backends/tensorflow/{{ .category_name }}.py](https://github.com/unifyai/ivy/tree/main/ivy/functional/backends/tensorflow/{{ .category_name }}.py).
- [ ] ❌: [ivy/functional/backends/torch/{{ .category_name }}.py](https://github.com/unifyai/ivy/tree/main/ivy/functional/backends/torch/{{ .category_name }}.py).
-2. - [ ] ❌: Implement the following if they don't exist:
+2. - [ ] ❌: Implement the following if they don't exist:
1. - [ ] ❌: The `ivy.Array` instance method in [ivy/data_classes/array/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/{{ .category_name }}.py).
2. - [ ] ❌: The `ivy.Array` special method in [ivy/data_classes/array/array.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/array.py).
3. - [ ] ❌: The `ivy.Array` reverse special method in [ivy/data_classes/array/array.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/array.py).
@@ -25,11 +25,11 @@ The [Ivy Docs](https://unify.ai/docs/ivy/) represent the ground truth for the ta
6. - [ ] ❌: The `ivy.Container` special method in [ivy/data_classes/container/container.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/container.py).
7. - [ ] ❌: The `ivy.Container` reverse special method in [ivy/data_classes/container/container.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/container.py).
3. - [ ] ❌: Make sure that the aforementioned methods are added into the correct category-specific parent class, such as `ivy.ArrayWithElementwise`, `ivy.ContainerWithManipulation` etc.
-4. - [ ] ❌: Correct all of the [Function Arguments and the type hints](https://unify.ai/docs/ivy/overview/deep_dive/function_arguments.html#function-arguments) for every function **and** its _relevant methods_, including those you did not implement yourself.
-5. - [ ] ❌: Add the correct [Docstrings](https://unify.ai/docs/ivy/overview/deep_dive/docstrings.html#docstrings) to every function **and** its _relevant methods_, including those you did not implement yourself. The following should be added:
- 1. - [ ] ❌: The function's [Array API standard](https://data-apis.org/array-api/latest/index.html) description in [ivy/functional/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/functional/ivy/{{ .category_name }}.py). If the function is not part of the Array API standard then a description of similar style should be added to the same file.
+4. - [ ] ❌: Correct all of the [Function Arguments and the type hints](https://unify.ai/docs/ivy/overview/deep_dive/function_arguments.html#function-arguments) for every function **and** its _relevant methods_, including those you did not implement yourself.
+5. - [ ] ❌: Add the correct [Docstrings](https://unify.ai/docs/ivy/overview/deep_dive/docstrings.html#docstrings) to every function **and** its _relevant methods_, including those you did not implement yourself. The following should be added:
+ 1. - [ ] ❌: The function's [Array API standard](https://data-apis.org/array-api/latest/index.html) description in [ivy/functional/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/functional/ivy/{{ .category_name }}.py). If the function is not part of the Array API standard then a description of similar style should be added to the same file.
The following modifications should be made to the description:
- - [ ] ❌: Remove type definitions in the `Parameters` and `Returns` sections.
+ - [ ] ❌: Remove type definitions in the `Parameters` and `Returns` sections.
- [ ] ❌: Add `out` to the `Parameters` section if function accepts an `out` argument.
- [ ] ❌: Replace `out` with `ret` in the `Returns` section.
2. - [ ] ❌: Reference to docstring for ivy.function_name ([5.a](#ref1)) for the function description **and** modified `Parameters` and `Returns` sections as described in [the docs](https://unify.ai/docs/ivy/overview/deep_dive/docstrings.html#docstrings) in:
@@ -40,48 +40,48 @@ The [Ivy Docs](https://unify.ai/docs/ivy/) represent the ground truth for the ta
- [ ] ❌: [ivy/container/container.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/container.py) if the function has a special method ( like `__function_name__` ).
- [ ] ❌: [ivy/container/container.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/container.py) if the function has a reverse special method ( like `__rfunction_name__` ).
6. - [ ] ❌: Add thorough [Docstring Examples](https://unify.ai/docs/ivy/overview/deep_dive/docstring_examples.html#docstring-examples) for every function **and** its _relevant methods_ and ensure they pass the docstring tests.
-
+
**Functional Examples** in [ivy/functional/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/functional/ivy/{{ .category_name }}.py).
- 1. - [ ] ❌: Cover all possible variants for each of the arguments independently (not combinatorily).
+ 1. - [ ] ❌: Cover all possible variants for each of the arguments independently (not combinatorily).
2. - [ ] ❌: Vary the values and input shapes considerably between examples.
3. - [ ] ❌: Start out simple and get more complex with each example.
- 4. - [ ] ❌: Show an example with:
- - [ ] ❌: `out` unused.
+ 4. - [ ] ❌: Show an example with:
+ - [ ] ❌: `out` unused.
- [ ] ❌: `out` used to update a new array y.
- - [ ] ❌: `out` used to inplace update the input array x (if x has the same dtype and shape as the return).
- 5. - [ ] ❌: If broadcasting is relevant for the function, then show examples which highlight this.
-
+ - [ ] ❌: `out` used to inplace update the input array x (if x has the same dtype and shape as the return).
+ 5. - [ ] ❌: If broadcasting is relevant for the function, then show examples which highlight this.
+
**Nestable Function Examples** in [ivy/functional/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/functional/ivy/{{ .category_name }}.py).
Only if the function supports nestable operations.
-
- 6. - [ ] ❌: Add an example that passes in an `ivy.Container` instance in place of one of the arguments.
+
+ 6. - [ ] ❌: Add an example that passes in an `ivy.Container` instance in place of one of the arguments.
7. - [ ] ❌: Add an example passes in `ivy.Container` instances for multiple arguments.
-
+
**Container Static Method Examples** in [ivy/container/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/{{ .category_name }}.py).
8. - [ ] ❌: The example from point ([6.f](#ref2)) should be replicated, but added to the `ivy.Container` **static method** docstring in with `ivy.` replaced with `ivy.Container.static_` in the example.
9. - [ ] ❌: The example from point ([6.g](#ref3)) should be replicated, but added to the `ivy.Container` **static method** docstring, with `ivy.` replaced with `ivy.Container.static_` in the example.
-
+
**Array Instance Method Example** in [ivy/array/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/{{ .category_name }}).
-
+
10. - [ ] ❌: Call this instance method of the `ivy.Array` class.
-
+
**Container Instance Method Example** in [ivy/container/{{ .category_name }}.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/{{ .category_name }}.py).
-
+
11. - [ ] ❌: Call this instance method of the `ivy.Container` class.
-
+
**Array Operator Examples** in [ivy/array/array.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/array.py).
-
+
12. - [ ] ❌: Call the operator on two `ivy.Array` instances.
13. - [ ] ❌: Call the operator with an `ivy.Array` instance on the left and `ivy.Container` on the right.
-
+
**Array Reverse Operator Example** in [ivy/array/array.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/array/array.py).
-
+
14. - [ ] ❌: Call the operator with a `Number` on the left and an `ivy.Array` instance on the right.
-
+
**Container Operator Examples** in [ivy/container/container.py](https://github.com/unifyai/ivy/blob/main/ivy/data_classes/container/container.py).
-
+
15. - [ ] ❌: Call the operator on two `ivy.Container` instances containing Number instances at the leaves.
16. - [ ] ❌: Call the operator on two `ivy.Container` instances containing `ivy.Array` instances at the leaves.
17. - [ ] ❌: Call the operator with an `ivy.Container` instance on the left and `ivy.Array` on the right.
diff --git a/automation_tools/dashboard_automation/update_db.py b/automation_tools/dashboard_automation/update_db.py
index 42c3f19cefa84..092e313725f91 100644
--- a/automation_tools/dashboard_automation/update_db.py
+++ b/automation_tools/dashboard_automation/update_db.py
@@ -22,9 +22,10 @@
def make_clickable(url, name):
- return ''.format(name)
+ return (
+ f''
+ )
def update_test_results():
@@ -45,7 +46,7 @@ def update_test_results():
res = make_clickable(action_url + run_id, result_config[result])
collection.update_one(
{"_id": test_configs[workflow][1]},
- {"$set": {backend + "." + submodule: res}},
+ {"$set": {f"{backend}.{submodule}": res}},
upsert=True,
)
return
diff --git a/determine_test_coverage.py b/determine_test_coverage.py
index e2fcbf0ab6691..588399a9ab8e5 100644
--- a/determine_test_coverage.py
+++ b/determine_test_coverage.py
@@ -17,8 +17,7 @@
test_names = get_all_tests()
# Create a Dictionary of Test Names to Index
-tests["index_mapping"] = test_names
-tests["tests_mapping"] = {}
+tests = {"index_mapping": test_names, "tests_mapping": {}}
for i in range(len(test_names)):
tests["tests_mapping"][test_names[i]] = i
@@ -47,7 +46,7 @@
for directory in directories:
for file_name in os.listdir(directory):
if file_name.endswith("cover"):
- file_name = directory + "/" + file_name
+ file_name = f"{directory}/{file_name}"
if file_name not in tests:
tests[file_name] = []
with open(file_name) as f:
diff --git a/determine_tests.py b/determine_tests.py
index d3a94ddc91fab..c422d2bee1e2e 100644
--- a/determine_tests.py
+++ b/determine_tests.py
@@ -44,15 +44,15 @@ def main():
modified_files = commit._parse_diff(diff_index)
for file in modified_files:
try:
- file_name = file.new_path + ",cover"
+ file_name = f"{file.new_path},cover"
except: # noqa
continue
if file_name not in tests.keys():
continue
tests_file = tests[file_name]
change = file.diff_parsed
- added = set([x - 1 for (x, _) in change["added"]])
- deleted = set([x - 1 for (x, _) in change["deleted"]])
+ added = {x - 1 for (x, _) in change["added"]}
+ deleted = {x - 1 for (x, _) in change["deleted"]}
updated = added.intersection(deleted)
added = added.difference(updated)
deleted = deleted.difference(updated)
@@ -121,9 +121,8 @@ def main():
relevant_added_tests.append(test)
break
added_tests = relevant_added_tests
- else:
- if len(added_tests) > 50:
- added_tests = added_tests[:50]
+ elif len(added_tests) > 50:
+ added_tests = added_tests[:50]
# Add these new_tests in the Mapping
old_num_tests = len(old_tests)
tests["index_mapping"] += added_tests
diff --git a/docs/_templates/top_data_toc.rst b/docs/_templates/top_data_toc.rst
index fd991a4641b6c..5d6c8bb764121 100644
--- a/docs/_templates/top_data_toc.rst
+++ b/docs/_templates/top_data_toc.rst
@@ -6,9 +6,9 @@
{% block options %}{{ super() }} :hide-table:
{% endblock %}
-{#
- As this toc generates files a little differently, we added this to fix linking
- issues
+{#
+ As this toc generates files a little differently, we added this to fix linking
+ issues
#}
{% block custom_content %}
.. autosummary::
diff --git a/docs/compiler/setting_up.rst b/docs/compiler/setting_up.rst
deleted file mode 100644
index 8fb9a17bbcb2c..0000000000000
--- a/docs/compiler/setting_up.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-Setting Up
-==========
-
-To use Ivy's compiler and transpiler, you'll need an **API key**. We are starting to
-grant pilot access to certain users, so you can `join the waitlist `_
-if you want to get one!
-
-Ivy Folder
-----------
-
-When importing Ivy for the first time, a ``.ivy`` folder will be created in your
-working directory. If you want to keep this folder in a different location,
-you can set an ``IVY_ROOT`` environment variable with the path of your ``.ivy`` folder.
-
-Setting Up the API key
-----------------------
-
-Once the ``.ivy`` folder has been created (either manually or automatically by
-importing Ivy), you will have to paste your API key as the content of the ``key.pem`` file.
-For reference, this would be equivalent to:
-
-.. code-block:: console
-
- echo -n API_KEY > .ivy/key.pem
-
-Issues and Questions
---------------------
-
-If you find any issue or bug while using the compiler and/or the transpiler, please
-raise an `issue in GitHub `_ and add the ``compiler``
-or the ``transpiler`` label accordingly. A member of the team will get back to you ASAP!
-
-Otherwise, if you haven't found a bug but want to ask a question, suggest something, or get help
-from the team directly, feel free to open a new post at the ``pilot-access`` forum in
-`Ivy's discord server! `_
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index dbfd99969b2bb..e88f08969b560 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,25 +3,40 @@
.. include:: ../README.md
:parser: myst_parser.sphinx_
+
+.. toctree::
+ :hidden:
+ :maxdepth: -1
+
+ Home
+
+
.. toctree::
:hidden:
:maxdepth: -1
- :caption: Overview
+ :caption: The Basics
overview/get_started.rst
- Examples
- overview/glossary.rst
- overview/faq.rst
+ demos/quickstart.ipynb
.. toctree::
:hidden:
:maxdepth: -1
- :caption: Users
+ :caption: Demos
+
+ demos/learn_the_basics.rst
+ demos/guides.rst
+ demos/examples_and_demos.rst
- overview/background.rst
+
+.. toctree::
+ :hidden:
+ :maxdepth: -1
+ :caption: Background
+
+ overview/motivation.rst
overview/related_work.rst
- overview/extensions.rst
.. toctree::
@@ -32,22 +47,21 @@
overview/design.rst
overview/contributing.rst
overview/deep_dive.rst
+ overview/glossary.rst
+ overview/faq.rst
.. toctree::
:hidden:
:maxdepth: -1
- :caption: Compiling and Transpiling
+ :caption: API Reference
- compiler/setting_up.rst
- compiler/compiler.rst
- compiler/transpiler.rst
+ overview/one_liners.rst
.. autosummary::
:toctree: docs/functional
:template: top_functional_toc.rst
- :caption: API Reference
:recursive:
:hide-table:
diff --git a/docs/overview/contributing.rst b/docs/overview/contributing.rst
index c5b3b1aca787c..6e988bba87b52 100644
--- a/docs/overview/contributing.rst
+++ b/docs/overview/contributing.rst
@@ -15,28 +15,25 @@ We want our ML unification journey to be as inclusive as possible, this is all o
The contributor guide is split into the sections below, it's best to go from start to finish, but you can also dive in at any stage! We're excited for you to get involved! 🦾
-| (a) `Setting Up `_
+| (a) `Setting Up `_
| Building the right environment 🏛️
|
-| (b) :ref:`The Basics`
+| (b) `The Basics `_
| Managing your fork 🇾, creating issues ⭕, and creating pull-requests ⬆️
|
-| (c) :ref:`Building the Docs`
+| (c) `Building the Docs `_
| How to build the documentation locally 🏗️
|
-| (d) :ref:`Deep Dive`
+| (d) `Deep Dive `_
| Take a deep dive into the codebase 🤿
|
-| (e) :ref:`Open Tasks`
+| (e) `Open Tasks `_
| See where you can help us out! 🙋
|
-| (f) :ref:`Applied Libraries`
-| Getting started with our applied libraries! 📚
-|
-| (g) :ref:`Helpful Resources`
+| (f) `Helpful Resources `_
| Resources you would find useful when learning Ivy 📖
-|
-| (g) :ref:`Error Handling`
+|
+| (g) `Error Handling `_
| Common errors you will be facing contributing to Ivy ❌
.. toctree::
@@ -49,7 +46,6 @@ The contributor guide is split into the sections below, it's best to go from sta
contributing/building_the_docs.rst
Deep Dive
contributing/open_tasks.rst
- contributing/applied_libraries.rst
contributing/helpful_resources.rst
contributing/error_handling.rst
diff --git a/docs/overview/contributing/applied_libraries.rst b/docs/overview/contributing/applied_libraries.rst
deleted file mode 100644
index 11de60c24d5cb..0000000000000
--- a/docs/overview/contributing/applied_libraries.rst
+++ /dev/null
@@ -1,142 +0,0 @@
-Applied Libraries
-=================
-
-.. _`Ivy Robot`: https://unify.ai/docs/robot/
-.. _`Mech`: https://unify.ai/docs/mech/
-.. _`Vision`: https://unify.ai/docs/vision/
-.. _`Demo Utils`: https://github.com/unifyai/demo-utils
-.. _`Ivy`: https://github.com/unifyai/ivy
-.. _`Docker Desktop`: https://www.docker.com/products/docker-desktop/
-.. _`discord`: https://discord.gg/sXyFF8tDtm
-.. _`pycharm channel`: https://discord.com/channels/799879767196958751/942114831039856730
-.. _`docker channel`: https://discord.com/channels/799879767196958751/942114744691740772
-.. _`pre-commit channel`: https://discord.com/channels/799879767196958751/982725464110034944
-.. _`pip packages channel`: https://discord.com/channels/799879767196958751/942114789642080317
-
-Introduction
-------------
-
-Helping to contribute towards the ivy libraries requires a slightly more complex setup than is needed for contributing to ivy alone.
-For instance, `Ivy Robot`_ depends on `Mech`_, `Vision`_ and `Demo Utils`_.
-Thus, the related repositories have to be pulled into the same local folder, and `Ivy`_ must also be pulled into this same folder.
-
-To have a better grasp, let's look at an example of Ivy Robot in the next section!
-
-Example - Ivy Robot
--------------------
-
-**Directory Tree**
-
-1. Due to dependencies, the related Ivy repositories have to be placed in the same local directory:
-
-.. code-block:: none
-
- |-- your-local-dir
- | |-- ivy
- | |-- mech
- | |-- vision
- | |-- robot
- | |-- demo-utils
-
-2. Clone all repositories into a mutual directory:
-
- .. code-block:: none
-
- git clone https://github.com/unifyai/ivy.git
-
- .. code-block:: none
-
- git clone https://github.com/unifyai/mech.git
-
- .. code-block:: none
-
- git clone https://github.com/unifyai/vision.git
-
- .. code-block:: none
-
- git clone https://github.com/unifyai/robot.git
-
- .. code-block:: none
-
- git clone https://github.com/unifyai/demo-utils.git
-
-3. The next steps will depend on your type of development.
-
-**Local Development**
-
-1. Create a virtual environment (venv) in the same directory:
-
- .. code-block:: none
-
- python3 -m venv ivy_dev
-
-2. Activate the environment:
-
- (on Windows)
- .. code-block:: none
-
- ivy_dev\Scripts\activate.bat
-
- (on Mac/Linux)
- .. code-block:: none
-
- source ivy_dev/bin/activate
-
-3. Go into each directory and install packages in develop/editable mode:
-
- .. code-block:: none
-
- cd ivy
- python3 -m pip install --user -e .
-
- (repeat for all repositories)
-
- **NOTE:** In develop mode, packages are linked to their local directory.
- Therefore, changes or edits are reflected immediately when in use.
-
-4. To use:
-
- .. code-block:: none
-
- python3
-
- .. code-block:: python
-
- import ivy_robot
-
-**Docker Development**
-
-1. Install `Docker Desktop`_
-
-2. Go into the :code:`robot` repository and build the docker image:
-
- .. code-block:: none
-
- cd robot
- docker build -t my-robot .
-
-3. To use, first mount the local directories, then start up :code:`python3` with Docker:
-
- (in the folder containing all repositories)
- .. code-block:: none
-
- docker run --rm -it -v `pwd`/ivy:/ivy -v `pwd`/mech:/mech -v `pwd`/vision:/vision -v `pwd`/robot:/robot -v `pwd`/demo-utils:/demo-utils my-robot python3
-
- **NOTE:** Mounting allows the docker container to use local folder as volumes, thus reflecting the local changes or edits made.
- Users are not required to rebuild the docker image after every change.
-
-**IDE Development**
-
-1. For **PyCharm**, configurations are saved in the :code:`.idea` folder (part of the ivy repo).
-
-2. For **VSCode**, configurations can be found in the :code:`.devcontainer` folder (not part of the ivy repo).
-
-**NOTE:** To use the development container in VSCode, the extension "Remote - Containers" needs to be installed.
-
-**NOTE:** When using GitHub Codespaces, the :code:`mounts` config in :code:`.devcontainer/devcontainer.json` is not supported.
-
-**Round Up**
-
-These examples should hopefully give you a good understanding of what is required when developing the Ivy applied libraries.
-
-If you have any questions, please feel free to reach out on `discord`_ in the `pycharm channel`_, `docker channel`_, `pre-commit channel`_, `pip packages channel`_ or `other channel`_, depending on the question!
diff --git a/docs/overview/contributing/building_the_docs.rst b/docs/overview/contributing/building_the_docs.rst
index 680e21b099089..12f59b1dbd618 100644
--- a/docs/overview/contributing/building_the_docs.rst
+++ b/docs/overview/contributing/building_the_docs.rst
@@ -2,7 +2,8 @@ Building the Docs
=================
This document describes how to build the Ivy docs. If you want to know more about how
-our custom building pipeline work, check our :ref:`Building the Docs Pipeline` deep dive
+our custom building pipeline work, check our `Building the Docs Pipeline
+<../deep_dive/building_the_docs_pipline.rst>`_ deep dive
Building the Docs using Docker
------------------------------
@@ -22,20 +23,20 @@ This script will build the docs for Ivy and store it in ``docs/build``.
Using existing image on Docker Hub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can also use the ``unifyai/doc-builder`` image hosted on
-`Docker Hub `_ to build the
-docs. This will be helpful if you want to build the docs for Ivy applied libraries.
+You can also use the ``unifyai/doc-builder`` image hosted on
+`Docker Hub `_ to build the
+docs.
-Run ``docker run`` to build the docs. The following command will build the docs for
+Run ``docker run`` to build the docs. The following command will build the docs for
the project in the current directory and output them to ``docs/build``.
.. code-block:: bash
- cd
+ cd
docker run --rm -v $(pwd):/project unifyai/doc-builder
This command will mount the module directory to ``/project`` in the container, the
-current directory can be the root of ``ivy`` or any applied library such as ``mech``.
+current directory should be the root of ``ivy``.
Building the image locally
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -66,7 +67,7 @@ Building the Docs without Docker
--------------------------------
You can also build the docs without Docker. You will first need to clone the
-``unifyai/doc-builder`` repository. Then use the convenience script
+``unifyai/doc-builder`` repository. Then use the convenience script
``make_docs_without_docker.sh``.
Run this command if you are using HTTPS:
@@ -86,8 +87,8 @@ Then, run the following command to build the docs:
.. code-block:: bash
cd doc-builder
- ./make_docs_without_docker.sh
+ ./make_docs_without_docker.sh
The script will install the required dependencies for `sphinx `_
-which is used to build the docs, as well as dependencies required by Ivy or the Ivy
-applied library. Then it will build the docs for Ivy and store it in ``docs/build``.
+which is used to build the docs, as well as dependencies required by Ivy. Then it will
+build the docs for Ivy and store it in ``docs/build``.
diff --git a/docs/overview/contributing/error_handling.rst b/docs/overview/contributing/error_handling.rst
index 44f4df41fee1b..ff4bbefbf7d8d 100644
--- a/docs/overview/contributing/error_handling.rst
+++ b/docs/overview/contributing/error_handling.rst
@@ -10,7 +10,7 @@ Error Handling
This section, "Error Handling" aims to assist you in navigating through some common errors you might encounter while working with the Ivy's Functional API. We'll go through some common errors which you might encounter while working as a contributor or a developer.
-#. This is the case where we pass in a dtype to `torch` which is not actually supported by the torch's native framework itself. The function which was
+#. This is the case where we pass in a dtype to `torch` which is not actually supported by the torch's native framework itself. The function which was
.. code-block:: python
@@ -33,17 +33,17 @@ This section, "Error Handling" aims to assist you in navigating through some com
E ),
E fn_name='logaddexp2',
E )
- E
+ E
E You can reproduce this example by temporarily adding @reproduce_failure('6.82.4', b'AXicY2BkAAMoBaaR2WAAAACVAAY=') as a decorator on your test case
#. This is the case where the value from the ground-truth backend(tensorflow) does not match the value of the backend(jax) we are testing for this case.
.. code-block:: python
-
+
E AssertionError: the results from backend jax and ground truth framework tensorflow do not match
- E 0.25830078125!=0.258544921875
- E
- E
+ E 0.25830078125!=0.258544921875
+ E
+ E
E Falsifying example: test_acosh(
E backend_fw='jax',
E on_device='cpu',
@@ -61,7 +61,7 @@ This section, "Error Handling" aims to assist you in navigating through some com
E ),
E fn_name='acosh',
E )
- E
+ E
E You can reproduce this example by temporarily adding @reproduce_failure('6.82.4', b'AXicY2BAABYQwQgiAABDAAY=') as a decorator on your test case
#. This is a similar assertion as stated in point 2 but with torch and ground-truth tensorflow not matching but the matrices are quite different so there should be an issue in the backends rather than a numerical instability here:
@@ -73,9 +73,9 @@ This section, "Error Handling" aims to assist you in navigating through some com
E [1.41421356 1.41421356 1.41421356]
E [1.41421356 inf 1.41421356]]!=[[1.41421356e+000 1.41421356e+000 1.41421356e+000]
E [1.41421356e+000 1.41421356e+000 1.41421356e+000]
- E [1.41421356e+000 1.34078079e+154 1.41421356e+000]]
- E
- E
+ E [1.41421356e+000 1.34078079e+154 1.41421356e+000]]
+ E
+ E
E Falsifying example: test_abs(
E backend_fw='torch',
E on_device='cpu',
@@ -96,7 +96,7 @@ This section, "Error Handling" aims to assist you in navigating through some com
E container=[False],
E ),
E )
- E
+ E
E You can reproduce this example by temporarily adding @reproduce_failure('6.82.4', b'AXicY2ZkYAIiBiBgZIAAxqHEXsAAB7jUQAAAMtEAzQ==') as a decorator on your test case
diff --git a/docs/overview/contributing/open_tasks.rst b/docs/overview/contributing/open_tasks.rst
index 186b3ee912cc0..081f7946d6488 100644
--- a/docs/overview/contributing/open_tasks.rst
+++ b/docs/overview/contributing/open_tasks.rst
@@ -7,13 +7,14 @@ Open Tasks
.. _`issue description`: https://github.com/unifyai/ivy/issues/1526
.. _`reference API`: https://numpy.org/doc/stable/reference/routines.linalg.html
.. _`imports`: https://github.com/unifyai/ivy/blob/38dbb607334cb32eb513630c4496ad0024f80e1c/ivy/functional/frontends/numpy/__init__.py#L27
+.. _`Deep Dive`: ../deep_dive.rst
Here, we explain all tasks which are currently open for contributions from the community!
This section of the docs will be updated frequently, whereby new tasks will be added and completed tasks will be removed.
The tasks outlined here are generally broad high-level tasks, each of which is made up of many individual sub-tasks, distributed across task-specific `ToDo List Issues `_.
-Please read about `ToDo List Issues `_ in detail before continuing.
+Please read about :ref:`overview/contributing/the_basics:ToDo List Issues` in detail before continuing.
All tasks should be selected and allocated as described in the ToDo List Issues section.
We make no mention of task selection and allocation in the explanations below, which instead focus on the steps to complete only once a sub-task has been allocated to you.
@@ -32,7 +33,7 @@ Function Formatting
Currently, we have many ToDo list issues `open `_ for a general function formatting task, which is explained below.
-Each function in each submodule should be updated to follow the implementation instructions given in the :ref:`Deep Dive` section.
+Each function in each submodule should be updated to follow the implementation instructions given in the `Deep Dive`_ section.
The updates should be applied for the:
#. ivy API
@@ -44,30 +45,30 @@ The updates should be applied for the:
#. container operators
#. container reverse operators
-The :ref:`Deep Dive` is an **essential** resource for learning how each of these functions/methods should be implemented.
-Before starting any contribution task, you should go through the :ref:`Deep Dive`, and familiarize yourself with the content.
+The `Deep Dive`_ is an **essential** resource for learning how each of these functions/methods should be implemented.
+Before starting any contribution task, you should go through the `Deep Dive`_, and familiarize yourself with the content.
At the time of writing, many of the functions are not implemented as they should be.
-You will need to make changes to the current implementations, but you do not need to address *all* sections of the :ref:`Deep Dive` in detail.
+You will need to make changes to the current implementations, but you do not need to address *all* sections of the `Deep Dive`_ in detail.
Specifically, you **do not** need to address the following:
#. Implement the hypothesis testing for the function
#. Get the tests passing for your function, if they are failing before you start
-However, everything else covered in the :ref:`Deep Dive` must be addressed.
+However, everything else covered in the `Deep Dive`_ must be addressed.
Some common important tasks are:
#. Remove all :code:`lambda` and direct bindings for the backend functions (in :code:`ivy.functional.backends`), with each function instead defined using :code:`def`.
#. Implement the following if they don't exist but should do: :class:`ivy.Array` instance method, :class:`ivy.Container` instance method, :class:`ivy.Array` special method, :class:`ivy.Array` reverse special method, :class:`ivy.Container` special method, :class:`ivy.Container` reverse special method.
#. Make sure that the aforementioned methods are added into the correct category-specific parent class, such as :class:`ivy.ArrayWithElementwise`, :class:`ivy.ContainerWithManipulation` etc.
-#. Correct all of the :ref:`Function Arguments` and the type hints for every function **and** its *relevant methods*, including those you did not implement yourself.
-#. Add the correct :ref:`Docstrings` to every function **and** its *relevant methods*, including those you did not implement yourself.
-#. Add thorough :ref:`Docstring Examples` for every function **and** its *relevant methods* and ensure they pass the docstring tests.
+#. Correct all of the `Function Arguments <../deep_dive/function_arguments.rst>`_ and the type hints for every function **and** its *relevant methods*, including those you did not implement yourself.
+#. Add the correct `Docstrings <../deep_dive/docstrings.rst>`_ to every function **and** its *relevant methods*, including those you did not implement yourself.
+#. Add thorough `Docstring Examples <../deep_dive/docstring_examples.rst>`_ for every function **and** its *relevant methods* and ensure they pass the docstring tests.
Formatting checklist
~~~~~~~~~~~~~~~~~~~~
-After creating your Pull Request on github, you should then produce the checklist for the formatting task as follows:
+After creating your Pull Request on github, you should then produce the checklist for the formatting task as follows:
1. Add a comment with the following format: :code:`add_reformatting_checklist_` on your PR, where ** is the name of the category that the function belongs to.
An example of this is shown below.
@@ -94,7 +95,7 @@ The PR assignee will then see this comment and address your issues.
.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/contributing/open_tasks/checklist_SOS.png?raw=true
:width: 420
-**Notes**:
+**Notes**:
1. It is important that the PR author is the one to add the checklist generating comment in order to ensure they will have access to edit and update it later.
2. The checklist items' statuses should be manually updated by the PR author.
@@ -106,15 +107,15 @@ The PR assignee will then see this comment and address your issues.
Frontend APIs
-------------
-For this task, the goal will be to implement functions for each of the frontend functional APIs (see :ref:`Ivy as a Transpiler`), with frontend APIs implemented for: :code:`JAX`, :code:`NumPy`, :code:`TensorFlow` :code:`PyTorch`, :code:`Paddle`, :code:`Scipy`, :code:`MXNet` and :code:`MindSpore`.
+For this task, the goal will be to implement functions for each of the frontend functional APIs (see `Ivy as a Transpiler <../design/ivy_as_a_transpiler.rst>`_), with frontend APIs implemented for: :code:`JAX`, :code:`NumPy`, :code:`TensorFlow` :code:`PyTorch`, :code:`Paddle`, :code:`Scipy`, :code:`MXNet` and :code:`MindSpore`.
Currently, we have many ToDo list issues `open `_ for this task.
The general workflow for this task is:
-#. Find the correct location for the function by following the :ref:`Where to place a frontend function` subsection below
-#. Implement the function by following the :ref:`Ivy Frontends` guide
-#. Write tests for your function by following the :ref:`Ivy Frontend Tests` guide
+#. Find the correct location for the function by following the :ref:`overview/contributing/open_tasks:Where to place a frontend function` subsection below
+#. Implement the function by following the `Ivy Frontends <../deep_dive/ivy_frontends.rst>`_ guide
+#. Write tests for your function by following the `Ivy Frontend Tests <../deep_dive/ivy_frontends_tests.rst>`_ guide
#. Verify that the tests for your function are passing
If you feel as though there is an ivy function :code:`ivy.` clearly missing, which would make your frontend function much simpler to implement, then you should first do the following:
@@ -128,7 +129,7 @@ At some point, a member of our team will assess whether it should be added, and
After this, you then have two options for how to proceed:
-#. Try to implement the function as a composition of currently present ivy functions, as explained in the "Temporary Compositions" sub-section of the :ref:`Ivy Frontends` guide, and add the :code:`#ToDo` comment in the implementation as explained.
+#. Try to implement the function as a composition of currently present ivy functions, as explained in the :ref:`overview/deep_dive/ivy_frontends:Short Frontend Implementations` sub-section of the `Ivy Frontends <../deep_dive/ivy_frontends.rst>`_ guide, and add the :code:`#ToDo` comment in the implementation as explained.
Once the PR is merged, your sub-task issue will then be closed as normal.
#. Alternatively, if you do not want to try and implement the frontend function compositionally, or if this is not feasible, then you can simply choose another frontend function to work on.
You could also choose to work on another open task entirely at this point if you wanted to.
@@ -217,7 +218,7 @@ However, you can still use the checklist as a reference in cases where you do un
**Notes**:
-1. More details on how to update the checklist items can be found in the :ref:`Formatting checklist` part of our docs.
+1. More details on how to update the checklist items can be found in the :ref:`overview/contributing/open_tasks:Formatting checklist` part of our docs.
2. Do not edit the checklist text, only the emoji symbols.
3. Please refrain from using the checkboxes next to checklist items.
@@ -233,29 +234,29 @@ There is only one central ToDo list `issue `_
-#. Every function will have a different file structure according to the function type, refer to :ref:`Where to place a backend function` subsection below.
-#. Implement the container instance method in :mod:`ivy/container/experimental/[relevant_submodule].py` and the array instance method
+#. Analyze the function type, we have a very detailed section for it in the deep dive `Function Types Guide <../deep_dive/function_types.rst>`_
+#. Every function will have a different file structure according to the function type, refer to :ref:`overview/contributing/open_tasks:Where to place a backend function` subsection below.
+#. Implement the container instance method in :mod:`ivy/container/experimental/[relevant_submodule].py` and the array instance method
in :mod:`ivy/array/experimental/[relevant_submodule].py`
-#. Write tests for the function using the :ref:`Ivy Tests` guide, and make sure they are passing.
+#. Write tests for the function using the `Ivy Tests <../deep_dive/ivy_tests.rst>`_ guide, and make sure they are passing.
A few points to keep in mind while doing this:
#. Make sure all the positional arguments are positional-only and optional arguments are keyword-only.
#. In case some tests require function-specific parameters, you can create composite hypothesis strategies using the :code:`draw` function in the hypothesis library.
-If you’re stuck on a function which requires complex compositions, feel free to reselect a function
+If you’re stuck on a function which requires complex compositions, feel free to reselect a function
Extending the Ivy API
~~~~~~~~~~~~~~~~~~~~~~~
-We primarily invite contributors to work on the tasks listed as :ref:`Open Tasks`, as these are on our current roadmap. As a result of this, we prompt everyone interested in contributing to our Experimental API to do so under the `Ivy Experimental API Open Task`_.
+We primarily invite contributors to work on the tasks listed as :ref:`overview/contributing/open_tasks:Open Tasks`, as these are on our current roadmap. As a result of this, we prompt everyone interested in contributing to our Experimental API to do so under the :ref:`Ivy Experimental API Open Task `.
-However, if you would like to extend Ivy's functionality with a new function, you are invited to open an issue using the *Missing Function Suggestion* template as described in `Creating an Issue on Ivy’s GitHub using a Template `_.
+However, if you would like to extend Ivy's functionality with a new function, you are invited to open an issue using the *Missing Function Suggestion* template as described in :ref:`overview/contributing/open_tasks:Creating an Issue on Ivy's GitHub using a Template`.
In this template form, you'll be asked to fill in the reason you think we should implement the suggested function, as well as the links to any native implementations of the suggested function.
-We will review your issue as soon as possible and let you know if it's been accepted or not. In case we deem that the suggested function fits our roadmap, we will add it as a subtask to the `Ivy Experimental API Open Task`_.
+We will review your issue as soon as possible and let you know if it's been accepted or not. In case we deem that the suggested function fits our roadmap, we will add it as a subtask to the `Ivy Experimental API Open Task `_.
Where to place a backend function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -267,15 +268,15 @@ There are multiple types of backend functions as discussed above, we will go thr
**Primary Functions**
Implement the function in :mod:`ivy/functional/ivy/experimental/[relevant_submodule].py` simply deferring to their backend-specific implementation
-(where ivy.current_backend(x).function_name() is called), refer to the `Ivy API Guide `_
+(where ivy.current_backend(x).function_name() is called), refer to the :ref:`Ivy API Guide `
to get a clearer picture of how this must be done. Then, implement the functions in each of the backend files :mod:`ivy/functional/backends/backend_name/experimental/[relevant_submodule].py`,
-you can refer to the `Backend API Guide `_ for this.
+you can refer to the :ref:`Backend API Guide ` for this.
**Compositional Functions**
Implement the function in :mod:`ivy/functional/ivy/experimental/[relevant_submodule].py`, we will not use the primary function approach in this
case, the implementation will be a composition of functions from Ivy's functional API. You can refer to
-`Compositional Functions Guide `_ for a better understanding of this.
+:ref:`overview/deep_dive/function_types:Compositional Functions` for a better understanding of this.
You don't need to add any implementation in any other file in this case.
**Mixed Functions**
@@ -287,8 +288,8 @@ will be a composition of functions from Ivy's functional API. After you are done
**Other Function Types**
-`Standalone Functions `_, `Nestable Functions `_ and
-`Convenience Functions `_ are the ones which you will rarely come across
+:ref:`overview/deep_dive/function_types:Standalone Functions`, :ref:`overview/deep_dive/function_types:Nestable Functions` and
+:ref:`overview/deep_dive/function_types:Convenience Functions` are the ones which you will rarely come across
while implementing a function from the ToDo List but they are an essential part of the Ivy API.
diff --git a/docs/overview/contributing/setting_up.rst b/docs/overview/contributing/setting_up.rst
index 6987e5e046ee1..188f1d04d095b 100644
--- a/docs/overview/contributing/setting_up.rst
+++ b/docs/overview/contributing/setting_up.rst
@@ -107,7 +107,7 @@ Using miniconda
#. Create the environment by running the command (:code:`ivy_dev` is the name of the environment)
.. code-block:: none
-
+
conda create --name ivy_dev python=3.10.0
#. Activate the environment by:
@@ -129,27 +129,27 @@ Using miniconda
a. Going to settings -> project -> Python Interpreter
b. Clicking add interpreter (currently by clicking the ⚙ icon on the right side) which should open a new window.
-
+
c. Choosing "conda environment" from the left panel. Choose the existing environment and select the drop down and you should find the path python in the environment.
#. VSCode
a. Go to the command palette (Ctrl+Shift+P) or (⌘+shift+p) for Mac and type "Python: Select Interpreter" and select the environment you created.
-
+
If you don't find a path to your created python environment, you can run :code:`where python` in the conda command line while the environment is activate and it should give the path which can be added manually.
#. Installing the development dependencies.
a. On Linux, Windows, or Intel Mac, you will need to use the `optional.txt` requirements file. To install dependencies.
-
+
.. code-block:: none
-
+
pip install -r requirements/optional.txt
-
+
b. On M1 Mac, you will need to use the optional_apple_silicon_1 and optional_apple_silicon_2 requirements files. To install dependencies.
-
+
.. code-block:: none
-
+
pip install -r requirements/optional_apple_silicon_1.txt
pip install -r requirements/optional_apple_silicon_2.txt
@@ -208,26 +208,26 @@ This is a builtin package and doesn't require explicit installation.
a. Go to the command palette (Ctrl+Shift+P) or (⌘+shift+p) for Mac and type `Python: Select Interpreter` and select the environment you created.
#. Installing the development dependencies.
-
+
a. On Linux, Windows, or Intel Mac, you will need to use the `optional.txt` requirements file. To install dependencies.
-
+
.. code-block:: none
-
+
pip install -r requirements/optional.txt
- Note: In case you are using Ubuntu 22.04, PaddlePaddle won't install properly. You have to download it from the source.
-
+ Note: In case you are using Ubuntu 22.04, PaddlePaddle won't install properly. You have to download it from the source.
+
.. code-block:: none
-
+
wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb
-
+
PS: If the link gets expired at some point in the future, check http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/?C=M;O=D for a valid one.
b. On M1 Mac, you will need to use the optional_apple_silicon_1 and optional_apple_silicon_2 requirements files. To install dependencies.
-
+
.. code-block:: none
-
+
pip install -r requirements/optional_apple_silicon_1.txt
pip install -r requirements/optional_apple_silicon_2.txt
@@ -423,14 +423,14 @@ Ubuntu
**Docker Connection not Successfull**
This is a common error which you might face. If you are not successfully able to connect docker with Pycharm(point 4a) and your docker is also running, the issue is that you are not able to use your docker socket. So, executing the below two commands should solve this.
-
+
.. code-block:: none
-
+
sudo chmod a+rwx /var/run/docker.sock
-
+
.. code-block:: none
-
- sudo chmod a+rwx /var/run/docker.pid
+
+ sudo chmod a+rwx /var/run/docker.pid
For questions, please reach out on `discord`_ in the `docker channel`_!
@@ -601,14 +601,14 @@ For windows users, the file path should be entered with "/" (forward-slashes), f
WSL
***
-
+
It is understandable that working with computationally heavy tools like Docker and PyCharm is not always comfortable for developers.
-By utilizing WSL, you can run a Linux distribution on your Windows machine, and in addition, venv is leveraged to create
-isolated Python environments eliminating the need for a full-fledged containerization solution like Docker, and with VSCode being an appropriate alternative to PyCharm,
+By utilizing WSL, you can run a Linux distribution on your Windows machine, and in addition, venv is leveraged to create
+isolated Python environments eliminating the need for a full-fledged containerization solution like Docker, and with VSCode being an appropriate alternative to PyCharm,
the steps explained below will help you in setting up a less resource-intensive Ivy environment.
#. Install `WSL `_.
-#. Install `Visual Studio Code `_.
+#. Install `Visual Studio Code `_.
You can follow `this guide `_ to integrate WSL into VSCode.
#. Open the WSL terminal by typing in the name of your Linux distribution in the windows start menu (e.g. :code:`Ubuntu`).
#. Create a virtual environment by following the steps below:
@@ -638,7 +638,7 @@ the steps explained below will help you in setting up a less resource-intensive
pip install git+https://github.com/unifyai/ivy.git
-#. If you want to set up a local repository, you can do so by following `this guide `_
+#. If you want to set up a local repository, you can do so by following :ref:`this guide `
as explained above and install the required development dependencies by running:
.. code-block:: none
@@ -650,12 +650,12 @@ the steps explained below will help you in setting up a less resource-intensive
pip install -r requirements/requirements.txt
#. Once done, you can now open VSCode right from your terminal and get started with your development by just running:
-
+
.. code-block:: none
code .
-#. To set up the Python Interpreter in VSCode, go to the command palette (Ctrl+Shift+P) and type **Python: Select Interpreter** and select the environment you created.
+#. To set up the Python Interpreter in VSCode, go to the command palette (Ctrl+Shift+P) and type **Python: Select Interpreter** and select the environment you created.
For a more detailed explanation, you can follow `this guide `_.
#. Now that your development environment is set up, you can now run tests locally by running :code:`pytest test_fle_path::test_fn_name` in the terminal or
if you want to set up testing in VSCode, you may follow the guide **Setting Up Testing** for VSCode as explained below, next to this subsection.
@@ -700,14 +700,14 @@ Just follow the steps outlined below:
:width: 420
3. Then you will head to the dropdown of "Dev container configuration", then select an image to set up with. As there are six options available as of now
-
+
- :code:`Default project configuration` - This is the default option, it will set up with the default codespaces environment.
- :code:`Ivy Development Environment (build)` - This will set up the development environment of ivy for CPU and build image from :code:`ivy/docker/Dockerfile`.
- :code:`Ivy GPU Development Environment (build)` - This will set up the development environment of ivy for GPU and build image from :code:`ivy/docker/DockerfileGPU`.
- :code:`Ivv Development Environment for Multiver...` - This will set up the development environment of multiversion support with ivy and build image from :code:`ivy/docker/DockerfileMultiversion`.
- :code:`Ivy Development Environment (image)` - This will set up the development environment of ivy for CPU and build image from the latest image from dockerhub.
- :code:`Ivy GPU Development Environment (image)` - This will set up the development environment of ivy for GPU and build image from the latest image from dockerhub.
-
+
For now, we will select :code:`Ivy Development Environment (image)`.
Select your region and preferred machine type, then click on "Create Codespace".
@@ -745,7 +745,7 @@ The configuration files install all the required packages, and extensions for yo
If you want to setup a GPU instance on codespaces and also have access to it, kindly follow the guidelines below:
-1. Points 1 and 2 are the same from ref:`Setting up Codespaces` section above. You will be on a screen shown below. Just select the Machine Type to be "6-Core (1 GPU)".
+1. Points 1 and 2 are the same from ref:`Setting up Codespaces` section above. You will be on a screen shown below. Just select the Machine Type to be "6-Core (1 GPU)".
.. image:: https://raw.githubusercontent.com/unifyai/unifyai.github.io/main/img/externally_linked/contributing/setting_up/github_codespaces/Selecting_the_GPU.png?raw=true
:width: 420
diff --git a/docs/overview/contributing/the_basics.rst b/docs/overview/contributing/the_basics.rst
index 2965789636ba0..96de0bfc02e9c 100644
--- a/docs/overview/contributing/the_basics.rst
+++ b/docs/overview/contributing/the_basics.rst
@@ -10,7 +10,6 @@ The Basics
.. _`commit frequency channel`: https://discord.com/channels/799879767196958751/982728822317256712
.. _`PyCharm blog`: https://www.jetbrains.com/help/pycharm/finding-and-replacing-text-in-file.html
.. _`Debugging`: https://www.jetbrains.com/help/pycharm/debugging-code.html
-.. _`Ivy Experimental API Open Task`: https://unify.ai/docs/ivy/overview/contributing/open_tasks.html#ivy-experimental-api
Getting Help
------------
@@ -54,7 +53,7 @@ We make extensive use of `ToDo list issues `_, `frontend APIs `_ and `ivy experimental API `_.
+a. Find a task to work on which (i) is not marked as completed with a tick (ii) does not have an issue created and (iii) is not mentioned in the comments. Currently, there are three open tasks: :ref:`overview/contributing/open_tasks:Function Formatting`, :ref:`overview/contributing/open_tasks:Frontend APIs` and :ref:`overview/contributing/open_tasks:Ivy Experimental API`.
b. Create a new issue with the title being just the name of the sub-task you would like to work on.
@@ -71,7 +70,7 @@ d. Start working on the task, and open a PR as soon as you have a full or partia
:code:`Close #Issue_number`
- This is important, so that the merging of your PR will automatically close the associated issue. Make sure this is in the
+ This is important, so that the merging of your PR will automatically close the associated issue. Make sure this is in the
description of the PR, otherwise it might not link correctly. If you have a partial solution, the Ivy team can help to guide you through the process of getting it working 🙂
Also, remember to make the PR name well described and if there are some details that can support your changes add them to the description of the PR.
@@ -340,16 +339,16 @@ With Docker
#. With PyCharm (With or without docker):
1. PyCharm enables users to run pytest using the green button present near every function declaration inside the :code:`ivy_tests` folder.
-
+
.. image:: https://raw.githubusercontent.com/unifyai/unifyai.github.io/main/img/externally_linked/contributing/the_basics/pytest_with_pycharm/pytest_button_pycharm.png?raw=true
:width: 420
-
+
2. Testing can be done for the entire project, individual submodules, individual files, and individual tests.
This can be done by selecting the appropriate configuration from the top pane in PyCharm.
-
+
.. image:: https://raw.githubusercontent.com/unifyai/unifyai.github.io/main/img/externally_linked/contributing/the_basics/pytest_with_pycharm/pytest_with_pycharm.png?raw=true
:width: 420
-
+
#. Through the command line (With docker):
1. We need to replace the folder inside the container with the current local ivy directory to run tests on the current local code.
@@ -357,29 +356,29 @@ With Docker
.. code-block:: none
docker exec rm -rf ivy
- docker cp ivy :/
+ docker cp ivy :/
2. We need to then enter inside the docker container and change into the :code:`ivy` directory using the following command.
.. code-block:: none
- docker exec -it ivy_container bash
+ docker exec -it ivy_container bash
cd ivy
3. Run the test using the pytest command.
1. Ivy Tests:
- 1. For a single function:
+ 1. For a single function:
.. code-block:: none
-
+
pytest ivy_tests/test_ivy/test_functional/test_core/test_image.py::test_random_crop --no-header --no-summary -q
-
+
2. For a single file:
.. code-block:: none
-
+
pytest ivy_tests/test_ivy/test_functional/test_core/test_image.py --no-header --no-summary -q
3. For all tests:
@@ -390,28 +389,28 @@ With Docker
2. Array API Tests:
- 1. For a single function:
+ 1. For a single function:
.. code-block:: none
-
+
pytest ivy_tests/array_api_testing/test_array_api/array_api_tests/test_creation_functions.py::test_arange --no-header --no-summary -q
-
+
2. For a single file:
.. code-block:: none
-
+
pytest ivy_tests/array_api_testing/test_array_api/array_api_tests/test_creation_functions.py --no-header --no-summary -q
-
+
3. For all tests:
.. code-block:: none
pytest ivy_tests/array_api_testing/test_array_api/ --no-header --no-summary -q
-
+
3. For the entire project:
.. code-block:: none
-
+
pytest ivy_tests/ --no-header --no-summary -q
#. Through the command line (Without docker):
@@ -435,16 +434,16 @@ With Docker
1. Ivy Tests:
- 1. For a single function:
+ 1. For a single function:
.. code-block:: none
-
+
python -m pytest ivy_tests/test_ivy/test_functional/test_core/test_image.py::test_random_crop --no-header --no-summary -q
-
+
2. For a single file:
.. code-block:: none
-
+
python -m pytest ivy_tests/test_ivy/test_functional/test_core/test_image.py --no-header --no-summary -q
3. For all tests:
@@ -453,34 +452,34 @@ With Docker
python -m pytest ivy_tests/test_ivy/ --no-header --no-summary -q
- 2. Array API Tests
+ 2. Array API Tests
- 1. For a single function:
+ 1. For a single function:
.. code-block:: none
-
+
python -m pytest ivy_tests/array_api_testing/test_array_api/array_api_tests/test_creation_functions.py::test_arange --no-header --no-summary -q
-
+
2. For a single file:
.. code-block:: none
-
+
python -m pytest ivy_tests/array_api_testing/test_array_api/array_api_tests/test_creation_functions.py --no-header --no-summary -q
-
+
3. For all tests:
.. code-block:: none
python -m pytest ivy_tests/array_api_testing/test_array_api/ --no-header --no-summary -q
-
+
3. For the entire project
.. code-block:: none
-
+
python -m pytest ivy_tests/ --no-header --no-summary -q
#. Optional Flags: Various optional flags are available for running the tests such as :code:`device`, :code:`backend`, etc.
- 1. :code:`device`:
+ 1. :code:`device`:
1. This flag enables the setting of the device where the tests would be run.
2. Possible values being :code:`cpu` and :code:`gpu`.
3. Default value is :code:`cpu`
@@ -542,7 +541,7 @@ with PyCharm
:align: center
3. Stepping through the code:
- 1. Step over:
+ 1. Step over:
Steps over the current line of code and takes you to the next line even if the highlighted line has method calls in it.
1. Click the Step Over button or press :code:`F8`
@@ -568,7 +567,7 @@ with PyCharm
2. Click the desired method.
- 4. Python Console:
+ 4. Python Console:
1. Click the Console option on Debug Tool Window:
This currently stores variables and their values upto which the code has been executed.
You can print outputs and debug the code further on.
diff --git a/docs/overview/deep_dive.rst b/docs/overview/deep_dive.rst
index e92fc8e1a7688..024dfd599ad43 100644
--- a/docs/overview/deep_dive.rst
+++ b/docs/overview/deep_dive.rst
@@ -4,7 +4,7 @@ Deep Dive
.. _`issues`: https://github.com/unifyai/ivy/issues
.. _`pull-requests`: https://github.com/unifyai/ivy/pulls
-For general users of the framework, who are mainly concerned with learning how to *use* Ivy, then the :ref:`Design` section is the best place to start 🙂
+For general users of the framework, who are mainly concerned with learning how to *use* Ivy, then the `Design `_ section is the best place to start 🙂
This *deep dive* section is more targeted at people who would like to dive deeper into how Ivy actually works under the hood 🔧
@@ -13,74 +13,79 @@ Going through the sections outlined below will get you right into the weeds of t
It's best to go through the sub-sections from start to finish, but you can also dive in at any stage!
We're excited for you to get involved! 🦾
-| (a) :ref:`Navigating the Code` 🧭
+| (a) `Navigating the Code `_ 🧭
| A quick tour through the codebase
|
-| (b) :ref:`Function Types` 🧮
+| (b) `Function Types `_ 🧮
| Primary, compositional, mixed, and nestable functions
|
-| (c) :ref:`Superset Behaviour` ⊃
+| (c) `Superset Behaviour `_ ⊃
| Ivy goes for the superset when unifying the backend functions
|
-| (d) :ref:`Backend Setting` ⚙
+| (d) `Backend Setting `_ ⚙
| How the backend is set, and what this means for each function type️
|
-| (e) :ref:`Arrays` 🔢
+| (e) `Arrays `_ 🔢
| Different types of arrays, and how they're handled
|
-| (f) :ref:`Containers` 🗂
+| (f) `Containers `_ 🗂
| What the :class:`ivy.Container` does
|
-| (g) :ref:`Data Types` 💾
+| (g) `Data Types `_ 💾
| How functions infer the correct data type
|
-| (h) :ref:`Devices` 📱
+| (h) `Devices `_ 📱
| How functions infer the correct device
|
-| (i) :ref:`Inplace Updates` 🎯
+| (i) `Inplace Updates `_ 🎯
| How the :code:`out` argument is used to specify the output target
|
-| (j) :ref:`Function Wrapping` 🎁
+| (j) `Function Wrapping `_ 🎁
| How functions are dynamically wrapped at runtime
|
-| (k) :ref:`Formatting` 📋
+| (k) `Formatting `_ 📋
| How the code is automatically formatted
|
-| (l) :ref:`Function Arguments` 📑
+| (l) `Ivy Lint `_ 🧹
+| Ivy's Custom Code Formatters
+|
+| (m) `Function Arguments `_ 📑
| How to add the correct function arguments
|
-| (m) :ref:`Docstrings` 📄
+| (n) `Docstrings `_ 📄
| How to properly write docstrings
|
-| (n) :ref:`Docstring Examples` 💯
+| (o) `Docstring Examples `_ 💯
| How to add useful examples to the docstrings
|
-| (o) :ref:`Array API Tests` 🤝
+| (p) `Array API Tests `_ 🤝
| How we're borrowing the test suite from the Array API Standard
|
-| (p) :ref:`Ivy Tests` 🧪
+| (q) `Ivy Tests `_ 🧪
| How to add new tests for each Ivy function
|
-| (q) :ref:`Ivy Frontends` ➡
+| (r) `Ivy Frontends `_ ➡
| How to implement frontend functions
|
-| (r) :ref:`Ivy Frontend Tests` 🧪
+| (s) `Ivy Frontend Tests `_ 🧪
| How to add new tests for each frontend function
|
-| (s) :ref:`Exception Handling` ⚠
+| (t) `Exception Handling `_ ⚠
| How to handle exceptions and assertions in a function
|
-| (t) :ref:`Continuous Integration` 🔁
+| (u) `Continuous Integration `_ 🔁
| Ivy Tests running on the Repository
|
-| (u) :ref:`Gradients` 🔁
+| (v) `Gradients `_ 🔁
| Everything about our Gradients API
|
-| (v) :ref:`Operating Modes` 🧮
+| (w) `Operating Modes `_ 🧮
| Everything about modes Ivy can operate in, along with their purposes
|
-| (w) :ref:`Building the Docs Pipeline` 📚
+| (x) `Building the Docs Pipeline `_ 📚
| How are we building our docs
+
+
.. toctree::
:hidden:
:maxdepth: -1
@@ -97,6 +102,7 @@ We're excited for you to get involved! 🦾
deep_dive/inplace_updates.rst
deep_dive/function_wrapping.rst
deep_dive/formatting.rst
+ deep_dive/ivy_lint.rst
deep_dive/function_arguments.rst
deep_dive/docstrings.rst
deep_dive/docstring_examples.rst
@@ -108,4 +114,4 @@ We're excited for you to get involved! 🦾
deep_dive/continuous_integration.rst
deep_dive/gradients.rst
deep_dive/operating_modes.rst
- deep_dive/building_the_docs_pipline.rst
+ deep_dive/building_the_docs_pipeline.rst
diff --git a/docs/overview/deep_dive/array_api_tests.rst b/docs/overview/deep_dive/array_api_tests.rst
index 6bc203297d22b..e9225fedc5c83 100644
--- a/docs/overview/deep_dive/array_api_tests.rst
+++ b/docs/overview/deep_dive/array_api_tests.rst
@@ -12,12 +12,10 @@ Array API Tests
.. _`array-api test repository`: https://github.com/data-apis/array-api/tree/main
.. _`issue`: https://github.com/numpy/numpy/issues/21213
.. _`ivy_tests/array_api_testing/test_array_api/array_api_tests/test_special_cases.py`: https://github.com/data-apis/array-api-tests/blob/ddd3b7a278cd0c0b68c0e4666b2c9f4e67b7b284/array_api_tests/test_special_cases.py
-.. _`here`: https://unify.ai/docs/ivy/overview/contributing/the_basics.html#running-tests-locally
.. _`git website`: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
.. _`hypothesis`: https://hypothesis.readthedocs.io/en/latest/
-.. _`ivy tests`: https://unify.ai/docs/ivy/overview/deep_dive/ivy_tests.html
-.. _`final section`: https://unify.ai/docs/ivy/overview/deep_dive/ivy_tests.html#re-running-failed-ivy-tests
-.. _`CI Pipeline`: https://unify.ai/docs/ivy/overview/deep_dive/continuous_integration.html
+.. _`ivy tests`: ivy_tests.rst
+.. _`CI Pipeline`: continuous_integration.html
In conjunction with our own ivy unit tests, we import the array-api `test suite`_.
These tests check that all ivy backend libraries behave according to the `Array API Standard`_ which was established in May 2020 by a group of maintainers.
@@ -99,7 +97,7 @@ Using the IDE
You can also run a specific test or test file by using your IDE.
To make this work, you should set the backend explicitly in the `_array_module.py` file as explained in the previous subsection.
After that, you can run the API test files as you typically would with other tests.
-See `here`_ for instructions on how to run tests in ivy more generally.
+See :ref:`here ` for instructions on how to run tests in ivy more generally.
*NB*: make sure to not add any changes to the array-api files to your commit.
@@ -107,7 +105,7 @@ Regenerating Test Failures
--------------------------
Array-API tests are written using `hypothesis`_ to perform property-based testing, just like the `ivy tests`_.
However, unlike the ivy tests, the Array-API tests make liberal use of :code:`data.draw` in the main body of the test function instead of generating the data in the :code:`@given` decorator that wraps it.
-This means that failed tests cannot be re-run with the :code:`@example` decorator, as explained in the `final section`_ of the ivy tests deep dive.
+This means that failed tests cannot be re-run with the :code:`@example` decorator, as explained in the :ref:`final section ` of the ivy tests deep dive.
Fortunately, it is possible to regenerate test failures using a unique decorator that appears in the final line of the falsifying example in the error stack trace:
.. code-block:: none
diff --git a/docs/overview/deep_dive/arrays.rst b/docs/overview/deep_dive/arrays.rst
index 7029354e696a5..02dccc5352c56 100644
--- a/docs/overview/deep_dive/arrays.rst
+++ b/docs/overview/deep_dive/arrays.rst
@@ -85,7 +85,7 @@ Therefore, most functions in Ivy must adopt the following pipeline:
#. call the backend-specific function, passing in these :class:`ivy.NativeArray` instances
#. convert all of the :class:`ivy.NativeArray` instances which are returned from the backend function back into :class:`ivy.Array` instances, and return
-Given the repeating nature of these steps, this is all entirely handled in the `inputs_to_native_arrays`_ and `outputs_to_ivy_arrays`_ wrappers, as explained in the :ref:`Function Wrapping` section.
+Given the repeating nature of these steps, this is all entirely handled in the `inputs_to_native_arrays`_ and `outputs_to_ivy_arrays`_ wrappers, as explained in the `Function Wrapping `_ section.
All Ivy functions *also* accept :class:`ivy.NativeArray` instances in the input.
This is for a couple of reasons.
@@ -93,11 +93,11 @@ Firstly, :class:`ivy.Array` instances must be converted to :class:`ivy.NativeArr
Secondly, this makes it easier to combine backend-specific code with Ivy code, without needing to explicitly wrap any arrays before calling sections of Ivy code.
Therefore, all input arrays to Ivy functions have type :code:`Union[ivy.Array, ivy.NativeArray]`, whereas the output arrays have type :class:`ivy.Array`.
-This is further explained in the :ref:`Function Arguments` section.
+This is further explained in the `Function Arguments `_ section.
However, :class:`ivy.NativeArray` instances are not permitted for the :code:`out` argument, which is used in most functions.
This is because the :code:`out` argument dictates the array to which the result should be written, and so it effectively serves the same purpose as the function return.
-This is further explained in the :ref:`Inplace Updates` section.
+This is further explained in the `Inplace Updates `_ section.
As a final point, extra attention is required for *compositional* functions, as these do not directly defer to a backend implementation.
If the first line of code in a compositional function performs operations on the input array, then this will call the special methods on an :class:`ivy.NativeArray` and not on an :class:`ivy.Array`.
@@ -113,7 +113,7 @@ Ivy's functional API and its functions can easily be integrated with non-Ivy cla
To make use of that feature, the class must contain an implementation for these functions and it must contain an implementation for the function :code:`__ivy_array_function__`. If a non-Ivy class is passed to an Ivy function, a call to this class's :code:`__ivy_array_function__` is made which directs Ivy's function to handle that input type correctly. This allows users to define custom implementations for any of the functions that can be found in Ivy's functional API which would further make it easy to integrate those classes with other Ivy projects.
**Note**
-This functionality is inspired by `NumPy's`_ :code:`__ivy_array_function__` and `PyTorch's`_ :code:`__torch_function__`.
+This functionality is inspired by `NumPy's`_ :code:`__ivy_array_function__` and `PyTorch's`_ :code:`__torch_function__`.
As an example, consider the following class :code:`MyArray` with the following definition:
@@ -138,12 +138,12 @@ There are different ways to do so. One way is to use a global dict :code:`HANDLE
return NotImplemented
if not all(issubclass(t, (MyArray, ivy.Array, ivy.NativeArray)) for t in types):
return NotImplemented
- return HANDLED_FUNCTIONS[func](*args, **kwargs)
+ return HANDLED_FUNCTIONS[func](*args, **kwargs)
-:code:`__ivy_array_function__` accepts four parameters: :code:`func` representing a reference to the array API function being
+:code:`__ivy_array_function__` accepts four parameters: :code:`func` representing a reference to the array API function being
overridden, :code:`types` a list of the types of objects implementing :code:`__ivy_array_function__`, :code:`args` a tuple of arguments supplied to the function, and :code:`kwargs` being a dictionary of keyword arguments passed to the function.
While this class contains an implementation for :code:`__ivy_array_function__`, it is still not enough as it is necessary to implement any needed Ivy functions with the new :code:`MyArray` class as input(s) for the code to run successfully.
-We will define a decorator function :code:`implements` that can be used to add functions to :code:`HANDLED_FUNCTIONS`:
+We will define a decorator function :code:`implements` that can be used to add functions to :code:`HANDLED_FUNCTIONS`:
.. code-block:: python
@@ -151,7 +151,7 @@ We will define a decorator function :code:`implements` that can be used to add f
def decorator(func):
HANDLED_FUNCTIONS[ivy_function] = func
return func
- return decorator
+ return decorator
Lastly, we need to apply that decorator to the override function. Let’s consider for example a function that overrides :code:`ivy.abs`:
@@ -168,7 +168,7 @@ Now that we have added the function to :code:`HANDLED_FUNCTIONS`, we can now use
X = MyArray(-3)
X = ivy.abs(X)
-Of course :code:`ivy.abs` is an example of a function that is easy to override since it only requires one operand. The same approach can be used to override functions with multiple operands, including arrays or array-like objects that define :code:`__ivy_array_function__`.
+Of course :code:`ivy.abs` is an example of a function that is easy to override since it only requires one operand. The same approach can be used to override functions with multiple operands, including arrays or array-like objects that define :code:`__ivy_array_function__`.
It is relevant to mention again that any function not stored inside the dict :code:`HANDLED_FUNCTIONS` will not work and it is also important to notice that the operands passed to the function must match that of the function stored in the dict. For instance :code:`my_abs` takes only one parameter which is a :code:`MyArray` object. So, passing any other operands to the function will result in an exception :code:`IvyBackendException` being thrown. Lastly, for a custom class to be covered completely with Ivy's functional API, it is necessary to create an implementation for all the relevant functions within the API that will be used by this custom class. That can be all the functions in the API or only a subset of them.
diff --git a/docs/overview/deep_dive/backend_setting.rst b/docs/overview/deep_dive/backend_setting.rst
index ac42524e05c80..b2be3a2f0a7a5 100644
--- a/docs/overview/deep_dive/backend_setting.rst
+++ b/docs/overview/deep_dive/backend_setting.rst
@@ -23,30 +23,30 @@ When calling `this function`_ for setting the backend, the following steps are p
#. loop through the original :code:`ivy_original_dict` (which has all functions, including compositional), and (a) add the primary function from the backend if it exists, (b) else add the compositional function from :code:`ivy_original_dict`.
#. `wrap the functions`_ where necessary, extending them with shared repeated functionality and `writing the function`_ to :attr:`ivy.__dict__`.
Wrapping is used in order to avoid excessive code duplication in every backend function implementation.
- This is explained in more detail in the next section: :ref:`Function Wrapping`.
+ This is explained in more detail in the next section: `Function Wrapping `_.
It's helpful to look at an example:
.. code-block:: python
x = ivy.array([[2., 3.]])
- ivy.get_backend()
+ ivy.current_backend()
.. code-block:: python
y = ivy.multiply(torch.Tensor([3.]), torch.Tensor([4.]))
- ivy.get_backend()
+ ivy.current_backend()
.. code-block:: python
ivy.set_backend('jax')
z = ivy.matmul(jax.numpy.array([[2.,3.]]), jax.numpy.array([[5.],[6.]]))
- ivy.get_backend()
+ ivy.current_backend()
ivy.previous_backend()
- ivy.get_backend()
+ ivy.current_backend()
In the last example above, the moment any backend is set, it will be used over the `implicit_backend`_.
@@ -74,7 +74,7 @@ Essentially, when the user calls :code:`ivy.set_backend(, dynamic=True)
#. Next, the global :code:`ivy.__dict__` is updated to the new backend as mentioned in the Backend Setting section above.
#. Finally, the objects are `converted from numpy`_ to the target backend using the newly set backend.
-By default, the dynamic backend attribute is set to True when you create an ivy array (e.g., :code:`x = ivy.array([1,2,3])`), but the attribute is mutable and can be changed after the ivy array is created (e.g., :code:`x.dynamic_backend= True`).
+By default, the dynamic backend attribute is set to True when you create an ivy array (e.g., :code:`x = ivy.array([1,2,3])`), but the attribute is mutable and can be changed after the ivy array is created (e.g., :code:`x.dynamic_backend= True`).
Here's an example to illustrate how this works in practice:
.. code-block:: python
diff --git a/docs/overview/deep_dive/building_the_docs_pipline.rst b/docs/overview/deep_dive/building_the_docs_pipeline.rst
similarity index 92%
rename from docs/overview/deep_dive/building_the_docs_pipline.rst
rename to docs/overview/deep_dive/building_the_docs_pipeline.rst
index 464bfa63eb372..e38f01b892941 100644
--- a/docs/overview/deep_dive/building_the_docs_pipline.rst
+++ b/docs/overview/deep_dive/building_the_docs_pipeline.rst
@@ -7,7 +7,7 @@ Building the Docs Pipeline
.. _doc-builder repository: https://github.com/unifyai/doc-builder
To build our docs, we use `Sphinx`_. Sphinx is an extendable documentation generator
-for Python. As our building pipeline is complex, we heavily customize Sphinx using
+for Python. As our building pipeline is complex, we heavily customize Sphinx using
custom and third party extensions. As well as having a convenience script to build
the docs.
@@ -43,7 +43,7 @@ document. The project should have the following characteristics:
5. It can contain an optional ``docs/partial_conf.py`` which is a partial `Sphinx
configuration file`_.
- This file will be imported with the default ``conf.py`` file located in the
+ This file will be imported with the default ``conf.py`` file located in the
``doc-builder`` repo.
Running the script:
@@ -52,7 +52,7 @@ Running the script:
./make_docs_without_docker.sh /path/to/project
-will result in the creation of documentation for the project in the directory
+will result in the creation of documentation for the project in the directory
``docs/build``.
Options
@@ -62,7 +62,7 @@ Options
-C, --no-cleanup Disable the backup/cleanup procedure
-g, --git-add Stage changed files before generating the docs
-s, --skip-dependencies-install Skip installing dependencies using pip
--j, --jobs N Build in parallel with N processes where possible
+-j, --jobs N Build in parallel with N processes where possible
(special value ``auto`` will set N to cpu-count)
-D setting Override a setting in ``conf.py``
@@ -71,7 +71,7 @@ The Docker image
The Docker image `unifyai/doc-builder `_
works as a wrapper around the ``make_docs_without_docker.sh`` script. It runs the script
-on the ``/project`` directory, located in the container `as shown here
+on the ``/project`` directory, located in the container `as shown here
`_:
.. code-block:: bash
@@ -84,10 +84,10 @@ To build the docs through docker you use this command:
docker run -v /path/to/project:/project unifyai/doc-builder
-You can also add options described in the :ref:`The convenience script` section.
+You can also add options described in the :ref:`overview/deep_dive/building_the_docs_pipeline:The convenience script` section.
.. code-block:: bash
-
+
docker run -v /path/to/project:/project unifyai/doc-builder --no-cleanup
How Ivy's docs is structured
@@ -160,22 +160,22 @@ the files that should be included in the table of contents. Which in recursively
to every page in this documentation, for example this page is included in the
``toctree`` of ``overview/deep_dive.rst``, which is included in the ``toctree`` of
``index.rst``. You can read more about the ``toctree`` directive in `sphinx docs
-`_, from
+`_, from
now on we'll only explain the directives that are custom to Ivy's doc-builder.
The last directive is ``autosummary``, which is used to automatically generate a table
of contents for a module, as well as the documentation itself automatically by
discovering the docstrings of the module. This is a custom directive, built on the original
`autosummary`_
-extension. We will explain in detail how did we change it, in :ref:`Custom Extensions`.
+extension. We will explain in detail how did we change it, in :ref:`overview/deep_dive/building_the_docs_pipeline:Custom Extensions`.
``partial_conf.py``
~~~~~~~~~~~~~~~~~~~
-This is a partial `Sphinx configuration file`_. Which is being imported in the
+This is a partial `Sphinx configuration file`_. Which is being imported in the
`conf.py `_,
it's used to customize options that are specific to the project being documented.
-While importing common configurations such as the theme, the extensions, etc in the
+While importing common configurations such as the theme, the extensions, etc in the
original ``conf.py``.
This is a part of ``partial_conf.py``:
@@ -190,18 +190,18 @@ This is a part of ``partial_conf.py``:
"ivy_tests.test_ivy.helpers": "Testing",
}
-Here we are overriding the ``ivy_toctree_caption_map`` configuration, which is used to
-customize the title of the table of contents for each module.
+Here we are overriding the ``ivy_toctree_caption_map`` configuration, which is used to
+customize the title of the table of contents for each module.
``ivy_toctree_caption_map`` is one of the configuration options we have in our
-``custom_autosummary`` extension, which will be covered extensively in
-:ref:`Custom Extensions`.
+``custom_autosummary`` extension, which will be covered extensively in
+:ref:`overview/deep_dive/building_the_docs_pipeline:Custom Extensions`.
``prebuild.sh``
~~~~~~~~~~~~~~~
This is an optional file, which is executed before the docs are built. This is useful
-if you need to install some dependencies for the docs to build. In Ivy's case, we
-install ``torch`` then ``torch-scatter`` sequentially to avoid a bug in
+if you need to install some dependencies for the docs to build. In Ivy's case, we
+install ``torch`` then ``torch-scatter`` sequentially to avoid a bug in
``torch-scatter``'s setup. And if we want to make any changes to the docker container
before building the docs.
@@ -250,7 +250,7 @@ The directive is included like this:
.. discussion-links:: module.foo
-First it will look for the ``discussion_channel_map`` configuration, in Ivy it looks like
+First it will look for the ``discussion_channel_map`` configuration, in Ivy it looks like
this:
.. code-block:: python
@@ -263,15 +263,15 @@ this:
}
The key is the module name, if it's not found the ``discussion-link`` directive will
-render an empty node. The first and only value in the list is the channel id of the
+render an empty node. The first and only value in the list is the channel id of the
module, it is in a list as we used to have forums as well but they are removed now.
The output string is generated by a series of replaces on template strings, which are
customizable using the config. To understand how it works, let's look at the default
configurations and their values:
-- ``discussion_paragraph``: ``"This should have hopefully given you an overview of the
- {{submodule}} submodule, if you have any questions, please feel free to reach out on
+- ``discussion_paragraph``: ``"This should have hopefully given you an overview of the
+ {{submodule}} submodule, if you have any questions, please feel free to reach out on
our [discord]({{discord_link}}) in the [{{submodule}} channel]({{channel_link}})!"``
- ``discord_link``: ``"https://discord.gg/ZVQdvbzNQJ"``
- ``channel_link``: ``"https://discord.com/channels/799879767196958751/{{channel_id}}"``
@@ -283,39 +283,39 @@ Here is an example of how it works for ``ivy.functional.ivy.creation``:
The result will be like this:
- This should have hopefully given you an overview of the
- **creation** submodule, if you have any questions, please feel free to reach out on
+ This should have hopefully given you an overview of the
+ **creation** submodule, if you have any questions, please feel free to reach out on
our [discord]({{discord_link}}) in the [**creation** channel]({{channel_link}})!
2. Then we resolve the ``{{discord_link}}`` template string.
The result will be like this:
-
- This should have hopefully given you an overview of the
- creation submodule, if you have any questions, please feel free to reach out on
+
+ This should have hopefully given you an overview of the
+ creation submodule, if you have any questions, please feel free to reach out on
our [discord](**https://discord.gg/ZVQdvbzNQJ**) in the [creation channel]({{channel_link}})!
3. Then we resolve the ``{{channel_link}}`` template string.
The result will be like this:
-
- This should have hopefully given you an overview of the
- creation submodule, if you have any questions, please feel free to reach out on
+
+ This should have hopefully given you an overview of the
+ creation submodule, if you have any questions, please feel free to reach out on
our [discord](\https://discord.gg/ZVQdvbzNQJ) in the [creation channel](**https://discord.com/channels/799879767196958751/{{channel_id}}**)!
4. We finally resolve ``{{channel_id}}`` template strings.
The result will be like this:
-
- This should have hopefully given you an overview of the
- creation submodule, if you have any questions, please feel free to reach out on
+
+ This should have hopefully given you an overview of the
+ creation submodule, if you have any questions, please feel free to reach out on
our [discord](\https://discord.gg/ZVQdvbzNQJ) in the [creation channel](\https://discord.com/channels/799879767196958751/**1000043690254946374**)!
5. After that we render the node paragraph as if it's a Markdown text resulting this:
- This should have hopefully given you an overview of the
- creation submodule, if you have any questions, please feel free to reach out on
- our `discord `_ in the `creation channel
+ This should have hopefully given you an overview of the
+ creation submodule, if you have any questions, please feel free to reach out on
+ our `discord `_ in the `creation channel
`_!
All of the above template strings can be customized using the configuration, so feel free
@@ -324,7 +324,7 @@ to change them to your liking.
``skippable_function``
~~~~~~~~~~~~~~~~~~~~~~
-This extension provides a custom auto documenter ``autoskippablemethod`` that skip
+This extension provides a custom auto documenter ``autoskippablemethod`` that skip
functions that match values in ``skippable_method_attributes`` configuration.
This is an example of ``skippable_method_attributes`` configuration in
@@ -338,14 +338,14 @@ This is an example of ``skippable_method_attributes`` configuration in
}
]
-This will remove any function that has ``__qualname__`` attribute equal to
+This will remove any function that has ``__qualname__`` attribute equal to
``_wrap_function..new_function``.
``ivy_data``
~~~~~~~~~~~~
This is a custom documenter for ``autodoc`` that documents Ivy data attributes that live
-in ``ivy.functional.ivy``, it will replace the module to ``ivy.`` instead of
+in ``ivy.functional.ivy``, it will replace the module to ``ivy.`` instead of
``ivy.functional.ivy.``.
It's used instead of simply using ``ivy.`` because data attributes have
@@ -353,6 +353,6 @@ no ``__doc__`` atribute, instead docs are discovered by parsing the source code
So for Sphinx to find the required docs, it needs to be supplied the full module name,
then using the ``autoivydata`` directive will replace the module name to ``ivy.``.
-Please refer to the `auto documenter guide in sphinx documentation
+Please refer to the `auto documenter guide in sphinx documentation
`_ for more
info.
diff --git a/docs/overview/deep_dive/containers.rst b/docs/overview/deep_dive/containers.rst
index 0b975eb990421..13521ec772f17 100644
--- a/docs/overview/deep_dive/containers.rst
+++ b/docs/overview/deep_dive/containers.rst
@@ -185,18 +185,18 @@ As for the special methods which are `implemented`_ in the main :class:`ivy.Cont
As a result, the operator functions will make use of the special methods of the lefthand passed input objects if available, otherwise it will make use of the reverse special method of the righthand operand.
For instance, if the lefthand operand at any given leaf of the container in an :class:`ivy.Array`, then the operator function will make calls to the special methods of this array object.
-As explained in the :ref:`Arrays` section of the Deep Dive, these special methods will in turn call the corresponding functions from the ivy functional API.
-
+As explained in the `Arrays `_ section of the Deep Dive, these special methods will in turn call the corresponding functions from the ivy functional API.
+
Examples include `__add__`_, `__sub__`_, `__mul__`_ and `__truediv__`_ which will make calls to :func:`ivy.add`, :func:`ivy.subtract`, :func:`ivy.multiply` and :func:`ivy.divide` respectively if the lefthand operand is an :class:`ivy.Array` object.
Otherwise, these special methods will be called on whatever objects are at the leaves of the container, such as int, float, :class:`ivy.NativeArray` etc.
Nestable Functions
------------------
-As introduced in the :ref:`Function Types` section, most functions in Ivy are *nestable*, which means that they can accept :class:`ivy.Container` instances in place of **any** of the arguments.
+As introduced in the `Function Types `_ section, most functions in Ivy are *nestable*, which means that they can accept :class:`ivy.Container` instances in place of **any** of the arguments.
Here, we expand on this explanation.
-Please check out the explanation in the :ref:`Function Types` section first.
+Please check out the explanation in the `Function Types `_ section first.
**Explicitly Nestable Functions**
diff --git a/docs/overview/deep_dive/continuous_integration.rst b/docs/overview/deep_dive/continuous_integration.rst
index bfabdc6973c00..e639efa7bcfca 100644
--- a/docs/overview/deep_dive/continuous_integration.rst
+++ b/docs/overview/deep_dive/continuous_integration.rst
@@ -289,7 +289,7 @@ Array API Tests
---------------
The `array-api-intelligent-tests.yml (Push) `_ and the `array-api-intelligent-tests-pr.yml (Pull Request) `_ workflows run the Array API Tests. Similar to Ivy Tests, The Array API tests are also determined intelligently and only relevant tests are triggered on each commit.
-More details about the Array API Tests are available `here `_.
+More details about the Array API Tests are available `here `_.
Periodic Testing
----------------
diff --git a/docs/overview/deep_dive/data_types.rst b/docs/overview/deep_dive/data_types.rst
index aecaebd30e9b2..f2f72dea820c2 100644
--- a/docs/overview/deep_dive/data_types.rst
+++ b/docs/overview/deep_dive/data_types.rst
@@ -80,7 +80,7 @@ Data Type Module
The `data_type.py`_ module provides a variety of functions for working with data types.
A few examples include :func:`ivy.astype` which copies an array to a specified data type, :func:`ivy.broadcast_to` which broadcasts an array to a specified shape, and :func:`ivy.result_type` which returns the dtype that results from applying the type promotion rules to the arguments.
-Many functions in the :mod:`data_type.py` module are *convenience* functions, which means that they do not directly modify arrays, as explained in the :ref:`Function Types` section.
+Many functions in the :mod:`data_type.py` module are *convenience* functions, which means that they do not directly modify arrays, as explained in the `Function Types `_ section.
For example, the following are all convenience functions:
`ivy.can_cast`_, which determines if one data type can be cast to another data type according to type-promotion rules, `ivy.dtype `__, which gets the data type for the input array, `ivy.set_default_dtype`_, which sets the global default data dtype, and `ivy.default_dtype`_, which returns the correct data type to use.
@@ -95,8 +95,7 @@ Data Type Promotion
In order to ensure that the same data type is always returned when operations are performed on arrays with different data types, regardless of which backend framework is set, Ivy has it's own set of data type promotion rules and corresponding functions.
These rules build directly on top of the `rules `_ outlined in the `Array API Standard`_.
-The rules are simple: all data type promotions in Ivy should adhere to this `promotion table `_,
-which is the union of the Array API Standard `promotion table `_ and an extra `promotion table `_.
+The rules are simple: all data type promotions in Ivy should adhere a promotion table that extends Array API Standard `promotion table `_ using this `promotion table `_, and one of two extra `promotion tables `_ depending on precision mode that will be explained in the following section.
In order to ensure adherence to this promotion table, many backend functions make use of the functions `ivy.promote_types `_, `ivy.type_promote_arrays `_, or `ivy.promote_types_of_inputs `_.
These functions: promote data types in the inputs and return the new data types, promote the data types of the arrays in the input and return new arrays, and promote the data types of the numeric or array values inputs and return new type promoted values, respectively.
@@ -182,10 +181,39 @@ Whenever the user defines data with a specific data type, they expect a certain
The user expects specific behaviour and memory constraints whenever they specify and use concrete data types, and those decisions should be respected.
Therefore, Ivy does not upcast specific values to improve the stability or precision of the computation.
+Precise Mode
+~~~~~~~~~~~~~~~
-Arguments in other Functions
-----------------------------
+There are cases that arise in mixed promotion (Integer and Float, Complex and Float) that aren't covered by the Array API Standard promotion table, and depending on each use case,
+the mixed promotion rules differ as observed in different frameworks, for example Tensorflow leaves integer/floating mixed promotion undefined to make behavior utterly predictable (at some cost to user convenience), while Numpy avoids precision loss at all costs even if that meant casting the arrays to wider-than-necessary dtypes
+
+Precise Promotion Table
+"""""""""""""""""""""""""
+
+This table focuses on numerical accuracy at the cost of a higher memory footprint. A 16-bit signed or unsigned integer cannot be represented at full precision by a 16-bit float, which has only 10 bits of mantissa. Therefore, it might make sense to promote integers to floats represented by twice the number of bits. There are two disadvantages of this approach:
+
+#. It still leaves int64 and uint64 promotion undefined, because there is no standard floating point type with enough bits of mantissa to represent their full range of values. We could relax the precision constraint and use ``float64`` as the upper bound for this case.
+#. Some operations result in types that are much wider than necessary; for example mixed operations between ``uint16`` and float16 would promote all the way to ``float64``, which is not ideal.
+
+.. code-block:: python
+
+ with ivy.PreciseMode(True):
+ print(ivy.promote_types("float32","int32"))
+ # float64
+Non-Precise Promotion Table
+"""""""""""""""""""""""""""""""""
+The advantage of this approach is that, outside unsigned ints, it avoids all wider-than-necessary promotions: you can never get an f64 output without a 64-bit input, and you can never get an ``float32`` output without a 32-bit input: this results in convenient semantics for working on accelerators while avoiding unwanted 64-bit values. This feature of giving primacy to floating point types resembles the type promotion behavior of PyTorch.
+the disadvantage of this approach is that mixed float/integer promotion is very prone to precision loss: for example, ``int64`` (with a maximum value of 9.2*10^18 can be promoted to ``float16`` (with a maximum value of 6.5*10^4, meaning most representable values will become inf, but we are fine accepting potential loss of precision (but not loss of magnitude) in mixed type promotion which satisfies most of the use cases in deep learning scenarios.
+
+.. code-block:: python
+
+ with ivy.PreciseMode(False):
+ print(ivy.promote_types("float32","int32"))
+ # float32
+
+Arguments in other Functions
+-------------------
All ``dtype`` arguments are keyword-only.
All creation functions include the ``dtype`` argument, for specifying the data type of the created array.
Some other non-creation functions also support the ``dtype`` argument, such as :func:`ivy.prod` and :func:`ivy.sum`, but most functions do not include it.
@@ -193,7 +221,7 @@ The non-creation functions which do support it are generally functions that invo
The ``dtype`` argument is handled in the `infer_dtype`_ wrapper, for all functions which have the decorator :code:`@infer_dtype`.
This function calls `ivy.default_dtype`_ in order to determine the correct data type.
-As discussed in the :ref:`Function Wrapping` section, this is applied to all applicable functions dynamically during `backend setting`_.
+As discussed in the `Function Wrapping `_ section, this is applied to all applicable functions dynamically during `backend setting`_.
Overall, `ivy.default_dtype`_ infers the data type as follows:
@@ -653,4 +681,4 @@ If you have any questions, please feel free to reach out on `discord`_ in the `d
\ No newline at end of file
+
diff --git a/docs/overview/deep_dive/devices.rst b/docs/overview/deep_dive/devices.rst
index 4f2cbbbcf24ce..1159535728bdb 100644
--- a/docs/overview/deep_dive/devices.rst
+++ b/docs/overview/deep_dive/devices.rst
@@ -33,7 +33,7 @@ The devices currently supported by Ivy are as follows:
* gpu:idx
* tpu:idx
-In a similar manner to the :class:`ivy.Dtype` and :class:`ivy.NativeDtype` classes (see :ref:`Data Types`), there is both an `ivy.Device`_ class and an :class:`ivy.NativeDevice` class, with :class:`ivy.NativeDevice` initially set as an `empty class`_.
+In a similar manner to the :class:`ivy.Dtype` and :class:`ivy.NativeDtype` classes (see `Data Types `_), there is both an `ivy.Device`_ class and an :class:`ivy.NativeDevice` class, with :class:`ivy.NativeDevice` initially set as an `empty class`_.
The :class:`ivy.Device` class derives from :code:`str`, and has simple logic in the constructor to verify that the string formatting is correct.
When a backend is set, the :class:`ivy.NativeDevice` is replaced with the backend-specific `device class`_.
@@ -43,7 +43,7 @@ Device Module
The `device.py`_ module provides a variety of functions for working with devices.
A few examples include :func:`ivy.get_all_ivy_arrays_on_dev` which gets all arrays which are currently alive on the specified device, :func:`ivy.dev` which gets the device for input array, and :func:`ivy.num_gpus` which determines the number of available GPUs for use with the backend framework.
-Many functions in the :mod:`device.py` module are *convenience* functions, which means that they do not directly modify arrays, as explained in the :ref:`Function Types` section.
+Many functions in the :mod:`device.py` module are *convenience* functions, which means that they do not directly modify arrays, as explained in the `Function Types `_ section.
For example, the following are all convenience functions: `ivy.total_mem_on_dev`_, which gets the total amount of memory for a given device, `ivy.dev_util`_, which gets the current utilization (%) for a given device, `ivy.num_cpu_cores`_, which determines the number of cores available in the CPU, and `ivy.default_device`_, which returns the correct device to use.
@@ -64,7 +64,7 @@ In cases where the input arrays are located on different devices, an error will
The :code:`device` argument is handled in `infer_device`_ for all functions which have the :code:`@infer_device` decorator, similar to how :code:`dtype` is handled.
This function calls `ivy.default_device`_ in order to determine the correct device.
-As discussed in the :ref:`Function Wrapping` section, this is applied to all applicable functions dynamically during `backend setting`_.
+As discussed in the `Function Wrapping `_ section, this is applied to all applicable functions dynamically during `backend setting`_.
Overall, `ivy.default_device`_ infers the device as follows:
@@ -77,7 +77,7 @@ Overall, `ivy.default_device`_ infers the device as follows:
For the majority of functions which defer to `infer_device`_ for handling the device, these steps will have been followed and the :code:`device` argument will be populated with the correct value before the backend-specific implementation is even entered into.
Therefore, whereas the :code:`device` argument is listed as optional in the ivy API at :mod:`ivy/functional/ivy/category_name.py`, the argument is listed as required in the backend-specific implementations at :mod:`ivy/functional/backends/backend_name/category_name.py`.
-This is exactly the same as with the :code:`dtype` argument, as explained in the :ref:`Data Types` section.
+This is exactly the same as with the :code:`dtype` argument, as explained in the `Data Types `_ section.
Let's take a look at the function :func:`ivy.zeros` as an example.
@@ -155,7 +155,7 @@ doesn't care about this, it moves all the tensors to the same device before perf
**Controlling Device Handling Behaviour**
-In Ivy, users can control the device on which the operation is to be executed using `ivy.set_soft_device_mode`_ flag. There are two cases for this,
+In Ivy, users can control the device on which the operation is to be executed using `ivy.set_soft_device_mode`_ flag. There are two cases for this,
either the soft device mode is set to :code:`True` or :code:`False`.
**When ivy.set_soft_device_mode(True)**:
@@ -167,7 +167,7 @@ In the example below, even though the input arrays :code:`x` and :code:`y` are c
are moved to :code:`ivy.default_device()` while performing :code:`ivy.add` operation, and the output array will be on this device.
.. code-block:: python
-
+
ivy.set_backend("torch")
ivy.set_soft_device_mode(True)
x = ivy.array([1], device="cpu")
@@ -214,7 +214,7 @@ This is the exception you will get while running the code above:
File "/content/ivy/ivy/func_wrapper.py", line 863, in _handle_device_shifting
raise ivy.utils.exceptions.IvyException(
During the handling of the above exception, another exception occurred:
- Expected all input arrays to be on the same device, but found atleast two devices - ('cpu', 'gpu:0'),
+ Expected all input arrays to be on the same device, but found atleast two devices - ('cpu', 'gpu:0'),
set `ivy.set_soft_device_mode(True)` to handle this problem.
b. If all the input arrays are on the same device, the operation is executed without raising any device exceptions.
@@ -278,5 +278,5 @@ If you have any questions, please feel free to reach out on `discord`_ in the `d
.. raw:: html
diff --git a/docs/overview/deep_dive/exception_handling.rst b/docs/overview/deep_dive/exception_handling.rst
index 9c192a3f0e3a7..8695c318fe42d 100644
--- a/docs/overview/deep_dive/exception_handling.rst
+++ b/docs/overview/deep_dive/exception_handling.rst
@@ -57,14 +57,14 @@ For a more general case, the :code:`IvyError` class can be used.
def __init__(self, *messages, include_backend=False):
super().__init__(*messages, include_backend=include_backend)
-More Custom Exception classes were created to unify sub-categories of errors. We try our best to ensure that the same type of
+More Custom Exception classes were created to unify sub-categories of errors. We try our best to ensure that the same type of
Exception is raised for the same type of Error regardless of the backend.
This will ensure that the exceptions are truly unified for all the different types of errors.
The implementations of these custom classes are exactly the same as :code:`IvyError` class.
Currently there are 5 custom exception classes in ivy.
1. :code:`IvyIndexError`: This Error is raised for anything Indexing related. For Instance, providing out of bound axis in any function.
-2. :code:`IvyValueError`: This is for anything related to providing wrong values. For instance, passing :code:`high` value
+2. :code:`IvyValueError`: This is for anything related to providing wrong values. For instance, passing :code:`high` value
smaller than :code:`low` value in :code:`ivy.random_uniform`.
3. :code:`IvyAttributeError`: This is raised when an undefined attribute is referenced.
4. :code:`IvyBroadcastShapeError`: This is raised whenever 2 shapes are expected to be broadcastable but are not.
@@ -75,12 +75,12 @@ The correct type of Exception class should be used for the corresponding type of
Configurable Mode for Stack Trace
---------------------------------
-Ivy's transpilation nature allows users to write code in their preferred frontend
-framework and then execute it with a different backend framework. For example, a
-user who is comfortable with NumPy can use Ivy's NumPy frontend to run their code
-with a JAX backend. However, since they may have no prior experience with JAX or
-other backend frameworks, they may not want to encounter stack traces that traverse
-Ivy and JAX functions. In such cases, it may be preferable for the user to avoid
+Ivy's transpilation nature allows users to write code in their preferred frontend
+framework and then execute it with a different backend framework. For example, a
+user who is comfortable with NumPy can use Ivy's NumPy frontend to run their code
+with a JAX backend. However, since they may have no prior experience with JAX or
+other backend frameworks, they may not want to encounter stack traces that traverse
+Ivy and JAX functions. In such cases, it may be preferable for the user to avoid
encountering stack traces that extend through Ivy and JAX functions.
Therefore, options are made available for the stack traces to either truncate
@@ -400,7 +400,7 @@ Let's look at the comparison of before and after adding the decorator.
In NumPy,
.. code-block:: none
-
+
>>> x = ivy.array([0,0,1])
>>> ivy.all(x, axis=2)
@@ -449,7 +449,7 @@ and for Numpy, :code:`AxisError` is raised. To unify the behaviour, we raise :co
In Numpy,
.. code-block:: python
-
+
# in ivy/functional/backends/numpy/utility.py
def all(
x: np.ndarray,
diff --git a/docs/overview/deep_dive/formatting.rst b/docs/overview/deep_dive/formatting.rst
index 307f059575dd3..c561f1fe04b97 100644
--- a/docs/overview/deep_dive/formatting.rst
+++ b/docs/overview/deep_dive/formatting.rst
@@ -3,7 +3,6 @@ Formatting
.. _`flake8`: https://flake8.pycqa.org/en/latest/index.html
.. _`black`: https://black.readthedocs.io/en/stable/index.html
-.. _`pre-commit guide`: https://unify.ai/docs/ivy/overview/contributing/setting_up.html#pre-commit
.. _`formatting channel`: https://discord.com/channels/799879767196958751/1028266706436624456
.. _`discord`: https://discord.gg/sXyFF8tDtm
@@ -19,7 +18,7 @@ Lint Checks
In addition to `black`_ and `flake8`_, Ivy uses other linters to help automate the formatting process, especially for
issues `flake8`_ detects but doesn't fix automatically. In addition to that, we validate docstring as part of our
-linting process. You can learn more about our docstring formatting in the :ref:`Docstrings` section.
+linting process. You can learn more about our docstring formatting in the `Docstrings `_ section.
We use the following linters:
@@ -28,7 +27,7 @@ We use the following linters:
* `autoflake `_
* `docformatter `_
* `pydocstyle `_
-* `ivy-lint `_ (WIP 🚧)
+* `ivy-lint `_
You can also take a look at our configuration for linting in `setup.cfg `_
file.
@@ -77,6 +76,7 @@ You should expect to see something similar to the following output when you run
flake8...................................................................Passed
docformatter.............................................................Passed
pydocstyle...............................................................Passed
+ ivy-lint.................................................................Passed
[INFO] Restored changes from ~/.cache/pre-commit/patch1687898304-8072.
[formatting-docs 3516aed563] Test commit
1 file changed, 1 insertion(+)
@@ -99,6 +99,7 @@ If something goes wrong, you will see the following output:
flake8...................................................................Passed
docformatter.............................................................Passed
pydocstyle...............................................................Passed
+ ivy-lint.................................................................Passed
[INFO] Restored changes from ~/.cache/pre-commit/patch1687898304-8072.
You will notice that some files have changed if you checked ``git status``, you'll need to add them and commit again.
@@ -168,22 +169,22 @@ We have a GitHub action that runs:
1. Every day at 08:00 UTC
2. Manually invoked by making a comment with ``ivy-gardener`` on a PR
-The first action is to ensure that the code in the whole codebase is always formatted correctly. The second action
-is to reformat the files you changed in your PR directly on GitHub. This is useful in case if you didn't setup
+The first action is to ensure that the code in the whole codebase is always formatted correctly. The second action
+is to reformat the files you changed in your PR directly on GitHub. This is useful in case if you didn't setup
pre-commit correctly or if you or one of our maintainers want to reformat your code remotely.
-Under the hood, when ``ivy-gardener`` is found in a comment, an ivy bot will trigger the same set of lint checks
+Under the hood, when ``ivy-gardener`` is found in a comment, an ivy bot will trigger the same set of lint checks
as in the pre-commit process. Then the suggested changes produced in the checks will be applied automatically as
-a new commit if there is any.
+a new commit if there is any.
-However, it is possible for the linters run in the ``ivy-gardener`` and the GitHub action every day to face
-formatting errors that need human intervention like typos and uninitialized arguments. In this case, errors will
-be thrown by the linters and by the lint checks that runs later, while fixes to other simpler errors will still
+However, it is possible for the linters run in the ``ivy-gardener`` and the GitHub action every day to face
+formatting errors that need human intervention like typos and uninitialized arguments. In this case, errors will
+be thrown by the linters and by the lint checks that runs later, while fixes to other simpler errors will still
be applied by the ``ivy-gardener`` properly.
-On the other hand, ``ivy-gardener`` itself can fail if the bot handling it (ivy-branch) can not apply the changes
-suggested by the linters, for example, when it does not have access to edit the target branch. In this case, you
-should try to give the maintainer bot the access to your branch (which is an option shown in GitHub UI) and give it
+On the other hand, ``ivy-gardener`` itself can fail if the bot handling it (ivy-branch) can not apply the changes
+suggested by the linters, for example, when it does not have access to edit the target branch. In this case, you
+should try to give the maintainer bot the access to your branch (which is an option shown in GitHub UI) and give it
another try, or manually resolve the formatting errors by commiting the changes yourself.
**Round Up**
diff --git a/docs/overview/deep_dive/function_arguments.rst b/docs/overview/deep_dive/function_arguments.rst
index 537b45dcb9bf5..988db211600ec 100644
--- a/docs/overview/deep_dive/function_arguments.rst
+++ b/docs/overview/deep_dive/function_arguments.rst
@@ -10,7 +10,7 @@ Function Arguments
Here, we explain how the function arguments differ between the placeholder implementation at :mod:`ivy/functional/ivy/category_name.py`, and the backend-specific implementation at :mod:`ivy/functional/backends/backend_name/category_name.py`.
-Many of these points are already addressed in the previous sections: :ref:`Arrays`, :ref:`Data Types`, :ref:`Devices` and :ref:`Inplace Updates`.
+Many of these points are already addressed in the previous sections: `Arrays `_, `Data Types `_, `Devices `_ and `Inplace Updates `_.
However, we thought it would be convenient to revisit all of these considerations in a single section, dedicated to function arguments.
As for type-hints, all functions in the Ivy API at :mod:`ivy/functional/ivy/category_name.py` should have full and thorough type-hints.
@@ -161,13 +161,13 @@ For example, calling any of (:code:`+`, :code:`-`, :code:`*`, :code:`/` etc.) on
:class:`ivy.NativeArray` instances are also not permitted for the :code:`out` argument, which is used in many functions.
This is because the :code:`out` argument dictates the array to which the result should be written, and so it effectively serves the same purpose as the function return when no :code:`out` argument is specified.
-This is all explained in more detail in the :ref:`Arrays` section.
+This is all explained in more detail in the `Arrays `_ section.
out Argument
------------
The :code:`out` argument should always be provided as a keyword-only argument, and it should be added to all functions in the Ivy API and backend API which support inplace updates, with a default value of :code:`None` in all cases.
-The :code:`out` argument is explained in more detail in the :ref:`Inplace Updates` section.
+The :code:`out` argument is explained in more detail in the `Inplace Updates `_ section.
dtype and device arguments
--------------------------
@@ -175,7 +175,7 @@ dtype and device arguments
In the Ivy API at :mod:`ivy/functional/ivy/category_name.py`, the :code:`dtype` and :code:`device` arguments should both always be provided as keyword-only arguments, with a default value of :code:`None`.
In contrast, these arguments should both be added as required arguments in the backend implementation at :mod:`ivy/functional/backends/backend_name/category_name.py`.
In a nutshell, by the time the backend implementation is entered, the correct :code:`dtype` and :code:`device` to use have both already been correctly handled by code which is wrapped around the backend implementation.
-This is further explained in the :ref:`Data Types` and :ref:`Devices` sections respectively.
+This is further explained in the `Data Types `_ and `Devices `_ sections respectively.
Numbers in Operator Functions
-----------------------------
diff --git a/docs/overview/deep_dive/function_types.rst b/docs/overview/deep_dive/function_types.rst
index 9765d6383aee6..aba496df485d1 100644
--- a/docs/overview/deep_dive/function_types.rst
+++ b/docs/overview/deep_dive/function_types.rst
@@ -81,8 +81,8 @@ The backend-specific implementation of :func:`ivy.tan` for PyTorch in :mod:`ivy
x = _cast_for_unary_op(x)
return torch.tan(x, out=out)
-The reason that the Ivy implementation has type hint :code:`Union[ivy.Array, ivy.NativeArray]` but PyTorch implementation has :class:`torch.Tensor` is explained in the :ref:`Arrays` section.
-Likewise, the reason that the :code:`out` argument in the Ivy implementation has array type hint :class:`ivy.Array` whereas :code:`x` has :code:`Union[ivy.Array, ivy.NativeArray]` is also explained in the :ref:`Arrays` section.
+The reason that the Ivy implementation has type hint :code:`Union[ivy.Array, ivy.NativeArray]` but PyTorch implementation has :class:`torch.Tensor` is explained in the `Arrays `_ section.
+Likewise, the reason that the :code:`out` argument in the Ivy implementation has array type hint :class:`ivy.Array` whereas :code:`x` has :code:`Union[ivy.Array, ivy.NativeArray]` is also explained in the `Arrays `_ section.
Compositional Functions
-----------------------
@@ -116,7 +116,7 @@ Mixed Functions
---------------
---------------
-Sometimes, a function may only be provided by some of the supported backends. In this case, we have to take a mixed approach. We should always have a backend-specific implementation if there is a similar function provided by a certain backend. This maximises runtime efficiency, as the function in the backend will be implemented directly in C or C++. Such functions have some backend-specific implementations in :mod:`ivy/functional/backends/backend_name/category_name.py`, but not for all backends. To support backends that do not have a backend-specific implementation, a compositional implementation is also provided in :mod:`ivy/functional/ivy/category_name.py`. Compositional functions should only be used when there is no similar function to wrap in the backend.
+Sometimes, a function may only be provided by some of the supported backends. In this case, we have to take a mixed approach. We should always have a backend-specific implementation if there is a similar function provided by a certain backend. This maximises runtime efficiency, as the function in the backend will be implemented directly in C or C++. Such functions have some backend-specific implementations in :mod:`ivy/functional/backends/backend_name/category_name.py`, but not for all backends. To support backends that do not have a backend-specific implementation, a compositional implementation is also provided in :mod:`ivy/functional/ivy/category_name.py`. Compositional functions should only be used when there is no similar function to wrap in the backend.
Because these functions include both a compositional implementation and also at least one backend-specific implementation, these functions are referred to as *mixed*.
@@ -135,7 +135,7 @@ One example of this is :code:`ivy.linear` for which the torch native function :c
to be a 2 dimensional tensor while as ivy also allows the :code:`weight` argument to be 3 dimensional. While achieving the objective of having superset
behaviour across the backends, the native functionality of frameworks should be made use of as much as possible. Even if a framework-specific function
doesn't provide complete superset behaviour, we should still make use of the partial behaviour that it provides and then add more logic for the
-remaining part. This is explained in detail in the :ref:`Maximizing Usage of Native Functionality` section. Ivy allows this partial support with the help of the `partial_mixed_handler`_
+remaining part. This is explained in detail in the :ref:`overview/deep_dive/superset_behaviour:Maximizing Usage of Native Functionality` section. Ivy allows this partial support with the help of the `partial_mixed_handler`_
attribute which should be added to the backend implementation with a boolean function that specifies some condition on the inputs to switch between the compositional
and primary implementations. For example, the :code:`torch` backend implementation of :code:`linear`` looks like:
@@ -159,7 +159,7 @@ the :code:`handle_partial_mixed_function` decorator first evaluates the boolean
is `True` and the compositional implementation otherwise.
-For further information on decorators, please refer to the :ref:`Function Wrapping` section.
+For further information on decorators, please refer to the `Function Wrapping `_ section.
For all mixed functions, we must add the :code:`mixed_backend_wrappers` attribute to the compositional implementation of mixed functions to specify which additional wrappers need to be applied to the primary implementation and which ones from the compositional implementation should be skipped.
We do this by creating a dictionary of two keys, :code:`to_add` and :code:`to_skip`, each containing the tuple of wrappers to be added or skipped respectively. In general, :code:`handle_out_argument`, :code:`inputs_to_native_arrays` and :code:`outputs_to_ivy_arrays`
@@ -215,9 +215,9 @@ This *nestable* property of Ivy functions means that the same function can be us
This added support for handling :class:`ivy.Container` instances is all handled automatically when `_wrap_function`_ is applied to every function in the :code:`ivy` module during `backend setting`_.
This will add the `handle_nestable`_ wrapping to the function if it has the :code:`@handle_nestable` decorator.
-This function wrapping process is covered in a bit more detail in the :ref:`Function Wrapping` section.
+This function wrapping process is covered in a bit more detail in the `Function Wrapping `_ section.
-Nestable functions are explained in more detail in the :ref:`Containers` section.
+Nestable functions are explained in more detail in the `Containers ` section.
Convenience Functions
---------------------
diff --git a/docs/overview/deep_dive/function_wrapping.rst b/docs/overview/deep_dive/function_wrapping.rst
index c07c0132298a1..8a585244222e6 100644
--- a/docs/overview/deep_dive/function_wrapping.rst
+++ b/docs/overview/deep_dive/function_wrapping.rst
@@ -17,8 +17,9 @@ Function Wrapping
.. _`handle_nestable`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L896
.. _`inputs_to_native_shapes`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L488
.. _`outputs_to_ivy_shapes`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L501
+.. _`to_native_shapes_and_back`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L514
.. _`handle_view`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L627
-.. _`handle_view_indexing`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L659
+.. _`handle_view_indexing`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L659
.. _`handle_array_function`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/func_wrapper.py#L299
.. _`handle_complex_input`: https://github.com/unifyai/ivy/blob/bd9b5b1080d33004e821a48c486b3a879b9d6616/ivy/func_wrapper.py#L1393
.. _`repo`: https://github.com/unifyai/ivy
@@ -29,6 +30,11 @@ Function Wrapping
.. _`ivy.linear`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/functional/ivy/layers.py#L81
.. _`handle_exceptions`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/utils/exceptions.py#L189
.. _`example`: https://github.com/unifyai/ivy/blob/5658401b266352d3bf72c95e4af6ae9233115722/ivy/functional/backends/torch/layers.py#L30
+.. _`Arrays`: arrays.rst
+.. _`Inplace Updates`: inplace_updates.rst
+.. _`Data Types`: data_types.rst
+.. _`Devices`: devices.rst
+.. _`Backend Setting`: backend_setting.rst
When a backend framework is set by calling :code:`ivy.set_backend(backend_name)`, then all Ivy functions are `wrapped`_.
This is achieved by calling `_wrap_function`_, which will apply the appropriate wrapping to the given function, based on what decorators it has.
@@ -37,7 +43,7 @@ For example, `abs`_ has the decorators :code:`@to_native_arrays_and_back` and :c
The new function returned by :code:`_wrap_function` is a replacement of the original function with extra code added to support requirements common to many functions in the API.
This is the main purpose of the wrapping, to avoid code duplication which would exist if we added identical logic in every single function independently.
-Depending on the function being wrapped, the new function might handle :ref:`Arrays`, :ref:`Inplace Updates`, :ref:`Data Types` and/or :ref:`Devices`.
+Depending on the function being wrapped, the new function might handle `Arrays`_, `Inplace Updates`_, `Data Types`_ and/or `Devices`_.
Our test decorators actually transforms to :code:`@given` decorators at Pytest collecting time, therefore this allows us to use other **Hypothesis** decorators like, :code:`@reproduce_failure`, :code:`@settings`, :code:`@seed`.
@@ -74,11 +80,11 @@ This recommended order is followed to ensure that tests are efficient and accura
Conversion Wrappers
^^^^^^^^^^^^^^^^^^^
-#. `inputs_to_native_arrays`_ : This wrapping function converts all :class:`ivy.Array` instances in the arguments to their :class:`ivy.NativeArray` counterparts, based on the :ref:`Backend Setting` before calling the function.
-#. `inputs_to_ivy_arrays`_ : This wrapping function converts all :class:`ivy.NativeArray` instances in the arguments to their :class:`ivy.Array` counterparts, based on the :ref:`Backend Setting` before calling the function.
-#. `outputs_to_ivy_arrays`_ : This wrapping function converts all :class:`ivy.NativeArray` instances in the outputs to their :class:`ivy.Array` counterparts, based on the :ref:`Backend Setting` before calling the function.
+#. `inputs_to_native_arrays`_ : This wrapping function converts all :class:`ivy.Array` instances in the arguments to their :class:`ivy.NativeArray` counterparts, based on the `Backend Setting`_ before calling the function.
+#. `inputs_to_ivy_arrays`_ : This wrapping function converts all :class:`ivy.NativeArray` instances in the arguments to their :class:`ivy.Array` counterparts, based on the `Backend Setting`_ before calling the function.
+#. `outputs_to_ivy_arrays`_ : This wrapping function converts all :class:`ivy.NativeArray` instances in the outputs to their :class:`ivy.Array` counterparts, based on the `Backend Setting`_ before calling the function.
#. `to_native_arrays_and_back`_ : This wrapping function converts all :class:`ivy.Array` instances in the arguments to their :class:`ivy.NativeArray` counterparts, calls the function with those arguments and then converts the :class:`ivy.NativeArray` instances in the output back to :class:`ivy.Array`.
- This wrapping function is heavily used because it enables achieving the objective of ensuring that every ivy function could accept an :class:`ivy.Array` and return an :class:`ivy.Array`, making it independent of the :ref:`Backend Setting`.
+ This wrapping function is heavily used because it enables achieving the objective of ensuring that every ivy function could accept an :class:`ivy.Array` and return an :class:`ivy.Array`, making it independent of the `Backend Setting`_.
Inference Wrappers
^^^^^^^^^^^^^^^^^^
@@ -95,7 +101,7 @@ Out Argument Support
#. `handle_out_argument`_ : This wrapping function is used in nearly all ivy functions.
It enables appropriate handling of the :code:`out` argument of functions.
In cases where the backend framework natively supports the :code:`out` argument for a function, we prefer to use it as it's a more efficient implementation of the :code:`out` argument for that particular backend framework.
- But in cases when it isn't supported, we support it anyway with :ref:`Inplace Updates`.
+ But in cases when it isn't supported, we support it anyway with `Inplace Updates`_.
Nestable Support
^^^^^^^^^^^^^^^^
@@ -105,7 +111,7 @@ Nestable Support
Partial Mixed Function Support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#. `handle_partial_mixed_function`_: This wrapping function enables switching between compositional and primary implementations of :ref:`Mixed Functions` based on some condition on the arguments of the function.
+#. `handle_partial_mixed_function`_: This wrapping function enables switching between compositional and primary implementations of :ref:`overview/deep_dive/function_types:Mixed Functions` based on some condition on the arguments of the function.
#. The condition is specified through a lambda function which when evaluates to `True` the primary implementation is run and otherwise the compositional implementation is executed.
#. For backends that have a primary implementation of a mixed function, the reference to the compositional implementation is `stored as an attribute`_ inside the backend function during backend setting. To make use of this decorator, one must
#. add the :code:`partial_mixed_handler` attribute containing the lambda function to the backend implementation. Here's an `example`_ from the torch backend implementation of linear.
@@ -113,29 +119,29 @@ Partial Mixed Function Support
Shape Conversion
^^^^^^^^^^^^^^^^
-#. `inputs_to_native_shapes`_ : This wrapping function converts all :class:`ivy.Shape` instances in the arguments to their :class:`ivy.NativeShape` counterparts, based on the :ref:`Backend Setting` before calling the function.
-#. `outputs_to_ivy_shapes`_ : This wrapping function converts all :class:`ivy.NativeShape` instances in the outputs to their :class:`ivy.Shape` counterparts, based on the :ref:`Backend Setting` before calling the function.
+#. `inputs_to_native_shapes`_ : This wrapping function converts all :class:`ivy.Shape` instances in the arguments to their :class:`ivy.NativeShape` counterparts, based on the `Backend Setting`_ before calling the function.
+#. `outputs_to_ivy_shapes`_ : This wrapping function converts all :class:`ivy.NativeShape` instances in the outputs to their :class:`ivy.Shape` counterparts, based on the `Backend Setting`_ before calling the function.
#. `to_native_shapes_and_back`_ : This wrapping function converts all :class:`ivy.Shape` instances in the arguments to their :class:`ivy.NativeShape` counterparts, calls the function with those arguments and then converts the :class:`ivy.NativeShape` instances in the output back to :class:`ivy.Shape`.
View Handling
^^^^^^^^^^^^^
-#. `handle_view`_ : This wrapping function performs view handling based on our :ref:`Views` policy.
+#. `handle_view`_ : This wrapping function performs view handling based on our :ref:`overview/deep_dive/inplace_updates:Views` policy.
#. `handle_view_indexing`_ : This wrapping function is aimed at handling views for indexing.
-Exception Handling
+Exception Handling
^^^^^^^^^^^^^^^^^^
-#. `handle_exceptions`_ : This wrapping function helps in catching native exceptions and unifying them into `IvyException` or the relevant subclasses. More information can be found in the :ref:`Exception Handling` section.
+#. `handle_exceptions`_ : This wrapping function helps in catching native exceptions and unifying them into `IvyException` or the relevant subclasses. More information can be found in the :ref:`overview/deep_dive/function_wrapping:Exception Handling` section.
-Miscellaneous Wrappers
+Miscellaneous Wrappers
^^^^^^^^^^^^^^^^^^^^^^
-#. `handle_array_function`_ : This wrapping function enables :ref:`Integrating custom classes with Ivy`
+#. `handle_array_function`_ : This wrapping function enables :ref:`overview/deep_dive/arrays:Integrating custom classes with Ivy`
#. `handle_complex_input`_ : This wrapping function enables handling of complex numbers. It introduces a keyword argument :code:`complex_mode`, which is used to choose the function's behaviour as per the wrapper's docstring.
-When calling `_wrap_function`_ during :ref:`Backend Setting`, firstly the attributes of the functions are checked to get all the wrapping functions for a particular function.
+When calling `_wrap_function`_ during `Backend Setting`_, firstly the attributes of the functions are checked to get all the wrapping functions for a particular function.
Then all the wrapping functions applicable to a function are used to wrap the function.
Each of these topics and each associated piece of logic added by the various wrapper functions are covered in more detail in the next sections.
diff --git a/docs/overview/deep_dive/gradients.rst b/docs/overview/deep_dive/gradients.rst
index 5ec644aa6a015..d33d17a7d2e7d 100644
--- a/docs/overview/deep_dive/gradients.rst
+++ b/docs/overview/deep_dive/gradients.rst
@@ -7,7 +7,7 @@ Gradients
Overview
--------
-Gradients are a crucial aspect of all modern deep learning workflows.
+Gradients are a crucial aspect of all modern deep learning workflows.
Different frameworks provide different APIs for gradient computation and there were a few considerations to be made while building a unified gradients API in Ivy.
There are a number of functions added in ivy to allow gradient computation, but we'll mainly focus on the most commonly used and the most general function :func:`ivy.execute_with_gradients`.
This is because the other gradient functions such as :func:`ivy.value_and_grad` and :func:`ivy.grad` can be considered as providing a subset of the functionality that :func:`ivy.execute_with_gradients` provides.
@@ -21,13 +21,13 @@ The :func:`ivy.execute_with_gradients` function signature
Following is the pseudo function signature for the :func:`ivy.execute_with_gradients` function,
.. code-block:: python
-
+
def execute_with_gradients (
func : Callable,
xs : Any arbitrary nest,
xs_grad_idxs : Input indices,
ret_grad_idxs : Output indices,
- ) :
+ ) :
return func_ret, grads
The :code:`func` in the input can be any user-defined function that returns a single scalar or any arbitrary nest of scalars.
@@ -36,13 +36,13 @@ By scalars, we are referring to zero-dimensional arrays.
So for example, the following are some valid outputs by the :code:`func`,
.. code-block:: python
-
+
ivy.array(12.)
-
+
# OR
ivy.Container(
- a=ivy.array(12.),
+ a=ivy.array(12.),
b=ivy.Container(
c=ivy.array(15.),
d=ivy.array(32.)
@@ -74,8 +74,8 @@ An example using :func:`ivy.execute_with_gradients`
xs = [x, y]
ret, grads = ivy.execute_with_gradients(
- func,
- xs,
+ func,
+ xs,
xs_grad_idxs=[[0]],
ret_grad_idxs=[["a"]]
)
@@ -126,7 +126,7 @@ Our policy on gradients
* The gradient API is fully-functional in ivy.
* There is no explicit variable class or any public-facing function for adding gradient support to an ivy.Array.
* The gradient functions in ivy implicitly convert all arrays to support gradient computation before computing gradients and detach all arrays after computing gradients.
-* We don't retain any previously tracked computations in arrays by frameworks like torch for e.g.
+* We don't retain any previously tracked computations in arrays by frameworks like torch for e.g.
* This makes our gradient API disambiguous, flexible, and easy to debug.
* Any framework-specific tracking of computations or variable classes should be handled in the corresponding frontends.
diff --git a/docs/overview/deep_dive/inplace_updates.rst b/docs/overview/deep_dive/inplace_updates.rst
index 2faaf7c9b3a77..42df6520a9668 100644
--- a/docs/overview/deep_dive/inplace_updates.rst
+++ b/docs/overview/deep_dive/inplace_updates.rst
@@ -9,7 +9,6 @@ Inplace Updates
.. _`jax.numpy.tan`: https://jax.readthedocs.io/en/latest/_autosummary/jax.numpy.tan.html?highlight=tan
.. _`presence of this attribute`: https://github.com/unifyai/ivy/blob/8ded4a5fc13a278bcbf2d76d1fa58ab41f5797d0/ivy/func_wrapper.py#L341
.. _`by the backend function`: https://github.com/unifyai/ivy/blob/8ded4a5fc13a278bcbf2d76d1fa58ab41f5797d0/ivy/func_wrapper.py#L372
-.. _`by the wrapper`: https://github.com/unifyai/ivy/blob/8ded4a5fc13a278bcbf2d76d1fa58ab41f5797d0/ivy/func_wrapper.py#L377
.. _`handled by the wrapper`: https://github.com/unifyai/ivy/blob/8ded4a5fc13a278bcbf2d76d1fa58ab41f5797d0/ivy/func_wrapper.py#L373
.. _`_wrap_fn`: https://github.com/unifyai/ivy/blob/6497b8a3d6b0d8aac735a158cd03c8f98eb288c2/ivy/container/wrapping.py#L69
.. _`NON_WRAPPED_FUNCTIONS`: https://github.com/unifyai/ivy/blob/fdaea62380c9892e679eba37f26c14a7333013fe/ivy/func_wrapper.py#L9
@@ -17,8 +16,6 @@ Inplace Updates
.. _`ivy.reshape`: https://github.com/unifyai/ivy/blob/633eb420c5006a0a17c238bfa794cf5b6add8598/ivy/functional/ivy/manipulation.py#L418
.. _`ivy.astype`: https://github.com/unifyai/ivy/blob/8482eb3fcadd0721f339a1a55c3f3b9f5c86d8ba/ivy/functional/ivy/data_type.py#L46
.. _`ivy.asarray`: https://github.com/unifyai/ivy/blob/8482eb3fcadd0721f339a1a55c3f3b9f5c86d8ba/ivy/functional/ivy/creation.py#L114
-.. _`wrapping`:
-.. _`ivy.inplace_update`: https://github.com/unifyai/ivy/blob/3a21a6bef52b93989f2fa2fa90e3b0f08cc2eb1b/ivy/functional/ivy/general.py#L1137
.. _`repo`: https://github.com/unifyai/ivy
.. _`discord`: https://discord.gg/sXyFF8tDtm
.. _`inplace updates channel`: https://discord.com/channels/799879767196958751/1028681763947552778
@@ -28,7 +25,7 @@ Inplace Updates
Inplace updates enable users to overwrite the contents of existing arrays with new data.
This enables much more control over the memory-efficiency of the program, preventing old unused arrays from being kept in memory for any longer than is strictly necessary.
-The function `ivy.inplace_update`_ enables explicit inplace updates.
+The function :func:`ivy.inplace_update` enables explicit inplace updates.
:func:`ivy.inplace_update` is a *primary* function, and the backend-specific implementations for each backend are presented below.
We also explain the rationale for why each implementation is the way it is, and the important differences.
@@ -256,14 +253,14 @@ This could for example be the input array itself, but can also be any other arra
All Ivy functions which return a single array should support inplace updates via the :code:`out` argument.
The type hint of the :code:`out` argument is :code:`Optional[ivy.Array]`.
However, as discussed above, if the function is *nestable* then :class:`ivy.Container` instances are also supported.
-:class:`ivy.Container` is omitted from the type hint in such cases, as explained in the :ref:`Function Arguments` section.
+:class:`ivy.Container` is omitted from the type hint in such cases, as explained in the `Function Arguments `_ section.
When the :code:`out` argument is unspecified, then the return is simply provided in a newly created :class:`ivy.Array` (or :class:`ivy.Container` if *nestable*).
However, when :code:`out` is specified, then the return is provided as an inplace update of the :code:`out` argument provided.
This can for example be the same as the input to the function, resulting in a simple inplace update of the input.
In the case of :class:`ivy.Array` return types, the :code:`out` argument is predominantly handled in `handle_out_argument`_.
-As explained in the :ref:`Function Wrapping` section, this wrapping is applied to every function with the :code:`@handle_out_argument` decorator dynamically during `backend setting`_.
+As explained in the `Function Wrapping `_ section, this wrapping is applied to every function with the :code:`@handle_out_argument` decorator dynamically during `backend setting`_.
**Primary Functions**
@@ -306,14 +303,14 @@ The implementations of :func:`ivy.tan` for each backend are as follows.
**PyTorch** (includes :code:`support_native_out` attribute):
.. code-block:: python
-
+
def tan(x: torch.Tensor, /, *, out: Optional[torch.Tensor] = None) -> torch.Tensor:
x = _cast_for_unary_op(x)
return torch.tan(x, out=out)
tan.support_native_out = True
-It's very important to ensure the :code:`support_native_out` attribute is not added to backend implementations that do not handle the :code:`out` argument, as the `presence of this attribute`_ dictates whether the argument should be handled `by the backend function`_ or `by the wrapper`_.
+It's very important to ensure the :code:`support_native_out` attribute is not added to backend implementations that do not handle the :code:`out` argument, as the `presence of this attribute`_ dictates whether the argument should be handled `by the backend function`_ or `by the wrapper `_.
This distinction only concerns how the inplace update is applied to the native array, which is operated upon directly by the backend.
If :code:`out` is specified in an Ivy function, then an inplace update is always **also** performed on the :class:`ivy.Array` instance itself, which is how :code:`out` is provided to the function originally.
@@ -351,10 +348,10 @@ Here we still have the :attr:`support_native_out` attribute since we want to tak
However, in the :code:`else` statement, the last operation is :func:`torch.transpose` which does not support the :code:`out` argument, and so the native inplace update can't be performed by torch here.
This is why we need to call :func:`ivy.inplace_update` explicitly here, to ensure the native inplace update is performed, as well as the :class:`ivy.Array` inplace update.
-Another case where we need to use :func:`ivy.inplace_update`_ with a function that has :attr:`support_native_out` is for the example of the :code:`torch` backend implementation of the :func:`ivy.remainder` function
+Another case where we need to use :func:`ivy.inplace_update` with a function that has :attr:`support_native_out` is for the example of the :code:`torch` backend implementation of the :func:`ivy.remainder` function
.. code-block:: python
-
+
def remainder(
x1: Union[float, torch.Tensor],
x2: Union[float, torch.Tensor],
@@ -435,7 +432,7 @@ Technically, this could be handled using the `handle_out_argument`_ wrapping, bu
**Mixed Functions**
-As explained in the :ref:`Function Types` section, *mixed* functions can effectively behave as either compositional or primary functions, depending on the backend that is selected. We must add the :code:`handle_out_argument` to the :code:`add_wrappers`key of
+As explained in the `Function Types `_ section, *mixed* functions can effectively behave as either compositional or primary functions, depending on the backend that is selected. We must add the :code:`handle_out_argument` to the :code:`add_wrappers`key of
the :code:`mixed_backend_wrappers` attribute so that the decorator gets added to the primary implementation when the backend is set. Here's an `example`_ from the linear function.
@@ -451,7 +448,7 @@ When :code:`copy` is not specified explicitly, then an inplace update is perform
Setting :code:`copy=False` is equivalent to passing :code:`out=input_array`.
If only one of :code:`copy` or :code:`out` is specified, then this specified argument is given priority.
If both are specified, then priority is given to the more general :code:`out` argument.
-As with the :code:`out` argument, the :code:`copy` argument is also handled `by the wrapper `_.
+As with the :code:`out` argument, the :code:`copy` argument is also handled `by the wrapper `_.
Views
@@ -484,7 +481,7 @@ Here's a brief description of the additional attributes added to :class:`ivy.Arr
#. PyTorch reference stack (:code:`._torch_view_refs`): Functional views referencing this array in its PyTorch base, only populated for original arrays or functional views.
#. PyTorch manipulation cache (:code:`._torch_manipulation`): Tuple storing array or view and function which made the functional view, only populated for functional views
-.. note::
+.. note::
Parts of an arrays metadata like :code:`stride` are attributed to the low-level memory layout of arrays while views in :code:`ivy` operate at a higher level of abstraction.
As a result, :func:`ivy.strides` isn't guaranteed to produce an output reflective of the underlying memory layout if the :class:`ivy.Array` passed in is a view (or in other words has a :code:`_base`).
diff --git a/docs/overview/deep_dive/ivy_frontends.rst b/docs/overview/deep_dive/ivy_frontends.rst
index 4954ba12d1611..8214423af7e3b 100644
--- a/docs/overview/deep_dive/ivy_frontends.rst
+++ b/docs/overview/deep_dive/ivy_frontends.rst
@@ -17,7 +17,6 @@ Ivy Frontends
.. _`YouTube tutorial series`: https://www.youtube.com/watch?v=72kBVJTpzIw&list=PLwNuX3xB_tv-wTpVDMSJr7XW6IP_qZH0t
.. _`discord`: https://discord.gg/sXyFF8tDtm
.. _`ivy frontends channel`: https://discord.com/channels/799879767196958751/998782045494976522
-.. _`open task`: https://unify.ai/docs/ivy/overview/contributing/open_tasks.html#frontend-apis
.. _`Array manipulation routines`: https://numpy.org/doc/stable/reference/routines.array-manipulation.html#
.. _`Array creation routines`: https://numpy.org/doc/stable/reference/routines.array-creation.html
@@ -62,7 +61,7 @@ Therefore, in order to avoid this potential conflict:
* You should ensure that the tests are passing before merging any frontend PRs.
The only exception to this rule is if the test is failing due to a bug in the Ivy functional API, which does not need to be solved as part of the frontend task.
-There will be some implicit discussion of the locations of frontend functions in these examples, however an explicit explanation of how to place a frontend function can be found in a sub-section of the Frontend APIs `open task`_.
+There will be some implicit discussion of the locations of frontend functions in these examples, however an explicit explanation of how to place a frontend function can be found in a sub-section of the Frontend APIs :ref:`open task `.
**NOTE:** Type hints, docstrings, and examples are not required when working on frontend functions.
@@ -73,7 +72,7 @@ There will be some implicit discussion of the locations of frontend functions in
The native arrays of each framework have their own attributes and instance methods which differ from the attributes and instance methods of :class:`ivy.Array`.
As such we have implemented framework-specific array classes: :class:`tf_frontend.Tensor`, :class:`torch_frontend.Tensor`, :class:`numpy_frontend.ndarray`, and :class:`jax_frontend.DeviceArray`.
These classes simply wrap an :class:`ivy.Array`, which is stored in the :code:`ivy_array` attribute, and behave as closely as possible to the native framework array classes.
-This is explained further in the `Classes and Instance Methods `_ section.
+This is explained further in the :ref:`overview/deep_dive/ivy_frontends:Classes and Instance Methods` section.
As we aim to replicate the frontend frameworks as closely as possible, all functions accept their frontend array class (as well as :class:`ivy.Array` and :class:`ivy.NativeArray`) and return a frontend array.
However, since most logic in each function is handled by Ivy, the :class:`ivy.Array` must be extracted from any frontend array inputs.
@@ -262,7 +261,7 @@ However, these functions are specified to have key-word only arguments and in so
In order to tackle these variations in behaviour, the :code:`map_raw_ops_alias` decorator was designed to wrap the functions that exist in the TensorFlow namespace, thus reducing unnecessary re-implementations.
.. code-block:: python
-
+
# in ivy/functional/frontends/tensorflow/math.py
@to_ivy_arrays_and_back
def argmax(input, axis, output_type=None, name=None):
@@ -318,7 +317,7 @@ Short Frontend Implementations
Ideally, all frontend functions should call the equivalent Ivy function and only be one line long. This is mainly because compositional implementations are bound to be slower than direct backend implementation calls.
-In case a frontend function is complex and there is no equivalent Ivy function to use, it is strongly advised to add that function to our Experimental API. To do so, you are invited to open a *Missing Function Suggestion* issue as described in the `Open Tasks `_ section. A member of our team will then review your issue, and if the proposed addition is deemed to be timely and sensible, we will add the function to the "Extend Ivy Functional API" `ToDo list issue `_.
+In case a frontend function is complex and there is no equivalent Ivy function to use, it is strongly advised to add that function to our Experimental API. To do so, you are invited to open a *Missing Function Suggestion* issue as described in the `Open Tasks <../contributing/open_tasks.rst>`_ section. A member of our team will then review your issue, and if the proposed addition is deemed to be timely and sensible, we will add the function to the "Extend Ivy Functional API" `ToDo list issue `_.
If you would rather not wait around for a member of our team to review your suggestion, you can instead go straight ahead and add the frontend function as a heavy composition of the existing Ivy functions, with a :code:`#ToDo` comment included, explaining that this frontend implementation will be simplified when :func:`ivy.func_name` is added.
@@ -348,7 +347,7 @@ The native TensorFlow function :func:`tf.reduce_logsumexp` does not have an equi
Through compositions, we can easily meet the required input-output behaviour for the TensorFlow frontend function.
-The entire workflow for extending the Ivy Frontends as an external contributor is explained in more detail in the `Open Tasks `_ section.
+The entire workflow for extending the Ivy Frontends as an external contributor is explained in more detail in the :ref:`Open Tasks ` section.
Unused Arguments
----------------
@@ -409,7 +408,7 @@ Classes and Instance Methods
----------------------------
Most frameworks include instance methods and special methods on their array class for common array processing functions, such as :func:`reshape`, :func:`expand_dims` and :func:`add`.
-This simple design choice comes with many advantages, some of which are explained in our :ref:`Ivy Array` section.
+This simple design choice comes with many advantages, some of which are explained in our `Ivy Array <../design/ivy_as_a_framework/ivy_array.rst>`_ section.
**Important Note**
Before implementing the instance method or special method, make sure that the regular function in the specific frontend is already implemented.
@@ -516,7 +515,7 @@ For example, :class:`numpy.matrix` has an instance method of :meth:`any`:
return any(self.A, axis=axis, out=out)
We need to create these frontend array classes and all of their instance methods and also their special methods such that we are able to transpile code which makes use of these methods.
-As explained in :ref:`Ivy as a Transpiler`, when transpiling code we first extract the computation graph in the source framework.
+As explained in `Ivy as a Transpiler <../design/ivy_as_a_transpiler.rst>`_, when transpiling code we first extract the computation graph in the source framework.
In the case of instance methods, we then replace each of the original instance methods in the extracted computation graph with these new instance methods defined in the Ivy frontend class.
Frontend Data Type Promotion Rules
diff --git a/docs/overview/deep_dive/ivy_frontends_tests.rst b/docs/overview/deep_dive/ivy_frontends_tests.rst
index 5b27829d9e5ff..97a6f7a6ab2c2 100644
--- a/docs/overview/deep_dive/ivy_frontends_tests.rst
+++ b/docs/overview/deep_dive/ivy_frontends_tests.rst
@@ -1,17 +1,16 @@
Ivy Frontend Tests
==================
-.. _`here`: https://unify.ai/docs/ivy/design/ivy_as_a_transpiler.html
+.. _`here`: ../design/ivy_as_a_transpiler.rst
.. _`ivy frontends tests channel`: https://discord.com/channels/799879767196958751/1028267758028337193
.. _`test ivy`: https://github.com/unifyai/ivy/tree/db9a22d96efd3820fb289e9997eb41dda6570868/ivy_tests/test_ivy
.. _`test_frontend_function`: https://github.com/unifyai/ivy/blob/591ac37a664ebdf2ca50a5b0751a3a54ee9d5934/ivy_tests/test_ivy/helpers.py#L1047
.. _`discord`: https://discord.gg/sXyFF8tDtm
-.. _`Function Wrapping`: https://unify.ai/docs/ivy/overview/deep_dive/function_wrapping.html
-.. _`open task`: https://unify.ai/docs/ivy/overview/contributing/open_tasks.html
-.. _`Ivy Tests`: https://unify.ai/docs/ivy/overview/deep_dive/ivy_tests.html
+.. _`Function Wrapping`: function_wrapping.rst
+.. _`open task`: ../contributing/open_tasks.rst
+.. _`Ivy Tests`: ivy_tests.rst
.. _`Function Testing Helpers`: https://github.com/unifyai/ivy/blob/bf0becd459004ae6cffeb3c38c02c94eab5b7721/ivy_tests/test_ivy/helpers/function_testing.py
-.. _`CI Pipeline`: https://unify.ai/docs/ivy/overview/deep_dive/continuous_integration.html
-.. _`setting up`: https://unify.ai/docs/ivy/compiler/setting_up.html#setting-up-testing
+.. _`CI Pipeline`: continuous_integration.rst
Introduction
@@ -168,7 +167,7 @@ ivy.tan()
**TensorFlow**
.. code-block:: python
-
+
# ivy_tests/test_ivy/test_frontends/test_tensorflow/test_math.py
@handle_frontend_test(
fn_tree="tensorflow.math.tan",
@@ -625,9 +624,9 @@ for example, :code:`ndarray.__add__` would expect an array as input, despite the
**Important Helper Functions**
:func:`@handle_frontend_method` requires 3 keyword only parameters:
- - :code:`class_tree` A full path to the array class in **Ivy** namespace.
+ - :code:`class_tree` A full path to the array class in **Ivy** namespace.
- :code:`init_tree` A full path to initialization function.
- - :code:`method_name` The name of the method to test.
+ - :code:`method_name` The name of the method to test.
:func:`helpers.test_frontend_method` is used to test frontend instance methods. It is used in the same way as :func:`helpers.test_frontend_function`. A few important arguments for this function are following:
- :code:`init_input_dtypes` Input dtypes of the arguments on which we are initializing the array on.
@@ -802,7 +801,7 @@ The CI Pipeline runs the entire collection of Frontend Tests for the frontend th
You will need to make sure the Frontend Test is passing for each Ivy Frontend function you introduce/modify.
If a test fails on the CI, you can see details about the failure under `Details -> Run Frontend Tests` as shown in `CI Pipeline`_.
-You can also run the tests locally before making a PR. See the relevant `setting up`_ section for instructions on how to do so.
+You can also run the tests locally before making a PR. See the relevant :ref:`overview/contributing/setting_up:Setting Up Testing in PyCharm` section for instructions on how to do so.
Frontend Framework Testing Configuration
----------------------------------------
diff --git a/docs/overview/deep_dive/ivy_lint.rst b/docs/overview/deep_dive/ivy_lint.rst
new file mode 100644
index 0000000000000..388e67bfd58b2
--- /dev/null
+++ b/docs/overview/deep_dive/ivy_lint.rst
@@ -0,0 +1,58 @@
+Ivy-Lint: Ivy's Custom Code Formatters
+======================================
+
+Overview
+--------
+
+``ivy-lint`` is a specialized suite of formatters crafted for the Ivy codebase. It addresses unique formatting requirements not catered to by standard Python formatters. While the suite currently highlights the ``FunctionOrderingFormatter``, we're continually expanding to include more formatters tailored to Ivy's needs.
+
+Existing Formatters
+-------------------
+
+FunctionOrderingFormatter
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This formatter ensures a standardized order of declarations within Python files, organizing functions, classes, and assignments based on a hierarchy designed for the Ivy codebase.
+
+**Purpose**: To bring a sense of uniformity and structure to the code files by sorting various Python declarations.
+
+**Target Files**: Specifically designed for frontends and tests.
+
+How the Formatter Works:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Header Management**:
+ - Removes pre-existing headers in the source code based on specific patterns.
+
+2. **Comments Handling**:
+ - Extracts code components along with their leading comments, ensuring that relevant comments are retained during the reordering process.
+
+3. **Dependency Handling**:
+ - Constructs dependency graphs to understand and maintain the relationships between classes and assignments.
+
+4. **Sorting Logic**:
+ - Prioritizes imports, followed by assignments based on certain dependencies, then classes, and finally functions.
+ - Preserves module-level docstrings at the top of the file.
+ - Organizes helper functions and primary functions into separate sections for clarity.
+
+5. **File Processing**:
+ - Processes files that align with certain patterns, rearranging their content as needed.
+
+Integration and Usage
+---------------------
+
+To get the best out of ``ivy-lint``, integrate it within a pre-commit hook. This ensures that whenever code changes are about to be committed, the suite checks and, if needed, formats the files to align with Ivy's standards.
+
+For comprehensive details on weaving ``ivy-lint`` into your development practices, kindly refer to our `formatting guide `_.
+
+Contribution
+------------
+
+We’re always thrilled to welcome contributions to ``ivy-lint``. If you're brimming with ideas for a new formatter or can enhance our existing ones, please connect with us either on our GitHub repository or our `discord `_ channel.
+
+Round Up
+--------
+
+``ivy-lint`` stands as a testament to Ivy's commitment to code clarity and uniformity. As the landscape of our needs shifts, we foresee further refining and expanding our suite of formatters.
+
+For all discussions or inquiries, you're always welcome on `discord `_ in the `formatting channel `_.
diff --git a/docs/overview/deep_dive/ivy_tests.rst b/docs/overview/deep_dive/ivy_tests.rst
index c151c7a7e8fb7..be78008687a57 100644
--- a/docs/overview/deep_dive/ivy_tests.rst
+++ b/docs/overview/deep_dive/ivy_tests.rst
@@ -13,7 +13,7 @@ Ivy Tests
.. _`methods`: https://hypothesis.readthedocs.io/en/latest/data.html
.. _`finfo`: https://github.com/unifyai/ivy/blob/d8f1ffe8ebf38fa75161c1a9459170e95f3c82b6/ivy/functional/ivy/data_type.py#L276
.. _`data generation`: https://github.com/unifyai/ivy/blob/7063bf4475b93f87a4a96ef26c56c2bd309a2338/ivy_tests/test_ivy/test_functional/test_core/test_dtype.py#L337
-.. _`Function Types`: https://unify.ai/docs/ivy/overview/deep_dive/function_types.html
+.. _`Function Types`: function_types.rst
.. _`test_default_int_dtype`: https://github.com/unifyai/ivy/blob/7063bf4475b93f87a4a96ef26c56c2bd309a2338/ivy_tests/test_ivy/test_functional/test_core/test_dtype.py#L835
.. _`sampled_from`: https://hypothesis.readthedocs.io/en/latest/data.html#hypothesis.strategies.sampled_from
.. _`lists`: https://hypothesis.readthedocs.io/en/latest/data.html#hypothesis.strategies.lists
@@ -53,9 +53,15 @@ Ivy Tests
.. _`dtype_and_values`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/array_helpers.py#L83
.. _`dtype_values_axis`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/array_helpers.py#L235
.. _`array_values`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/array_helpers.py#L543
-.. _`CI Pipeline`: https://unify.ai/docs/ivy/overview/deep_dive/continuous_integration.html
-.. _`Setting Up Testing in PyCharm`: https://unify.ai/docs/ivy/overview/contributing/setting_up.html#setting-up-testing-in-pycharm
-.. _`Setting up for Free`: https://unify.ai/docs/ivy/overview/contributing/setting_up.html#setting-up-for-free
+.. _`array_dtypes`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/dtype_helpers.py#L15
+.. _`array_bools`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/array_helpers.py#L17
+.. _`reshape_shapes`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/general_helpers.py#L16
+.. _`get_axis`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/general_helpers.py#L178
+.. _`get_shape`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/general_helpers.py#L67
+.. _`get_bounds`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/general_helpers.py#L145
+.. _`subsets`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/hypothesis_helpers/general_helpers.py#L48
+.. _`num_positional_args`: https://github.com/unifyai/ivy/blob/e50f71e283313caa9737f3c284496022ac67b58b/ivy_tests/test_ivy/helpers/testing_helpers.py#L78
+.. _`CI Pipeline`: continuous_integration.rst
.. _`Hypothesis docs`: https://hypothesis.readthedocs.io/en/latest/data.html#core-strategies
On top of the Array API `test suite`_, which is included as a submodule mapped to the folder :code:`test_array_api`, there is also a collection of Ivy tests, located in subfolder `test_ivy`_.
@@ -252,7 +258,7 @@ Writing Ivy Tests
^^^^^^^^^^^^^^^^^
As mentioned previously, testing Ivy functions needs a lot of pre-processing and past-processing, using only :code:`given` decorator would not be sufficient
-to write an effective test, the following example describes how to implement a test for the function :code:`ivy.abs, using our test decorators and test helpers.
+to write an effective test, the following example describes how to implement a test for the function :code:`ivy.abs`, using our test decorators and test helpers.
.. code-block:: python
@handle_test(
@@ -306,7 +312,7 @@ One thing to note here is the :code:`test_flags` variable in the test function.
The test flags can also be generated explicitly like this -:
.. code-block:: python
-
+
@handle_test(
as_variable_flags = st.lists(st.booleans(), min_size = , max_size = ),
native_array_flags = st.lists(st.booleans(), min_size = , max_size = ),
@@ -485,7 +491,7 @@ Meaning if the input is to be treated as a container, at the same time, is it a
The generated values are then passed to the array creation functions inside the test function as tuples.
-9. `valid_axes`_ - This function generates valid axes for a given array dimension.
+9. valid_axes - This function generates valid axes for a given array dimension.
For example -:
.. code-block:: python
@@ -561,7 +567,7 @@ This function should be used in places where the result doesn’t depend on the
**Note** - Under the hood, **array_values** strategy is called if the data type is *integer*, and **none_or_list_of_floats** is called when the data type is *float*.
-15. `get_probs`_ - This is used to generate a tuple containing two values.
+15. get_probs - This is used to generate a tuple containing two values.
The first one being the *unnormalized probabilities* for all elements in a population, the second one being the *population size*.
For example-:
@@ -616,7 +622,7 @@ It would be helpful to keep in mind the following points while writing test -:
Testing Partial Mixed Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-As explained in the :ref:`Function Types` section, partial mixed functions are a special type of mixed functions that either utilize the compositional implementation
+As explained in the `Function Types `_ section, partial mixed functions are a special type of mixed functions that either utilize the compositional implementation
or the primary implementation depending on some conditions on the input. Therefore, the data-types supported by partial mixed functions depend on which implementation will
be used for the given input. For example, when :code:`function_supported_dtypes` is called with respect to `ivy.linear` with torch backend, the following output is returned:
@@ -625,7 +631,7 @@ be used for the given input. For example, when :code:`function_supported_dtypes`
{'compositional': ('float32', 'int8', 'uint8', 'float64', 'int16', 'int32', 'int64'), 'primary': ('bool', 'float32', 'int8', 'uint8', 'float64', 'int64', 'int16', 'int32')}
As can be seen from the above output that the data-types supported will depend on the implementation used for the given input. It's because of this reason that we need a slightly
-different pipeline for testing partial mixed functions. Basically, while writing the strategies for the tests of these functions, we need to first determine which implementation
+different pipeline for testing partial mixed functions. Basically, while writing the strategies for the tests of these functions, we need to first determine which implementation
will be used and then based on that generate the data to test the function. Here's an example from the test of :code:`ivy.linear` function:
@@ -678,8 +684,8 @@ will be used and then based on that generate the data to test the function. Here
As can be seen from the above code, a boolean parameter :code:`mixed_fn_compos` is generated first to determine whether to generate test data for
the compositional implementation or the primary one. When it is equal to :code:`True`, the relevant data for the compositional implementation should
-be generated and when :code:`False`, data corresponding to the primary implementation should be generated. Another boolean, :code:`is_torch_backend`
-is to be used to determine if the current backend is :code:`torch`. Then these booleans are used together in this :code:`if` condition:
+be generated and when :code:`False`, data corresponding to the primary implementation should be generated. Another boolean, :code:`is_torch_backend`
+is to be used to determine if the current backend is :code:`torch`. Then these booleans are used together in this :code:`if` condition:
:code:`if is_torch_backend and not mixed_fn_compos` and :code:`weight_shape` is updated to be 2 dimensional because the torch backend implementation
only supports 2 dimensional weights. Notice that the parameter :code:`mixed_fn_compos` is also be passed to :code:`helpers.get_dtypes` and
:code:`helpers.ints` functions so that the dtypes corresponding to the implementation to be tested are returned. In general, :code:`helpers.get_dtypes`,
@@ -843,7 +849,7 @@ You will need to make sure the Ivy Test is passing for each Ivy function you int
If a test fails on the CI, you can see details about the failure under `Details -> Run Ivy Tests` as shown in `CI Pipeline`_.
You can also run the tests locally before making a PR. The instructions differ according to the IDE you are using. For
-PyCharm and Visual Studio Code you can refer to the `Setting Up Testing in PyCharm`_ section and `Setting up for Free`_
+PyCharm and Visual Studio Code you can refer to the :ref:`overview/contributing/setting_up:Setting Up Testing in PyCharm` section and :ref:`overview/contributing/setting_up:Setting up for Free`
section respectively.
Re-Running Failed Ivy Tests
diff --git a/docs/overview/deep_dive/navigating_the_code.rst b/docs/overview/deep_dive/navigating_the_code.rst
index 29049c1bd6748..1bd9b0ae9dd7d 100644
--- a/docs/overview/deep_dive/navigating_the_code.rst
+++ b/docs/overview/deep_dive/navigating_the_code.rst
@@ -7,7 +7,6 @@ Navigating the Code
.. _`navigating the code channel`: https://discord.com/channels/799879767196958751/982737793476345888
.. _`Array API Standard convention`: https://data-apis.org/array-api/2021.12/API_specification/array_object.html#api-specification-array-object--page-root
.. _`flake8`: https://flake8.pycqa.org/en/latest/index.html
-.. _`pre-commit guide`: https://unify.ai/docs/ivy/overview/contributing/setting_up.html#pre-commit
Categorization
--------------
diff --git a/docs/overview/deep_dive/superset_behaviour.rst b/docs/overview/deep_dive/superset_behaviour.rst
index 446544c9fb936..5e232c7ceabd3 100644
--- a/docs/overview/deep_dive/superset_behaviour.rst
+++ b/docs/overview/deep_dive/superset_behaviour.rst
@@ -73,7 +73,7 @@ We explore this through the examples of :func:`softplus`.
**ivy.softplus**
-When looking at the :func:`softplus` (or closest equivalent) implementations for `Ivy `_, `JAX `_, `TensorFlow `_, and `PyTorch `_, we can see that torch is the only framework which supports the inclusion of the :code:`beta` and :code:`threshold` arguments, which are added for improved numerical stability.
+When looking at the :func:`softplus` (or closest equivalent) implementations for `Ivy <../../docs/functional/ivy/activations/ivy.functional.ivy.activations.softplus.rst>`_, `JAX `_, `TensorFlow `_, and `PyTorch `_, we can see that torch is the only framework which supports the inclusion of the :code:`beta` and :code:`threshold` arguments, which are added for improved numerical stability.
We can also see that numpy does not support a :func:`softplus` function at all.
Ivy should also support the :code:`beta` and :code:`threshold` arguments, in order to provide the generalized superset implementation among the backend frameworks.
@@ -143,25 +143,25 @@ The first three examples are more-or-less superset examples, while the last exam
**ivy.linspace**
-When looking at the :func:`linspace` (or closest equivalent) implementations for `Ivy `_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that torch does not support arrays for the :code:`start` and :code:`end` arguments, while JAX, numpy, and tensorflow all do.
+When looking at the :func:`linspace` (or closest equivalent) implementations for `Ivy <../../docs/functional/ivy/creation/ivy.functional.ivy.creation.linspace.rst>`_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that torch does not support arrays for the :code:`start` and :code:`end` arguments, while JAX, numpy, and tensorflow all do.
Likewise, Ivy also supports arrays for the :code:`start` and :code:`stop` arguments, and in doing so provides the generalized superset implementation among the backend frameworks.
**ivy.eye**
-When looking at the :func:`eye` (or closest equivalent) implementations for `Ivy `_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that tensorflow is the only framework which supports a :code:`batch_shape` argument.
+When looking at the :func:`eye` (or closest equivalent) implementations for `Ivy <../../docs/functional/ivy/creation/ivy.functional.ivy.creation.eye.rst>`_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that tensorflow is the only framework which supports a :code:`batch_shape` argument.
Likewise, Ivy also supports a :code:`batch_shape` argument, and in doing so provides the generalized superset implementation among the backend frameworks.
**ivy.scatter_nd**
-When looking at the :func:`scatter_nd` (or closest equivalent) implementations for `Ivy `_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that torch only supports scattering along a single dimension, while all other frameworks support scattering across multiple dimensions at once.
+When looking at the :func:`scatter_nd` (or closest equivalent) implementations for `Ivy <../../docs/functional/ivy/general/ivy.functional.ivy.general.scatter_nd.rst>`_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that torch only supports scattering along a single dimension, while all other frameworks support scattering across multiple dimensions at once.
Likewise, Ivy also supports scattering across multiple dimensions at once, and in doing so provides the generalized superset implementation among the backend frameworks.
**ivy.logical_and**
-When looking at the :func:`logical_and` (or closest equivalent) implementations for `Ivy `_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that numpy and torch support the :code:`out` argument for performing inplace updates, while JAX and tensorflow do not.
+When looking at the :func:`logical_and` (or closest equivalent) implementations for `Ivy <../../docs/functional/ivy/elementwise/ivy.functional.ivy.elementwise.logical_and.rst>`_, `JAX `_, `NumPy `_, `TensorFlow `_, and `PyTorch `_, we can see that numpy and torch support the :code:`out` argument for performing inplace updates, while JAX and tensorflow do not.
With regards to the supported data types, JAX, numpy, and torch support numeric arrays, while tensorflow supports only boolean arrays.
With regards to both of these points, Ivy provides the generalized superset implementation among the backend frameworks, with support for the :code:`out` argument and also support for both numeric and boolean arrays in the input.
@@ -174,8 +174,8 @@ Maximizing Usage of Native Functionality
While achieving the objective of having superset behaviour across the backends, the native functionality of frameworks should be made use of as much as possible.
Even if a framework-specific function doesn't provide complete superset behaviour, we should still make use of the partial behaviour that it provides and then add more logic for the remaining part.
-This is for efficiency reasons and is more explained under the `Mixed Function `_ section.
-In cases when a framework-specific function exists for one or two backends but not the others, we implement a `Mixed Function `_.
+This is for efficiency reasons and is more explained under the :ref:`Mixed Function ` section.
+In cases when a framework-specific function exists for one or two backends but not the others, we implement a :ref:`Mixed Function `.
But when the framework-specific functions do not cover all superset functionality, Ivy also allows for a mixed-compositional hybrid approach.
Consider the example of :func:`interpolate`.
diff --git a/docs/overview/design.rst b/docs/overview/design.rst
index d487262d5f4d2..ea32c66512596 100644
--- a/docs/overview/design.rst
+++ b/docs/overview/design.rst
@@ -1,11 +1,13 @@
Design
======
+.. _`Deep Dive`: deep_dive.rst
+
This section is aimed at general users, who would like to learn how to use Ivy, and are less concerned about how it all works under the hood 🔧
-The :ref:`Deep Dive` section is more targeted at potential contributors, and at users who would like to dive deeper into the weeds of the framework🌱, and gain a better understanding of what is actually going on behind the scenes 🎬
+The `Deep Dive`_ section is more targeted at potential contributors, and at users who would like to dive deeper into the weeds of the framework🌱, and gain a better understanding of what is actually going on behind the scenes 🎬
-If that sounds like you, feel free to check out the :ref:`Deep Dive` section after you've gone through the higher level overview which is covered in this *design* section!
+If that sounds like you, feel free to check out the `Deep Dive`_ section after you've gone through the higher level overview which is covered in this *design* section!
| So, starting off with our higher level *design* section, Ivy can fulfill two distinct purposes:
|
@@ -23,16 +25,16 @@ If that sounds like you, feel free to check out the :ref:`Deep Dive` section aft
:align: center
:width: 100%
-| (a) :ref:`Building Blocks`
+| (a) `Building Blocks `_
| back-end functional APIs ✅
| Ivy functional API ✅
| Framework Handler ✅
| Ivy Compiler 🚧
|
-| (b) :ref:`Ivy as a Transpiler`
+| (b) `Ivy as a Transpiler `_
| front-end functional APIs 🚧
|
-| (c) :ref:`Ivy as a Framework`
+| (c) `Ivy as a Framework `_
| Ivy stateful API ✅
| Ivy Container ✅
| Ivy Array ✅
diff --git a/docs/overview/design/building_blocks.rst b/docs/overview/design/building_blocks.rst
index 3b77f3b1d26aa..0d1e2b22250d8 100644
--- a/docs/overview/design/building_blocks.rst
+++ b/docs/overview/design/building_blocks.rst
@@ -1,8 +1,6 @@
Building Blocks
===============
-.. _`out argument`: https://unify.ai/docs/ivy/overview/deep_dive/inplace_updates.html#out-argument
-
Here we explain the components of Ivy which are fundamental to its usage either as a code converter or as a fully-fledged framework-agnostic ML framework.
These are the 4 parts labelled as (a) in the image below:
@@ -73,7 +71,7 @@ There are separate backend modules for JAX, TensorFlow, PyTorch, and NumPy, and
stack.support_native_out = True
-There were no changes required for this function, however NumPy and PyTorch both had to be marked as supporting the `out argument`_ natively.
+There were no changes required for this function, however NumPy and PyTorch both had to be marked as supporting the :ref:`overview/deep_dive/inplace_updates:out argument` natively.
For more complicated functions, we need to do more than simply wrap and maybe change the name.
For functions with differing behavior then we must modify the function to fit the unified in-out behavior of Ivy’s API.
@@ -491,7 +489,7 @@ The example above further emphasizes that the graph compiler creates a computati
Specifically, the same Ivy code compiles to different graphs depending on the selected backend.
However, when compiling native framework code, we are only able to compile a graph for that same framework.
For example, we cannot take torch code and compile this into tensorflow code.
-However, we can transpile torch code into tensorflow code (see :ref:`Ivy as a Transpiler` for more details).
+However, we can transpile torch code into tensorflow code (see `Ivy as a Transpiler `_ for more details).
The graph compiler does not compile to C++, CUDA, or any other lower level language.
It simply traces the backend functional methods in the graph, stores this graph, and then efficiently traverses this graph at execution time, all in Python.
diff --git a/docs/overview/design/ivy_as_a_framework.rst b/docs/overview/design/ivy_as_a_framework.rst
index 5d5e5cb73b0ec..bf1201048a94b 100644
--- a/docs/overview/design/ivy_as_a_framework.rst
+++ b/docs/overview/design/ivy_as_a_framework.rst
@@ -1,10 +1,10 @@
Ivy as a Framework
==================
-On the :ref:`Building Blocks` page, we explored the role of the backend functional APIs, the Ivy functional API, the framework handler, and the graph compiler.
+On the `Building Blocks `_ page, we explored the role of the backend functional APIs, the Ivy functional API, the framework handler, and the graph compiler.
These are parts labeled as (a) in the image below.
-On the :ref:`Ivy as a Transpiler` page, we explained the role of the backend-specific frontends in Ivy, and how these enable automatic code conversions between different ML frameworks.
+On the `Ivy as a Transpiler `_ page, we explained the role of the backend-specific frontends in Ivy, and how these enable automatic code conversions between different ML frameworks.
This part is labeled as (b) in the image below.
So far, by considering parts (a) and (b), we have mainly treated Ivy as a fully functional framework with code conversion abilities.
@@ -19,13 +19,13 @@ These parts are labeled as (c) in the image below.
You may choose from the following upcoming discussions or click next.
-| (a) :ref:`Ivy Container`
+| (a) `Ivy Container `_
| Hierarchical container solving almost everything behind the scenes in Ivy
|
-| (b) :ref:`Ivy Stateful API`
+| (b) `Ivy Stateful API `_
| Trainable Layers, Modules, Optimizers, and more built on the functional API and the Ivy Container
|
-| (c) :ref:`Ivy Array`
+| (c) `Ivy Array `_
| Bringing methods as array attributes to Ivy, cleaning up and simplifying code
.. toctree::
diff --git a/docs/overview/design/ivy_as_a_framework/ivy_array.rst b/docs/overview/design/ivy_as_a_framework/ivy_array.rst
index cdce00d179a58..96d0ba2e6ef76 100644
--- a/docs/overview/design/ivy_as_a_framework/ivy_array.rst
+++ b/docs/overview/design/ivy_as_a_framework/ivy_array.rst
@@ -197,7 +197,7 @@ API Monkey Patching
All ivy functions with array inputs/outputs have been wrapped to return :class:`ivy.Array` instances while accepting both :class:`ivy.Array` and :class:`ivy.NativeArray` instances.
This allows for the control required to provide a unified array interface.
-For more details on wrapping, see the `Function Wrapping `_ page in deep dive.
+For more details on wrapping, see the `Function Wrapping <../../deep_dive/function_wrapping.rst>`_ page in deep dive.
Instance Methods
diff --git a/docs/overview/design/ivy_as_a_framework/ivy_container.rst b/docs/overview/design/ivy_as_a_framework/ivy_container.rst
index f566472a6147d..fad13c67f9f26 100644
--- a/docs/overview/design/ivy_as_a_framework/ivy_container.rst
+++ b/docs/overview/design/ivy_as_a_framework/ivy_container.rst
@@ -145,7 +145,7 @@ Or we can flip each sub-array:
}
}
-There are about 200 such functions for the :class:`ivy.Container` class in total, check out the `code `_ or `docs `_ to see what they are!
+There are about 200 such functions for the :class:`ivy.Container` class in total, check out the `code `_ or `docs <../../../docs/data_classes/data_classes/ivy.data_classes.container.rst>`_ to see what they are!
Built-ins
----------
@@ -458,7 +458,7 @@ All nested structures above this height are truncated into single keys with a
These are very useful methods when stepping through code and debugging complex nested structures such as the weights of a network.
There are also methods: :code:`cont_with_print_limit` for controlling the printable size of arrays before the shape is instead displayed, :code:`cont_with_key_length_limit` for setting the maximum key length before string clipping, :code:`cont_with_print_indent` for controlling the nested indent, and many more.
-Check out the `docs `_ for more details!
+Check out the `docs <../../../docs/data_classes/data_classes/ivy.data_classes.container.rst>`_ for more details!
Use Cases
---------
diff --git a/docs/overview/design/ivy_as_a_framework/ivy_stateful_api.rst b/docs/overview/design/ivy_as_a_framework/ivy_stateful_api.rst
index 2993a8f5279e2..3c6574b884d04 100644
--- a/docs/overview/design/ivy_as_a_framework/ivy_stateful_api.rst
+++ b/docs/overview/design/ivy_as_a_framework/ivy_stateful_api.rst
@@ -370,7 +370,7 @@ The actual implementation for the :class:`ivy.Linear` layer exposed in the Ivy s
self.v.b if self._with_bias else None)
The :class:`ivy.Initializer` class has a single abstract method, :code:`create_variables(var_shape, dev, fan_out=None, fan_in=None, *args, **kwargs)`.
-Check out the `code `_ or `docs `_ for more details.
+Check out the `code `_ or :ref:`docs ` for more details.
The default initializer for the weights is :class:`ivy.GlorotUniform` and for this bias is :class:`ivy.Zeros`.
Let’s take a quick look at what these look like.
:class:`ivy.GlorotUniform` derives from a more general :class:`ivy.Uniform` initializer class, and is then simply implemented as follows:
diff --git a/docs/overview/design/ivy_as_a_transpiler.rst b/docs/overview/design/ivy_as_a_transpiler.rst
index 56467a8d6e53b..50dd33d747ada 100644
--- a/docs/overview/design/ivy_as_a_transpiler.rst
+++ b/docs/overview/design/ivy_as_a_transpiler.rst
@@ -1,7 +1,7 @@
Ivy as a Transpiler
===================
-On the :ref:`Building Blocks` page, we explored the role of the backend functional APIs, the Ivy functional API, the backend handler, and the graph compiler.
+On the `Building Blocks `_ page, we explored the role of the backend functional APIs, the Ivy functional API, the backend handler, and the graph compiler.
These parts are labelled (a) in the image below.
Here, we explain the role of the backend-specific frontends in Ivy, and how these enable automatic code conversions between different ML frameworks.
diff --git a/docs/overview/extensions.rst b/docs/overview/extensions.rst
deleted file mode 100644
index dce2922e795d8..0000000000000
--- a/docs/overview/extensions.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-Extensions
-==========
-
-| (a) :ref:`Applied Libraries` ✅
-| Ivy libraries in mechanics, vision, robotics, memory and other areas
-|
-| (b) **Builder [page coming soon!]** ✅
-| :code:`ivy.Trainer`, :code:`ivy.Dataset`, :code:`ivy.Dataloader` and other helpful classes and functions for creating training workflows in only a few lines of code
-
-.. toctree::
- :hidden:
- :maxdepth: -1
- :caption: Extensions
-
- extensions/applied_libraries.rst
diff --git a/docs/overview/extensions/applied_libraries.rst b/docs/overview/extensions/applied_libraries.rst
deleted file mode 100644
index 3798463466737..0000000000000
--- a/docs/overview/extensions/applied_libraries.rst
+++ /dev/null
@@ -1,113 +0,0 @@
-Applied Libraries
-=================
-
-In other parts of the overview, we have focused on the the Ivy framework itself.
-Here, we explore how Ivy has been used to create a suite of libraries in various fields related to ML.
-Aside from being useful tools for ML developers in any framework, these libraries are a perfect showcase of what is possible using Ivy!
-
-Currently, there are Ivy libraries for: Mechanics, 3D Vision, Robotics, Gym Environments, and Differentiable Memory.
-We run through some demos from these libraries now, and encourage you to pip install the libraries and run the demos yourself if you like what you see!
-
-Ivy Mechanics
--------------
-
-`Ivy Mechanics `_ provides functions for conversions of orientation, pose, and positional representations, as well as transformations, and some other more applied functions.
-The orientation module is the largest, with conversions to and from all Euler conventions, quaternions, rotation matrices, rotation vectors, and axis-angle representations.
-
-For example, this demo shows the use of :code:`ivy_mech.target_facing_rotation_matrix`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_mech/demo_a.gif?raw=true
- :align: center
- :width: 100%
-
-This demo shows the use of :code:`ivy_mech.polar_to_cartesian_coords`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_mech/demo_b.gif?raw=true
- :align: center
- :width: 100%
-
-Ivy Vision
-----------
-
-`Ivy Vision `_ focuses predominantly on 3D vision, with functions for image projections, co-ordinate frame transformation, forward warping, inverse warping, optical flow, depth generation, voxel grids, point clouds, and others.
-
-For example, this demo shows the use of :code:`ivy_vision.coords_to_voxel_grid`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_vision/voxel_grid_demo.gif?raw=true
- :align: center
- :width: 100%
-
-This demo shows the use of :code:`ivy_vision.render_pixel_coords`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_vision/point_render_demo.gif?raw=true
- :align: center
- :width: 100%
-
-This demo shows Neural Radiance Fields (NeRF):
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_vision/nerf_demo.gif?raw=true
- :align: center
- :width: 100%
-
-
-Ivy Robot
----------
-
-`Ivy Robot `_ provides functions and classes for gradient-based trajectory optimization and motion planning.
-Classes are provided both for mobile robots and robot manipulators.
-
-For example, this demo shows the use of :code:`ivy_robot.sample_spline_path` and :code:`ivy_robot.RigidMobile.sample_body` for gradient-based motion planning of a drone.
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_robot/demo_a.gif?raw=true
- :align: center
- :width: 100%
-
-This demo shows the use of :code:`ivy_robot.sample_spline_path` and :code:`ivy_robot.Manipulator.sample_links` for gradient-based motion planning of a robot manipulator:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_robot/demo_b.gif?raw=true
- :align: center
- :width: 100%
-
-Ivy Gym
--------
-
-`Ivy Gym `_ provides differentiable implementations of the control environments provided by OpenAI Gym, as well as a new “Swimmer” task which illustrates the simplicity of creating new tasks.
-The differentiable nature of the environments means that the cumulative reward can be directly optimized in a supervised manner, without the need for reinforcement learning.
-Ivy Gym opens the door for intersectional research between supervised learning, trajectory optimization, and reinforcement learning.
-
-For example, we show demos of each of the environments :code:`cartpole`, :code:`mountain_car`, :code:`pendulum`, :code:`reacher`, and :code:`swimmer` solved using direct trajectory optimization below.
-We optimize for a specific starting state of the environment:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_gym/demo_a.gif?raw=true
- :align: center
- :width: 100%
-
-We show demos of each of the environments :code:`cartpole`, :code:`mountain_car`, :code:`pendulum`, :code:`reacher`, and :code:`swimmer` solved using supervised learning via a policy network.
-We train a policy which is conditioned on the environment state, and the starting state is then randomized between training steps:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_gym/demo_b.gif?raw=true
- :align: center
- :width: 100%
-
-Ivy Memory
-----------
-
-`Ivy Memory `_ provides differentiable memory modules, including learnt modules such as Neural Turing Machines (NTM), but also parameter-free modules such as End-to-End Egospheric Spatial Memory (ESM).
-
-For example, in this demo we learn to copy a sequence using :code:`ivy_memory.NTM`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_memory/demo_a.gif?raw=true
- :align: center
- :width: 100%
-
-In this demo we create an egocentric 3D map of a room using :code:`ivy_memory.ESM`:
-
-.. image:: https://github.com/unifyai/unifyai.github.io/blob/main/img/externally_linked/ivy_memory/demo_b.gif?raw=true
- :align: center
- :width: 100%
-
-**Round Up**
-
-Hopefully, this has given you an idea of what’s possible using Ivy’s collection of applied libraries, and more importantly, given you inspiration for what’s possible using Ivy 🙂
-
-Please reach out on `discord `_ if you have any questions!
diff --git a/docs/overview/faq.rst b/docs/overview/faq.rst
index 9c47fb1e15ba1..e74df1b21dff7 100644
--- a/docs/overview/faq.rst
+++ b/docs/overview/faq.rst
@@ -4,7 +4,6 @@ FAQ
.. _`dex`: https://github.com/dexidp/dex
.. _`API for distributed training`: https://github.com/unifyai/ivy/blob/a2f37b1bae232b7ba5257e59f8b46a0374cca9f1/ivy/functional/ivy/device.py#L660
.. _`fully support these`: https://pytorch.org/tutorials/prototype/vmap_recipe.html
-.. _`Ivy Builder`: https://github.com/unifyai/builder
.. _`README`: https://github.com/unifyai/ivy
These are some of the most common technical questions that continue to arise when we're discussing Ivy with developers in the community.
@@ -53,7 +52,7 @@ For some backends, shape-checking will be performed during the compilation phase
GPU handling
------------
-**Q:** How does Ivy handle GPU usage?
+**Q:** How does Ivy handle GPU usage?
**A:** Ivy handles GPU usage by simply wrapping the backend frameworks, so Ivy will use GPUs in the same manner as the backend framework does.
E.g. When using a torch backend, torch will be a dependency of Ivy, and its handling of GPU functionalities will be inherited and extended upon by Ivy.
@@ -156,7 +155,6 @@ The Pipeline
**A:** We are not advocating to replace all code with Ivy.
We would encourage users to continue using whatever data loaders they want to, and perhaps just use an Ivy model, or use Ivy to convert a model, or even just a single function from a library.
-If users want to use Ivy more deeply, then they can use `Ivy Builder`_, which includes framework-agnostic abstract data loaders, trainers, and other higher level classes for composing full training pipelines.
State
-----
diff --git a/docs/overview/get_started.rst b/docs/overview/get_started.rst
index 5e850df91bb20..9d891f143e5c6 100644
--- a/docs/overview/get_started.rst
+++ b/docs/overview/get_started.rst
@@ -3,8 +3,8 @@ Get Started
..
- If you want to use **Ivy's compiler and transpiler**, make sure to follow the
- `setting up instructions for the API key `_
+ If you want to use **Ivy's compiler and transpiler**, make sure to follow the
+ :ref:`setting up instructions for the API key `
after installing Ivy!
@@ -24,7 +24,7 @@ Keep in mind that this **won't** install any framework other than NumPy!
Docker
------
-If you prefer to use containers, we also have pre-built Docker images with all the
+If you prefer to use containers, we also have pre-built Docker images with all the
supported frameworks and some relevant packages already installed, which you can pull from:
.. code-block:: bash
@@ -40,17 +40,54 @@ If you are working on a GPU device, you can pull from:
Installing from source
----------------------
-You can also install Ivy from source if you want to take advantage of the latest
+You can also install Ivy from source if you want to take advantage of the latest
changes, but we can't ensure everything will work as expected!
.. code-block:: bash
git clone https://github.com/unifyai/ivy.git
- cd ivy
+ cd ivy
pip install --user -e .
-If you are planning to contribute, you want to run the tests, or you are looking
-for more in-depth instructions, it's probably best to check out
-the `Contributing - Setting Up `_ page,
+If you are planning to contribute, you want to run the tests, or you are looking
+for more in-depth instructions, it's probably best to check out
+the `Contributing - Setting Up `_ page,
where OS-specific and IDE-specific instructions and video tutorials to install Ivy are available!
+
+
+Ivy's compiler and transpiler
+-----------------------------
+
+To use Ivy's compiler and transpiler, you'll need an **API key**. We are starting to
+grant pilot access to certain users, so you can `join the waitlist `_
+if you want to get one!
+
+Ivy Folder
+~~~~~~~~~~
+
+When importing Ivy for the first time, a ``.ivy`` folder will be created in your
+working directory. If you want to keep this folder in a different location,
+you can set an ``IVY_ROOT`` environment variable with the path of your ``.ivy`` folder.
+
+Setting Up the API key
+~~~~~~~~~~~~~~~~~~~~~~
+
+Once the ``.ivy`` folder has been created (either manually or automatically by
+importing Ivy), you will have to paste your API key as the content of the ``key.pem`` file.
+For reference, this would be equivalent to:
+
+.. code-block:: bash
+
+ echo -n API_KEY > .ivy/key.pem
+
+Issues and Questions
+~~~~~~~~~~~~~~~~~~~~
+
+If you find any issue or bug while using the compiler and/or the transpiler, please
+raise an `issue in GitHub `_ and add the ``compiler``
+or the ``transpiler`` label accordingly. A member of the team will get back to you ASAP!
+
+Otherwise, if you haven't found a bug but want to ask a question, suggest something, or get help
+from the team directly, feel free to open a new post at the ``pilot-access`` forum in
+`Ivy's discord server! `_
diff --git a/docs/overview/glossary.rst b/docs/overview/glossary.rst
index 606dbf1c8a934..956654fd5758f 100644
--- a/docs/overview/glossary.rst
+++ b/docs/overview/glossary.rst
@@ -45,12 +45,6 @@ All of these new words can get confusing! We've created a glossary to help nail
Automatic Code Conversions
Allows code to be converted from one framework to another whilst retaining its functional assets.
- Applied Libraries
- Suite of various machine learning libraries that have been built using the Ivy framework.
-
- Ivy Builder
- Helpful classes and functions for creating training workflows.
-
Primary Functions
Primary functions are the lowest level building blocks in Ivy and are generally implemented as light wrapping around an existing function in the backend framework, which serves a near-identical purpose.
diff --git a/docs/overview/background.rst b/docs/overview/motivation.rst
similarity index 51%
rename from docs/overview/background.rst
rename to docs/overview/motivation.rst
index d203a51b18c52..a6f9278225af7 100644
--- a/docs/overview/background.rst
+++ b/docs/overview/motivation.rst
@@ -1,13 +1,13 @@
-Background
+Motivation
==========
-| (a) :ref:`ML Explosion`
+| (a) `ML Explosion `_
| A huge number of ML tools have exploded onto the scene!
|
-| (b) :ref:`Why Unify?`
+| (b) `Why Unify? `_
| Why should we try to unify them?
|
-| (c) :ref:`Standardization`
+| (c) `Standardization `_
| We’re collaborating with The `Consortium for Python Data API Standards `_
.. toctree::
@@ -15,6 +15,6 @@ Background
:maxdepth: -1
:caption: Background
- background/ml_explosion.rst
- background/why_unify.rst
- background/standardization.rst
+ motivation/ml_explosion.rst
+ motivation/why_unify.rst
+ motivation/standardization.rst
diff --git a/docs/overview/background/ml_explosion.rst b/docs/overview/motivation/ml_explosion.rst
similarity index 100%
rename from docs/overview/background/ml_explosion.rst
rename to docs/overview/motivation/ml_explosion.rst
diff --git a/docs/overview/background/standardization.rst b/docs/overview/motivation/standardization.rst
similarity index 100%
rename from docs/overview/background/standardization.rst
rename to docs/overview/motivation/standardization.rst
diff --git a/docs/overview/background/why_unify.rst b/docs/overview/motivation/why_unify.rst
similarity index 100%
rename from docs/overview/background/why_unify.rst
rename to docs/overview/motivation/why_unify.rst
diff --git a/docs/overview/one_liners.rst b/docs/overview/one_liners.rst
new file mode 100644
index 0000000000000..0b11527b0b132
--- /dev/null
+++ b/docs/overview/one_liners.rst
@@ -0,0 +1,30 @@
+One liners
+----------
+
+.. grid:: 1 1 3 3
+ :gutter: 4
+
+ .. grid-item-card:: ``ivy.compile()``
+ :link: one_liners/compile.rst
+
+ Compiles a ``Callable`` or set of them into an Ivy graph.
+
+ .. grid-item-card:: ``ivy.transpile()``
+ :link: one_liners/transpile.rst
+
+ Transpiles a ``Callable`` or set of them from a ``source`` framework to another
+ framework.
+
+ .. grid-item-card:: ``ivy.unify()``
+ :link: one_liners/unify.rst
+
+ Transpiles an object into Ivy code. It's an alias to
+ ``ivy.transpile(..., to="ivy", ...)``
+
+.. toctree::
+ :hidden:
+ :maxdepth: -1
+
+ one_liners/compile.rst
+ one_liners/transpile.rst
+ one_liners/unify.rst
diff --git a/docs/compiler/compiler.rst b/docs/overview/one_liners/compile.rst
similarity index 89%
rename from docs/compiler/compiler.rst
rename to docs/overview/one_liners/compile.rst
index f6f0b5ab2a9e4..98d3cfd826a3a 100644
--- a/docs/compiler/compiler.rst
+++ b/docs/overview/one_liners/compile.rst
@@ -1,34 +1,34 @@
-Graph Compiler
-==============
+``ivy.compile()``
+=================
..
⚠️ **Warning**: The compiler and the transpiler are not publicly available yet, so certain parts of this doc won't work as expected as of now!
-When we call an Ivy function, there is always a small performance hit due to added
-Python wrapping. This overhead becomes increasingly noticeable when we use large
-models with multiple function calls. The Graph Compiler improves the performance of
-Ivy by removing the extra wrapping around each function call.
+When we call an Ivy function, there is always a small performance hit due to added
+Python wrapping. This overhead becomes increasingly noticeable when we use large
+models with multiple function calls. The Graph Compiler improves the performance of
+Ivy by removing the extra wrapping around each function call.
-The Graph Compiler takes in any Ivy function, framework-specific (backend) function,
-or composition of both, and produces a simplified executable computation graph composed
+The Graph Compiler takes in any Ivy function, framework-specific (backend) function,
+or composition of both, and produces a simplified executable computation graph composed
of functions from the backend functional API only, which results in:
-- Simplified code: The Graph Compiler simplifies the code by removing all the wrapping
+- Simplified code: The Graph Compiler simplifies the code by removing all the wrapping
and functions that don't contribute to the output: print statements, loggers, etc.
-- Improved performance: The compiled graph has no performance overhead due to Ivy's
- function wrapping, likewise, redundant operations from the original function are also
+- Improved performance: The compiled graph has no performance overhead due to Ivy's
+ function wrapping, likewise, redundant operations from the original function are also
removed, increasing its overall performance.
Compiler API
------------
.. py:function:: ivy.compile(*objs, stateful = None, arg_stateful_idxs = None, kwarg_stateful_idxs = None, to = None, include_generators = True, array_caching = True, return_backend_compiled_fn = False, static_argnums = None, static_argnames = None, args = None, kwargs = None,)
-
- Compiles a ``Callable`` or set of them into an Ivy graph. If ``args`` or ``kwargs`` are specified,
+
+ Compiles a ``Callable`` or set of them into an Ivy graph. If ``args`` or ``kwargs`` are specified,
compilation is performed eagerly, otherwise, compilation will happen lazily.
-
+
:param objs: Callable(s) to compile and create a graph of.
:type objs: ``Callable``
:param stateful: List of instances to be considered stateful during the graph compilation.
@@ -91,12 +91,12 @@ In this case, the compiled graph would be:
From the graph, we can observe that:
1. As ``x`` and ``y`` are the only variables used when calculating the returned value ``z``,
- the non-contributing variable(s), ``k`` was not included in the graph. Function calls that
+ the non-contributing variable(s), ``k`` was not included in the graph. Function calls that
don't contribute to the output like the ``print`` function were also excluded.
-2. As we set the backend to ``torch`` during the compilation process, the compiled
+2. As we set the backend to ``torch`` during the compilation process, the compiled
functions are torch functions, and the input and output types are torch tensors.
-3. The tensor shape in the graph only indicates the shape of the inputs the graph was
- traced with. The compiler doesn't impose additional restrictions on the shape or
+3. The tensor shape in the graph only indicates the shape of the inputs the graph was
+ traced with. The compiler doesn't impose additional restrictions on the shape or
datatype of the input array(s).
.. code-block:: python
@@ -114,17 +114,17 @@ From the graph, we can observe that:
Eager vs lazy Compilation
~~~~~~~~~~~~~~~~~~~~~~~~~
-The graph compiler runs the original function under the hood and tracks its computation
-to create the compiled graph. The **eager compilation** method traces the graph in the
-corresponding function call with the specified inputs before we use the compiled
+The graph compiler runs the original function under the hood and tracks its computation
+to create the compiled graph. The **eager compilation** method traces the graph in the
+corresponding function call with the specified inputs before we use the compiled
function.
-Instead of compiling functions before using them, Ivy also allows you to compile the
-function dynamically. This can be done by passing only the function to the
-compile method and not including the function arguments. In this case, the output will be a
-``LazyGraph`` instead of a ``Graph`` instance. When this ``LazyGraph`` object is first invoked with
-function arguments, it compiles the function and returns the output of the compiled
-function. Once the graph has been initialized, calls to the ``LazyGraph`` object will
+Instead of compiling functions before using them, Ivy also allows you to compile the
+function dynamically. This can be done by passing only the function to the
+compile method and not including the function arguments. In this case, the output will be a
+``LazyGraph`` instead of a ``Graph`` instance. When this ``LazyGraph`` object is first invoked with
+function arguments, it compiles the function and returns the output of the compiled
+function. Once the graph has been initialized, calls to the ``LazyGraph`` object will
use the compiled function to compute the outputs directly.
.. code-block:: python
@@ -138,18 +138,18 @@ use the compiled function to compute the outputs directly.
# Compile and return the output
out = lazy_graph(x, y)
-To sum up, lazy compilation enables you to delay the compilation process until you have
-the necessary inputs during execution. This is particularly useful in cases like
-compiling libraries, where it’s not feasible to provide valid arguments for every
+To sum up, lazy compilation enables you to delay the compilation process until you have
+the necessary inputs during execution. This is particularly useful in cases like
+compiling libraries, where it’s not feasible to provide valid arguments for every
function call.
-Now let's look at additional functionalities that you can find in the
+Now let's look at additional functionalities that you can find in the
compiler.
Array caching
~~~~~~~~~~~~~
-The compiler is able to cache constant arrays and their operations through the
+The compiler is able to cache constant arrays and their operations through the
``array_caching`` flag, reducing computation time after compilation.
.. code-block:: python
@@ -166,15 +166,15 @@ The compiler is able to cache constant arrays and their operations through the
comp_func = ivy.compile(fn, args=(x,))
-When calling ``ivy.compile()``, the ``array_caching`` argument is set to ``True`` by
+When calling ``ivy.compile()``, the ``array_caching`` argument is set to ``True`` by
default, which returns the following graph.
.. image:: https://raw.githubusercontent.com/unifyai/unifyai.github.io/main/img/externally_linked/compiler/figure2.png
-This shows that by caching the constant operation in the graph, a simpler graph can be
-obtained. However, if desired, this argument can be set to ``False``, which results in the
-graph below. This ultimately results in a trade-off between time and memory, as
-cached results need to be stored in memory but if they are not cached these operations
+This shows that by caching the constant operation in the graph, a simpler graph can be
+obtained. However, if desired, this argument can be set to ``False``, which results in the
+graph below. This ultimately results in a trade-off between time and memory, as
+cached results need to be stored in memory but if they are not cached these operations
need to be performed.
.. image:: https://raw.githubusercontent.com/unifyai/unifyai.github.io/main/img/externally_linked/compiler/figure3.png
@@ -195,7 +195,7 @@ are included as nodes or "baked" into the graph.
a = torch.randint(0, 100, size=[1])
z = x ** a
return z + torch.rand([1])
-
+
comp_func = ivy.compile(fn, include_generators=True, args=(x,))
Returns:
@@ -224,7 +224,7 @@ Returns:
Stateful
~~~~~~~~
-Finally, you can also track ``__setattr__`` and ``__getattr__`` methods of
+Finally, you can also track ``__setattr__`` and ``__getattr__`` methods of
arbitrary classes using the ``stateful`` parameters.
.. code-block:: python
@@ -248,34 +248,34 @@ arbitrary classes using the ``stateful`` parameters.
Sharp bits
----------
-As some parts of the graph compiler are still under development, there are some sharp
-bits to take into account when using it. All of these points are WIP, so they'll be
+As some parts of the graph compiler are still under development, there are some sharp
+bits to take into account when using it. All of these points are WIP, so they'll be
removed soon!
-1. **Dynamic control flow**: The compiled graph is built using function tracing at the
- moment, so dynamic control flow such as conditional branches or conditional loops
- will not be registered correctly. As an example, if there is a while loop in your
- code that depends on a changing value, the number of iterations in the final graph
- will be the same as the number of iterations performed with the input passed to the
+1. **Dynamic control flow**: The compiled graph is built using function tracing at the
+ moment, so dynamic control flow such as conditional branches or conditional loops
+ will not be registered correctly. As an example, if there is a while loop in your
+ code that depends on a changing value, the number of iterations in the final graph
+ will be the same as the number of iterations performed with the input passed to the
compile function.
-2. **Non-framework-specific code**: As the compiler traces the function using the
- functional API of the underlying framework, any piece of code inside the model that
- is not from the said framework will not be correctly registered, this includes other
- frameworks code (such as NumPy statements inside a torch model) or python statements
+2. **Non-framework-specific code**: As the compiler traces the function using the
+ functional API of the underlying framework, any piece of code inside the model that
+ is not from the said framework will not be correctly registered, this includes other
+ frameworks code (such as NumPy statements inside a torch model) or python statements
such as len().
-3. **Incorrectly cached parts of the graph**: There are certain cases where compilation
+3. **Incorrectly cached parts of the graph**: There are certain cases where compilation
can succeed but hide some cached parts of the graph which shouldn't really be cached.
- To check this, it's recommended to compile with a noise array of the same shape and
+ To check this, it's recommended to compile with a noise array of the same shape and
then check if the output of the original function and the compiled graph with another
- input is the same. If you find out that the graph is not right, feel free to open an
- `issue `_ with a minimal example and we'll look
+ input is the same. If you find out that the graph is not right, feel free to open an
+ `issue `_ with a minimal example and we'll look
into it!
Examples
--------
-Below, we compile a ResNet50 model from
-`Hugging Face `_ and use it to classify the
+Below, we compile a ResNet50 model from
+`Hugging Face
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
-Last but not least, we are also working on specific extensions totally
-written in Ivy and therefore usable within any framework, covering
-topics like [Mechanics](https://github.com/unifyai/mech), [Computer
-Vision](https://github.com/unifyai/vision),
-[Robotics](https://github.com/unifyai/robot), a [Reinforcement Learning
-Gym](https://github.com/unifyai/gym),
-[Memory](https://github.com/unifyai/memory) and implementation of
-various [Models](https://github.com/unifyai/models) or [Builder
-tools](https://github.com/unifyai/builder) with trainers, data loaders
-and more!
-
-