{"id":18711131,"url":"https://github.com/rocm/hip-python","last_synced_at":"2025-04-12T11:34:50.314Z","repository":{"id":194073950,"uuid":"592736376","full_name":"ROCm/hip-python","owner":"ROCm","description":"HIP Python Low-level Bindings ","archived":false,"fork":false,"pushed_at":"2024-10-22T15:55:16.000Z","size":2819,"stargazers_count":17,"open_issues_count":1,"forks_count":3,"subscribers_count":11,"default_branch":"new_main","last_synced_at":"2024-11-02T17:12:45.738Z","etag":null,"topics":["ai","cuda","cython","gpu","hip","hpc","interoperability","ml","python","radeon-instinct-mi-series"],"latest_commit_sha":null,"homepage":"https://rocm.docs.amd.com/projects/hip-python/en/latest/","language":"Shell","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.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-24T12:27:41.000Z","updated_at":"2024-10-22T15:55:13.000Z","dependencies_parsed_at":"2024-01-30T02:05:16.948Z","dependency_job_id":"14a892f0-1753-44e1-b35d-6d2192d8e329","html_url":"https://github.com/ROCm/hip-python","commit_stats":null,"previous_names":["rocmsoftwareplatform/hip-python","rocm/hip-python"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fhip-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fhip-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fhip-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ROCm%2Fhip-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ROCm","download_url":"https://codeload.github.com/ROCm/hip-python/tar.gz/refs/heads/new_main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223515976,"owners_count":17158458,"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","cuda","cython","gpu","hip","hpc","interoperability","ml","python","radeon-instinct-mi-series"],"created_at":"2024-11-07T12:37:12.778Z","updated_at":"2025-04-12T11:34:50.308Z","avatar_url":"https://github.com/ROCm.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- MIT License\n  -- \n  -- Copyright (c) 2023-2024 Advanced Micro Devices, Inc.\n  -- \n  -- Permission is hereby granted, free of charge, to any person obtaining a copy\n  -- of this software and associated documentation files (the \"Software\"), to deal\n  -- in the Software without restriction, including without limitation the rights\n  -- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n  -- copies of the Software, and to permit persons to whom the Software is\n  -- furnished to do so, subject to the following conditions:\n  -- \n  -- The above copyright notice and this permission notice shall be included in all\n  -- copies or substantial portions of the Software.\n  -- \n  -- THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n  -- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n  -- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n  -- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n  -- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n  -- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n  -- SOFTWARE.\n  --\u003e\n# HIP Python Source Repository\n\nThis repository provides low-level Python and Cython Bindings \nfor HIP and an interoperability layer for CUDA\u0026reg; Python programs\n(Python and Cython).\n\n## Requirements\n\n* Currently, only Linux is supported (prebuilt packages and code).\n  * Prebuilt packages distributed via PyPI (or Test PyPI) are only provided for Linux systems that agree with the `manylinux_2_17_x86_64` tag.\n* Requires that a compatible ROCm\u0026trade; HIP SDK is installed on your system.\n  * Source code is provided only for particular ROCm versions.\n    * See the `git` branches tagged with `release/rocm-rel-X.Y[.Z]`\n  * Prebuilt packages are built only for particular ROCm versions. \n\n\u003e [!NOTE]\n\u003e You may find that packages for one ROCm\u0026trade; release might be compatible with the ROCm\u0026trade; HIP SDK of another release as the HIP Python functions load HIP C functions in a lazy manner.\n\n### Build requirements\n\n* A Linux operating system\n* A C compiler\n* `bash`, `python3` + `venv`\n* The ROCm\u0026trade; HIP SDK\n* All other Python build requirements are taken care of by installation scripts.\n  If you decide not to use these scripts, take a look into the `requirements.txt` file \n  in the top-level folder of the this repository and those \n  in the repository's subfolders `hip-python` and `hip-python-as-cuda`.\n\n## Install Prebuilt Package(s)\n\n\u003c!--\n\u003e **NOTE**: The prebuilt packages might not be available on PyPI directly after a ROCm release as this project is not an official part of the ROCm HIP SDK yet and thus is not fully integrated into the global ROCm HIP SDK build process. Check the `simple` lists to see if your operating system and Python version is supported: [hip-python](https://test.pypi.org/simple/hip-python/), [hip-python-as-cuda](https://test.pypi.org/simple/hip-python-as-cuda/).\n--\u003e\n\n\u003e [!NOTE]\n\u003e Prebuilt packages for some ROCm releases are published to Test PyPI first. Check the `simple` lists to see if your operating system and Python version is supported: [hip-python](https://test.pypi.org/simple/hip-python/), [hip-python-as-cuda](https://test.pypi.org/simple/hip-python-as-cuda/).\n\n\u003e [!CAUTION]\n\u003e We have not uploaded any HIP Python packages to PyPI. So far we have only uploaded packages to TestPyPI, mainly intended for internal testing purposes. If you find similar named packages on PyPI they may been provided by others, possibly with malicious intent.\n\n### Via TestPyPI\n\nFirst identify the first three digits of the version number of your ROCm\u0026trade; installation.\nThen install the HIP Python package(s) as follows:\n\n```shell\npython3 -m pip install -i https://test.pypi.org/simple hip-python~=$rocm_version\n# if you want to install the CUDA Python interoperability package too, run:\npython3 -m pip install -i https://test.pypi.org/simple hip-python-as-cuda~=$rocm_version\n```\n\n\u003c!--\n-- #### Via TestPyPI\n-- \n-- Packages can be installed via the TestPyPI index by prefixing the\n-- the PIP install commands as follows:\n-- \n-- ```shell\n-- python3 -m pip install -i https://test.pypi.org/simple ...\n-- ```\n--\u003e\n\n### Via Wheel in Local Filesystem\n\nIf you have HIP Python package wheels n your filesystem, you can run:\n\n```shell\npython3 -m pip install \u003cpath/to/hip_python\u003e.whl\n# if you want to install the CUDA Python interoperability package too, run:\npython3 -m pip install \u003cpath/to/hip_python_as_cuda\u003e.whl\n```\n\u003e [!NOTE]\n\u003e See the HIP Python user guide for more details:\n\u003e https://rocm.docs.amd.com/projects/hip-python/en/latest/index.html\n\n## Build From Source\n\n\u003e [!NOTE]\n\u003e The `new_main` branch is used for tracking updates to the docs, examples and CI scripts. \n\u003e The source code can be found on the release branches `release/rocm-rel-X.Y[.Z]`.\n\n1. Install ROCM\n1. Install `pip`, virtual environment and development headers for Python 3:\n   ```bash\n   # Ubuntu:\n   sudo apt install python3-pip python3-venv python3-dev\n   ```\n1. Check out the feature branch `release/rocm-rel-X.Y[.Z]` for your particular ROCm\u0026trade; installation:\n1. Initialize the branch:\n   ```bash\n   ./init.sh\n   ```\n1. Finally run:\n   ```bash\n   ./build_hip_python_pkgs.sh --hip --cuda --post-clean\n   ```\n\nThe build process will produce Python binary wheels in the subdirectories\n`hip-python/dist/` and `hip-python-as-cuda/dist`, which can be installed\nas discussed in the previous section.\n\n\u003e [!NOTE]\n\u003e See the HIP Python developer guide for more details:\n\u003e https://rocm.docs.amd.com/projects/hip-python/en/latest/index.html\n\n### Build Options\n\n```\nUsage: ./build_hip_python_pkgs.sh [OPTIONS]\n\nOptions:\n  --rocm-path          Path to a ROCm installation, defaults to variable 'ROCM_PATH' if set or '/opt/rocm'.\n  --libs               HIP Python libraries to build as comma separated list without whitespaces, defaults to variable 'HIP_PYTHON_LIBS' if set or '*'.\n                       Add a prefix '^' to NOT build the comma-separated list of libraries that follows but all other libraries.\n  --cuda-libs          HIP Python CUDA interop libraries to build as comma separated list without whitespaces, defaults to variable 'HIP_PYTHON_CUDA_LIBS' if set or '*'.\n                       Add a prefix '^' to NOT build the comma-separated list of libraries that follows but all other libraries.\n  --hip                Build package 'hip-python'.\n  --cuda               Build package 'hip-python-as-cuda'.\n  --docs               Build the docs.\n  --no-api-docs        Temporarily move the 'docs/python_api' subfolder so that sphinx does not see it.\n  --no-clean-docs      Do not generate docs from scratch, i.e. don't run sphinx with -E switch.\n  --docs-use-testpypi  Get the HIP Python packages for building the docs from Test PyPI.\n  --docs-use-pypi      Get the HIP Python packages for building the docs from PyPI.\n  --no-archive         Do not put previously created packages into the archive folder.\n  --run-tests          Run the tests.\n  -j,--num-jobs        Number of build jobs to use. Defaults to 1.\n  --pre-clean          Remove the virtual Python environment subfolder '_venv' --- if it exists --- before all other tasks.\n  --post-clean         Remove the virtual Python environment subfolder '_venv' --- if it exists --- after all other tasks.\n  -n, --no-venv        Do not create and use a virtual Python environment.\n  -h, --help           Show this help message.\n```\n\n## Known Compilation Issues\n\n### The `hipsparse` Module won't Compile with Older GCC Release\n\nWith all ROCm\u0026trade; versions before version 5.6.0 (exclusive) and older GCC versions, \ncompiling HIP Python's `hipsparse` module results in a compiler error caused by lines such as:\n\n```c\nHIPSPARSE_ORDER_COLUMN [[deprecated(\"Please use HIPSPARSE_ORDER_COL instead\")]] = 1,\n```\n\n#### Workaround 1: Disable Build of 'hipsparse' Module\n\nDisabling the build of the `hipsparse` HIP python module can, e.g., \nbe achieved by supplying `--libs \"^hipsparse\"` to `build_hip_python_pkgs.sh`.\n\n#### Workaround 2 (Requires Access to Header File): Edit Header File\n\nFor this fix, you need write access to the ROCm\u0026trade; header files.\nThen, e.g., modify file `\u003cpath_to_rocm\u003e/hiprand/hiprand_hcc.h` such that:\n\n```c\nHIPSPARSE_ORDER_COLUMN [[deprecated(\"Please use HIPSPARSE_ORDER_COL instead\")]] = 1,\n```\n\nbecomes \n\n```c\nHIPSPARSE_ORDER_COLUMN = 1, // [[deprecated(\"Please use HIPSPARSE_ORDER_COL instead\")]] = 1,\n```\n\n### The `hiprand` module Won't Compile\n\nWith all ROCm\u0026trade; versions before and including version 5.6.0, compiling HIP Python's `hiprand` \nmodule results in a compiler error.\n\nThe error is caused by the following line in the C compilation\npath of `\u003cpath_to_rocm\u003e/hiprand/hiprand_hcc.h`, which is not legal in C\nfor aliasing a `struct` type:\n\n```c\ntypedef rocrand_generator_base_type hiprandGenerator_st;\n```\n\n#### Workaround 1: Disable Build of Hiprand Module\n\nDisabling the build of the `hiprand` HIP python module can, e.g., \nbe achieved by supplying `--libs \"^hiprand\"` to `build_hip_python_pkgs.sh`.\n\n#### Workaround 2 (Requires Access to Header File): Edit Header File\n\nFor this fix, you need write access to the ROCm\u0026trade; header files.\nThen, modify file `\u003cpath_to_rocm\u003e/hiprand/hiprand_hcc.h` such that\n\n```c\ntypedef rocrand_generator_base_type hiprandGenerator_st;\n```\n\nbecomes \n\n```c\ntypedef struct rocrand_generator_base_type hiprandGenerator_st;\n```\n\nNote that Cython users will experience the same issue if they use one\nof the Cython modules in their code and use `c` as compilation language.\n\n## Other Known Issues\n\n### ROCm\u0026trade; 5.5.0 and ROCm\u0026trade; 5.5.1\n\nOn systems with ROCm\u0026trade; HIP SDK 5.5.0 or 5.5.1, the examples\n\n* hip-python/examples/0\\_Basic\\_Usage/hiprtc\\_launch\\_kernel\\_args.py\n* hip-python/examples/0\\_Basic\\_Usage/hiprtc\\_launch\\_kernel\\_no\\_args.py\n\nabort with errors.\n\nAn upgrade to version HIP SDK 5.6 or later (or a downgrade to version 5.4) is advised if \nthe showcased functionality is needed.\n\n### Unspecific\n\nOn certain Ubuntu 20 systems, we encountered issues when running the examples:\n\n* hip-python/examples/0\\_Basic\\_Usage/hiprtc\\_launch\\_kernel\\_args.py\n* hip-python/examples/0\\_Basic\\_Usage/rccl\\_comminitall\\_bcast.py\n\nWe could not identify the cause yet.\n\n## Documentation\n\nFor examples, guides and API reference, please take a\nlook at the official HIP Python documentation pages:\n\nhttps://rocm.docs.amd.com/projects/hip-python/en/latest/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Fhip-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocm%2Fhip-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocm%2Fhip-python/lists"}