{"id":18711202,"url":"https://github.com/rocm/numba-hip","last_synced_at":"2025-08-31T14:32:07.034Z","repository":{"id":251138371,"uuid":"794927750","full_name":"ROCm/numba-hip","owner":"ROCm","description":"HIP backend patch for Numba, the NumPy aware dynamic Python compiler using LLVM.","archived":false,"fork":false,"pushed_at":"2024-12-20T09:16:43.000Z","size":636,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2024-12-20T10:24:35.230Z","etag":null,"topics":["ai","compiler","cuda","gpu","hip","hpc","jit","ml","numba","python","radeon-instinct-mi-series","rocm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ROCm.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-02T08:38:01.000Z","updated_at":"2024-12-20T09:16:47.000Z","dependencies_parsed_at":"2024-08-19T13:47:23.239Z","dependency_job_id":"c9ca01a8-bbe9-40b6-978d-1b516ea60f2a","html_url":"https://github.com/ROCm/numba-hip","commit_stats":null,"previous_names":["rocm/numba-hip"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fnumba-hip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fnumba-hip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fnumba-hip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fnumba-hip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ROCm","download_url":"https://codeload.github.com/ROCm/numba-hip/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231600666,"owners_count":18398551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","compiler","cuda","gpu","hip","hpc","jit","ml","numba","python","radeon-instinct-mi-series","rocm"],"created_at":"2024-11-07T12:37:47.898Z","updated_at":"2025-08-31T14:32:07.021Z","avatar_url":"https://github.com/ROCm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"*********\nNumba HIP\n*********\n\nThis repository provides a ROCm(TM) HIP backend for Numba.\n\n.. note:: Only for AMD MI series GPUs on Linux systems\n\n    So far the Numba HIP backend has only been used and tested with AMD MI series GPUs\n    on Linux systems. CUDA(R) devices are not supported.\n\n.. note:: Experimental project\n    \n    With this release, we primarily want to accomplish two things:\n\n    1. Support internal projects that require a Numba backend for AMD GPUs.\n       All features that have been implemented so far were driven by the\n       requirements of those internal projects.\n    2. Give Numba developers additional context on how to create infrastructure that\n       supports multiple accelerator targets.\n       (See also: `RFC: Moving the CUDA target to a new package maintained by NVIDIA \u003chttps://numba.discourse.group/t/rfc-moving-the-cuda-target-to-a-new-package-maintained-by-nvidia/2628/2\u003e`_)\n    \n    However, we are also happy to get feedback from early adopters on their experience with the new Numba HIP backend.\n    So if you give Numba HIP a try, let us know about your experience. We are looking forward to your suggestions, issue reports, and\n    pull requests!\n\n\nAbout Numba: A Just-In-Time Compiler for Numerical Functions in Python\n######################################################################\n\nNumba is an open source, NumPy-aware optimizing compiler for Python sponsored\nby Anaconda, Inc.  It uses the LLVM compiler project to generate machine code\nfrom Python syntax.\n\nNumba can compile a large subset of numerically-focused Python, including many\nNumPy functions.  Additionally, Numba has support for automatic\nparallelization of loops, generation of GPU-accelerated code, and creation of\nufuncs and C callbacks.\n\nFor more information about Numba, see the Numba homepage:\nhttps://numba.pydata.org and the online documentation:\nhttps://numba.readthedocs.io/en/stable/index.html\n\nNumba HIP: Basic Usage\n======================\n\nNumba HIP's programming interfaces follow Numba CUDA's design very closely.\nAside from the module name ``hip``, there is often no difference between\nNumba CUDA to Numba HIP code.\n\n**Example 1 (Numba HIP):**\n\n.. code-block:: python\n\n   from numba import hip\n\n   @hip.jit\n   def f(a, b, c):\n      # like threadIdx.x + (blockIdx.x * blockDim.x)\n      tid = hip.grid(1)\n      size = len(c)\n\n      if tid \u003c size:\n          c[tid] = a[tid] + b[tid]\n\n\n**Example 2 (Numba CUDA):**\n\n.. code-block:: python\n\n   from numba import cuda\n\n   @cuda.jit\n   def f(a, b, c):\n      # like threadIdx.x + (blockIdx.x * blockDim.x)\n      tid = cuda.grid(1)\n      size = len(c)\n\n      if tid \u003c size:\n          c[tid] = a[tid] + b[tid]\n\nNumba HIP: Posing As Numba CUDA\n===============================\n\nAs Numba HIP allows to use syntax that is so similar to that of Numba CUDA and\nthere are already many projects that use Numba CUDA, we have introduced a\nfeature to the Numba HIP backend that allows it to pose as the Numba CUDA\nbackend to dependent applications. We demonstrate the usage of this feature in\nthe example below:\n\n**Example 3 (Numba HIP posing as Numba CUDA):**\n\n.. code-block:: python\n\n   from numba import hip\n   hip.pose_as_cuda() # now 'from numba import cuda'\n                      # and `numba.cuda` delegate to Numba HIP.\n\n   # unchanged Numba CUDA snippet (Example 2)\n\n   from numba import cuda\n\n   @cuda.jit\n   def f(a, b, c):\n      # like threadIdx.x + (blockIdx.x * blockDim.x)\n      tid = cuda.grid(1)\n      size = len(c)\n\n      if tid \u003c size:\n          c[tid] = a[tid] + b[tid]\n\n\nNumba HIP: Limitations\n======================\n\nGenerally, we aim for feature parity with Numba CUDA.\n\nThe following Numba CUDA features are not available via Numba HIP:\n\n* Cooperative groups support (ex: ``cg.this_grid()``,\n  ``cg.this_grid().sync()``)\n* Atomic operations for tuple and array types,\n* Runtime kernel debugging functionality,\n* Device code printf,\n* HIP Simulator equivalent to CUDA Simulator (low priority, users can\n  potentially reuse CUDA simulator),\n* Half precision (fp16) operations.\n\nNote further that so far only limited effort has been spent on optimizing the\nperformance of the just-in-time compilation infrastructure.\n\nNumba HIP: Design Differences vs. Numba CUDA\n============================================\n\n* While Numba CUDA utilizes the ``nvvm`` IR library, Numba HIP generates\n  an architecture-specific LLVM bitcode library from a HIP C++ header file\n  at startup of a Numba HIP program. However, a filesystem cache ensures that\n  this needs to be done only once for a given session. The presence of such an\n  additional caching mechanism must be considered when benchmarking.\n\n* While Numba CUDA manually/semi-automatically creates basic device function signatures and the respective lowering\n  procedures, Numba HIP does this fully-automatically from the aforementioned HIP C++ header file via the LLVM ``clang`` Python bindings.\n\n* Furthermore, Numba HIP automatically links the HIP device library functions with the ``math`` module and uses a\n  mechanism for recursive attribute resolution.\n\nInstallation\n============\n\n.. note:: Supported Numba versions\n\n   The Numba HIP backend has been tested with the following Numba versions:\n\n   * 0.58.*\n   * 0.59.*\n   * 0.60.0\n\n   Other versions have not been tested; using the Numba HIP backend with these versions might work or not.\n\nImportant things to know before installing\n------------------------------------------\n\nMake sure that your ``pip`` is upgraded by running\n\n.. code-block:: bash\n\n   pip install --upgrade pip\n\nDependencies of Numba HIP are currently partially distributed via Test PyPI.\nTherefore, you need to specify an extra index URL in your ``pip`` config\nas shown below:\n\n.. code-block:: bash\n\n   pip config set global.extra-index-url https://test.pypi.org/simple\n\nThose dependencies further are depending on a particular ROCm release.\nWe use optional dependency lists to make this configurable; see the\n``pyproject.toml`` file for more details.\nTo install dependencies for a ROCm release of a particular version, you need\nto specify an dependency key in the format\n``rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e`` (example: ``rocm-6-1-2``) when building\nthe Numba HIP package. If you leave the key aside, ``pip`` will either use\nalready installed versions of the dependencies or install the latest release\nof these dependencies, which are compatible with the most recent release of ROCm\nbut potentially not with older ROCm releases.\n\nInstall via Github URL\n----------------------\n\nThe easiest way to install Numba HIP is by passing the repository URL and\noptionally the branch that you want to build directly to ``pip``:\n\n.. code-block:: bash\n\n   pip install --upgrade pip\n   pip config set global.extra-index-url https://test.pypi.org/simple\n   # syntax 1: pip install git+\u003cURL\u003e@\u003cbranch\u003e\n   # syntax 2: pip install \"numba-hip[rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e] @ git+\u003cURL\u003e@\u003cbranch\u003e\"\n   pip install \"numba-hip[rocm-6-1-2] @ git+https://github.com/ROCm/numba-hip.git\"\n     # alternatively: checkout a branch like 'dev':\n     # pip install \"numba-hip[rocm-6-1-2] @ git+https://github.com/ROCm/numba-hip.git@dev\"\n\n.. note:: ROCm key must agree with your environment\n\n   Do not forget to change the ROCm version ``rocm-6-1-2``\n   (format: ``rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e``) to a key that agrees with your\n   ROCm installation so that dependency versions compatible with your\n   ROCm installation are installed by ``pip``.\n\nInstall with optional test dependencies:\n\n.. code-block:: bash\n\n   pip install --upgrade pip\n   pip config set global.extra-index-url https://test.pypi.org/simple\n   # syntax 1: pip install \"numba-hip[test] @  git+\u003cURL\u003e@\u003cbranch\u003e\"\n   # syntax 2: pip install \"numba-hip[rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e,test] @ git+\u003cURL\u003e@\u003cbranch\u003e\"\n   pip install \"numba-hip[rocm-6-1-2,test] @ git+https://github.com/ROCm/numba-hip.git\"\n     # alternatively: checkout a branch like 'dev':\n     # pip install \"numba-hip[rocm-6-1-2,test] @ git+https://github.com/ROCm/numba-hip.git@dev\"\n\nInstall via pip install\n-----------------------\n\nAfter cloning the repository, you can also install the package via ``pip install``:\n\n.. code-block:: bash\n\n   git clone https://github.com/ROCm/numba-hip.git\n     # alternatively: checkout a branch like 'dev':\n     # pip clone https://github.com/ROCm/numba-hip.git -b branch\n   pip install --upgrade pip\n   pip config set global.extra-index-url https://test.pypi.org/simple\n   python3 -m pip install .[rocm-6-1-2]\n     # alternatively: install optional test dependencies:\n     # variant 1: python3 -m pip install .[test]\n     # variant 2: python3 -m pip install .[rocm-6-1-2,test]\n\n.. note:: ROCm key must agree with your environment\n\n   Do not forget to change the ROCm version ``rocm-6-1-2``\n   (format: ``rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e``) to a key that agrees with your\n   ROCm installation so that dependency versions compatible with your\n   ROCm installation are installed by ``pip``.\n\nCreate a wheel via PyPA build\n-----------------------------\n\nAfter cloning the repository, you can also build a Python wheel\nand then distribute it (or install it):\n\n.. code-block:: bash\n\n   git clone https://github.com/ROCm/numba-hip.git\n     # alternatively: checkout a branch like 'dev':\n     # pip clone https://github.com/ROCm/numba-hip.git -b branch\n   pip install --upgrade pip\n   pip config set global.extra-index-url https://test.pypi.org/simple\n   pip install build # install PyPA build \n   python3 -m build --wheel .\n\n   # optional: install the wheel:\n   pip install dist/*.whl\n   # alternatively: install optional test dependencies:\n   # pip3 install dist/numba_hip-0.1-py3-none-any.whl[rocm-6-1-2]\n\n.. note:: ROCm key must agree with your environment\n\n   Do not forget to change the ROCm version ``rocm-6-1-2``\n   (format: ``rocm-\u003cmajor\u003e-\u003cminor\u003e-\u003cpatch\u003e``) to a key that agrees with your\n   ROCm installation so that dependency versions compatible with your\n   ROCm installation are installed by ``pip``.\n\nContact\n=======\n\nNumba has a discourse forum for discussions:\n\n* https://numba.discourse.group\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Fnumba-hip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocm%2Fnumba-hip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Fnumba-hip/lists"}