Open Tasks

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

The tasks currently open are:

  1. Function Formatting

  2. Frontend APIs

  3. Ivy Experimental API

We try to explain these tasks as clearly as possible, but in cases where things are not clear, then please feel free to reach out on discord in the open tasks channel!

Please always use the latest commit on GitHub when working on any of these tasks, DO NOT develop your code using the latest PyPI release of ivy-core.

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 Deep Dive section. The updates should be applied for the:

  1. ivy API

  2. all backend APIs

  3. container static methods

  4. array instance methods

  5. container instance methods

  6. array operators

  7. array reverse operators

  8. container operators

  9. container reverse operators

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 Deep Dive in detail. Specifically, you do not need to address the following:

  1. Implement the hypothesis testing for the function

  2. Get the tests passing for your function, if they are failing before you start

However, everything else covered in the Deep Dive must be addressed. Some common important tasks are:

  1. Remove all lambda and direct bindings for the backend functions (in ivy.functional.backends), with each function instead defined using def.

  2. Implement the following if they don’t exist but should do: ivy.Array instance method, ivy.Container static method, ivy.Container instance method, ivy.Array special method, ivy.Array reverse special method, ivy.Container special method, ivy.Container reverse special method.

  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 for every function and its relevant methods, including those you did not implement yourself.

  5. Add the correct Docstrings to every function and its relevant methods, including those you did not implement yourself.

  6. Add thorough Docstring Examples 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:

  1. Add a comment with the following format: add_reformatting_checklist_<category_name> on your PR, where <category_name> is the name of the category that the function belongs to. An example of this is shown below.

https://github.com/unifyai/unifyai.github.io/blob/master/img/externally_linked/contributing/open_tasks/checklist_generator.png?raw=true

Using this formatting will then trigger our github automation bots to update your comment with the proper markdown text for the checklist. These updates might take a few moments to take effect, so please be patient 🙂.

  1. After adding the checklist to your PR, you should then modify this checklist with the status of each item according to the symbols(emojis) within the LEGEND section.

https://github.com/unifyai/unifyai.github.io/blob/master/img/externally_linked/contributing/open_tasks/checklist_legend.png?raw=true
  1. When all check items are marked as (✅, ⏩, or 🆗), you should request a review for your PR and we will start checking your implementation and marking the items as complete using the checkboxes next to them.

https://github.com/unifyai/unifyai.github.io/blob/master/img/externally_linked/contributing/open_tasks/checklist_checked.png?raw=true

4. In case you are stuck or need help with one of the checklist items, please add the 🆘 symbol next to the item on the checklist, and proceed to add a comment elaborating on your point of struggle with this item. The PR assignee will then see this comment and address your issues.

https://github.com/unifyai/unifyai.github.io/blob/master/img/externally_linked/contributing/open_tasks/checklist_SOS.png?raw=true

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. It does not automatically run any tests to update them!

  3. Do not edit the checklist text, only the emoji symbols. 😅

  4. Please refrain from using the checkboxes next to checklist items.

Frontend APIs

For this task, the goal will be to implement functions for each of the frontend functional APIs (see Ivy as a Transpiler), with frontend APIs implemented for: JAX, NumPy, TensorFlow and PyTorch.

Currently, we have many ToDo list issues open for this task.

The general workflow for this task is:

  1. Find the correct location for the function by following the Where to place a frontend function subsection below

  2. Implement the function by following the Ivy Frontends guide

  3. Write tests for your function by following the Ivy Frontend Tests guide

  4. Verify that the tests for your function are passing

If you feel as though there is an ivy function ivy. clearly missing, which would make your frontend function much simpler to implement, then you should first do the following:

  1. Create a new issue with the title ivy.

  2. Add the labels Suggestion, Experimental, Ivy API and Next Release to it

  3. Then simply leave this issue open.

At some point, a member of our team will assess whether it should be added, and if so, they will add it to another appropriate ToDo list issue (see the open task below).

You do not need to wait for this in order to proceed.

After this, you then have two options for how to proceed:

  1. Try to implement the function as a composition of currently present ivy functions, as explained in the “Temporary Compositions” sub-section of the Ivy Frontends guide, and add the #ToDo comment in the implementation as explained. Once the PR is merged, your sub-task issue will then be closed as normal.

  2. 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. For example, you might decide to wait for a member of our team to review your suggested addition ivy., and potentially add this to an Ivy Experimental ToDo list issue (see the open task below). In either case, you should add the label “Pending other Issue” to the frontend sub-task issue, and leave it open. This issue will then still show up as open in the original frontend ToDo list, helpfully preventing others from working on this problematic frontend function, which depends on the unimplemented ivy.. Finally, you should add a comment to the issue with the contents: pending <issue_link>, which links to the ivy. issue, making the “Pending other Issue” label more informative.

There are a few other points to take note of when working on your chosen frontend function:

  1. You should only implement one frontend function.

  2. The frontend function is framework-specific, thus it should be implemented in its respective frontend framework only.

  3. Each frontend function should be tested on all backends to ensure that conversions are working correctly.

  4. Type hints, docstrings and examples are not required for frontend functions.

  5. Some frontend functions shown in the ToDo list issues are aliases of other functions. If you detect that this is the case, then you should add all aliases in your PR, with a single implementation and then simple bindings to this implementation, such as <alias_name> = <function_name>. If you notice that an alias function has already been implemented and pushed, then you can simply add this one-liner binding and get this very simple PR merged.

In the case where your chosen function exists in all frameworks by default, but is not implemented in Ivy’s functional API, please convert your existing GitHub issue to request for the function to be added to Ivy. Meanwhile, you can select another frontend function to work on from the ToDo list! If you’re stuck on a function which requires complex compositions, you’re allowed to reselect a function too!

Where to place a frontend function

The placement of new frontend functions for a given backend should follow the categorisation of the backend API as faithfully as possible. In each issue description, there will be a link to the relevant reference API. Check where the function you’re working on is located, e.g. numpy.inner falls under numpy.linalg. Then, in the Ivy source code, check ivy/functional/frontends/[backend] for pre-existing files which best match the function’s category in the backend reference API.

Taking numpy.inner as an example, we can see that there are a few ivy/functional/frontends/numpy sub-directories to choose from:

creation_routines
fft
indexing_routines
linalg
logic
ma
manipulation_routines
mathematical_functions
matrix
ndarray
random
sorting_searching_counting
statistics
ufunc

There is a linalg sub-directory, so we choose this. Then we need to choose from the files at this hierarchy:

__init__.py
decompositions.py
matrix_and_vector_products.py
matrix_eigenvalues.py
norms_and_other_numbers.py
solving_equations_and_inverting_matrices.py

This may require a bit of reasoning. inner calculates the inner product of two arrays, so matrix_and_vector_products.py seems like the most appropriate option. It is important to note that some functions require the np.linalg.[func] namespace, as can gleamed from the numpy reference API. These functions are listed out under the functional/frontends/numpy/__init__.py imports. There are some functions which have not been implemented yet, and are therefore commented out. Once you have finished the implementation of one of these functions, uncomment it from the list.

The location of test_numpy_inner should mirror the location of its corresponding function, this time in ivy_tests/test_ivy/test_frontends/[backend].

If you’re unsure about where to put the function you’re working on, explore the content of these files to see if you can find a similar function. In matrix_and_vector_products.py, we can see other functions such as outer that are similar to inner. This is confirmation that we’ve found the correct place! If many of the files are empty and you’re unsure where to place your function, feel free to ask the member of the Ivy team reviewing your PR.

Ivy Experimental API

The goal of this task is to add functions to the existing Ivy API which would help with the implementation for many of the functions in the frontend.

Your task is to implement these functions in Ivy, along with their Implementation in the respective backends which are Jax, PyTorch, TensorFlow and NumPy. You must also implement tests for these functions.

There is only one central ToDo list issue for this task.

A general workflow for these tasks would be:

  1. Implement the functions in each of the backend files ivy/functional/backends/backend_name/experimental/[relevant_submodule].py, sometimes as a composition if the respective backends do not behave in a similar way. You may also use submodule-specific helper functions to recreate the behaviour. Refer the Backend API Guide on how this can be done.

  2. Implement the functions in ivy/functional/ivy/experimental/[relevant_submodule].py simply deferring to their backend-specific implementation. Refer the Ivy API Guide to get a clearer picture of how this must be done.

  3. Implement the container instance method in ivy/container/experimental/[relevant_submodule].py and the array instance method in ivy/array/experimental/[relevant_submodule].py

  4. Write tests for the function using the Ivy Tests guide, and make sure they are passing.

A few points to keep in mind while doing this:

  1. Make sure all the positional arguments are positional-only and optional arguments are keyword-only.

  2. In case some tests require function-specific parameters, you can create composite hypothesis strategies using the draw function in the hypothesis library.

If you’re stuck on a function which requires complex compositions, feel free to reselect a function 🙂.

Round Up

This should have hopefully given you a good understanding of the basics for contributing.

If you have any questions, please feel free to reach out on discord in the open tasks channel!