From 8ab98dffafc84c4e8d57889a9b44b9d62b4703e8 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Mon, 11 Mar 2024 09:26:16 -0700 Subject: [PATCH 01/17] Add PDM/Invoke build instructions --- README.md | 11 + pdm.lock | 1103 ++++++++++++++++++++++++++++++++++++++++++++++++ pyproject.toml | 27 ++ tasks.py | 42 ++ 4 files changed, 1183 insertions(+) create mode 100644 pdm.lock create mode 100644 pyproject.toml create mode 100644 tasks.py diff --git a/README.md b/README.md index 0a019446..e64b662e 100644 --- a/README.md +++ b/README.md @@ -16,3 +16,14 @@ pip3 install -r sphinx/requirements.txt python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html ``` + +## Build Using PDM + +Alternatively, you can use [`pdm`] to manage the build environment. + +Ensure [`pdm` is installed](https://pdm-project.org/latest/#installation) + +* Create venv, install build requirements: `pdm install` +* Build the docs: `pdm run inv build` + +Now you can open `docs/_build/html/index.html` in your browser diff --git a/pdm.lock b/pdm.lock new file mode 100644 index 00000000..f53f6019 --- /dev/null +++ b/pdm.lock @@ -0,0 +1,1103 @@ +# This file is @generated by PDM. +# It is not intended for manual editing. + +[metadata] +groups = ["default", "dev"] +strategy = ["cross_platform", "inherit_metadata"] +lock_version = "4.4.1" +content_hash = "sha256:ad1844da5379124e59503e18dde3cf2397932a4ddf38d4b10f3d99cfbe9799fc" + +[[package]] +name = "accessible-pygments" +version = "0.0.4" +summary = "A collection of accessible pygments styles" +groups = ["default"] +dependencies = [ + "pygments>=1.5", +] +files = [ + {file = "accessible-pygments-0.0.4.tar.gz", hash = "sha256:e7b57a9b15958e9601c7e9eb07a440c813283545a20973f2574a5f453d0e953e"}, + {file = "accessible_pygments-0.0.4-py2.py3-none-any.whl", hash = "sha256:416c6d8c1ea1c5ad8701903a20fcedf953c6e720d64f33dc47bfb2d3f2fa4e8d"}, +] + +[[package]] +name = "alabaster" +version = "0.7.16" +requires_python = ">=3.9" +summary = "A light, configurable Sphinx theme" +groups = ["default"] +files = [ + {file = "alabaster-0.7.16-py3-none-any.whl", hash = "sha256:b46733c07dce03ae4e150330b975c75737fa60f0a7c591b6c8bf4928a28e2c92"}, + {file = "alabaster-0.7.16.tar.gz", hash = "sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65"}, +] + +[[package]] +name = "asttokens" +version = "2.4.1" +summary = "Annotate AST trees with source code positions" +groups = ["dev"] +dependencies = [ + "six>=1.12.0", +] +files = [ + {file = "asttokens-2.4.1-py2.py3-none-any.whl", hash = "sha256:051ed49c3dcae8913ea7cd08e46a606dba30b79993209636c4875bc1d637bc24"}, + {file = "asttokens-2.4.1.tar.gz", hash = "sha256:b03869718ba9a6eb027e134bfdf69f38a236d681c83c160d510768af11254ba0"}, +] + +[[package]] +name = "babel" +version = "2.14.0" +requires_python = ">=3.7" +summary = "Internationalization utilities" +groups = ["default"] +files = [ + {file = "Babel-2.14.0-py3-none-any.whl", hash = "sha256:efb1a25b7118e67ce3a259bed20545c29cb68be8ad2c784c83689981b7a57287"}, + {file = "Babel-2.14.0.tar.gz", hash = "sha256:6919867db036398ba21eb5c7a0f6b28ab8cbc3ae7a73a44ebe34ae74a4e7d363"}, +] + +[[package]] +name = "beautifulsoup4" +version = "4.12.3" +requires_python = ">=3.6.0" +summary = "Screen-scraping library" +groups = ["default"] +dependencies = [ + "soupsieve>1.2", +] +files = [ + {file = "beautifulsoup4-4.12.3-py3-none-any.whl", hash = "sha256:b80878c9f40111313e55da8ba20bdba06d8fa3969fc68304167741bbf9e082ed"}, + {file = "beautifulsoup4-4.12.3.tar.gz", hash = "sha256:74e3d1928edc070d21748185c46e3fb33490f22f52a3addee9aee0f4f7781051"}, +] + +[[package]] +name = "breathe" +version = "4.35.0" +summary = "Sphinx Doxygen renderer" +groups = ["default"] +dependencies = [ + "Sphinx!=5.0.0,>=4.0", + "docutils>=0.12", +] +files = [ + {file = "breathe-4.35.0-py3-none-any.whl", hash = "sha256:52c581f42ca4310737f9e435e3851c3d1f15446205a85fbc272f1f97ed74f5be"}, + {file = "breathe-4.35.0.tar.gz", hash = "sha256:5165541c3c67b6c7adde8b3ecfe895c6f7844783c4076b6d8d287e4f33d62386"}, +] + +[[package]] +name = "certifi" +version = "2024.2.2" +requires_python = ">=3.6" +summary = "Python package for providing Mozilla's CA Bundle." +groups = ["default"] +files = [ + {file = "certifi-2024.2.2-py3-none-any.whl", hash = "sha256:dc383c07b76109f368f6106eee2b593b04a011ea4d55f652c6ca24a754d1cdd1"}, + {file = "certifi-2024.2.2.tar.gz", hash = "sha256:0569859f95fc761b18b45ef421b1290a0f65f147e92a1e5eb3e635f9a5e4e66f"}, +] + +[[package]] +name = "cffi" +version = "1.16.0" +requires_python = ">=3.8" +summary = "Foreign Function Interface for Python calling C code." +groups = ["default"] +dependencies = [ + "pycparser", +] +files = [ + {file = "cffi-1.16.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:6b3d6606d369fc1da4fd8c357d026317fbb9c9b75d36dc16e90e84c26854b088"}, + {file = "cffi-1.16.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:ac0f5edd2360eea2f1daa9e26a41db02dd4b0451b48f7c318e217ee092a213e9"}, + {file = "cffi-1.16.0-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7e61e3e4fa664a8588aa25c883eab612a188c725755afff6289454d6362b9673"}, + {file = "cffi-1.16.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a72e8961a86d19bdb45851d8f1f08b041ea37d2bd8d4fd19903bc3083d80c896"}, + {file = "cffi-1.16.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5b50bf3f55561dac5438f8e70bfcdfd74543fd60df5fa5f62d94e5867deca684"}, + {file = "cffi-1.16.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7651c50c8c5ef7bdb41108b7b8c5a83013bfaa8a935590c5d74627c047a583c7"}, + {file = "cffi-1.16.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e4108df7fe9b707191e55f33efbcb2d81928e10cea45527879a4749cbe472614"}, + {file = "cffi-1.16.0-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:32c68ef735dbe5857c810328cb2481e24722a59a2003018885514d4c09af9743"}, + {file = "cffi-1.16.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:673739cb539f8cdaa07d92d02efa93c9ccf87e345b9a0b556e3ecc666718468d"}, + {file = "cffi-1.16.0-cp310-cp310-win32.whl", hash = "sha256:9f90389693731ff1f659e55c7d1640e2ec43ff725cc61b04b2f9c6d8d017df6a"}, + {file = "cffi-1.16.0-cp310-cp310-win_amd64.whl", hash = "sha256:e6024675e67af929088fda399b2094574609396b1decb609c55fa58b028a32a1"}, + {file = "cffi-1.16.0.tar.gz", hash = "sha256:bcb3ef43e58665bbda2fb198698fcae6776483e0c4a631aa5647806c25e02cc0"}, +] + +[[package]] +name = "charset-normalizer" +version = "3.3.2" +requires_python = ">=3.7.0" +summary = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet." +groups = ["default"] +files = [ + {file = "charset-normalizer-3.3.2.tar.gz", hash = "sha256:f30c3cb33b24454a82faecaf01b19c18562b1e89558fb6c56de4d9118a032fd5"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:25baf083bf6f6b341f4121c2f3c548875ee6f5339300e08be3f2b2ba1721cdd3"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:06435b539f889b1f6f4ac1758871aae42dc3a8c0e24ac9e60c2384973ad73027"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9063e24fdb1e498ab71cb7419e24622516c4a04476b17a2dab57e8baa30d6e03"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6897af51655e3691ff853668779c7bad41579facacf5fd7253b0133308cf000d"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1d3193f4a680c64b4b6a9115943538edb896edc190f0b222e73761716519268e"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cd70574b12bb8a4d2aaa0094515df2463cb429d8536cfb6c7ce983246983e5a6"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8465322196c8b4d7ab6d1e049e4c5cb460d0394da4a27d23cc242fbf0034b6b5"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a9a8e9031d613fd2009c182b69c7b2c1ef8239a0efb1df3f7c8da66d5dd3d537"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:beb58fe5cdb101e3a055192ac291b7a21e3b7ef4f67fa1d74e331a7f2124341c"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:e06ed3eb3218bc64786f7db41917d4e686cc4856944f53d5bdf83a6884432e12"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_ppc64le.whl", hash = "sha256:2e81c7b9c8979ce92ed306c249d46894776a909505d8f5a4ba55b14206e3222f"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_s390x.whl", hash = "sha256:572c3763a264ba47b3cf708a44ce965d98555f618ca42c926a9c1616d8f34269"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:fd1abc0d89e30cc4e02e4064dc67fcc51bd941eb395c502aac3ec19fab46b519"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-win32.whl", hash = "sha256:3d47fa203a7bd9c5b6cee4736ee84ca03b8ef23193c0d1ca99b5089f72645c73"}, + {file = "charset_normalizer-3.3.2-cp310-cp310-win_amd64.whl", hash = "sha256:10955842570876604d404661fbccbc9c7e684caf432c09c715ec38fbae45ae09"}, + {file = "charset_normalizer-3.3.2-py3-none-any.whl", hash = "sha256:3e4d1f6587322d2788836a99c69062fbb091331ec940e02d12d179c1d53e25fc"}, +] + +[[package]] +name = "click" +version = "8.1.7" +requires_python = ">=3.7" +summary = "Composable command line interface toolkit" +groups = ["default"] +dependencies = [ + "colorama; platform_system == \"Windows\"", +] +files = [ + {file = "click-8.1.7-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28"}, + {file = "click-8.1.7.tar.gz", hash = "sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de"}, +] + +[[package]] +name = "colorama" +version = "0.4.6" +requires_python = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7" +summary = "Cross-platform colored terminal text." +groups = ["default", "dev"] +marker = "sys_platform == \"win32\" or platform_system == \"Windows\"" +files = [ + {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"}, + {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"}, +] + +[[package]] +name = "cryptography" +version = "42.0.5" +requires_python = ">=3.7" +summary = "cryptography is a package which provides cryptographic recipes and primitives to Python developers." +groups = ["default"] +dependencies = [ + "cffi>=1.12; platform_python_implementation != \"PyPy\"", +] +files = [ + {file = "cryptography-42.0.5-cp37-abi3-macosx_10_12_universal2.whl", hash = "sha256:a30596bae9403a342c978fb47d9b0ee277699fa53bbafad14706af51fe543d16"}, + {file = "cryptography-42.0.5-cp37-abi3-macosx_10_12_x86_64.whl", hash = "sha256:b7ffe927ee6531c78f81aa17e684e2ff617daeba7f189f911065b2ea2d526dec"}, + {file = "cryptography-42.0.5-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2424ff4c4ac7f6b8177b53c17ed5d8fa74ae5955656867f5a8affaca36a27abb"}, + {file = "cryptography-42.0.5-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:329906dcc7b20ff3cad13c069a78124ed8247adcac44b10bea1130e36caae0b4"}, + {file = "cryptography-42.0.5-cp37-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:b03c2ae5d2f0fc05f9a2c0c997e1bc18c8229f392234e8a0194f202169ccd278"}, + {file = "cryptography-42.0.5-cp37-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:f8837fe1d6ac4a8052a9a8ddab256bc006242696f03368a4009be7ee3075cdb7"}, + {file = "cryptography-42.0.5-cp37-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:0270572b8bd2c833c3981724b8ee9747b3ec96f699a9665470018594301439ee"}, + {file = "cryptography-42.0.5-cp37-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:b8cac287fafc4ad485b8a9b67d0ee80c66bf3574f655d3b97ef2e1082360faf1"}, + {file = "cryptography-42.0.5-cp37-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:16a48c23a62a2f4a285699dba2e4ff2d1cff3115b9df052cdd976a18856d8e3d"}, + {file = "cryptography-42.0.5-cp37-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:2bce03af1ce5a5567ab89bd90d11e7bbdff56b8af3acbbec1faded8f44cb06da"}, + {file = "cryptography-42.0.5-cp37-abi3-win32.whl", hash = "sha256:b6cd2203306b63e41acdf39aa93b86fb566049aeb6dc489b70e34bcd07adca74"}, + {file = "cryptography-42.0.5-cp37-abi3-win_amd64.whl", hash = "sha256:98d8dc6d012b82287f2c3d26ce1d2dd130ec200c8679b6213b3c73c08b2b7940"}, + {file = "cryptography-42.0.5-cp39-abi3-macosx_10_12_universal2.whl", hash = "sha256:5e6275c09d2badf57aea3afa80d975444f4be8d3bc58f7f80d2a484c6f9485c8"}, + {file = "cryptography-42.0.5-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e4985a790f921508f36f81831817cbc03b102d643b5fcb81cd33df3fa291a1a1"}, + {file = "cryptography-42.0.5-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7cde5f38e614f55e28d831754e8a3bacf9ace5d1566235e39d91b35502d6936e"}, + {file = "cryptography-42.0.5-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:7367d7b2eca6513681127ebad53b2582911d1736dc2ffc19f2c3ae49997496bc"}, + {file = "cryptography-42.0.5-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:cd2030f6650c089aeb304cf093f3244d34745ce0cfcc39f20c6fbfe030102e2a"}, + {file = "cryptography-42.0.5-cp39-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:a2913c5375154b6ef2e91c10b5720ea6e21007412f6437504ffea2109b5a33d7"}, + {file = "cryptography-42.0.5-cp39-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:c41fb5e6a5fe9ebcd58ca3abfeb51dffb5d83d6775405305bfa8715b76521922"}, + {file = "cryptography-42.0.5-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:3eaafe47ec0d0ffcc9349e1708be2aaea4c6dd4978d76bf6eb0cb2c13636c6fc"}, + {file = "cryptography-42.0.5-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:1b95b98b0d2af784078fa69f637135e3c317091b615cd0905f8b8a087e86fa30"}, + {file = "cryptography-42.0.5-cp39-abi3-win32.whl", hash = "sha256:1f71c10d1e88467126f0efd484bd44bca5e14c664ec2ede64c32f20875c0d413"}, + {file = "cryptography-42.0.5-cp39-abi3-win_amd64.whl", hash = "sha256:a011a644f6d7d03736214d38832e030d8268bcff4a41f728e6030325fea3e400"}, + {file = "cryptography-42.0.5-pp310-pypy310_pp73-macosx_10_12_x86_64.whl", hash = "sha256:9481ffe3cf013b71b2428b905c4f7a9a4f76ec03065b05ff499bb5682a8d9ad8"}, + {file = "cryptography-42.0.5-pp310-pypy310_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:ba334e6e4b1d92442b75ddacc615c5476d4ad55cc29b15d590cc6b86efa487e2"}, + {file = "cryptography-42.0.5-pp310-pypy310_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:ba3e4a42397c25b7ff88cdec6e2a16c2be18720f317506ee25210f6d31925f9c"}, + {file = "cryptography-42.0.5-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:111a0d8553afcf8eb02a4fea6ca4f59d48ddb34497aa8706a6cf536f1a5ec576"}, + {file = "cryptography-42.0.5-pp39-pypy39_pp73-macosx_10_12_x86_64.whl", hash = "sha256:cd65d75953847815962c84a4654a84850b2bb4aed3f26fadcc1c13892e1e29f6"}, + {file = "cryptography-42.0.5-pp39-pypy39_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:e807b3188f9eb0eaa7bbb579b462c5ace579f1cedb28107ce8b48a9f7ad3679e"}, + {file = "cryptography-42.0.5-pp39-pypy39_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:f12764b8fffc7a123f641d7d049d382b73f96a34117e0b637b80643169cec8ac"}, + {file = "cryptography-42.0.5-pp39-pypy39_pp73-win_amd64.whl", hash = "sha256:37dd623507659e08be98eec89323469e8c7b4c1407c85112634ae3dbdb926fdd"}, + {file = "cryptography-42.0.5.tar.gz", hash = "sha256:6fe07eec95dfd477eb9530aef5bead34fec819b3aaf6c5bd6d20565da607bfe1"}, +] + +[[package]] +name = "decorator" +version = "5.1.1" +requires_python = ">=3.5" +summary = "Decorators for Humans" +groups = ["dev"] +files = [ + {file = "decorator-5.1.1-py3-none-any.whl", hash = "sha256:b8c3f85900b9dc423225913c5aace94729fe1fa9763b38939a95226f02d37186"}, + {file = "decorator-5.1.1.tar.gz", hash = "sha256:637996211036b6385ef91435e4fae22989472f9d571faba8927ba8253acbc330"}, +] + +[[package]] +name = "defusedxml" +version = "0.7.1" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" +summary = "XML bomb protection for Python stdlib modules" +groups = ["default"] +files = [ + {file = "defusedxml-0.7.1-py2.py3-none-any.whl", hash = "sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61"}, + {file = "defusedxml-0.7.1.tar.gz", hash = "sha256:1bb3032db185915b62d7c6209c5a8792be6a32ab2fedacc84e01b52c51aa3e69"}, +] + +[[package]] +name = "deprecated" +version = "1.2.14" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +summary = "Python @deprecated decorator to deprecate old python classes, functions or methods." +groups = ["default"] +dependencies = [ + "wrapt<2,>=1.10", +] +files = [ + {file = "Deprecated-1.2.14-py2.py3-none-any.whl", hash = "sha256:6fac8b097794a90302bdbb17b9b815e732d3c4720583ff1b198499d78470466c"}, + {file = "Deprecated-1.2.14.tar.gz", hash = "sha256:e5323eb936458dccc2582dc6f9c322c852a775a27065ff2b0c4970b9d53d01b3"}, +] + +[[package]] +name = "docutils" +version = "0.19" +requires_python = ">=3.7" +summary = "Docutils -- Python Documentation Utilities" +groups = ["default"] +files = [ + {file = "docutils-0.19-py3-none-any.whl", hash = "sha256:5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc"}, + {file = "docutils-0.19.tar.gz", hash = "sha256:33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6"}, +] + +[[package]] +name = "exceptiongroup" +version = "1.2.0" +requires_python = ">=3.7" +summary = "Backport of PEP 654 (exception groups)" +groups = ["dev"] +marker = "python_version < \"3.11\"" +files = [ + {file = "exceptiongroup-1.2.0-py3-none-any.whl", hash = "sha256:4bfd3996ac73b41e9b9628b04e079f193850720ea5945fc96a08633c66912f14"}, + {file = "exceptiongroup-1.2.0.tar.gz", hash = "sha256:91f5c769735f051a4290d52edd0858999b57e5876e9f85937691bd4c9fa3ed68"}, +] + +[[package]] +name = "executing" +version = "2.0.1" +requires_python = ">=3.5" +summary = "Get the currently executing AST node of a frame, and other information" +groups = ["dev"] +files = [ + {file = "executing-2.0.1-py2.py3-none-any.whl", hash = "sha256:eac49ca94516ccc753f9fb5ce82603156e590b27525a8bc32cce8ae302eb61bc"}, + {file = "executing-2.0.1.tar.gz", hash = "sha256:35afe2ce3affba8ee97f2d69927fa823b08b472b7b994e36a52a964b93d16147"}, +] + +[[package]] +name = "fastjsonschema" +version = "2.19.1" +summary = "Fastest Python implementation of JSON schema" +groups = ["default"] +files = [ + {file = "fastjsonschema-2.19.1-py3-none-any.whl", hash = "sha256:3672b47bc94178c9f23dbb654bf47440155d4db9df5f7bc47643315f9c405cd0"}, + {file = "fastjsonschema-2.19.1.tar.gz", hash = "sha256:e3126a94bdc4623d3de4485f8d468a12f02a67921315ddc87836d6e456dc789d"}, +] + +[[package]] +name = "gitdb" +version = "4.0.11" +requires_python = ">=3.7" +summary = "Git Object Database" +groups = ["default"] +dependencies = [ + "smmap<6,>=3.0.1", +] +files = [ + {file = "gitdb-4.0.11-py3-none-any.whl", hash = "sha256:81a3407ddd2ee8df444cbacea00e2d038e40150acfa3001696fe0dcf1d3adfa4"}, + {file = "gitdb-4.0.11.tar.gz", hash = "sha256:bf5421126136d6d0af55bc1e7c1af1c397a34f5b7bd79e776cd3e89785c2b04b"}, +] + +[[package]] +name = "gitpython" +version = "3.1.42" +requires_python = ">=3.7" +summary = "GitPython is a Python library used to interact with Git repositories" +groups = ["default"] +dependencies = [ + "gitdb<5,>=4.0.1", +] +files = [ + {file = "GitPython-3.1.42-py3-none-any.whl", hash = "sha256:1bf9cd7c9e7255f77778ea54359e54ac22a72a5b51288c457c881057b7bb9ecd"}, + {file = "GitPython-3.1.42.tar.gz", hash = "sha256:2d99869e0fef71a73cbd242528105af1d6c1b108c60dfabd994bf292f76c3ceb"}, +] + +[[package]] +name = "idna" +version = "3.6" +requires_python = ">=3.5" +summary = "Internationalized Domain Names in Applications (IDNA)" +groups = ["default"] +files = [ + {file = "idna-3.6-py3-none-any.whl", hash = "sha256:c05567e9c24a6b9faaa835c4821bad0590fbb9d5779e7caa6e1cc4978e7eb24f"}, + {file = "idna-3.6.tar.gz", hash = "sha256:9ecdbbd083b06798ae1e86adcbfe8ab1479cf864e4ee30fe4e46a003d12491ca"}, +] + +[[package]] +name = "imagesize" +version = "1.4.1" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +summary = "Getting image size from png/jpeg/jpeg2000/gif file" +groups = ["default"] +files = [ + {file = "imagesize-1.4.1-py2.py3-none-any.whl", hash = "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b"}, + {file = "imagesize-1.4.1.tar.gz", hash = "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a"}, +] + +[[package]] +name = "invoke" +version = "2.2.0" +requires_python = ">=3.6" +summary = "Pythonic task execution" +groups = ["dev"] +files = [ + {file = "invoke-2.2.0-py3-none-any.whl", hash = "sha256:6ea924cc53d4f78e3d98bc436b08069a03077e6f85ad1ddaa8a116d7dad15820"}, + {file = "invoke-2.2.0.tar.gz", hash = "sha256:ee6cbb101af1a859c7fe84f2a264c059020b0cb7fe3535f9424300ab568f6bd5"}, +] + +[[package]] +name = "ipdb" +version = "0.13.13" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +summary = "IPython-enabled pdb" +groups = ["dev"] +dependencies = [ + "decorator; python_version > \"3.6\" and python_version < \"3.11\"", + "ipython>=7.31.1; python_version > \"3.6\" and python_version < \"3.11\"", + "tomli; python_version > \"3.6\" and python_version < \"3.11\"", +] +files = [ + {file = "ipdb-0.13.13-py3-none-any.whl", hash = "sha256:45529994741c4ab6d2388bfa5d7b725c2cf7fe9deffabdb8a6113aa5ed449ed4"}, + {file = "ipdb-0.13.13.tar.gz", hash = "sha256:e3ac6018ef05126d442af680aad863006ec19d02290561ac88b8b1c0b0cfc726"}, +] + +[[package]] +name = "ipython" +version = "8.22.2" +requires_python = ">=3.10" +summary = "IPython: Productive Interactive Computing" +groups = ["dev"] +dependencies = [ + "colorama; sys_platform == \"win32\"", + "decorator", + "exceptiongroup; python_version < \"3.11\"", + "jedi>=0.16", + "matplotlib-inline", + "pexpect>4.3; sys_platform != \"win32\" and sys_platform != \"emscripten\"", + "prompt-toolkit<3.1.0,>=3.0.41", + "pygments>=2.4.0", + "stack-data", + "traitlets>=5.13.0", +] +files = [ + {file = "ipython-8.22.2-py3-none-any.whl", hash = "sha256:3c86f284c8f3d8f2b6c662f885c4889a91df7cd52056fd02b7d8d6195d7f56e9"}, + {file = "ipython-8.22.2.tar.gz", hash = "sha256:2dcaad9049f9056f1fef63514f176c7d41f930daa78d05b82a176202818f2c14"}, +] + +[[package]] +name = "jedi" +version = "0.19.1" +requires_python = ">=3.6" +summary = "An autocompletion tool for Python that can be used for text editors." +groups = ["dev"] +dependencies = [ + "parso<0.9.0,>=0.8.3", +] +files = [ + {file = "jedi-0.19.1-py2.py3-none-any.whl", hash = "sha256:e983c654fe5c02867aef4cdfce5a2fbb4a50adc0af145f70504238f18ef5e7e0"}, + {file = "jedi-0.19.1.tar.gz", hash = "sha256:cf0496f3651bc65d7174ac1b7d043eff454892c708a87d1b683e57b569927ffd"}, +] + +[[package]] +name = "jinja2" +version = "3.1.3" +requires_python = ">=3.7" +summary = "A very fast and expressive template engine." +groups = ["default"] +dependencies = [ + "MarkupSafe>=2.0", +] +files = [ + {file = "Jinja2-3.1.3-py3-none-any.whl", hash = "sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa"}, + {file = "Jinja2-3.1.3.tar.gz", hash = "sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90"}, +] + +[[package]] +name = "markdown-it-py" +version = "2.2.0" +requires_python = ">=3.7" +summary = "Python port of markdown-it. Markdown parsing, done right!" +groups = ["default"] +dependencies = [ + "mdurl~=0.1", +] +files = [ + {file = "markdown-it-py-2.2.0.tar.gz", hash = "sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1"}, + {file = "markdown_it_py-2.2.0-py3-none-any.whl", hash = "sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30"}, +] + +[[package]] +name = "markupsafe" +version = "2.1.5" +requires_python = ">=3.7" +summary = "Safely add untrusted strings to HTML/XML markup." +groups = ["default"] +files = [ + {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:a17a92de5231666cfbe003f0e4b9b3a7ae3afb1ec2845aadc2bacc93ff85febc"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:72b6be590cc35924b02c78ef34b467da4ba07e4e0f0454a2c5907f473fc50ce5"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e61659ba32cf2cf1481e575d0462554625196a1f2fc06a1c777d3f48e8865d46"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2174c595a0d73a3080ca3257b40096db99799265e1c27cc5a610743acd86d62f"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ae2ad8ae6ebee9d2d94b17fb62763125f3f374c25618198f40cbb8b525411900"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:075202fa5b72c86ad32dc7d0b56024ebdbcf2048c0ba09f1cde31bfdd57bcfff"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:598e3276b64aff0e7b3451b72e94fa3c238d452e7ddcd893c3ab324717456bad"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:fce659a462a1be54d2ffcacea5e3ba2d74daa74f30f5f143fe0c58636e355fdd"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-win32.whl", hash = "sha256:d9fad5155d72433c921b782e58892377c44bd6252b5af2f67f16b194987338a4"}, + {file = "MarkupSafe-2.1.5-cp310-cp310-win_amd64.whl", hash = "sha256:bf50cd79a75d181c9181df03572cdce0fbb75cc353bc350712073108cba98de5"}, + {file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"}, +] + +[[package]] +name = "matplotlib-inline" +version = "0.1.6" +requires_python = ">=3.5" +summary = "Inline Matplotlib backend for Jupyter" +groups = ["dev"] +dependencies = [ + "traitlets", +] +files = [ + {file = "matplotlib-inline-0.1.6.tar.gz", hash = "sha256:f887e5f10ba98e8d2b150ddcf4702c1e5f8b3a20005eb0f74bfdbd360ee6f304"}, + {file = "matplotlib_inline-0.1.6-py3-none-any.whl", hash = "sha256:f1f41aab5328aa5aaea9b16d083b128102f8712542f819fe7e6a420ff581b311"}, +] + +[[package]] +name = "mdit-py-plugins" +version = "0.3.5" +requires_python = ">=3.7" +summary = "Collection of plugins for markdown-it-py" +groups = ["default"] +dependencies = [ + "markdown-it-py<3.0.0,>=1.0.0", +] +files = [ + {file = "mdit-py-plugins-0.3.5.tar.gz", hash = "sha256:eee0adc7195e5827e17e02d2a258a2ba159944a0748f59c5099a4a27f78fcf6a"}, + {file = "mdit_py_plugins-0.3.5-py3-none-any.whl", hash = "sha256:ca9a0714ea59a24b2b044a1831f48d817dd0c817e84339f20e7889f392d77c4e"}, +] + +[[package]] +name = "mdurl" +version = "0.1.2" +requires_python = ">=3.7" +summary = "Markdown URL utilities" +groups = ["default"] +files = [ + {file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"}, + {file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"}, +] + +[[package]] +name = "myst-parser" +version = "1.0.0" +requires_python = ">=3.7" +summary = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +groups = ["default"] +dependencies = [ + "docutils<0.20,>=0.15", + "jinja2", + "markdown-it-py<3.0.0,>=1.0.0", + "mdit-py-plugins~=0.3.4", + "pyyaml", + "sphinx<7,>=5", +] +files = [ + {file = "myst-parser-1.0.0.tar.gz", hash = "sha256:502845659313099542bd38a2ae62f01360e7dd4b1310f025dd014dfc0439cdae"}, + {file = "myst_parser-1.0.0-py3-none-any.whl", hash = "sha256:69fb40a586c6fa68995e6521ac0a525793935db7e724ca9bac1d33be51be9a4c"}, +] + +[[package]] +name = "packaging" +version = "23.2" +requires_python = ">=3.7" +summary = "Core utilities for Python packages" +groups = ["default"] +files = [ + {file = "packaging-23.2-py3-none-any.whl", hash = "sha256:8c491190033a9af7e1d931d0b5dacc2ef47509b34dd0de67ed209b5203fc88c7"}, + {file = "packaging-23.2.tar.gz", hash = "sha256:048fb0e9405036518eaaf48a55953c750c11e1a1b68e0dd1a9d62ed0c092cfc5"}, +] + +[[package]] +name = "parso" +version = "0.8.3" +requires_python = ">=3.6" +summary = "A Python Parser" +groups = ["dev"] +files = [ + {file = "parso-0.8.3-py2.py3-none-any.whl", hash = "sha256:c001d4636cd3aecdaf33cbb40aebb59b094be2a74c556778ef5576c175e19e75"}, + {file = "parso-0.8.3.tar.gz", hash = "sha256:8c07be290bb59f03588915921e29e8a50002acaf2cdc5fa0e0114f91709fafa0"}, +] + +[[package]] +name = "pexpect" +version = "4.9.0" +summary = "Pexpect allows easy control of interactive console applications." +groups = ["dev"] +marker = "sys_platform != \"win32\" and sys_platform != \"emscripten\"" +dependencies = [ + "ptyprocess>=0.5", +] +files = [ + {file = "pexpect-4.9.0-py2.py3-none-any.whl", hash = "sha256:7236d1e080e4936be2dc3e326cec0af72acf9212a7e1d060210e70a47e253523"}, + {file = "pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f"}, +] + +[[package]] +name = "prompt-toolkit" +version = "3.0.43" +requires_python = ">=3.7.0" +summary = "Library for building powerful interactive command lines in Python" +groups = ["dev"] +dependencies = [ + "wcwidth", +] +files = [ + {file = "prompt_toolkit-3.0.43-py3-none-any.whl", hash = "sha256:a11a29cb3bf0a28a387fe5122cdb649816a957cd9261dcedf8c9f1fef33eacf6"}, + {file = "prompt_toolkit-3.0.43.tar.gz", hash = "sha256:3527b7af26106cbc65a040bcc84839a3566ec1b051bb0bfe953631e704b0ff7d"}, +] + +[[package]] +name = "ptyprocess" +version = "0.7.0" +summary = "Run a subprocess in a pseudo terminal" +groups = ["dev"] +marker = "sys_platform != \"win32\" and sys_platform != \"emscripten\"" +files = [ + {file = "ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35"}, + {file = "ptyprocess-0.7.0.tar.gz", hash = "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"}, +] + +[[package]] +name = "pure-eval" +version = "0.2.2" +summary = "Safely evaluate AST nodes without side effects" +groups = ["dev"] +files = [ + {file = "pure_eval-0.2.2-py3-none-any.whl", hash = "sha256:01eaab343580944bc56080ebe0a674b39ec44a945e6d09ba7db3cb8cec289350"}, + {file = "pure_eval-0.2.2.tar.gz", hash = "sha256:2b45320af6dfaa1750f543d714b6d1c520a1688dec6fd24d339063ce0aaa9ac3"}, +] + +[[package]] +name = "pycparser" +version = "2.21" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +summary = "C parser in Python" +groups = ["default"] +files = [ + {file = "pycparser-2.21-py2.py3-none-any.whl", hash = "sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9"}, + {file = "pycparser-2.21.tar.gz", hash = "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"}, +] + +[[package]] +name = "pydata-sphinx-theme" +version = "0.15.2" +requires_python = ">=3.9" +summary = "Bootstrap-based Sphinx theme from the PyData community" +groups = ["default"] +dependencies = [ + "Babel", + "accessible-pygments", + "beautifulsoup4", + "docutils!=0.17.0", + "packaging", + "pygments>=2.7", + "sphinx>=5.0", + "typing-extensions", +] +files = [ + {file = "pydata_sphinx_theme-0.15.2-py3-none-any.whl", hash = "sha256:0c5fa1fa98a9b26dae590666ff576f27e26c7ba708fee754ecb9e07359ed4588"}, + {file = "pydata_sphinx_theme-0.15.2.tar.gz", hash = "sha256:4243fee85b3afcfae9df64f83210a04e7182e53bc3db8841ffff6d21d95ae320"}, +] + +[[package]] +name = "pygithub" +version = "2.2.0" +requires_python = ">=3.7" +summary = "Use the full Github API v3" +groups = ["default"] +dependencies = [ + "Deprecated", + "pyjwt[crypto]>=2.4.0", + "pynacl>=1.4.0", + "requests>=2.14.0", + "typing-extensions>=4.0.0", + "urllib3>=1.26.0", +] +files = [ + {file = "PyGithub-2.2.0-py3-none-any.whl", hash = "sha256:41042ea53e4c372219db708c38d2ca1fd4fadab75475bac27d89d339596cfad1"}, + {file = "PyGithub-2.2.0.tar.gz", hash = "sha256:e39be7c4dc39418bdd6e3ecab5931c636170b8b21b4d26f9ecf7e6102a3b51c3"}, +] + +[[package]] +name = "pygments" +version = "2.17.2" +requires_python = ">=3.7" +summary = "Pygments is a syntax highlighting package written in Python." +groups = ["default", "dev"] +files = [ + {file = "pygments-2.17.2-py3-none-any.whl", hash = "sha256:b27c2826c47d0f3219f29554824c30c5e8945175d888647acd804ddd04af846c"}, + {file = "pygments-2.17.2.tar.gz", hash = "sha256:da46cec9fd2de5be3a8a784f434e4c4ab670b4ff54d605c4c2717e9d49c4c367"}, +] + +[[package]] +name = "pyjwt" +version = "2.8.0" +requires_python = ">=3.7" +summary = "JSON Web Token implementation in Python" +groups = ["default"] +files = [ + {file = "PyJWT-2.8.0-py3-none-any.whl", hash = "sha256:59127c392cc44c2da5bb3192169a91f429924e17aff6534d70fdc02ab3e04320"}, + {file = "PyJWT-2.8.0.tar.gz", hash = "sha256:57e28d156e3d5c10088e0c68abb90bfac3df82b40a71bd0daa20c65ccd5c23de"}, +] + +[[package]] +name = "pyjwt" +version = "2.8.0" +extras = ["crypto"] +requires_python = ">=3.7" +summary = "JSON Web Token implementation in Python" +groups = ["default"] +dependencies = [ + "cryptography>=3.4.0", + "pyjwt==2.8.0", +] +files = [ + {file = "PyJWT-2.8.0-py3-none-any.whl", hash = "sha256:59127c392cc44c2da5bb3192169a91f429924e17aff6534d70fdc02ab3e04320"}, + {file = "PyJWT-2.8.0.tar.gz", hash = "sha256:57e28d156e3d5c10088e0c68abb90bfac3df82b40a71bd0daa20c65ccd5c23de"}, +] + +[[package]] +name = "pynacl" +version = "1.5.0" +requires_python = ">=3.6" +summary = "Python binding to the Networking and Cryptography (NaCl) library" +groups = ["default"] +dependencies = [ + "cffi>=1.4.1", +] +files = [ + {file = "PyNaCl-1.5.0-cp36-abi3-macosx_10_10_universal2.whl", hash = "sha256:401002a4aaa07c9414132aaed7f6836ff98f59277a234704ff66878c2ee4a0d1"}, + {file = "PyNaCl-1.5.0-cp36-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl", hash = "sha256:52cb72a79269189d4e0dc537556f4740f7f0a9ec41c1322598799b0bdad4ef92"}, + {file = "PyNaCl-1.5.0-cp36-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a36d4a9dda1f19ce6e03c9a784a2921a4b726b02e1c736600ca9c22029474394"}, + {file = "PyNaCl-1.5.0-cp36-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:0c84947a22519e013607c9be43706dd42513f9e6ae5d39d3613ca1e142fba44d"}, + {file = "PyNaCl-1.5.0-cp36-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:06b8f6fa7f5de8d5d2f7573fe8c863c051225a27b61e6860fd047b1775807858"}, + {file = "PyNaCl-1.5.0-cp36-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:a422368fc821589c228f4c49438a368831cb5bbc0eab5ebe1d7fac9dded6567b"}, + {file = "PyNaCl-1.5.0-cp36-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:61f642bf2378713e2c2e1de73444a3778e5f0a38be6fee0fe532fe30060282ff"}, + {file = "PyNaCl-1.5.0-cp36-abi3-win32.whl", hash = "sha256:e46dae94e34b085175f8abb3b0aaa7da40767865ac82c928eeb9e57e1ea8a543"}, + {file = "PyNaCl-1.5.0-cp36-abi3-win_amd64.whl", hash = "sha256:20f42270d27e1b6a29f54032090b972d97f0a1b0948cc52392041ef7831fee93"}, + {file = "PyNaCl-1.5.0.tar.gz", hash = "sha256:8ac7448f09ab85811607bdd21ec2464495ac8b7c66d146bf545b0f08fb9220ba"}, +] + +[[package]] +name = "pyyaml" +version = "6.0.1" +requires_python = ">=3.6" +summary = "YAML parser and emitter for Python" +groups = ["default"] +files = [ + {file = "PyYAML-6.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d858aa552c999bc8a8d57426ed01e40bef403cd8ccdd0fc5f6f04a00414cac2a"}, + {file = "PyYAML-6.0.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:fd66fc5d0da6d9815ba2cebeb4205f95818ff4b79c3ebe268e75d961704af52f"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"}, + {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"}, + {file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"}, + {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"}, + {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"}, + {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, +] + +[[package]] +name = "requests" +version = "2.31.0" +requires_python = ">=3.7" +summary = "Python HTTP for Humans." +groups = ["default"] +dependencies = [ + "certifi>=2017.4.17", + "charset-normalizer<4,>=2", + "idna<4,>=2.5", + "urllib3<3,>=1.21.1", +] +files = [ + {file = "requests-2.31.0-py3-none-any.whl", hash = "sha256:58cd2187c01e70e6e26505bca751777aa9f2ee0b7f4300988b709f44e013003f"}, + {file = "requests-2.31.0.tar.gz", hash = "sha256:942c5a758f98d790eaed1a29cb6eefc7ffb0d1cf7af05c3d2791656dbd6ad1e1"}, +] + +[[package]] +name = "rocm-docs-core" +version = "0.35.0" +requires_python = ">=3.8" +summary = "Core utilities for all ROCm documentation on RTD" +groups = ["default"] +dependencies = [ + "GitPython>=3.1.30", + "PyGithub>=1.58.1", + "breathe>=4.34.0", + "fastjsonschema>=2.16", + "myst-parser>=1.0.0", + "pydata-sphinx-theme>=0.13.3", + "pyyaml>=6.0", + "sphinx-book-theme>=1.0.1", + "sphinx-copybutton>=0.5.1", + "sphinx-design>=0.3.0", + "sphinx-external-toc>=0.3.1", + "sphinx-notfound-page>=0.8.3", + "sphinx>=5.3.0", +] +files = [ + {file = "rocm-docs-core-0.35.0.tar.gz", hash = "sha256:38949ca6a1ba773283013974f74b97fa992c4a6987c70305c7d2491d216ccc45"}, + {file = "rocm_docs_core-0.35.0-py3-none-any.whl", hash = "sha256:304bc05073d75df1b95a2df54c08ce39ddbb7a8fd9618c8096c07a15591a8f37"}, +] + +[[package]] +name = "six" +version = "1.16.0" +requires_python = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*" +summary = "Python 2 and 3 compatibility utilities" +groups = ["dev"] +files = [ + {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"}, + {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"}, +] + +[[package]] +name = "smmap" +version = "5.0.1" +requires_python = ">=3.7" +summary = "A pure Python implementation of a sliding window memory map manager" +groups = ["default"] +files = [ + {file = "smmap-5.0.1-py3-none-any.whl", hash = "sha256:e6d8668fa5f93e706934a62d7b4db19c8d9eb8cf2adbb75ef1b675aa332b69da"}, + {file = "smmap-5.0.1.tar.gz", hash = "sha256:dceeb6c0028fdb6734471eb07c0cd2aae706ccaecab45965ee83f11c8d3b1f62"}, +] + +[[package]] +name = "snowballstemmer" +version = "2.2.0" +summary = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms." +groups = ["default"] +files = [ + {file = "snowballstemmer-2.2.0-py2.py3-none-any.whl", hash = "sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a"}, + {file = "snowballstemmer-2.2.0.tar.gz", hash = "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1"}, +] + +[[package]] +name = "soupsieve" +version = "2.5" +requires_python = ">=3.8" +summary = "A modern CSS selector implementation for Beautiful Soup." +groups = ["default"] +files = [ + {file = "soupsieve-2.5-py3-none-any.whl", hash = "sha256:eaa337ff55a1579b6549dc679565eac1e3d000563bcb1c8ab0d0fefbc0c2cdc7"}, + {file = "soupsieve-2.5.tar.gz", hash = "sha256:5663d5a7b3bfaeee0bc4372e7fc48f9cff4940b3eec54a6451cc5299f1097690"}, +] + +[[package]] +name = "sphinx" +version = "5.3.0" +requires_python = ">=3.6" +summary = "Python documentation generator" +groups = ["default"] +dependencies = [ + "Jinja2>=3.0", + "Pygments>=2.12", + "alabaster<0.8,>=0.7", + "babel>=2.9", + "colorama>=0.4.5; sys_platform == \"win32\"", + "docutils<0.20,>=0.14", + "imagesize>=1.3", + "packaging>=21.0", + "requests>=2.5.0", + "snowballstemmer>=2.0", + "sphinxcontrib-applehelp", + "sphinxcontrib-devhelp", + "sphinxcontrib-htmlhelp>=2.0.0", + "sphinxcontrib-jsmath", + "sphinxcontrib-qthelp", + "sphinxcontrib-serializinghtml>=1.1.5", +] +files = [ + {file = "Sphinx-5.3.0.tar.gz", hash = "sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5"}, + {file = "sphinx-5.3.0-py3-none-any.whl", hash = "sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d"}, +] + +[[package]] +name = "sphinx-book-theme" +version = "1.1.2" +requires_python = ">=3.9" +summary = "A clean book theme for scientific explanations and documentation with Sphinx" +groups = ["default"] +dependencies = [ + "pydata-sphinx-theme>=0.14", + "sphinx>=5", +] +files = [ + {file = "sphinx_book_theme-1.1.2-py3-none-any.whl", hash = "sha256:cee744466fde48f50302b851291b208aa67e726ca31b7a3bfb9b6e6a145663e0"}, + {file = "sphinx_book_theme-1.1.2.tar.gz", hash = "sha256:7f3abcd146ca82e6f39d6db53711102b1c1d328d12f65e3e47ad9bf842614a49"}, +] + +[[package]] +name = "sphinx-copybutton" +version = "0.5.2" +requires_python = ">=3.7" +summary = "Add a copy button to each of your code cells." +groups = ["default"] +dependencies = [ + "sphinx>=1.8", +] +files = [ + {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"}, + {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"}, +] + +[[package]] +name = "sphinx-design" +version = "0.5.0" +requires_python = ">=3.8" +summary = "A sphinx extension for designing beautiful, view size responsive web components." +groups = ["default"] +dependencies = [ + "sphinx<8,>=5", +] +files = [ + {file = "sphinx_design-0.5.0-py3-none-any.whl", hash = "sha256:1af1267b4cea2eedd6724614f19dcc88fe2e15aff65d06b2f6252cee9c4f4c1e"}, + {file = "sphinx_design-0.5.0.tar.gz", hash = "sha256:e8e513acea6f92d15c6de3b34e954458f245b8e761b45b63950f65373352ab00"}, +] + +[[package]] +name = "sphinx-external-toc" +version = "1.0.1" +requires_python = ">=3.9" +summary = "A sphinx extension that allows the site-map to be defined in a single YAML file." +groups = ["default"] +dependencies = [ + "click>=7.1", + "pyyaml", + "sphinx>=5", +] +files = [ + {file = "sphinx_external_toc-1.0.1-py3-none-any.whl", hash = "sha256:d9e02d50731dee9697c1887e4f8b361e7b86d38241f0e66bd5a9f4096779646f"}, + {file = "sphinx_external_toc-1.0.1.tar.gz", hash = "sha256:a7d2c63cc47ec688546443b28bc4ef466121827ef3dc7bb509de354bad4ea2e0"}, +] + +[[package]] +name = "sphinx-notfound-page" +version = "1.0.0" +requires_python = ">=3.8" +summary = "Sphinx extension to build a 404 page with absolute URLs" +groups = ["default"] +dependencies = [ + "sphinx>=5", +] +files = [ + {file = "sphinx_notfound_page-1.0.0-py3-none-any.whl", hash = "sha256:40a5741a6b07245a08fe55dbbd603ad6719e191b1419ab2e5337c706ebd16554"}, + {file = "sphinx_notfound_page-1.0.0.tar.gz", hash = "sha256:14cd388956de5cdf8710ab4ff31776ef8d85759c4f46014ee30f368e83bd3a3b"}, +] + +[[package]] +name = "sphinx-substitution-extensions" +version = "2022.2.16" +summary = "Extensions for Sphinx which allow for substitutions." +groups = ["default"] +dependencies = [ + "docutils>=0.15", + "sphinx>=4.0.0", +] +files = [ + {file = "Sphinx_Substitution_Extensions-2022.2.16-py3-none-any.whl", hash = "sha256:5a8ca34dac3984486344e95c36e3ed4766d402a71bdee7390d600f153db9795b"}, +] + +[[package]] +name = "sphinxcontrib-applehelp" +version = "1.0.8" +requires_python = ">=3.9" +summary = "sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books" +groups = ["default"] +files = [ + {file = "sphinxcontrib_applehelp-1.0.8-py3-none-any.whl", hash = "sha256:cb61eb0ec1b61f349e5cc36b2028e9e7ca765be05e49641c97241274753067b4"}, + {file = "sphinxcontrib_applehelp-1.0.8.tar.gz", hash = "sha256:c40a4f96f3776c4393d933412053962fac2b84f4c99a7982ba42e09576a70619"}, +] + +[[package]] +name = "sphinxcontrib-datatemplates" +version = "0.11.0" +requires_python = ">=3.8" +summary = "Sphinx extension for rendering data files as nice HTML" +groups = ["default"] +dependencies = [ + "PyYAML", + "Sphinx", + "defusedxml", + "sphinxcontrib-runcmd", +] +files = [ + {file = "sphinxcontrib.datatemplates-0.11.0-py3-none-any.whl", hash = "sha256:88d02f5edab32b88211ebb72a90553e3676a5737877bad1de412f84058ac282e"}, + {file = "sphinxcontrib.datatemplates-0.11.0.tar.gz", hash = "sha256:793222e803430076341509cc167f8d715830b05e418c885313101d60fd442557"}, +] + +[[package]] +name = "sphinxcontrib-devhelp" +version = "1.0.6" +requires_python = ">=3.9" +summary = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp documents" +groups = ["default"] +files = [ + {file = "sphinxcontrib_devhelp-1.0.6-py3-none-any.whl", hash = "sha256:6485d09629944511c893fa11355bda18b742b83a2b181f9a009f7e500595c90f"}, + {file = "sphinxcontrib_devhelp-1.0.6.tar.gz", hash = "sha256:9893fd3f90506bc4b97bdb977ceb8fbd823989f4316b28c3841ec128544372d3"}, +] + +[[package]] +name = "sphinxcontrib-htmlhelp" +version = "2.0.5" +requires_python = ">=3.9" +summary = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files" +groups = ["default"] +files = [ + {file = "sphinxcontrib_htmlhelp-2.0.5-py3-none-any.whl", hash = "sha256:393f04f112b4d2f53d93448d4bce35842f62b307ccdc549ec1585e950bc35e04"}, + {file = "sphinxcontrib_htmlhelp-2.0.5.tar.gz", hash = "sha256:0dc87637d5de53dd5eec3a6a01753b1ccf99494bd756aafecd74b4fa9e729015"}, +] + +[[package]] +name = "sphinxcontrib-jsmath" +version = "1.0.1" +requires_python = ">=3.5" +summary = "A sphinx extension which renders display math in HTML via JavaScript" +groups = ["default"] +files = [ + {file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"}, + {file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"}, +] + +[[package]] +name = "sphinxcontrib-qthelp" +version = "1.0.7" +requires_python = ">=3.9" +summary = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp documents" +groups = ["default"] +files = [ + {file = "sphinxcontrib_qthelp-1.0.7-py3-none-any.whl", hash = "sha256:e2ae3b5c492d58fcbd73281fbd27e34b8393ec34a073c792642cd8e529288182"}, + {file = "sphinxcontrib_qthelp-1.0.7.tar.gz", hash = "sha256:053dedc38823a80a7209a80860b16b722e9e0209e32fea98c90e4e6624588ed6"}, +] + +[[package]] +name = "sphinxcontrib-runcmd" +version = "0.2.0" +summary = "Sphinx \"runcmd\" extension" +groups = ["default"] +dependencies = [ + "sphinx", +] +files = [ + {file = "sphinxcontrib-runcmd-0.2.0.tar.gz", hash = "sha256:3551c389d9c5fe82d693c7222feb9658b1a1a5a1abcb0063e8385e5528c64c76"}, + {file = "sphinxcontrib_runcmd-0.2.0-py2.py3-none-any.whl", hash = "sha256:7b739b68e27210b4c7c12ba16e5b3da7b313c49991401f896d29bea0f0771934"}, +] + +[[package]] +name = "sphinxcontrib-serializinghtml" +version = "1.1.10" +requires_python = ">=3.9" +summary = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)" +groups = ["default"] +files = [ + {file = "sphinxcontrib_serializinghtml-1.1.10-py3-none-any.whl", hash = "sha256:326369b8df80a7d2d8d7f99aa5ac577f51ea51556ed974e7716cfd4fca3f6cb7"}, + {file = "sphinxcontrib_serializinghtml-1.1.10.tar.gz", hash = "sha256:93f3f5dc458b91b192fe10c397e324f262cf163d79f3282c158e8436a2c4511f"}, +] + +[[package]] +name = "stack-data" +version = "0.6.3" +summary = "Extract data from python stack frames and tracebacks for informative displays" +groups = ["dev"] +dependencies = [ + "asttokens>=2.1.0", + "executing>=1.2.0", + "pure-eval", +] +files = [ + {file = "stack_data-0.6.3-py3-none-any.whl", hash = "sha256:d5558e0c25a4cb0853cddad3d77da9891a08cb85dd9f9f91b9f8cd66e511e695"}, + {file = "stack_data-0.6.3.tar.gz", hash = "sha256:836a778de4fec4dcd1dcd89ed8abff8a221f58308462e1c4aa2a3cf30148f0b9"}, +] + +[[package]] +name = "tomli" +version = "2.0.1" +requires_python = ">=3.7" +summary = "A lil' TOML parser" +groups = ["dev"] +marker = "python_version > \"3.6\" and python_version < \"3.11\"" +files = [ + {file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"}, + {file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"}, +] + +[[package]] +name = "traitlets" +version = "5.14.1" +requires_python = ">=3.8" +summary = "Traitlets Python configuration system" +groups = ["dev"] +files = [ + {file = "traitlets-5.14.1-py3-none-any.whl", hash = "sha256:2e5a030e6eff91737c643231bfcf04a65b0132078dad75e4936700b213652e74"}, + {file = "traitlets-5.14.1.tar.gz", hash = "sha256:8585105b371a04b8316a43d5ce29c098575c2e477850b62b848b964f1444527e"}, +] + +[[package]] +name = "typing-extensions" +version = "4.10.0" +requires_python = ">=3.8" +summary = "Backported and Experimental Type Hints for Python 3.8+" +groups = ["default"] +files = [ + {file = "typing_extensions-4.10.0-py3-none-any.whl", hash = "sha256:69b1a937c3a517342112fb4c6df7e72fc39a38e7891a5730ed4985b5214b5475"}, + {file = "typing_extensions-4.10.0.tar.gz", hash = "sha256:b0abd7c89e8fb96f98db18d86106ff1d90ab692004eb746cf6eda2682f91b3cb"}, +] + +[[package]] +name = "urllib3" +version = "2.2.1" +requires_python = ">=3.8" +summary = "HTTP library with thread-safe connection pooling, file post, and more." +groups = ["default"] +files = [ + {file = "urllib3-2.2.1-py3-none-any.whl", hash = "sha256:450b20ec296a467077128bff42b73080516e71b56ff59a60a02bef2232c4fa9d"}, + {file = "urllib3-2.2.1.tar.gz", hash = "sha256:d0570876c61ab9e520d776c38acbbb5b05a776d3f9ff98a5c8fd5162a444cf19"}, +] + +[[package]] +name = "wcwidth" +version = "0.2.13" +summary = "Measures the displayed width of unicode strings in a terminal" +groups = ["dev"] +files = [ + {file = "wcwidth-0.2.13-py2.py3-none-any.whl", hash = "sha256:3da69048e4540d84af32131829ff948f1e022c1c6bdb8d6102117aac784f6859"}, + {file = "wcwidth-0.2.13.tar.gz", hash = "sha256:72ea0c06399eb286d978fdedb6923a9eb47e1c486ce63e9b4e64fc18303972b5"}, +] + +[[package]] +name = "wrapt" +version = "1.16.0" +requires_python = ">=3.6" +summary = "Module for decorators, wrappers and monkey patching." +groups = ["default"] +files = [ + {file = "wrapt-1.16.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:ffa565331890b90056c01db69c0fe634a776f8019c143a5ae265f9c6bc4bd6d4"}, + {file = "wrapt-1.16.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:e4fdb9275308292e880dcbeb12546df7f3e0f96c6b41197e0cf37d2826359020"}, + {file = "wrapt-1.16.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bb2dee3874a500de01c93d5c71415fcaef1d858370d405824783e7a8ef5db440"}, + {file = "wrapt-1.16.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2a88e6010048489cda82b1326889ec075a8c856c2e6a256072b28eaee3ccf487"}, + {file = "wrapt-1.16.0-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac83a914ebaf589b69f7d0a1277602ff494e21f4c2f743313414378f8f50a4cf"}, + {file = "wrapt-1.16.0-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:73aa7d98215d39b8455f103de64391cb79dfcad601701a3aa0dddacf74911d72"}, + {file = "wrapt-1.16.0-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:807cc8543a477ab7422f1120a217054f958a66ef7314f76dd9e77d3f02cdccd0"}, + {file = "wrapt-1.16.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:bf5703fdeb350e36885f2875d853ce13172ae281c56e509f4e6eca049bdfb136"}, + {file = "wrapt-1.16.0-cp310-cp310-win32.whl", hash = "sha256:f6b2d0c6703c988d334f297aa5df18c45e97b0af3679bb75059e0e0bd8b1069d"}, + {file = "wrapt-1.16.0-cp310-cp310-win_amd64.whl", hash = "sha256:decbfa2f618fa8ed81c95ee18a387ff973143c656ef800c9f24fb7e9c16054e2"}, + {file = "wrapt-1.16.0-py3-none-any.whl", hash = "sha256:6906c4100a8fcbf2fa735f6059214bb13b97f75b1a61777fcf6432121ef12ef1"}, + {file = "wrapt-1.16.0.tar.gz", hash = "sha256:5f370f952971e7d17c7d1ead40e49f32345a7f7a5373571ef44d800d06b1899d"}, +] diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..b2438226 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,27 @@ +[project] +name = "rocm-install-on-linux" +version = "0.1.0" +description = "Default template for PDM package" +authors = [ + {name = "Logan Grado", email = "logan.grado@amd.com"}, +] +dependencies = [ + "sphinx==5.3.0", + "rocm-docs-core==0.35.0", + "Sphinx-Substitution-Extensions==2022.2.16", + "sphinxcontrib-datatemplates==0.11.0", +] +requires-python = "==3.10.*" +readme = "README.md" +license = {text = "MIT"} + + +[tool.pdm] +distribution = false + +[tool.pdm.dev-dependencies] +dev = [ + "invoke>=2.2.0", + "ipython>=8.22.2", + "ipdb>=0.13.13", +] diff --git a/tasks.py b/tasks.py new file mode 100644 index 00000000..b9a6aaa0 --- /dev/null +++ b/tasks.py @@ -0,0 +1,42 @@ +#!/usr/bin/env python3 + +from invoke import task +from pathlib import Path + +SOURCE_DIR = Path(__file__).parent / "docs" +BUILD_DIR = SOURCE_DIR / "_build" + + +@task +def clean(c): + import shutil + + print(f"Removing build dir: {BUILD_DIR}") + if BUILD_DIR.exists(): + shutil.rmtree(BUILD_DIR) + + +@task +def build(c): + from sphinx.application import Sphinx + + build_dir_html = BUILD_DIR / "html" + build_dir_doctree = BUILD_DIR / "doctrees" + + conf_overrides = {"language": "en"} + + app = Sphinx( + str(SOURCE_DIR), + str(SOURCE_DIR), # Directory containing conf.py, typically the same as SOURCE_DIR + str(build_dir_html), # Output directory + str(build_dir_doctree), # Doctree directory + "html", # Builder name + conf_overrides, # Configuration overrides + freshenv=True, # Equivalent to -E option + warningiserror=False, # You can change this as needed + tags=[], # Tags can be used to conditionally include/exclude content + verbosity=0, # Increase verbosity (0 by default, increase for more messages) + ) + + # Build the project + app.build(force_all=True) # force_all is like the -a option, rebuild everything From e80406ca7627ede9a5ccb188e51b351c84624d13 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Mon, 11 Mar 2024 14:27:32 -0700 Subject: [PATCH 02/17] Fix pre-reqs formatting --- docs/how-to/prerequisites.rst | 63 ++++++++++++++++------------------- 1 file changed, 29 insertions(+), 34 deletions(-) diff --git a/docs/how-to/prerequisites.rst b/docs/how-to/prerequisites.rst index 0e7d1b42..343eb5b3 100644 --- a/docs/how-to/prerequisites.rst +++ b/docs/how-to/prerequisites.rst @@ -8,43 +8,41 @@ Installation prerequisites Before installing ROCm, complete the following prerequisites. -1. Confirm the system has a supported Linux version. +#. Confirm the system has a supported Linux version. - a. To obtain the Linux distribution information, type the following command on your system from - the Command Line Interface (CLI): + * To obtain the Linux distribution information, type the following command on your system from the Command Line Interface (CLI): - .. code-block:: shell + .. code-block:: shell - uname -m && cat /etc/*release + uname -m && cat /etc/*release - b. Confirm that your Linux distribution matches a - :ref:`supported distribution`. + * Confirm that your Linux distribution matches a :ref:`supported distribution`. - **Example:** Running the preceding command on an Ubuntu system produces the following output: + **Example:** Running the preceding command on an Ubuntu system produces the following output: - .. code-block:: shell + .. code-block:: shell - x86_64 - DISTRIB_ID=Ubuntu - DISTRIB_RELEASE=20.04 - DISTRIB_CODENAME=focal - DISTRIB_DESCRIPTION="Ubuntu 20.04.5 LTS" + x86_64 + DISTRIB_ID=Ubuntu + DISTRIB_RELEASE=20.04 + DISTRIB_CODENAME=focal + DISTRIB_DESCRIPTION="Ubuntu 20.04.5 LTS" -2. Verify the kernel version. +#. Verify the kernel version. - a. To check the kernel version of your Linux system, type the following command: + * To check the kernel version of your Linux system, type the following command: - .. code-block:: shell + .. code-block:: shell - uname -srmv + uname -srmv - **Example:** The preceding command lists the kernel version in the following format: + **Example:** The preceding command lists the kernel version in the following format: - .. code-block:: shell + .. code-block:: shell - Linux 5.15.0-46-generic #44~20.04.5-Ubuntu SMP Fri Jun 24 13:27:29 UTC 2022 x86_64 + Linux 5.15.0-46-generic #44~20.04.5-Ubuntu SMP Fri Jun 24 13:27:29 UTC 2022 x86_64 - b. Confirm that your kernel version matches the system requirements, as listed in :ref:`supported_distributions`. + * Confirm that your kernel version matches the system requirements, as listed in :ref:`supported_distributions`. Additional package repositories ========================================================== @@ -65,28 +63,25 @@ installation. Follow the instructions below based on your distributions. 1. Add the EPEL repository. - .. datatemplate:nodata:: + .. datatemplate:nodata:: - .. tab-set:: - {% for os_release in config.html_context['rhel_release_version_numbers'] %} - .. tab-item:: RHEL/OL {{ os_release }} + .. tab-set:: + {% for os_release in config.html_context['rhel_release_version_numbers'] %} + .. tab-item:: RHEL/OL {{ os_release }} - .. code-block:: shell + .. code-block:: shell - wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_release }}.noarch.rpm - sudo rpm -ivh epel-release-latest-{{ os_release }}.noarch.rpm - {% endfor %} + wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_release }}.noarch.rpm + sudo rpm -ivh epel-release-latest-{{ os_release }}.noarch.rpm + {% endfor %} 2. Enable the CodeReady Linux Builder (CRB) repository. - In order to enable CRB, you may need to install ``dnf-plugin-config-manager`` first. + In order to enable CRB, you may need to install ``dnf-plugin-config-manager`` first. .. code-block:: shell sudo dnf install dnf-plugin-config-manager - - .. code-block:: shell - sudo crb enable .. tab-item:: SUSE Linux Enterprise Server From cb4c9482a220c7defc60f9c74c6a5b15f065856c Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 14:11:12 -0700 Subject: [PATCH 03/17] Fix index, basic page ordering --- docs/index.rst | 16 ++++++++-------- docs/sphinx/_toc.yml.in | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 8a8b3297..c1d05259 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,19 +20,19 @@ complete instructions, refer to the following sections. ROCm quick-start installation guide. - .. grid-item-card:: Install options - :link: tutorial/install-overview - :link-type: doc - - * Package manager vs AMDGPU installer - * Single-version vs multi-version - .. grid-item-card:: Prerequisites :link: how-to/prerequisites :link-type: doc Steps required before installation. + .. grid-item-card:: Install overview + :link: tutorial/install-overview + :link-type: doc + + * Package manager vs AMDGPU installer + * Single-version vs multi-version + Choose your install method ======================================== @@ -72,4 +72,4 @@ Additional resources .. grid-item-card:: How-to guides - :doc:`how-to/docker` - - :doc:`how-to/spack` \ No newline at end of file + - :doc:`how-to/spack` diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 4c62254f..52cee7db 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -4,12 +4,12 @@ defaults: root: index subtrees: - entries: - - file: tutorial/install-overview - title: Installation overview - file: tutorial/quick-start title: Quick-start install guide - file: how-to/prerequisites title: Prerequisites + - file: tutorial/install-overview + title: Installation overview - file: reference/system-requirements title: System requirements - file: how-to/amdgpu-install From 6522dc1a17291bf55480efb726da95d02ca88b1b Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 14:11:20 -0700 Subject: [PATCH 04/17] post-isntall: fix formatting --- docs/how-to/native-install/post-install.rst | 64 ++++++++++----------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/how-to/native-install/post-install.rst b/docs/how-to/native-install/post-install.rst index 4b053b1b..1aaeca2e 100644 --- a/docs/how-to/native-install/post-install.rst +++ b/docs/how-to/native-install/post-install.rst @@ -6,59 +6,59 @@ Post-installation instructions ************************************************************************* -1. Configure the system linker. +#. Configure the system linker. - Instruct the system linker where to find shared objects (``.so``-files) for ROCm applications. + Instruct the system linker where to find shared objects (``.so``-files) for ROCm applications. - .. code-block:: bash + .. code-block:: bash - sudo tee --append /etc/ld.so.conf.d/rocm.conf < Date: Mon, 11 Mar 2024 15:12:35 -0700 Subject: [PATCH 05/17] revamp docker instructions --- docs/how-to/amdgpu-install.rst | 11 ++++ docs/how-to/docker.rst | 98 ++++++++++++++++++---------------- 2 files changed, 64 insertions(+), 45 deletions(-) diff --git a/docs/how-to/amdgpu-install.rst b/docs/how-to/amdgpu-install.rst index f6daee3a..1d2f418f 100644 --- a/docs/how-to/amdgpu-install.rst +++ b/docs/how-to/amdgpu-install.rst @@ -154,6 +154,17 @@ output below. - ASAN enabled ROCm libraries +.. _amdgpu-install-dkms: + +Install ``amdgpu-dkms`` +------------------------------------------------- + +In order to install the DKMS only (minimal requirement for launching containers with GPU access), you use the ``dkms`` usecase, as follows: + +.. code-block:: bash + + amdgpu-install --usecase=dkms + Upgrading ROCm ================================================= diff --git a/docs/how-to/docker.rst b/docs/how-to/docker.rst index 366860c7..9f0aa99a 100644 --- a/docs/how-to/docker.rst +++ b/docs/how-to/docker.rst @@ -3,84 +3,92 @@ :keywords: installation instructions, Docker, AMD, ROCm ******************************************************************************** -Install ROCm Docker containers +Running ROCm Docker containers ******************************************************************************** +Using Docker to run your ROCm applications is one of the best ways to get consistent and reproducible environments. + Prerequisites ========================================== -Docker containers share the kernel with the host operating system, therefore the -ROCm kernel-mode driver must be installed on the host. Please refer to -:doc:`/tutorial/install-overview` on installing ``amdgpu-dkms``. The other -user-space parts (like the HIP-runtime or math libraries) of the ROCm stack will -be loaded from the container image and don't need to be installed to the host. +* ``amdgpu-dkms`` + + Docker containers share the kernel with the host OS, therefore, the ROCm kernel-mode driver (``amdgpu-dkms``) must be installed on the host. + If you've already installed ROCm, you probably already have ``amdgpu-dkms``. + + * Check for ``amdgpu-dkms``: + + + + * Install ``amdgpu-dkms`` + + * You can follow the :ref:`standard install instructions` (which comes with amdgpu-dkms), or :ref:`install amdgpu-dkms only` .. _docker-access-gpus-in-container: Accessing GPUs in containers ========================================== -In order to access GPUs in a container (to run applications using HIP, OpenCL or -OpenMP offloading) explicit access to the GPUs must be granted. +In order to grant access go GPUs from within a container, you should run your container with the following options: -The ROCm runtimes make use of multiple device files: +.. code-block:: shell -- ``/dev/kfd``: the main compute interface shared by all GPUs -- ``/dev/dri/renderD``: direct rendering interface (DRI) devices for each - GPU. Where ```` is a number for each card in the system starting from 128. + docker run --device /dev/kfd --device /dev/dri --security-opt seccomp=unconfined -Exposing these devices to a container is done by using the -`--device `_ -option, i.e. to allow access to all GPUs expose ``/dev/kfd`` and all -``/dev/dri/renderD`` devices: +The purpose of each option is listed below: -.. code-block:: shell +* ``--device /dev/fdk`` - docker run --device /dev/kfd --device /dev/renderD128 --device /dev/renderD129 ... + This is the main compute interface, shared by all GPUs. -More conveniently, instead of listing all devices, the entire ``/dev/dri`` folder -can be exposed to the new container: +* ``--device /dev/dri`` -.. code-block:: shell + This directory contains the Direct Rendering Interface (DRI) for each GPU. To restrict access to specific GPUs, see :ref:`docker-restrict-gpus`. - docker run --device /dev/kfd --device /dev/dri +* ``--security-opt seccomp=unconfined`` (optional) -Note that this gives more access than strictly required, as it also exposes the -other device files found in that folder to the container. + This option enables memory mapping, and is recommended for containers running in HPC environments. -.. _docker-restrict-gpus: - -Restricting a container to a subset of the GPUs -------------------------------------------------------------------------------------------------- + The performance of an application can vary depending on the assignment of GPUs + and CPUs to the task. Typically, ``numactl`` is installed as part of many HPC + applications to provide GPU/CPU mappings. This Docker runtime option supports + memory mapping and can improve performance. -If a ``/dev/dri/renderD`` device is not exposed to a container then it cannot use -the GPU associated with it; this allows to restrict a container to any subset of -devices. +Docker Compose +------------------------------ -For example to allow the container to access the first and third GPU start it -like: +You can also use ``docker compose`` to launch your containers, even when launching a single container. This can be a convienent way to +run complex docker commands (like the one above) without having to remember all the CLI arguments Here is a docker-compose file which +is equivalent to the ``docker run`` command above: -.. code-block:: shell +.. code-block:: yaml - docker run --device /dev/kfd --device /dev/dri/renderD128 --device /dev/dri/renderD130 + version: "3.7" + services: + my-service: + image: + device: + - /dev/fdk + - /dev/dri + security_opt: + - seccomp:unconfined -Additional options -------------------------------------------------------------------------------------------------- +You can then run this with ``docker compose run my-service``. -The performance of an application can vary depending on the assignment of GPUs -and CPUs to the task. Typically, ``numactl`` is installed as part of many HPC -applications to provide GPU/CPU mappings. This Docker runtime option supports -memory mapping and can improve performance. +.. _docker-restrict-gpus: -.. code-block:: shell +Restricting GPU access +---------------------- - --security-opt seccomp=unconfined +By passing ``--device /dev/dri``, you are granting access to all GPUs on the system. In order to limit access to a subset of GPUs, you +can pass each device individually using one or more ``-device /dev/dri/renderD``, where ```` is the card index, starting from 128. -This option is recommended for Docker Containers running HPC applications. +For example, to expose the first and second GPU: .. code-block:: shell - docker run --device /dev/kfd --device /dev/dri --security-opt seccomp=unconfined ... + docker run --device /dev/kfd --device /dev/dri/renderD128 --device /dev/dri/renderD129 .. + Docker images in the ROCm ecosystem ======================================================= From bb3e27095f5301185c17df373b3b7811b42b8b19 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 14:25:00 -0700 Subject: [PATCH 06/17] Improve docker instructions --- docs/how-to/docker.rst | 12 +++--------- docs/how-to/native-install/post-install.rst | 2 ++ docs/sphinx/_toc.yml.in | 2 +- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/how-to/docker.rst b/docs/how-to/docker.rst index 9f0aa99a..77cd8ebf 100644 --- a/docs/how-to/docker.rst +++ b/docs/how-to/docker.rst @@ -11,18 +11,12 @@ Using Docker to run your ROCm applications is one of the best ways to get consis Prerequisites ========================================== -* ``amdgpu-dkms`` - - Docker containers share the kernel with the host OS, therefore, the ROCm kernel-mode driver (``amdgpu-dkms``) must be installed on the host. +* ``amdgpu-dkms`` : Docker containers share the kernel with the host OS, therefore, the ROCm kernel-mode driver (``amdgpu-dkms``) must be installed on the host. If you've already installed ROCm, you probably already have ``amdgpu-dkms``. - * Check for ``amdgpu-dkms``: - - - - * Install ``amdgpu-dkms`` + * :ref:`Chedk for amdgpu-dkms` - * You can follow the :ref:`standard install instructions` (which comes with amdgpu-dkms), or :ref:`install amdgpu-dkms only` + * If missing, you can follow the :ref:`standard install instructions` (which comes with amdgpu-dkms), or :ref:`install amdgpu-dkms only`. .. _docker-access-gpus-in-container: diff --git a/docs/how-to/native-install/post-install.rst b/docs/how-to/native-install/post-install.rst index 1aaeca2e..536c7020 100644 --- a/docs/how-to/native-install/post-install.rst +++ b/docs/how-to/native-install/post-install.rst @@ -27,6 +27,8 @@ Post-installation instructions export PATH=$PATH:/opt/rocm-|rocm_directory_version|/bin +.. _verify-dkms: + #. Verify kernel-mode driver installation. .. code-block:: bash diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 52cee7db..d77f3362 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -41,7 +41,7 @@ subtrees: - caption: How-to entries: - file: how-to/docker - title: Install Docker containers + title: Running Docker containers - file: how-to/spack title: Introduction to Spack From 6a8355c98fb781d170bd69746516eadb3216f7fc Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 11:58:40 -0700 Subject: [PATCH 07/17] Significant progress on torch instructions --- .../torch/dockerfile_from_dev_ubuntu | 26 + docs/how-to/3rd-party/pytorch-docker.rst | 117 +++++ docs/how-to/3rd-party/pytorch-index.rst | 2 + docs/how-to/3rd-party/pytorch-install-old.rst | 478 +++++++++++++++++ docs/how-to/3rd-party/pytorch-install.rst | 480 ++---------------- docs/sphinx/_toc.yml.in | 11 +- 6 files changed, 680 insertions(+), 434 deletions(-) create mode 100644 docs/docker_examples/torch/dockerfile_from_dev_ubuntu create mode 100644 docs/how-to/3rd-party/pytorch-docker.rst create mode 100644 docs/how-to/3rd-party/pytorch-index.rst create mode 100644 docs/how-to/3rd-party/pytorch-install-old.rst diff --git a/docs/docker_examples/torch/dockerfile_from_dev_ubuntu b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu new file mode 100644 index 00000000..6164b219 --- /dev/null +++ b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu @@ -0,0 +1,26 @@ +ARG ROCM_VERSION=5.7 +FROM rocm/dev-ubuntu-22.04:$ROCM_VERSION + +ARG ROCM_VERSION # Re-declare for use in this scope + +ARG DEBIAN_FRONTEND=noninteractive +RUN apt-get update \ + # Add the deadsnakes repo for python + && apt-get install -y software-properties-common && add-apt-repository ppa:deadsnakes/ppa \ + # Install Pyton 3.11 and other deps + && apt-get update && apt-get install -y \ + python3.11 \ + python3.11-venv \ + wget \ + # Clean up the cache + && rm -rf /var/lib/apt/lists/* + +# Create a virtual environment, and put it at the front of our PATH +RUN python3.11 -m venv venv +ENV PATH=/venv/bin:$PATH + +# Install Pytorch +RUN --mount=type=cache,target=/root/.cache/pip pip3 install torch==2.2.1 torchvision==0.17.1 --index-url https://download.pytorch.org/whl/rocm$ROCM_VERSION/ + +# Install additional python dependencies +RUN pip3 install transformers==4.38.2 diff --git a/docs/how-to/3rd-party/pytorch-docker.rst b/docs/how-to/3rd-party/pytorch-docker.rst new file mode 100644 index 00000000..93fc17d7 --- /dev/null +++ b/docs/how-to/3rd-party/pytorch-docker.rst @@ -0,0 +1,117 @@ +PyTorch+ROCm in Docker +======================= + +Using Docker to run your PyTorch + ROCm application is one of the best ways to get consistent and reproducible environemnts. + +Additional PyTorch Docker Args +------------------------------- + +Regardless of which image you use or build, running PyTorch docker images requires several arguments in addition to those discussed in :ref:`docker-access-gpus-in-container`. + +* ``--ipc=host`` OR ``--shm-size=Xg`` + + PyTorch uses shared memory to share data betwee processes (such as multithreaded data loaders). As such, you must increase the shared memory size, which defaults to 64M. This can be done in two ways: + + * ``--ipc=host`` shares the IPC directly from the host, which will allow the container access to all resources on the host. For most applications, this is sufficient. + + * ``--shm-size`` allows more granular control over resourcing for a container. In applications with multiple containers running simultaneously, setting this value appropriately can help prevent memory errors. + + See the `PyTorch docs on using docker images `_ for information on these options. + +.. code-block:: bash + + docker run -it --device=/dev/fkd --device=/dev/dri --security-opt seccomp=unconfined --ipc=host + + +Pre-Built PyTorch+ROCm Docker Images +-------------------------------------- + +The easiest method to run PyTorch+ROCm is to use a pre-built image from `AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. + +* `rocm/pytorch `_ - latest stable builds +* `rocm/pytorch-nightly `_ - latest nightly builds + +For example, to run the latest rocm/pytorch image, run: + +.. code-block:: bash + + docker run -it --device=/dev/fkd --device=/dev/dri --security-opt seccomp=unconfined --ipc=host rocm/pytorch:latest + + +Custom Docker Images +-------------------- + +As is often the case, your specific requirements may not be met by one of the pre-built PyTorch+ROCm images. For example, you may need additional pythond dependencies, a different version of PyTorch, or even a completely different combination of OS, ROCm, Python, and PyTorch. + +To meet these needs, you can build your own ROCm docker images. + +From ROCm dev container +....................... + +We provide several dev containers, which contain just the base OS + ROCm. These containers are a great place to start when building custom images, as you don't have to install ROCm into the image yourself. + +* Select a base image that neets your needs. To find a list of base images, `search rocm/dev `_ on Docker Hub. +* Build your ``dockerfile`` + + * Install required python version + * Install PyTorch, and other python dependencies + +Below is an example ``dockerfile`` based on ``rocm/dev-ubuntu-22.04:5.7`` + +.. literalinclude:: ../../docker_examples/torch/dockerfile_from_dev_ubuntu + :language: dockerfile + +.. tip:: + + * Using ARGs can help simplify your dockerfiles, and prevent version mismatches + * Use specific versions, rather than ``latest``, to help keep builds reproducible. This also applies to python packages. + * It is always a good idea to use virtual environments, *even inside docker*! + +Building PyTorch from source +............................ + +You may need to install a version of pytorch which is not available as a pre-built binary. In this case, you can build and install PyTorch from source. + +For details, see :ref:`building pytorch from source `_. + +.. literalinclude:: ../../docker_examples/torch/dockerfile_from_base + :language: dockerfile + + +From scratch +............ + +Using Dependency Managers (PDM) +............................... + +Using Pre-Compiled MIOpen KDB Files +=================================== + + + +PyTorch uses MIOpen for machine learning primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up application warm-up phases. + +.. tip:: + + The MIOpen installation script takes time. + +MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in a specific location with respect to the PyTorch installation path. A helper script simplifies this task by taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. + +You can download the helper script here: install_kdb_files_for_pytorch_wheels.sh, or use: + +.. code-block:: bash + + wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh + + #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version + export GFX_ARCH=gfx90a # Limiting architectures can greatly speed up install time + export ROCM_VERSION=5.6 + + ./install_kdb_files_for_pytorch_wheels.sh + +LINKS: + +* https://github.com/ROCm/pytorch/wiki/Using-MIOpen-kdb-files-with-ROCm-PyTorch-wheels +* https://docs.amd.com/projects/MIOpen/en/latest/#installing-miopen-kernels-package +* https://docs.amd.com/projects/MIOpen/en/latest/cache.html#installing-pre-compiled-kernels +* https://github.com/ROCm/MIOpen diff --git a/docs/how-to/3rd-party/pytorch-index.rst b/docs/how-to/3rd-party/pytorch-index.rst new file mode 100644 index 00000000..c7f409af --- /dev/null +++ b/docs/how-to/3rd-party/pytorch-index.rst @@ -0,0 +1,2 @@ +PyTorch +======== diff --git a/docs/how-to/3rd-party/pytorch-install-old.rst b/docs/how-to/3rd-party/pytorch-install-old.rst new file mode 100644 index 00000000..c10c3ce2 --- /dev/null +++ b/docs/how-to/3rd-party/pytorch-install-old.rst @@ -0,0 +1,478 @@ +.. meta:: + :description: Installing PyTorch for ROCm + :keywords: installation instructions, PyTorch, AMD, ROCm + +********************************************************************************** +Installing PyTorch for ROCm +********************************************************************************** + +`PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on +ROCm provides mixed-precision and large-scale training using our +`MIOpen `_ and +`RCCL `_ libraries. + +To install +`PyTorch for ROCm `_, +you have the following options: + +* :ref:`using-docker-with-pytorch-pre-installed` + (recommended) +* :ref:`using-wheels-package` +* :ref:`using-pytorch-rocm-docker-image` +* :ref:`using-pytorch-upstream-docker-image` + +For hardware, software, and third-party framework compatibility between ROCm and PyTorch, refer to: + +* :ref:`system-requirements` +* :ref:`3rd-party-support-matrix` + +.. _using-docker-with-pytorch-pre-installed: + +Using a Docker image with PyTorch pre-installed +=============================================================== + +1. Download the latest public `PyTorch Docker image `_. + + .. code-block:: bash + + docker pull rocm/pytorch:latest + + You can also download a specific and supported configuration with different user-space ROCm + versions, PyTorch versions, and operating systems. + +2. Start a Docker container using the image. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ + --device=/dev/kfd --device=/dev/dri --group-add video \ + --ipc=host --shm-size 8G rocm/pytorch:latest + + .. note:: + + This will automatically download the image if it does not exist on the host. You can also pass the ``-v`` + argument to mount any data directories from the host onto the container. + +.. _install_pytorch_wheels: +.. _using-wheels-package: + +Using a wheels package +=============================================================== + +PyTorch supports the ROCm platform by providing tested wheels packages. To access this feature, go +to `pytorch.org/get-started/locally/ `_. For the correct +wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matrix. + +1. Choose one of the following three options: + + **Option 1:** + + a. Download a base Docker image with the correct user-space ROCm version. + + .. list-table:: + :header-rows: 1 + + * - Base OS + - Docker Image + * - Ubuntu 20.04 + - `rocm/dev-ubuntu-20.04 `_ + * - Ubuntu 22.04 + - `rocm/dev-ubuntu-22.04 `_ + * - CentOS 7 + - `rocm/dev-centos-7 `_ + + b. Pull the selected image. + + .. code-block:: bash + + docker pull rocm/dev-ubuntu-20.04:latest + + c. Start a Docker container using the downloaded image. + + .. code-block:: bash + + docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-20.04:latest + + **Option 2:** + + Select a base OS Docker image (Check :ref:`system-requirements`) + + Pull selected base OS image (Ubuntu 20.04 for example) + + .. code-block:: bash + + docker pull ubuntu:20.04 + + Start a Docker container using the downloaded image + + .. code-block:: bash + + docker run -it --device=/dev/kfd --device=/dev/dri --group-add video ubuntu:20.04 + + Install ROCm using the directions in the :ref:`rocm-install-overview` section. + + **Option 3:** + + Install on bare metal. Check :ref:`system-requirements` and install ROCm using the + directions in the :ref:`rocm-install-overview` section. + +2. Install the required dependencies for the wheels package. + + .. code-block:: bash + + sudo apt update + sudo apt install libjpeg-dev python3-dev python3-pip + pip3 install wheel setuptools + +3. Install ``torch``, ``torchvision``, and ``torchaudio``, as specified in the + `installation matrix `_. + + .. note:: + + The following command uses the ROCm 5.6 PyTorch wheel. If you want a different version of ROCm, + modify the command accordingly. + + .. code-block:: bash + + pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm5.6/ + +4. (Optional) Use MIOpen kdb files with ROCm PyTorch wheels. + + PyTorch uses `MIOpen `_ for machine learning + primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up + phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up + application warm-up phases. + + MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in + a specific location with respect to the PyTorch installation path. A helper script simplifies this task by + taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. + + You can download the helper script here: + `install_kdb_files_for_pytorch_wheels.sh `_, or use: + + .. code-block:: bash + + wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh + + After installing ROCm PyTorch wheels, run the following code: + + .. code-block:: bash + + #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version + export GFX_ARCH=gfx90a + + #Optional + export ROCM_VERSION=5.6 + + ./install_kdb_files_for_pytorch_wheels.sh + +.. _using-pytorch-rocm-docker-image: + +Using the PyTorch ROCm base Docker image +=============================================================== + +The pre-built base Docker image has all dependencies installed, including: + +* ROCm +* torchvision +* Conda packages +* The compiler toolchain + +Additionally, a particular environment flag (``BUILD_ENVIRONMENT``) is set, which is used by the build +scripts to determine the configuration of the build environment. + +1. Download the Docker image. This is the base image, which does not contain PyTorch. + + .. code-block:: bash + + docker pull rocm/pytorch:latest-base + +2. Start a Docker container using the downloaded image. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd --device=/dev/dri --group-add video --ipc=host --shm-size 8G rocm/pytorch:latest-base + + You can also pass the ``-v`` argument to mount any data directories from the host onto the container. + +3. Clone the PyTorch repository. + + .. code-block:: bash + + cd ~ + git clone https://github.com/pytorch/pytorch.git + cd /pytorch + git submodule update --init --recursive + +4. Set ROCm architecture (optional). The Docker image tag is ``rocm/pytorch:latest-base``. + + .. note:: + + By default in the ``rocm/pytorch:latest-base`` image, PyTorch builds simultaneously for the following + architectures: + * gfx900 + * gfx906 + * gfx908 + * gfx90a + * gfx1030 + + If you want to compile *only* for your microarchitecture (uarch), run: + + .. code-block:: bash + + export PYTORCH_ROCM_ARCH= + + Where ```` is the architecture reported by the ``rocminfo`` command. + + To find your uarch, run: + + .. code-block:: bash + + rocminfo | grep gfx + +5. Build PyTorch. + + .. code-block:: bash + + ./.ci/pytorch/build.sh + + This converts PyTorch sources for HIP compatibility and builds the PyTorch framework. + + To check if your build is successful, run: + + .. code-block:: bash + + echo $? # should return 0 if success + +.. _using-pytorch-upstream-docker-image: + +Using the PyTorch upstream Docker file +=============================================================== + +If you don't want to use a prebuilt base Docker image, you can build a custom base Docker image +using scripts from the PyTorch repository. This uses a standard Docker image from operating system +maintainers and installs all the required dependencies, including: + +* ROCm +* torchvision +* Conda packages +* The compiler toolchain + +1. Clone the PyTorch repository. + + .. code-block:: bash + + cd ~ + git clone https://github.com/pytorch/pytorch.git + cd /pytorch + git submodule update --init --recursive + +2. Build the PyTorch Docker image. + + .. code-block:: bash + + cd .ci/docker + ./build.sh pytorch-linux--rocm-py -t rocm/pytorch:build_from_dockerfile + + Where: + * ````: ``ubuntu20.04`` (or ``focal``), ``ubuntu22.04`` (or ``jammy``), ``centos7.5``, or ``centos9`` + * ````: ``5.4``, ``5.5``, or ``5.6`` + * ````: ``3.8`` - ``3.11`` + + To verify that your image was successfully created, run: + + .. code-block:: bash + + docker image ls rocm/pytorch:build_from_dockerfile + + If successful, the output looks like this: + + .. code-block:: bash + + REPOSITORY TAG IMAGE ID CREATED SIZE + rocm/pytorch build_from_dockerfile 17071499be47 2 minutes ago 32.8GB + +3. Start a Docker container using the image with the mounted PyTorch folder. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt --user root \ + seccomp=unconfined --device=/dev/kfd --device=/dev/dri \ + --group-add video --ipc=host --shm-size 8G \ + -v ~/pytorch:/pytorch rocm/pytorch:build_from_dockerfile + + You can also pass the ``-v`` argument to mount any data directories from the host onto the container. + +4. Go to the PyTorch directory. + + .. code-block:: bash + + cd pytorch + +5. Set ROCm architecture. + + To determine your AMD architecture, run: + + .. code-block:: bash + + rocminfo | grep gfx + + The result looks like this (for ``gfx1030`` architecture): + + .. code-block:: bash + + Name: gfx1030 + Name: amdgcn-amd-amdhsa--gfx1030 + + Set the ``PYTORCH_ROCM_ARCH`` environment variable to specify the architectures you want to + build PyTorch for. + + .. code-block:: bash + + export PYTORCH_ROCM_ARCH= + + where ```` is the architecture reported by the ``rocminfo`` command. + +6. Build PyTorch. + + .. code-block:: bash + + ./.ci/pytorch/build.sh + + This converts PyTorch sources for + `HIP compatibility `_ and builds the + PyTorch framework. + + To check if your build is successful, run: + + .. code-block:: bash + + echo $? # should return 0 if success + +Testing the PyTorch installation +=============================================================== + +You can use PyTorch unit tests to validate your PyTorch installation. If you used a +**prebuilt PyTorch Docker image from AMD ROCm Docker Hub** or installed an +**official wheels package**, validation tests are not necessary. + +If you want to manually run unit tests to validate your PyTorch installation fully, follow these steps: + +1. Import the torch package in Python to test if PyTorch is installed and accessible. + + .. note:: + + Do not run the following command in the PyTorch git folder. + + .. code-block:: bash + + python3 -c 'import torch' 2> /dev/null && echo 'Success' || echo 'Failure' + +2. Check if the GPU is accessible from PyTorch. In the PyTorch framework, ``torch.cuda`` is a generic way + to access the GPU. This can only access an AMD GPU if one is available. + + .. code-block:: bash + + python3 -c 'import torch; print(torch.cuda.is_available())' + + +3. Run unit tests to validate the PyTorch installation fully. + + .. note:: + + You must run the following command from the PyTorch home directory. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/run_test.py --verbose \ + --include test_nn test_torch test_cuda test_ops \ + test_unary_ufuncs test_binary_ufuncs test_autograd + + This command ensures that the required environment variable is set to skip certain unit tests for + ROCm. This also applies to wheel installs in a non-controlled environment. + + .. note:: + + Make sure your PyTorch source code corresponds to the PyTorch wheel or the installation in the + Docker image. Incompatible PyTorch source code can give errors when running unit tests. + + Some tests may be skipped, as appropriate, based on your system configuration. ROCm doesn't + support all PyTorch features; tests that evaluate unsupported features are skipped. Other tests might + be skipped, depending on the host or GPU memory and the number of available GPUs. + + If the compilation and installation are correct, all tests will pass. + +4. Run individual unit tests. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/test_nn.py --verbose + + You can replace ``test_nn.py`` with any other test set. + +Running a basic PyTorch example +=============================================================== + +The PyTorch examples repository provides basic examples that exercise the functionality of your +framework. + +Two of our favorite testing databases are: + +* **MNIST** (Modified National Institute of Standards and Technology): A database of handwritten + digits that can be used to train a Convolutional Neural Network for **handwriting recognition**. +* **ImageNet**: A database of images that can be used to train a network for + **visual object recognition**. + +MNIST PyTorch example +--------------------------------------------------------------------------------------------------------- + +1. Clone the PyTorch examples repository. + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the MNIST example folder. + + .. code-block:: bash + + cd examples/mnist + +3. Follow the instructions in the ``README.md`` file in this folder to install the requirements. Then run: + + .. code-block:: bash + + python3 main.py + + This generates the following output: + + .. code-block:: + + ... + Train Epoch: 14 [58240/60000 (97%)] Loss: 0.010128 + Train Epoch: 14 [58880/60000 (98%)] Loss: 0.001348 + Train Epoch: 14 [59520/60000 (99%)] Loss: 0.005261 + + Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) + +ImageNet PyTorch example +--------------------------------------------------------------------------------------------------------- + +1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST + example). + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the ImageNet example folder. + + .. code-block:: bash + + cd examples/imagenet + +3. Follow the instructions in the ``README.md`` file in this folder to install the Requirements. Then run: + + .. code-block:: bash + + python3 main.py diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch-install.rst index c10c3ce2..a04c562b 100644 --- a/docs/how-to/3rd-party/pytorch-install.rst +++ b/docs/how-to/3rd-party/pytorch-install.rst @@ -1,9 +1,9 @@ .. meta:: - :description: Installing PyTorch for ROCm + :description: PyTorch with ROCm :keywords: installation instructions, PyTorch, AMD, ROCm ********************************************************************************** -Installing PyTorch for ROCm +PyTorch for ROCm ********************************************************************************** `PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on @@ -11,468 +11,82 @@ ROCm provides mixed-precision and large-scale training using our `MIOpen `_ and `RCCL `_ libraries. -To install -`PyTorch for ROCm `_, -you have the following options: -* :ref:`using-docker-with-pytorch-pre-installed` - (recommended) -* :ref:`using-wheels-package` -* :ref:`using-pytorch-rocm-docker-image` -* :ref:`using-pytorch-upstream-docker-image` -For hardware, software, and third-party framework compatibility between ROCm and PyTorch, refer to: +Installation (Pip) +------------------ -* :ref:`system-requirements` -* :ref:`3rd-party-support-matrix` +PyTorch supports the ROCm platform by providing pre-built wheels packages for a variety of PyTorch and ROCm versions. To install the +latest version: -.. _using-docker-with-pytorch-pre-installed: +* Navigate to `pytorch.org/get-started/locally/ `_. +* Select ``Stable``, ``Linux``, ``Pip``, ``Python``, and ``ROCm`` -Using a Docker image with PyTorch pre-installed -=============================================================== +You should see ``pip3 install`` commmand -1. Download the latest public `PyTorch Docker image `_. +.. code-block:: shell - .. code-block:: bash + pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.7 - docker pull rocm/pytorch:latest +.. Note:: - You can also download a specific and supported configuration with different user-space ROCm - versions, PyTorch versions, and operating systems. + You should use a virtual environment when installing python packages in order to separate dependencies + from the system and other projects. -2. Start a Docker container using the image. +Additional Versions +................... - .. code-block:: bash +In addition to the latest stable version, you can also install new, preview versions, as well as older versions. - docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ - --device=/dev/kfd --device=/dev/dri --group-add video \ - --ipc=host --shm-size 8G rocm/pytorch:latest +* Preview (Nightly): Select ``Preview (Nightly)`` from the `installation matrix `_ - .. note:: +* Previous versions: You can search for previous versions on `PyTorch's docs here `_ - This will automatically download the image if it does not exist on the host. You can also pass the ``-v`` - argument to mount any data directories from the host onto the container. + Make sure to search for the appropriate ROCm version -.. _install_pytorch_wheels: -.. _using-wheels-package: +Other Package Managers +...................... -Using a wheels package -=============================================================== +You can also use more sophisticated dependency management tools like PDM and Poetry. These tools provide several benefits over ``pip``, including +automatic creation of virtual environments, complex dependency resolution, lockfiles, and more. -PyTorch supports the ROCm platform by providing tested wheels packages. To access this feature, go -to `pytorch.org/get-started/locally/ `_. For the correct -wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matrix. +`PDM `_ +++++++++++++++++++++++++++++++++++++++++++++++ -1. Choose one of the following three options: +* Add the ``index-url`` from above as a `source `_ by adding the following lines to your ``pyproject.toml`` file: - **Option 1:** + .. code-block:: - a. Download a base Docker image with the correct user-space ROCm version. + [[tool.pdm.source]] + name = "torch-index" # You can give this any name + url = "https://download.pytorch.org/whl/rocm5.7/" - .. list-table:: - :header-rows: 1 +* Add dependencies - * - Base OS - - Docker Image - * - Ubuntu 20.04 - - `rocm/dev-ubuntu-20.04 `_ - * - Ubuntu 22.04 - - `rocm/dev-ubuntu-22.04 `_ - * - CentOS 7 - - `rocm/dev-centos-7 `_ + .. code-block:: shell - b. Pull the selected image. + pdm add torch ... - .. code-block:: bash +PDM will then first look in the proided source to install any package, before falling back to `pypi.org `_. - docker pull rocm/dev-ubuntu-20.04:latest +`Poetry `_ +++++++++++++++++++++++++++++++++++++++++++++ - c. Start a Docker container using the downloaded image. - .. code-block:: bash +* Add the ``index-url`` from above as a `source `_: - docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-20.04:latest + .. code-block:: - **Option 2:** + poetry source add torch-index https://download.pytorch.org/whl/rocm5.7 - Select a base OS Docker image (Check :ref:`system-requirements`) +* Add dependencies, and specify the source: - Pull selected base OS image (Ubuntu 20.04 for example) + .. code-block:: - .. code-block:: bash + poetry add torch --source torch-index - docker pull ubuntu:20.04 +Install From Source +-------------------- - Start a Docker container using the downloaded image - - .. code-block:: bash - - docker run -it --device=/dev/kfd --device=/dev/dri --group-add video ubuntu:20.04 - - Install ROCm using the directions in the :ref:`rocm-install-overview` section. - - **Option 3:** - - Install on bare metal. Check :ref:`system-requirements` and install ROCm using the - directions in the :ref:`rocm-install-overview` section. - -2. Install the required dependencies for the wheels package. - - .. code-block:: bash - - sudo apt update - sudo apt install libjpeg-dev python3-dev python3-pip - pip3 install wheel setuptools - -3. Install ``torch``, ``torchvision``, and ``torchaudio``, as specified in the - `installation matrix `_. - - .. note:: - - The following command uses the ROCm 5.6 PyTorch wheel. If you want a different version of ROCm, - modify the command accordingly. - - .. code-block:: bash - - pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm5.6/ - -4. (Optional) Use MIOpen kdb files with ROCm PyTorch wheels. - - PyTorch uses `MIOpen `_ for machine learning - primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up - phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up - application warm-up phases. - - MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in - a specific location with respect to the PyTorch installation path. A helper script simplifies this task by - taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. - - You can download the helper script here: - `install_kdb_files_for_pytorch_wheels.sh `_, or use: - - .. code-block:: bash - - wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh - - After installing ROCm PyTorch wheels, run the following code: - - .. code-block:: bash - - #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version - export GFX_ARCH=gfx90a - - #Optional - export ROCM_VERSION=5.6 - - ./install_kdb_files_for_pytorch_wheels.sh - -.. _using-pytorch-rocm-docker-image: - -Using the PyTorch ROCm base Docker image -=============================================================== - -The pre-built base Docker image has all dependencies installed, including: - -* ROCm -* torchvision -* Conda packages -* The compiler toolchain - -Additionally, a particular environment flag (``BUILD_ENVIRONMENT``) is set, which is used by the build -scripts to determine the configuration of the build environment. - -1. Download the Docker image. This is the base image, which does not contain PyTorch. - - .. code-block:: bash - - docker pull rocm/pytorch:latest-base - -2. Start a Docker container using the downloaded image. - - .. code-block:: bash - - docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd --device=/dev/dri --group-add video --ipc=host --shm-size 8G rocm/pytorch:latest-base - - You can also pass the ``-v`` argument to mount any data directories from the host onto the container. - -3. Clone the PyTorch repository. - - .. code-block:: bash - - cd ~ - git clone https://github.com/pytorch/pytorch.git - cd /pytorch - git submodule update --init --recursive - -4. Set ROCm architecture (optional). The Docker image tag is ``rocm/pytorch:latest-base``. - - .. note:: - - By default in the ``rocm/pytorch:latest-base`` image, PyTorch builds simultaneously for the following - architectures: - * gfx900 - * gfx906 - * gfx908 - * gfx90a - * gfx1030 - - If you want to compile *only* for your microarchitecture (uarch), run: - - .. code-block:: bash - - export PYTORCH_ROCM_ARCH= - - Where ```` is the architecture reported by the ``rocminfo`` command. - - To find your uarch, run: - - .. code-block:: bash - - rocminfo | grep gfx - -5. Build PyTorch. - - .. code-block:: bash - - ./.ci/pytorch/build.sh - - This converts PyTorch sources for HIP compatibility and builds the PyTorch framework. - - To check if your build is successful, run: - - .. code-block:: bash - - echo $? # should return 0 if success - -.. _using-pytorch-upstream-docker-image: - -Using the PyTorch upstream Docker file -=============================================================== - -If you don't want to use a prebuilt base Docker image, you can build a custom base Docker image -using scripts from the PyTorch repository. This uses a standard Docker image from operating system -maintainers and installs all the required dependencies, including: - -* ROCm -* torchvision -* Conda packages -* The compiler toolchain - -1. Clone the PyTorch repository. - - .. code-block:: bash - - cd ~ - git clone https://github.com/pytorch/pytorch.git - cd /pytorch - git submodule update --init --recursive - -2. Build the PyTorch Docker image. - - .. code-block:: bash - - cd .ci/docker - ./build.sh pytorch-linux--rocm-py -t rocm/pytorch:build_from_dockerfile - - Where: - * ````: ``ubuntu20.04`` (or ``focal``), ``ubuntu22.04`` (or ``jammy``), ``centos7.5``, or ``centos9`` - * ````: ``5.4``, ``5.5``, or ``5.6`` - * ````: ``3.8`` - ``3.11`` - - To verify that your image was successfully created, run: - - .. code-block:: bash - - docker image ls rocm/pytorch:build_from_dockerfile - - If successful, the output looks like this: - - .. code-block:: bash - - REPOSITORY TAG IMAGE ID CREATED SIZE - rocm/pytorch build_from_dockerfile 17071499be47 2 minutes ago 32.8GB - -3. Start a Docker container using the image with the mounted PyTorch folder. - - .. code-block:: bash - - docker run -it --cap-add=SYS_PTRACE --security-opt --user root \ - seccomp=unconfined --device=/dev/kfd --device=/dev/dri \ - --group-add video --ipc=host --shm-size 8G \ - -v ~/pytorch:/pytorch rocm/pytorch:build_from_dockerfile - - You can also pass the ``-v`` argument to mount any data directories from the host onto the container. - -4. Go to the PyTorch directory. - - .. code-block:: bash - - cd pytorch - -5. Set ROCm architecture. - - To determine your AMD architecture, run: - - .. code-block:: bash - - rocminfo | grep gfx - - The result looks like this (for ``gfx1030`` architecture): - - .. code-block:: bash - - Name: gfx1030 - Name: amdgcn-amd-amdhsa--gfx1030 - - Set the ``PYTORCH_ROCM_ARCH`` environment variable to specify the architectures you want to - build PyTorch for. - - .. code-block:: bash - - export PYTORCH_ROCM_ARCH= - - where ```` is the architecture reported by the ``rocminfo`` command. - -6. Build PyTorch. - - .. code-block:: bash - - ./.ci/pytorch/build.sh - - This converts PyTorch sources for - `HIP compatibility `_ and builds the - PyTorch framework. - - To check if your build is successful, run: - - .. code-block:: bash - - echo $? # should return 0 if success - -Testing the PyTorch installation -=============================================================== - -You can use PyTorch unit tests to validate your PyTorch installation. If you used a -**prebuilt PyTorch Docker image from AMD ROCm Docker Hub** or installed an -**official wheels package**, validation tests are not necessary. - -If you want to manually run unit tests to validate your PyTorch installation fully, follow these steps: - -1. Import the torch package in Python to test if PyTorch is installed and accessible. - - .. note:: - - Do not run the following command in the PyTorch git folder. - - .. code-block:: bash - - python3 -c 'import torch' 2> /dev/null && echo 'Success' || echo 'Failure' - -2. Check if the GPU is accessible from PyTorch. In the PyTorch framework, ``torch.cuda`` is a generic way - to access the GPU. This can only access an AMD GPU if one is available. - - .. code-block:: bash - - python3 -c 'import torch; print(torch.cuda.is_available())' - - -3. Run unit tests to validate the PyTorch installation fully. - - .. note:: - - You must run the following command from the PyTorch home directory. - - .. code-block:: bash - - PYTORCH_TEST_WITH_ROCM=1 python3 test/run_test.py --verbose \ - --include test_nn test_torch test_cuda test_ops \ - test_unary_ufuncs test_binary_ufuncs test_autograd - - This command ensures that the required environment variable is set to skip certain unit tests for - ROCm. This also applies to wheel installs in a non-controlled environment. - - .. note:: - - Make sure your PyTorch source code corresponds to the PyTorch wheel or the installation in the - Docker image. Incompatible PyTorch source code can give errors when running unit tests. - - Some tests may be skipped, as appropriate, based on your system configuration. ROCm doesn't - support all PyTorch features; tests that evaluate unsupported features are skipped. Other tests might - be skipped, depending on the host or GPU memory and the number of available GPUs. - - If the compilation and installation are correct, all tests will pass. - -4. Run individual unit tests. - - .. code-block:: bash - - PYTORCH_TEST_WITH_ROCM=1 python3 test/test_nn.py --verbose - - You can replace ``test_nn.py`` with any other test set. - -Running a basic PyTorch example -=============================================================== - -The PyTorch examples repository provides basic examples that exercise the functionality of your -framework. - -Two of our favorite testing databases are: - -* **MNIST** (Modified National Institute of Standards and Technology): A database of handwritten - digits that can be used to train a Convolutional Neural Network for **handwriting recognition**. -* **ImageNet**: A database of images that can be used to train a network for - **visual object recognition**. - -MNIST PyTorch example ---------------------------------------------------------------------------------------------------------- - -1. Clone the PyTorch examples repository. - - .. code-block:: bash - - git clone https://github.com/pytorch/examples.git - -2. Go to the MNIST example folder. - - .. code-block:: bash - - cd examples/mnist - -3. Follow the instructions in the ``README.md`` file in this folder to install the requirements. Then run: - - .. code-block:: bash - - python3 main.py - - This generates the following output: - - .. code-block:: - - ... - Train Epoch: 14 [58240/60000 (97%)] Loss: 0.010128 - Train Epoch: 14 [58880/60000 (98%)] Loss: 0.001348 - Train Epoch: 14 [59520/60000 (99%)] Loss: 0.005261 - - Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) - -ImageNet PyTorch example ---------------------------------------------------------------------------------------------------------- - -1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST - example). - - .. code-block:: bash - - git clone https://github.com/pytorch/examples.git - -2. Go to the ImageNet example folder. - - .. code-block:: bash - - cd examples/imagenet - -3. Follow the instructions in the ``README.md`` file in this folder to install the Requirements. Then run: - - .. code-block:: bash - - python3 main.py +If a pre-built wheel is not available to match your specific Python, PyTorch, and ROCm versions, +you can build and install PyTorch from source. See the `official build instructions `_ for details. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index d77f3362..365d1844 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -31,9 +31,18 @@ subtrees: - caption: Tutorials entries: + - file: how-to/3rd-party/pytorch-index + title: PyTorch + subtrees: + - entries: + - file: how-to/3rd-party/pytorch-install + title: Install PyTorch + - file: how-to/3rd-party/pytorch-docker + title: PyTorch + Docker + - file: how-to/3rd-party/magma-install title: Install Magma - - file: how-to/3rd-party/pytorch-install + - file: how-to/3rd-party/pytorch-install-old title: Install PyTorch - file: how-to/3rd-party/tensorflow-install title: Install TensorFlow From ccb970550d4031545a8bb3ad7d34a001cb5a752b Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 14:40:14 -0700 Subject: [PATCH 08/17] Add MIOpen kdb instructions to bottom of install --- docs/how-to/3rd-party/pytorch-install.rst | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch-install.rst index a04c562b..9e73b591 100644 --- a/docs/how-to/3rd-party/pytorch-install.rst +++ b/docs/how-to/3rd-party/pytorch-install.rst @@ -90,3 +90,39 @@ Install From Source If a pre-built wheel is not available to match your specific Python, PyTorch, and ROCm versions, you can build and install PyTorch from source. See the `official build instructions `_ for details. + +[Optional] Installing pre-compiled MIOpen kernels +-------------------------------------------------- + +PyTorch uses `MIOpen `_ for machine learning +primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up +phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up +application warm-up phases. + +MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in +a specific location with respect to the PyTorch installation path. A helper script simplifies this task by +taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. + +.. note:: + + Installing pre-compiled MIOpen kernels can speed up warm-up, but will not affect performance after the + initial warm-up. Additionally, as MIOpen caches kernels, this warm-up cost is only paid once. + +To install MIOpen kbd files for pytorch, run: + +.. code-block:: shell + + wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh + + #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version + export GFX_ARCH=gfx90a + export ROCM_VERSION=5.6 + + ./install_kdb_files_for_pytorch_wheels.sh + +Further reading: + +* `Using MIOpen kbd files with PyTorch Wheels `_ +* `MIOpen Docs `_ +* `Installing pre-compiled MIOpen kernels `_ +* `MIOpen repo `_ From 24d51825a873313ce524b2e1c871e84c14e588b1 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 13 Mar 2024 14:48:10 -0700 Subject: [PATCH 09/17] Further consolidate pytorch/docker instructions --- docs/how-to/3rd-party/pytorch-docker.rst | 49 -- docs/how-to/3rd-party/pytorch-install-old.rst | 478 ------------------ docs/how-to/3rd-party/pytorch-install.rst | 132 ++++- docs/sphinx/_toc.yml.in | 1 + 4 files changed, 130 insertions(+), 530 deletions(-) delete mode 100644 docs/how-to/3rd-party/pytorch-install-old.rst diff --git a/docs/how-to/3rd-party/pytorch-docker.rst b/docs/how-to/3rd-party/pytorch-docker.rst index 93fc17d7..ed8ff4a4 100644 --- a/docs/how-to/3rd-party/pytorch-docker.rst +++ b/docs/how-to/3rd-party/pytorch-docker.rst @@ -66,52 +66,3 @@ Below is an example ``dockerfile`` based on ``rocm/dev-ubuntu-22.04:5.7`` * Using ARGs can help simplify your dockerfiles, and prevent version mismatches * Use specific versions, rather than ``latest``, to help keep builds reproducible. This also applies to python packages. * It is always a good idea to use virtual environments, *even inside docker*! - -Building PyTorch from source -............................ - -You may need to install a version of pytorch which is not available as a pre-built binary. In this case, you can build and install PyTorch from source. - -For details, see :ref:`building pytorch from source `_. - -.. literalinclude:: ../../docker_examples/torch/dockerfile_from_base - :language: dockerfile - - -From scratch -............ - -Using Dependency Managers (PDM) -............................... - -Using Pre-Compiled MIOpen KDB Files -=================================== - - - -PyTorch uses MIOpen for machine learning primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up application warm-up phases. - -.. tip:: - - The MIOpen installation script takes time. - -MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in a specific location with respect to the PyTorch installation path. A helper script simplifies this task by taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. - -You can download the helper script here: install_kdb_files_for_pytorch_wheels.sh, or use: - -.. code-block:: bash - - wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh - - #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version - export GFX_ARCH=gfx90a # Limiting architectures can greatly speed up install time - export ROCM_VERSION=5.6 - - ./install_kdb_files_for_pytorch_wheels.sh - -LINKS: - -* https://github.com/ROCm/pytorch/wiki/Using-MIOpen-kdb-files-with-ROCm-PyTorch-wheels -* https://docs.amd.com/projects/MIOpen/en/latest/#installing-miopen-kernels-package -* https://docs.amd.com/projects/MIOpen/en/latest/cache.html#installing-pre-compiled-kernels -* https://github.com/ROCm/MIOpen diff --git a/docs/how-to/3rd-party/pytorch-install-old.rst b/docs/how-to/3rd-party/pytorch-install-old.rst deleted file mode 100644 index c10c3ce2..00000000 --- a/docs/how-to/3rd-party/pytorch-install-old.rst +++ /dev/null @@ -1,478 +0,0 @@ -.. meta:: - :description: Installing PyTorch for ROCm - :keywords: installation instructions, PyTorch, AMD, ROCm - -********************************************************************************** -Installing PyTorch for ROCm -********************************************************************************** - -`PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on -ROCm provides mixed-precision and large-scale training using our -`MIOpen `_ and -`RCCL `_ libraries. - -To install -`PyTorch for ROCm `_, -you have the following options: - -* :ref:`using-docker-with-pytorch-pre-installed` - (recommended) -* :ref:`using-wheels-package` -* :ref:`using-pytorch-rocm-docker-image` -* :ref:`using-pytorch-upstream-docker-image` - -For hardware, software, and third-party framework compatibility between ROCm and PyTorch, refer to: - -* :ref:`system-requirements` -* :ref:`3rd-party-support-matrix` - -.. _using-docker-with-pytorch-pre-installed: - -Using a Docker image with PyTorch pre-installed -=============================================================== - -1. Download the latest public `PyTorch Docker image `_. - - .. code-block:: bash - - docker pull rocm/pytorch:latest - - You can also download a specific and supported configuration with different user-space ROCm - versions, PyTorch versions, and operating systems. - -2. Start a Docker container using the image. - - .. code-block:: bash - - docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ - --device=/dev/kfd --device=/dev/dri --group-add video \ - --ipc=host --shm-size 8G rocm/pytorch:latest - - .. note:: - - This will automatically download the image if it does not exist on the host. You can also pass the ``-v`` - argument to mount any data directories from the host onto the container. - -.. _install_pytorch_wheels: -.. _using-wheels-package: - -Using a wheels package -=============================================================== - -PyTorch supports the ROCm platform by providing tested wheels packages. To access this feature, go -to `pytorch.org/get-started/locally/ `_. For the correct -wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matrix. - -1. Choose one of the following three options: - - **Option 1:** - - a. Download a base Docker image with the correct user-space ROCm version. - - .. list-table:: - :header-rows: 1 - - * - Base OS - - Docker Image - * - Ubuntu 20.04 - - `rocm/dev-ubuntu-20.04 `_ - * - Ubuntu 22.04 - - `rocm/dev-ubuntu-22.04 `_ - * - CentOS 7 - - `rocm/dev-centos-7 `_ - - b. Pull the selected image. - - .. code-block:: bash - - docker pull rocm/dev-ubuntu-20.04:latest - - c. Start a Docker container using the downloaded image. - - .. code-block:: bash - - docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-20.04:latest - - **Option 2:** - - Select a base OS Docker image (Check :ref:`system-requirements`) - - Pull selected base OS image (Ubuntu 20.04 for example) - - .. code-block:: bash - - docker pull ubuntu:20.04 - - Start a Docker container using the downloaded image - - .. code-block:: bash - - docker run -it --device=/dev/kfd --device=/dev/dri --group-add video ubuntu:20.04 - - Install ROCm using the directions in the :ref:`rocm-install-overview` section. - - **Option 3:** - - Install on bare metal. Check :ref:`system-requirements` and install ROCm using the - directions in the :ref:`rocm-install-overview` section. - -2. Install the required dependencies for the wheels package. - - .. code-block:: bash - - sudo apt update - sudo apt install libjpeg-dev python3-dev python3-pip - pip3 install wheel setuptools - -3. Install ``torch``, ``torchvision``, and ``torchaudio``, as specified in the - `installation matrix `_. - - .. note:: - - The following command uses the ROCm 5.6 PyTorch wheel. If you want a different version of ROCm, - modify the command accordingly. - - .. code-block:: bash - - pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm5.6/ - -4. (Optional) Use MIOpen kdb files with ROCm PyTorch wheels. - - PyTorch uses `MIOpen `_ for machine learning - primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up - phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up - application warm-up phases. - - MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in - a specific location with respect to the PyTorch installation path. A helper script simplifies this task by - taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. - - You can download the helper script here: - `install_kdb_files_for_pytorch_wheels.sh `_, or use: - - .. code-block:: bash - - wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh - - After installing ROCm PyTorch wheels, run the following code: - - .. code-block:: bash - - #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version - export GFX_ARCH=gfx90a - - #Optional - export ROCM_VERSION=5.6 - - ./install_kdb_files_for_pytorch_wheels.sh - -.. _using-pytorch-rocm-docker-image: - -Using the PyTorch ROCm base Docker image -=============================================================== - -The pre-built base Docker image has all dependencies installed, including: - -* ROCm -* torchvision -* Conda packages -* The compiler toolchain - -Additionally, a particular environment flag (``BUILD_ENVIRONMENT``) is set, which is used by the build -scripts to determine the configuration of the build environment. - -1. Download the Docker image. This is the base image, which does not contain PyTorch. - - .. code-block:: bash - - docker pull rocm/pytorch:latest-base - -2. Start a Docker container using the downloaded image. - - .. code-block:: bash - - docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd --device=/dev/dri --group-add video --ipc=host --shm-size 8G rocm/pytorch:latest-base - - You can also pass the ``-v`` argument to mount any data directories from the host onto the container. - -3. Clone the PyTorch repository. - - .. code-block:: bash - - cd ~ - git clone https://github.com/pytorch/pytorch.git - cd /pytorch - git submodule update --init --recursive - -4. Set ROCm architecture (optional). The Docker image tag is ``rocm/pytorch:latest-base``. - - .. note:: - - By default in the ``rocm/pytorch:latest-base`` image, PyTorch builds simultaneously for the following - architectures: - * gfx900 - * gfx906 - * gfx908 - * gfx90a - * gfx1030 - - If you want to compile *only* for your microarchitecture (uarch), run: - - .. code-block:: bash - - export PYTORCH_ROCM_ARCH= - - Where ```` is the architecture reported by the ``rocminfo`` command. - - To find your uarch, run: - - .. code-block:: bash - - rocminfo | grep gfx - -5. Build PyTorch. - - .. code-block:: bash - - ./.ci/pytorch/build.sh - - This converts PyTorch sources for HIP compatibility and builds the PyTorch framework. - - To check if your build is successful, run: - - .. code-block:: bash - - echo $? # should return 0 if success - -.. _using-pytorch-upstream-docker-image: - -Using the PyTorch upstream Docker file -=============================================================== - -If you don't want to use a prebuilt base Docker image, you can build a custom base Docker image -using scripts from the PyTorch repository. This uses a standard Docker image from operating system -maintainers and installs all the required dependencies, including: - -* ROCm -* torchvision -* Conda packages -* The compiler toolchain - -1. Clone the PyTorch repository. - - .. code-block:: bash - - cd ~ - git clone https://github.com/pytorch/pytorch.git - cd /pytorch - git submodule update --init --recursive - -2. Build the PyTorch Docker image. - - .. code-block:: bash - - cd .ci/docker - ./build.sh pytorch-linux--rocm-py -t rocm/pytorch:build_from_dockerfile - - Where: - * ````: ``ubuntu20.04`` (or ``focal``), ``ubuntu22.04`` (or ``jammy``), ``centos7.5``, or ``centos9`` - * ````: ``5.4``, ``5.5``, or ``5.6`` - * ````: ``3.8`` - ``3.11`` - - To verify that your image was successfully created, run: - - .. code-block:: bash - - docker image ls rocm/pytorch:build_from_dockerfile - - If successful, the output looks like this: - - .. code-block:: bash - - REPOSITORY TAG IMAGE ID CREATED SIZE - rocm/pytorch build_from_dockerfile 17071499be47 2 minutes ago 32.8GB - -3. Start a Docker container using the image with the mounted PyTorch folder. - - .. code-block:: bash - - docker run -it --cap-add=SYS_PTRACE --security-opt --user root \ - seccomp=unconfined --device=/dev/kfd --device=/dev/dri \ - --group-add video --ipc=host --shm-size 8G \ - -v ~/pytorch:/pytorch rocm/pytorch:build_from_dockerfile - - You can also pass the ``-v`` argument to mount any data directories from the host onto the container. - -4. Go to the PyTorch directory. - - .. code-block:: bash - - cd pytorch - -5. Set ROCm architecture. - - To determine your AMD architecture, run: - - .. code-block:: bash - - rocminfo | grep gfx - - The result looks like this (for ``gfx1030`` architecture): - - .. code-block:: bash - - Name: gfx1030 - Name: amdgcn-amd-amdhsa--gfx1030 - - Set the ``PYTORCH_ROCM_ARCH`` environment variable to specify the architectures you want to - build PyTorch for. - - .. code-block:: bash - - export PYTORCH_ROCM_ARCH= - - where ```` is the architecture reported by the ``rocminfo`` command. - -6. Build PyTorch. - - .. code-block:: bash - - ./.ci/pytorch/build.sh - - This converts PyTorch sources for - `HIP compatibility `_ and builds the - PyTorch framework. - - To check if your build is successful, run: - - .. code-block:: bash - - echo $? # should return 0 if success - -Testing the PyTorch installation -=============================================================== - -You can use PyTorch unit tests to validate your PyTorch installation. If you used a -**prebuilt PyTorch Docker image from AMD ROCm Docker Hub** or installed an -**official wheels package**, validation tests are not necessary. - -If you want to manually run unit tests to validate your PyTorch installation fully, follow these steps: - -1. Import the torch package in Python to test if PyTorch is installed and accessible. - - .. note:: - - Do not run the following command in the PyTorch git folder. - - .. code-block:: bash - - python3 -c 'import torch' 2> /dev/null && echo 'Success' || echo 'Failure' - -2. Check if the GPU is accessible from PyTorch. In the PyTorch framework, ``torch.cuda`` is a generic way - to access the GPU. This can only access an AMD GPU if one is available. - - .. code-block:: bash - - python3 -c 'import torch; print(torch.cuda.is_available())' - - -3. Run unit tests to validate the PyTorch installation fully. - - .. note:: - - You must run the following command from the PyTorch home directory. - - .. code-block:: bash - - PYTORCH_TEST_WITH_ROCM=1 python3 test/run_test.py --verbose \ - --include test_nn test_torch test_cuda test_ops \ - test_unary_ufuncs test_binary_ufuncs test_autograd - - This command ensures that the required environment variable is set to skip certain unit tests for - ROCm. This also applies to wheel installs in a non-controlled environment. - - .. note:: - - Make sure your PyTorch source code corresponds to the PyTorch wheel or the installation in the - Docker image. Incompatible PyTorch source code can give errors when running unit tests. - - Some tests may be skipped, as appropriate, based on your system configuration. ROCm doesn't - support all PyTorch features; tests that evaluate unsupported features are skipped. Other tests might - be skipped, depending on the host or GPU memory and the number of available GPUs. - - If the compilation and installation are correct, all tests will pass. - -4. Run individual unit tests. - - .. code-block:: bash - - PYTORCH_TEST_WITH_ROCM=1 python3 test/test_nn.py --verbose - - You can replace ``test_nn.py`` with any other test set. - -Running a basic PyTorch example -=============================================================== - -The PyTorch examples repository provides basic examples that exercise the functionality of your -framework. - -Two of our favorite testing databases are: - -* **MNIST** (Modified National Institute of Standards and Technology): A database of handwritten - digits that can be used to train a Convolutional Neural Network for **handwriting recognition**. -* **ImageNet**: A database of images that can be used to train a network for - **visual object recognition**. - -MNIST PyTorch example ---------------------------------------------------------------------------------------------------------- - -1. Clone the PyTorch examples repository. - - .. code-block:: bash - - git clone https://github.com/pytorch/examples.git - -2. Go to the MNIST example folder. - - .. code-block:: bash - - cd examples/mnist - -3. Follow the instructions in the ``README.md`` file in this folder to install the requirements. Then run: - - .. code-block:: bash - - python3 main.py - - This generates the following output: - - .. code-block:: - - ... - Train Epoch: 14 [58240/60000 (97%)] Loss: 0.010128 - Train Epoch: 14 [58880/60000 (98%)] Loss: 0.001348 - Train Epoch: 14 [59520/60000 (99%)] Loss: 0.005261 - - Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) - -ImageNet PyTorch example ---------------------------------------------------------------------------------------------------------- - -1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST - example). - - .. code-block:: bash - - git clone https://github.com/pytorch/examples.git - -2. Go to the ImageNet example folder. - - .. code-block:: bash - - cd examples/imagenet - -3. Follow the instructions in the ``README.md`` file in this folder to install the Requirements. Then run: - - .. code-block:: bash - - python3 main.py diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch-install.rst index 9e73b591..f5752679 100644 --- a/docs/how-to/3rd-party/pytorch-install.rst +++ b/docs/how-to/3rd-party/pytorch-install.rst @@ -3,7 +3,7 @@ :keywords: installation instructions, PyTorch, AMD, ROCm ********************************************************************************** -PyTorch for ROCm +Installing PyTorch for ROCm ********************************************************************************** `PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on @@ -122,7 +122,133 @@ To install MIOpen kbd files for pytorch, run: Further reading: -* `Using MIOpen kbd files with PyTorch Wheels `_ * `MIOpen Docs `_ -* `Installing pre-compiled MIOpen kernels `_ * `MIOpen repo `_ +* `Installing pre-compiled MIOpen kernels `_ +* `Using MIOpen kbd files with PyTorch Wheels `_ + +Testing the PyTorch installation +--------------------------------- + +You can use PyTorch unit tests to validate your PyTorch installation. + +If you want to manually run unit tests to validate your PyTorch installation fully, follow these steps: + +1. Import the torch package in Python to test if PyTorch is installed and accessible. + + .. note:: + + Do not run the following command in the PyTorch git folder. + + .. code-block:: bash + + python3 -c 'import torch' 2> /dev/null && echo 'Success' || echo 'Failure' + +2. Check if the GPU is accessible from PyTorch. In the PyTorch framework, ``torch.cuda`` is a generic way + to access the GPU. This can only access an AMD GPU if one is available. + + .. code-block:: bash + + python3 -c 'import torch; print(torch.cuda.is_available())' + + +3. Run unit tests to validate the PyTorch installation fully. + + .. note:: + + You must run the following command from the PyTorch home directory. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/run_test.py --verbose \ + --include test_nn test_torch test_cuda test_ops \ + test_unary_ufuncs test_binary_ufuncs test_autograd + + This command ensures that the required environment variable is set to skip certain unit tests for + ROCm. This also applies to wheel installs in a non-controlled environment. + + .. note:: + + Make sure your PyTorch source code corresponds to the PyTorch wheel or the installation in the + Docker image. Incompatible PyTorch source code can give errors when running unit tests. + + Some tests may be skipped, as appropriate, based on your system configuration. ROCm doesn't + support all PyTorch features; tests that evaluate unsupported features are skipped. Other tests might + be skipped, depending on the host or GPU memory and the number of available GPUs. + + If the compilation and installation are correct, all tests will pass. + +4. Run individual unit tests. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/test_nn.py --verbose + + You can replace ``test_nn.py`` with any other test set. + +Running a basic PyTorch example +--------------------------------- + +The PyTorch examples repository provides basic examples that exercise the functionality of your +framework. + +Two of our favorite testing databases are: + +* **MNIST** (Modified National Institute of Standards and Technology): A database of handwritten + digits that can be used to train a Convolutional Neural Network for **handwriting recognition**. +* **ImageNet**: A database of images that can be used to train a network for + **visual object recognition**. + +MNIST PyTorch example +....................... + +1. Clone the PyTorch examples repository. + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the MNIST example folder. + + .. code-block:: bash + + cd examples/mnist + +3. Follow the instructions in the ``README.md`` file in this folder to install the requirements. Then run: + + .. code-block:: bash + + python3 main.py + + This generates the following output: + + .. code-block:: + + ... + Train Epoch: 14 [58240/60000 (97%)] Loss: 0.010128 + Train Epoch: 14 [58880/60000 (98%)] Loss: 0.001348 + Train Epoch: 14 [59520/60000 (99%)] Loss: 0.005261 + + Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) + +ImageNet PyTorch example +............................ + +1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST + example). + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the ImageNet example folder. + + .. code-block:: bash + + cd examples/imagenet + +3. Follow the instructions in the ``README.md`` file in this folder to install the Requirements. Then run: + + .. code-block:: bash + + python3 main.py diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 365d1844..f40f55f8 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -40,6 +40,7 @@ subtrees: - file: how-to/3rd-party/pytorch-docker title: PyTorch + Docker + - file: how-to/3rd-party/magma-install title: Install Magma - file: how-to/3rd-party/pytorch-install-old From 0dd3ed77aeba58291002d4b3dc3bbd411020a7c3 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Thu, 14 Mar 2024 10:49:36 -0700 Subject: [PATCH 10/17] Improve torch docs --- docs/how-to/3rd-party/pytorch-index.rst | 2 - .../docker.rst} | 0 docs/how-to/3rd-party/pytorch/index.rst | 29 ++++++++++ .../install.rst} | 58 +++++++++++++++---- docs/sphinx/_toc.yml.in | 6 +- 5 files changed, 78 insertions(+), 17 deletions(-) delete mode 100644 docs/how-to/3rd-party/pytorch-index.rst rename docs/how-to/3rd-party/{pytorch-docker.rst => pytorch/docker.rst} (100%) create mode 100644 docs/how-to/3rd-party/pytorch/index.rst rename docs/how-to/3rd-party/{pytorch-install.rst => pytorch/install.rst} (83%) diff --git a/docs/how-to/3rd-party/pytorch-index.rst b/docs/how-to/3rd-party/pytorch-index.rst deleted file mode 100644 index c7f409af..00000000 --- a/docs/how-to/3rd-party/pytorch-index.rst +++ /dev/null @@ -1,2 +0,0 @@ -PyTorch -======== diff --git a/docs/how-to/3rd-party/pytorch-docker.rst b/docs/how-to/3rd-party/pytorch/docker.rst similarity index 100% rename from docs/how-to/3rd-party/pytorch-docker.rst rename to docs/how-to/3rd-party/pytorch/docker.rst diff --git a/docs/how-to/3rd-party/pytorch/index.rst b/docs/how-to/3rd-party/pytorch/index.rst new file mode 100644 index 00000000..26987cd3 --- /dev/null +++ b/docs/how-to/3rd-party/pytorch/index.rst @@ -0,0 +1,29 @@ +.. meta:: + :description: Pytorch+ROcm + :keywords: PyTorch, ROCm + +.. _pytorch-home: + +**************************************************************** +PyTorch +**************************************************************** + +`PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on +ROCm provides mixed-precision and large-scale training using our +`MIOpen `_ and +`RCCL `_ libraries. + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: Install PyTorch + :link: how-to/3rd-party/pytorch/install + :link-type: doc + + PyTorch installation instructions + + .. grid-item-card:: PyTorch + Docker + :link: how-to/3rd-party/pytorch/docker + :link-type: doc + + Running PyTorch in Docker diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch/install.rst similarity index 83% rename from docs/how-to/3rd-party/pytorch-install.rst rename to docs/how-to/3rd-party/pytorch/install.rst index f5752679..f30fe8dc 100644 --- a/docs/how-to/3rd-party/pytorch-install.rst +++ b/docs/how-to/3rd-party/pytorch/install.rst @@ -11,41 +11,75 @@ ROCm provides mixed-precision and large-scale training using our `MIOpen `_ and `RCCL `_ libraries. +Install from pre-built wheels +----------------------------- +PyTorch supports the ROCm platform by providing pre-built wheels packages for a variety of PyTorch and ROCm versions. -Installation (Pip) ------------------- +.. Warning:: -PyTorch supports the ROCm platform by providing pre-built wheels packages for a variety of PyTorch and ROCm versions. To install the -latest version: + **Make sure the PyTorch version you install was compiled for your ROCm version!** If there is a mismatch, you may experience + performace degredation or errors. + +The Major and Minor versions must match, but different Patch versions are acceptable. For example, PyTorch 2.2.1+ROCm6.0 will work with ROCm 6.0.1, but not 6.1, or 5.7. + +To check your rocm version: + +.. code-block:: shell + + $ rocm-smi -V + ROCM-SMI-LIB version: 5.7.0 + +Latest Stable +============= +To install the latest version: * Navigate to `pytorch.org/get-started/locally/ `_. * Select ``Stable``, ``Linux``, ``Pip``, ``Python``, and ``ROCm`` -You should see ``pip3 install`` commmand + * The ``ROCm`` box will indicate which ROCm version these wheels were built for + +You should see a ``pip3 install`` commmand: .. code-block:: shell pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm5.7 + .. Note:: + **PyTorch typically only builds the latest stable builds against a single version of ROCm.** If this ROCm version + does not match your needs, see :ref:`torch-nightly` or :ref:`torch-additional-versions` below. + +.. Tip:: + You should use a virtual environment when installing python packages in order to separate dependencies from the system and other projects. -Additional Versions -................... +.. _torch-nightly: + +Nightly +======= + +In addition to stable wheels, PyTorch also publishes nightly builds, which *may* be against a newer version of ROCm. Nightly builds can be a great way +to get access to newer features. -In addition to the latest stable version, you can also install new, preview versions, as well as older versions. +To install from nightly: -* Preview (Nightly): Select ``Preview (Nightly)`` from the `installation matrix `_ +* Navigate to `pytorch.org/get-started/locally/ `_. +* Select **``Nightly``**, ``Linux``, ``Pip``, ``Python``, and ``ROCm`` + +.. _torch-additional-versions: + +Additional Versions +=================== -* Previous versions: You can search for previous versions on `PyTorch's docs here `_ +In addition to the latest stable and nightly wheels, you can search for previous versions on `PyTorch's docs here `_ - Make sure to search for the appropriate ROCm version +**Make sure to search for the appropriate ROCm version** Other Package Managers -...................... +----------------------- You can also use more sophisticated dependency management tools like PDM and Poetry. These tools provide several benefits over ``pip``, including automatic creation of virtual environments, complex dependency resolution, lockfiles, and more. diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index f40f55f8..9f121d28 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -31,13 +31,13 @@ subtrees: - caption: Tutorials entries: - - file: how-to/3rd-party/pytorch-index + - file: how-to/3rd-party/pytorch/index title: PyTorch subtrees: - entries: - - file: how-to/3rd-party/pytorch-install + - file: how-to/3rd-party/pytorch/install title: Install PyTorch - - file: how-to/3rd-party/pytorch-docker + - file: how-to/3rd-party/pytorch/docker title: PyTorch + Docker From 5acbf7ebc682cf7fb9735b6f68582f90419fc8a5 Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Thu, 14 Mar 2024 10:57:17 -0700 Subject: [PATCH 11/17] torch docker: add docker-compose --- docs/how-to/3rd-party/pytorch/docker.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/how-to/3rd-party/pytorch/docker.rst b/docs/how-to/3rd-party/pytorch/docker.rst index ed8ff4a4..6b204169 100644 --- a/docs/how-to/3rd-party/pytorch/docker.rst +++ b/docs/how-to/3rd-party/pytorch/docker.rst @@ -22,11 +22,26 @@ Regardless of which image you use or build, running PyTorch docker images requir docker run -it --device=/dev/fkd --device=/dev/dri --security-opt seccomp=unconfined --ipc=host +Alternatively, you can use the equivalent ``docker-compose.yaml``: + +.. code-block:: yaml + + version: "3.7" + services: + my-service: + image: + device: + - /dev/fdk + - /dev/dri + security_opt: + - seccomp:unconfined + ipc: host + Pre-Built PyTorch+ROCm Docker Images -------------------------------------- -The easiest method to run PyTorch+ROCm is to use a pre-built image from `AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. +The easiest method to run PyTorch+ROCm is to use a pre-built image from ``AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. * `rocm/pytorch `_ - latest stable builds * `rocm/pytorch-nightly `_ - latest nightly builds From bd5f913cfd0be04c75c6e3735288753e00719b4f Mon Sep 17 00:00:00 2001 From: Logan Grado Date: Wed, 20 Mar 2024 09:16:55 -0700 Subject: [PATCH 12/17] Fix formatting errors --- .../torch/dockerfile_from_dev_ubuntu | 2 +- docs/how-to/3rd-party/pytorch/docker.rst | 15 ++++++-- docs/how-to/3rd-party/pytorch/install.rst | 38 +++++++++---------- 3 files changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/docker_examples/torch/dockerfile_from_dev_ubuntu b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu index 6164b219..39df3f2b 100644 --- a/docs/docker_examples/torch/dockerfile_from_dev_ubuntu +++ b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu @@ -20,7 +20,7 @@ RUN python3.11 -m venv venv ENV PATH=/venv/bin:$PATH # Install Pytorch -RUN --mount=type=cache,target=/root/.cache/pip pip3 install torch==2.2.1 torchvision==0.17.1 --index-url https://download.pytorch.org/whl/rocm$ROCM_VERSION/ +RUN pip3 install torch==2.2.1 torchvision==0.17.1 --index-url https://download.pytorch.org/whl/rocm$ROCM_VERSION/ # Install additional python dependencies RUN pip3 install transformers==4.38.2 diff --git a/docs/how-to/3rd-party/pytorch/docker.rst b/docs/how-to/3rd-party/pytorch/docker.rst index 6b204169..3729ccb6 100644 --- a/docs/how-to/3rd-party/pytorch/docker.rst +++ b/docs/how-to/3rd-party/pytorch/docker.rst @@ -20,7 +20,9 @@ Regardless of which image you use or build, running PyTorch docker images requir .. code-block:: bash - docker run -it --device=/dev/fkd --device=/dev/dri --security-opt seccomp=unconfined --ipc=host + docker run -it --device=/dev/fkd --device=/dev/dri \ + --security-opt seccomp=unconfined --ipc=host \ + Alternatively, you can use the equivalent ``docker-compose.yaml``: @@ -41,7 +43,7 @@ Alternatively, you can use the equivalent ``docker-compose.yaml``: Pre-Built PyTorch+ROCm Docker Images -------------------------------------- -The easiest method to run PyTorch+ROCm is to use a pre-built image from ``AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. +The easiest method to run PyTorch+ROCm is to use a pre-built image from `AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. * `rocm/pytorch `_ - latest stable builds * `rocm/pytorch-nightly `_ - latest nightly builds @@ -50,8 +52,13 @@ For example, to run the latest rocm/pytorch image, run: .. code-block:: bash - docker run -it --device=/dev/fkd --device=/dev/dri --security-opt seccomp=unconfined --ipc=host rocm/pytorch:latest + docker run -it --device=/dev/fkd --device=/dev/dri \ + --security-opt seccomp=unconfined --ipc=host \ + rocm/pytorch:rocm6.0.2_ubuntu22.04_py3.10_pytorch_2.1.2 +.. Tip:: + + Always use a specific tag (e.g. ``rocm6.0.2_ubuntu22.04_py3.10_pytorch_2.1.2``) over ``latest``! Otherwise, the image may change without your knowledge. Custom Docker Images -------------------- @@ -73,7 +80,7 @@ We provide several dev containers, which contain just the base OS + ROCm. These Below is an example ``dockerfile`` based on ``rocm/dev-ubuntu-22.04:5.7`` -.. literalinclude:: ../../docker_examples/torch/dockerfile_from_dev_ubuntu +.. literalinclude:: ../../../docker_examples/torch/dockerfile_from_dev_ubuntu :language: dockerfile .. tip:: diff --git a/docs/how-to/3rd-party/pytorch/install.rst b/docs/how-to/3rd-party/pytorch/install.rst index f30fe8dc..ca095f01 100644 --- a/docs/how-to/3rd-party/pytorch/install.rst +++ b/docs/how-to/3rd-party/pytorch/install.rst @@ -12,7 +12,7 @@ ROCm provides mixed-precision and large-scale training using our `RCCL `_ libraries. Install from pre-built wheels ------------------------------ +============================= PyTorch supports the ROCm platform by providing pre-built wheels packages for a variety of PyTorch and ROCm versions. @@ -31,7 +31,8 @@ To check your rocm version: ROCM-SMI-LIB version: 5.7.0 Latest Stable -============= +------------- + To install the latest version: * Navigate to `pytorch.org/get-started/locally/ `_. @@ -59,7 +60,7 @@ You should see a ``pip3 install`` commmand: .. _torch-nightly: Nightly -======= +------- In addition to stable wheels, PyTorch also publishes nightly builds, which *may* be against a newer version of ROCm. Nightly builds can be a great way to get access to newer features. @@ -72,20 +73,26 @@ To install from nightly: .. _torch-additional-versions: Additional Versions -=================== +------------------- In addition to the latest stable and nightly wheels, you can search for previous versions on `PyTorch's docs here `_ **Make sure to search for the appropriate ROCm version** +Install From Source +=================== + +If a pre-built wheel is not available to match your specific Python, PyTorch, and ROCm versions, +you can build and install PyTorch from source. See the `official build instructions `_ for details. + Other Package Managers ------------------------ +======================= You can also use more sophisticated dependency management tools like PDM and Poetry. These tools provide several benefits over ``pip``, including automatic creation of virtual environments, complex dependency resolution, lockfiles, and more. `PDM `_ -++++++++++++++++++++++++++++++++++++++++++++++ +------------------------------------------- * Add the ``index-url`` from above as a `source `_ by adding the following lines to your ``pyproject.toml`` file: @@ -104,8 +111,7 @@ automatic creation of virtual environments, complex dependency resolution, lockf PDM will then first look in the proided source to install any package, before falling back to `pypi.org `_. `Poetry `_ -++++++++++++++++++++++++++++++++++++++++++++ - +---------------------------------------------- * Add the ``index-url`` from above as a `source `_: @@ -119,14 +125,8 @@ PDM will then first look in the proided source to install any package, before fa poetry add torch --source torch-index -Install From Source --------------------- - -If a pre-built wheel is not available to match your specific Python, PyTorch, and ROCm versions, -you can build and install PyTorch from source. See the `official build instructions `_ for details. - [Optional] Installing pre-compiled MIOpen kernels --------------------------------------------------- +=================================================== PyTorch uses `MIOpen `_ for machine learning primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up @@ -162,7 +162,7 @@ Further reading: * `Using MIOpen kbd files with PyTorch Wheels `_ Testing the PyTorch installation ---------------------------------- +================================= You can use PyTorch unit tests to validate your PyTorch installation. @@ -221,7 +221,7 @@ If you want to manually run unit tests to validate your PyTorch installation ful You can replace ``test_nn.py`` with any other test set. Running a basic PyTorch example ---------------------------------- +================================ The PyTorch examples repository provides basic examples that exercise the functionality of your framework. @@ -234,7 +234,7 @@ Two of our favorite testing databases are: **visual object recognition**. MNIST PyTorch example -....................... +------------------------ 1. Clone the PyTorch examples repository. @@ -266,7 +266,7 @@ MNIST PyTorch example Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) ImageNet PyTorch example -............................ +---------------------------- 1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST example). From bd766c4a06e4298404f91af96e77af5dd4eb6a88 Mon Sep 17 00:00:00 2001 From: Peter Jun Park Date: Fri, 26 Apr 2024 12:59:58 -0400 Subject: [PATCH 13/17] Fix merge conflict: gh actions --- .github/dependabot.yml | 5 +++++ .github/workflows/linting.yml | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 69f6d30d..c4b67ec3 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -11,3 +11,8 @@ updates: schedule: interval: "daily" versioning-strategy: increase + labels: + - "documentation" + - "dependencies" + reviewers: + - "samjwu" diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 90c3cbc1..88ff147d 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -17,4 +17,4 @@ on: jobs: call-workflow-passing-data: name: Documentation - uses: RadeonOpenCompute/rocm-docs-core/.github/workflows/linting.yml@develop + uses: ROCm/rocm-docs-core/.github/workflows/linting.yml@develop From 64e010c767eb5e954f604ac9cbf8565bc320cec1 Mon Sep 17 00:00:00 2001 From: Peter Jun Park Date: Fri, 26 Apr 2024 14:10:47 -0400 Subject: [PATCH 14/17] Revert "Merge remote-tracking branch 'upstream/torch_update' into torch_update" This reverts commit e84c48f989928356d1418247d3215664c44f8c9f, reversing changes made to 55c77b97878799b0789aedfa1b43bd914dbc2391. --- .wordlist.txt | 1 + README.md | 7 +- docs/conf.py | 16 +- docs/how-to/3rd-party/jax-install.rst | 108 ++++ docs/how-to/3rd-party/pytorch-install.rst | 481 ++++++++++++++++++ docs/how-to/amdgpu-install.rst | 108 ++-- docs/how-to/docker.rst | 20 +- docs/how-to/native-install/index.rst | 28 +- docs/how-to/native-install/install-faq.rst | 93 ++++ docs/how-to/native-install/rhel.rst | 99 +++- docs/how-to/native-install/sles.rst | 64 ++- docs/how-to/native-install/ubuntu.rst | 87 ++++ docs/how-to/prerequisites.rst | 43 +- docs/how-to/spack.rst | 2 +- docs/index.rst | 16 +- docs/reference/3rd-party-support-matrix.rst | 100 ++-- docs/reference/system-requirements.rst | 17 +- .../user-kernel-space-compat-matrix.rst | 5 +- docs/sphinx/_toc.yml.in | 14 +- docs/sphinx/requirements.txt | 10 +- docs/tutorial/quick-start.rst | 283 +++++------ 21 files changed, 1254 insertions(+), 348 deletions(-) create mode 100644 docs/how-to/3rd-party/jax-install.rst create mode 100644 docs/how-to/3rd-party/pytorch-install.rst create mode 100644 docs/how-to/native-install/install-faq.rst diff --git a/.wordlist.txt b/.wordlist.txt index 3644272e..408c2f02 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,2 +1,3 @@ ROCmVersionWithoutCommas TensorFlowVersion +dkms diff --git a/README.md b/README.md index d80d1f36..0dc98b3c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # ROCm installation documentation (Linux) -This repository contains installation instructions for ROCm on Linux, along with installation-related information. +This repository contains installation instructions for ROCm on Linux, along with installation-related +information. -For Windows-related installation information (HIP SDK), refer to the [Windows installation GitHub repository](https://github.com/ROCm/rocm-install-on-windows) or the [ROCm docs Windows install page](https://rocm.docs.amd.com/projects/install-on-windows/en/latest/). +For Windows-related installation information (HIP SDK), refer to the +[Windows installation GitHub repository](https://github.com/ROCm/rocm-install-on-windows) or the +[ROCm docs Windows install page](https://rocm.docs.amd.com/projects/install-on-windows/en/latest/). ## Building our documentation diff --git a/docs/conf.py b/docs/conf.py index cfec670f..4758745b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -5,10 +5,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html # ROCm version numbers -rocm_version = '6.0.2' -rocm_directory_version = '6.0.2' # in 6.0 rocm was located in /opt/rocm-6.0.0 -amdgpu_version = '6.0.2' # directory in https://repo.radeon.com/rocm/apt/ and https://repo.radeon.com/amdgpu-install/ -amdgpu_install_version = '6.0.60002-1' # version in https://repo.radeon.com/amdgpu-install/6.0.2/ubuntu/jammy/ +rocm_version = '6.1' +rocm_multi_versions = '6.1.0 6.0.2' +rocm_directory_version = '6.1.0' # in 6.0 rocm was located in /opt/rocm-6.0.0 +amdgpu_version = '6.1' # directory in https://repo.radeon.com/rocm/apt/ and https://repo.radeon.com/amdgpu-install/ +amdgpu_install_version = '6.1.60100-1' # version in https://repo.radeon.com/amdgpu-install/6.0.2/ubuntu/jammy/ latex_engine = "xelatex" latex_elements = { @@ -23,8 +24,8 @@ project = "ROCm installation on Linux" author = "Advanced Micro Devices, Inc." copyright = "Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved." -version = "6.0.2" -release = "6.0.2" +version = "6.1.0" +release = "6.1.0" setting_all_article_info = True all_article_info_os = ["linux"] all_article_info_author = "" @@ -32,7 +33,7 @@ # Supported linux version numbers ubuntu_version_numbers = [('22.04', 'jammy'), ('20.04', 'focal')] rhel_release_version_numbers = ['9', '8'] -rhel_version_numbers = [('9', '9.3'), ('9', '9.2'), ('8', '8.9'), ('8', '8.8')] +rhel_version_numbers = ['9.3', '9.2', '8.9', '8.8'] sles_version_numbers = ['15.5', '15.4'] ol_release_version_numbers = ['8'] ol_version_numbers = [('8', '8.8')] @@ -70,6 +71,7 @@ # Add the following replacements to every RST file. rst_prolog = f""" .. |rocm_version| replace:: {rocm_version} +.. |rocm_multi_versions| replace:: {rocm_multi_versions} .. |amdgpu_version| replace:: {amdgpu_version} .. |rocm_directory_version| replace:: {rocm_directory_version} .. |amdgpu_install_version| replace:: {amdgpu_install_version} diff --git a/docs/how-to/3rd-party/jax-install.rst b/docs/how-to/3rd-party/jax-install.rst new file mode 100644 index 00000000..91d3f993 --- /dev/null +++ b/docs/how-to/3rd-party/jax-install.rst @@ -0,0 +1,108 @@ +.. meta:: + :description: Installing JAX for ROCm + :keywords: installation instructions, JAX, AMD, ROCm + +******************************************************************************************* +Installing JAX for ROCm +******************************************************************************************* + +JAX provides a NumPy-like API, which combines automatic differentiation and the Accelerated Linear +Algebra (XLA) compiler to achieve high-performance machine learning at scale. + +JAX uses composable transformations of Python+NumPy through just-in-time (JIT) compilation, +automatic vectorization, and parallelization. + +To learn about JAX, including profiling and optimizations, refer to the +`JAX documentation `_. + +Compatibility +====================================== + +You can currently use JAX with the following hardware and software: + +* GPUs: MI250 and MI300 +* OS: Ubuntu 20.04 +* Python: 3.9, 3.10, 3.11 +* ROCm: 5.7.0, 6.0.0 + +Installing JAX +======================================== + +JAX wheels and Docker images are released through the GitHub +`ROCm JAX fork `_. + +.. tip:: + + To build JAX from source files, refer to the `JAX developer documentation `_ + or use the `ROCm build script `_. + +1. Pull the latest public JAX Docker image. + + .. code-block:: shell + + docker pull rocm/jax:latest + +2. Start Docker container. + + .. code-block:: shell + + docker run -it -w /workspace --device=/dev/kfd --device=/dev/dri --group-add video \ + --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --shm-size 16G rocm/jax:latest + +3. Verify the installation. + + .. code-block:: shell + + python3 -c 'import jax' 2> /dev/null && echo 'Success' || echo 'Failure' + +4. Verify that the GPU is accessible from JAX. + + .. code-block:: shell + + python3 -c 'import jax; print(jax.devices())' + +5. Run a basic example to ensure installation is successful. + + + .. code-block:: shell + + git clone https://github.com/google/jax.git jax + cd jax + export PYTHONPATH=/workspace/jax/examples/:$PYTHONPATH + python3 examples/mnist_classifier.py + + Your output should look similar to this: + + .. code-block:: text + + Starting training... + Epoch 0 in 10.97 sec + Training set accuracy 0.871916651725769 + Test set accuracy 0.880299985408783 + Epoch 1 in 0.34 sec + Training set accuracy 0.8979166746139526 + Test set accuracy 0.9030999541282654 + Epoch 2 in 0.33 sec + Training set accuracy 0.9092333316802979 + Test set accuracy 0.9142999649047852 + Epoch 3 in 0.33 sec + Training set accuracy 0.9170833230018616 + Test set accuracy 0.9220999479293823 + Epoch 4 in 0.33 sec + Training set accuracy 0.9226333498954773 + Test set accuracy 0.9279999732971191 + Epoch 5 in 0.33 sec + Training set accuracy 0.9271667003631592 + Test set accuracy 0.9297999739646912 + Epoch 6 in 0.34 sec + Training set accuracy 0.9323500394821167 + Test set accuracy 0.9328999519348145 + Epoch 7 in 0.34 sec + Training set accuracy 0.935699999332428 + Test set accuracy 0.9364999532699585 + Epoch 8 in 0.33 sec + Training set accuracy 0.938800036907196 + Test set accuracy 0.9393999576568604 + Epoch 9 in 0.33 sec + Training set accuracy 0.9425833225250244 + Test set accuracy 0.9418999552726746 diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch-install.rst new file mode 100644 index 00000000..1b5d6d42 --- /dev/null +++ b/docs/how-to/3rd-party/pytorch-install.rst @@ -0,0 +1,481 @@ +.. meta:: + :description: Installing PyTorch for ROCm + :keywords: installation instructions, PyTorch, AMD, ROCm + +********************************************************************************** +Installing PyTorch for ROCm +********************************************************************************** + +`PyTorch `_ is an open-source tensor library designed for deep learning. PyTorch on +ROCm provides mixed-precision and large-scale training using our +`MIOpen `_ and +`RCCL `_ libraries. + +To install +`PyTorch for ROCm `_, +you have the following options: + +* :ref:`using-docker-with-pytorch-pre-installed` + (recommended) +* :ref:`using-wheels-package` +* :ref:`using-pytorch-rocm-docker-image` +* :ref:`using-pytorch-upstream-docker-image` + +For hardware, software, and third-party framework compatibility between ROCm and PyTorch, refer to: + +* :ref:`system-requirements` +* :ref:`3rd-party-support-matrix` + +.. _using-docker-with-pytorch-pre-installed: + +Using a Docker image with PyTorch pre-installed +=============================================================== + +1. Download the latest public `PyTorch Docker image `_. + + .. code-block:: bash + + docker pull rocm/pytorch:latest + + You can also download a specific and supported configuration with different user-space ROCm + versions, PyTorch versions, and operating systems. + +2. Start a Docker container using the image. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ + --device=/dev/kfd --device=/dev/dri --group-add video \ + --ipc=host --shm-size 8G rocm/pytorch:latest + + .. note:: + + This will automatically download the image if it does not exist on the host. You can also pass the ``-v`` + argument to mount any data directories from the host onto the container. + +.. _install_pytorch_wheels: +.. _using-wheels-package: + +Using a wheels package +=============================================================== + +PyTorch supports the ROCm platform by providing tested wheels packages. To access this feature, go +to `pytorch.org/get-started/locally/ `_. For the correct +wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matrix. + +.. note:: + The available ROCm release varies between the 'Pytorch Build' of ``Stable`` or ``Nightly``. More recent releases are generally available through the Nightly builds. + +1. Choose one of the following three options: + + **Option 1:** + + a. Download a base Docker image with the correct user-space ROCm version. + + .. list-table:: + :header-rows: 1 + + * - Base OS + - Docker Image + * - Ubuntu 20.04 + - `rocm/dev-ubuntu-20.04 `_ + * - Ubuntu 22.04 + - `rocm/dev-ubuntu-22.04 `_ + * - CentOS 7 + - `rocm/dev-centos-7 `_ + + b. Pull the selected image. + + .. code-block:: bash + + docker pull rocm/dev-ubuntu-20.04:latest + + c. Start a Docker container using the downloaded image. + + .. code-block:: bash + + docker run -it --device=/dev/kfd --device=/dev/dri --group-add video rocm/dev-ubuntu-20.04:latest + + **Option 2:** + + Select a base OS Docker image (Check :ref:`system-requirements`) + + Pull selected base OS image (Ubuntu 20.04 for example) + + .. code-block:: bash + + docker pull ubuntu:20.04 + + Start a Docker container using the downloaded image + + .. code-block:: bash + + docker run -it --device=/dev/kfd --device=/dev/dri --group-add video ubuntu:20.04 + + Install ROCm using the directions in the :ref:`rocm-install-overview` section. + + **Option 3:** + + Install on bare metal. Check :ref:`system-requirements` and install ROCm using the + directions in the :ref:`rocm-install-overview` section. + +2. Install the required dependencies for the wheels package. + + .. code-block:: bash + + sudo apt update + sudo apt install libjpeg-dev python3-dev python3-pip + pip3 install wheel setuptools + +3. Install ``torch``, ``torchvision``, and ``torchaudio``, as specified in the + `installation matrix `_. + + .. note:: + + The following command uses the ROCm 5.6 PyTorch wheel. If you want a different version of ROCm, + modify the command accordingly. + + .. code-block:: bash + + pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm5.6/ + +4. (Optional) Use MIOpen kdb files with ROCm PyTorch wheels. + + PyTorch uses `MIOpen `_ for machine learning + primitives, which are compiled into kernels at runtime. Runtime compilation causes a small warm-up + phase when starting PyTorch, and MIOpen kdb files contain precompiled kernels that can speed up + application warm-up phases. + + MIOpen kdb files can be used with ROCm PyTorch wheels. However, the kdb files need to be placed in + a specific location with respect to the PyTorch installation path. A helper script simplifies this task by + taking the ROCm version and GPU architecture as inputs. This works for Ubuntu and CentOS. + + You can download the helper script here: + `install_kdb_files_for_pytorch_wheels.sh `_, or use: + + .. code-block:: bash + + wget https://raw.githubusercontent.com/wiki/ROCmSoftwarePlatform/pytorch/files/install_kdb_files_for_pytorch_wheels.sh + + After installing ROCm PyTorch wheels, run the following code: + + .. code-block:: bash + + #Optional; replace 'gfx90a' with your architecture and 5.6 with your preferred ROCm version + export GFX_ARCH=gfx90a + + #Optional + export ROCM_VERSION=5.6 + + ./install_kdb_files_for_pytorch_wheels.sh + +.. _using-pytorch-rocm-docker-image: + +Using the PyTorch ROCm base Docker image +=============================================================== + +The pre-built base Docker image has all dependencies installed, including: + +* ROCm +* torchvision +* Conda packages +* The compiler toolchain + +Additionally, a particular environment flag (``BUILD_ENVIRONMENT``) is set, which is used by the build +scripts to determine the configuration of the build environment. + +1. Download the Docker image. This is the base image, which does not contain PyTorch. + + .. code-block:: bash + + docker pull rocm/pytorch:latest-base + +2. Start a Docker container using the downloaded image. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd --device=/dev/dri --group-add video --ipc=host --shm-size 8G rocm/pytorch:latest-base + + You can also pass the ``-v`` argument to mount any data directories from the host onto the container. + +3. Clone the PyTorch repository. + + .. code-block:: bash + + cd ~ + git clone https://github.com/pytorch/pytorch.git + cd pytorch + git submodule update --init --recursive + +4. Set ROCm architecture (optional). The Docker image tag is ``rocm/pytorch:latest-base``. + + .. note:: + + By default in the ``rocm/pytorch:latest-base`` image, PyTorch builds simultaneously for the following + architectures: + * gfx900 + * gfx906 + * gfx908 + * gfx90a + * gfx1030 + + If you want to compile *only* for your microarchitecture (uarch), run: + + .. code-block:: bash + + export PYTORCH_ROCM_ARCH= + + Where ```` is the architecture reported by the ``rocminfo`` command. + + To find your uarch, run: + + .. code-block:: bash + + rocminfo | grep gfx + +5. Build PyTorch. + + .. code-block:: bash + + ./.ci/pytorch/build.sh + + This converts PyTorch sources for HIP compatibility and builds the PyTorch framework. + + To check if your build is successful, run: + + .. code-block:: bash + + echo $? # should return 0 if success + +.. _using-pytorch-upstream-docker-image: + +Using the PyTorch upstream Docker file +=============================================================== + +If you don't want to use a prebuilt base Docker image, you can build a custom base Docker image +using scripts from the PyTorch repository. This uses a standard Docker image from operating system +maintainers and installs all the required dependencies, including: + +* ROCm +* torchvision +* Conda packages +* The compiler toolchain + +1. Clone the PyTorch repository. + + .. code-block:: bash + + cd ~ + git clone https://github.com/pytorch/pytorch.git + cd /pytorch + git submodule update --init --recursive + +2. Build the PyTorch Docker image. + + .. code-block:: bash + + cd .ci/docker + ./build.sh pytorch-linux--rocm-py -t rocm/pytorch:build_from_dockerfile + + Where: + * ````: ``ubuntu20.04`` (or ``focal``), ``ubuntu22.04`` (or ``jammy``), ``centos7.5``, or ``centos9`` + * ````: ``5.4``, ``5.5``, or ``5.6`` + * ````: ``3.8`` - ``3.11`` + + To verify that your image was successfully created, run: + + .. code-block:: bash + + docker image ls rocm/pytorch:build_from_dockerfile + + If successful, the output looks like this: + + .. code-block:: bash + + REPOSITORY TAG IMAGE ID CREATED SIZE + rocm/pytorch build_from_dockerfile 17071499be47 2 minutes ago 32.8GB + +3. Start a Docker container using the image with the mounted PyTorch folder. + + .. code-block:: bash + + docker run -it --cap-add=SYS_PTRACE --security-opt --user root \ + seccomp=unconfined --device=/dev/kfd --device=/dev/dri \ + --group-add video --ipc=host --shm-size 8G \ + -v ~/pytorch:/pytorch rocm/pytorch:build_from_dockerfile + + You can also pass the ``-v`` argument to mount any data directories from the host onto the container. + +4. Go to the PyTorch directory. + + .. code-block:: bash + + cd pytorch + +5. Set ROCm architecture. + + To determine your AMD architecture, run: + + .. code-block:: bash + + rocminfo | grep gfx + + The result looks like this (for ``gfx1030`` architecture): + + .. code-block:: bash + + Name: gfx1030 + Name: amdgcn-amd-amdhsa--gfx1030 + + Set the ``PYTORCH_ROCM_ARCH`` environment variable to specify the architectures you want to + build PyTorch for. + + .. code-block:: bash + + export PYTORCH_ROCM_ARCH= + + where ```` is the architecture reported by the ``rocminfo`` command. + +6. Build PyTorch. + + .. code-block:: bash + + ./.ci/pytorch/build.sh + + This converts PyTorch sources for + `HIP compatibility `_ and builds the + PyTorch framework. + + To check if your build is successful, run: + + .. code-block:: bash + + echo $? # should return 0 if success + +Testing the PyTorch installation +=============================================================== + +You can use PyTorch unit tests to validate your PyTorch installation. If you used a +**prebuilt PyTorch Docker image from AMD ROCm Docker Hub** or installed an +**official wheels package**, validation tests are not necessary. + +If you want to manually run unit tests to validate your PyTorch installation fully, follow these steps: + +1. Import the torch package in Python to test if PyTorch is installed and accessible. + + .. note:: + + Do not run the following command in the PyTorch git folder. + + .. code-block:: bash + + python3 -c 'import torch' 2> /dev/null && echo 'Success' || echo 'Failure' + +2. Check if the GPU is accessible from PyTorch. In the PyTorch framework, ``torch.cuda`` is a generic way + to access the GPU. This can only access an AMD GPU if one is available. + + .. code-block:: bash + + python3 -c 'import torch; print(torch.cuda.is_available())' + + +3. Run unit tests to validate the PyTorch installation fully. + + .. note:: + + You must run the following command from the PyTorch home directory. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/run_test.py --verbose \ + --include test_nn test_torch test_cuda test_ops \ + test_unary_ufuncs test_binary_ufuncs test_autograd + + This command ensures that the required environment variable is set to skip certain unit tests for + ROCm. This also applies to wheel installs in a non-controlled environment. + + .. note:: + + Make sure your PyTorch source code corresponds to the PyTorch wheel or the installation in the + Docker image. Incompatible PyTorch source code can give errors when running unit tests. + + Some tests may be skipped, as appropriate, based on your system configuration. ROCm doesn't + support all PyTorch features; tests that evaluate unsupported features are skipped. Other tests might + be skipped, depending on the host or GPU memory and the number of available GPUs. + + If the compilation and installation are correct, all tests will pass. + +4. Run individual unit tests. + + .. code-block:: bash + + PYTORCH_TEST_WITH_ROCM=1 python3 test/test_nn.py --verbose + + You can replace ``test_nn.py`` with any other test set. + +Running a basic PyTorch example +=============================================================== + +The PyTorch examples repository provides basic examples that exercise the functionality of your +framework. + +Two of our favorite testing databases are: + +* **MNIST** (Modified National Institute of Standards and Technology): A database of handwritten + digits that can be used to train a Convolutional Neural Network for **handwriting recognition**. +* **ImageNet**: A database of images that can be used to train a network for + **visual object recognition**. + +MNIST PyTorch example +--------------------------------------------------------------------------------------------------------- + +1. Clone the PyTorch examples repository. + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the MNIST example folder. + + .. code-block:: bash + + cd examples/mnist + +3. Follow the instructions in the ``README.md`` file in this folder to install the requirements. Then run: + + .. code-block:: bash + + python3 main.py + + This generates the following output: + + .. code-block:: + + ... + Train Epoch: 14 [58240/60000 (97%)] Loss: 0.010128 + Train Epoch: 14 [58880/60000 (98%)] Loss: 0.001348 + Train Epoch: 14 [59520/60000 (99%)] Loss: 0.005261 + + Test set: Average loss: 0.0252, Accuracy: 9921/10000 (99%) + +ImageNet PyTorch example +--------------------------------------------------------------------------------------------------------- + +1. Clone the PyTorch examples repository (if you didn't already do this in the preceding MNIST + example). + + .. code-block:: bash + + git clone https://github.com/pytorch/examples.git + +2. Go to the ImageNet example folder. + + .. code-block:: bash + + cd examples/imagenet + +3. Follow the instructions in the ``README.md`` file in this folder to install the Requirements. Then run: + + .. code-block:: bash + + python3 main.py diff --git a/docs/how-to/amdgpu-install.rst b/docs/how-to/amdgpu-install.rst index 3c8ebb78..cd2c644b 100644 --- a/docs/how-to/amdgpu-install.rst +++ b/docs/how-to/amdgpu-install.rst @@ -6,14 +6,14 @@ Installation via AMDGPU installer ************************************************************************************* -``amdgpu-install`` is a tool that helps you install and update AMDGPU and ROCm -and its components. +``amdgpu-install`` is a tool that helps you install and update AMDGPU, ROCm, and ROCm components. .. warning:: - ROCm doesn't currently support integrated graphics. Should your system have an - AMD IGP installed, disable it in the BIOS prior to using ROCm. If the driver can - enumerate the IGP, the ROCm runtime may crash the system, even if told to omit - it via `HIP_VISIBLE_DEVICES `_. + + ROCm doesn't currently support integrated graphics. Should your system have an + AMD IGP installed, disable it in the BIOS prior to using ROCm. If the driver can + enumerate the IGP, the ROCm runtime may crash the system, even if told to omit + it via `HIP_VISIBLE_DEVICES `_. .. _amdgpu-install-installation: @@ -48,14 +48,15 @@ Red Hat Enterprise Linux .. datatemplate:nodata:: .. tab-set:: - {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} + {% for os_version in config.html_context['rhel_version_numbers'] %} + {% set os_major, _ = os_version.split('.') %} .. tab-item:: RHEL {{ os_version }} - :sync: rhel-{{ os_version }} rhel-{{ os_release }} + :sync: rhel-{{ os_version }} rhel-{{ os_major }} .. code-block:: bash :substitutions: - sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_release }}.noarch.rpm + sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_major }}.noarch.rpm {% endfor %} SUSE Linux Enterprise @@ -76,18 +77,16 @@ SUSE Linux Enterprise Use cases ================================================= -Instead of installing individual applications or libraries the installer script -groups packages into specific use cases, matching typical workflows and -runtimes. +Instead of installing individual applications or libraries, the installer script groups packages into specific +use cases that match typical workflows and runtimes. -To display a list of available use cases execute the command: +To display a list of available use cases, run: .. code-block:: bash sudo amdgpu-install --list-usecase -The available use-cases will be printed in a format similar to the example -output below. +The available use-cases are printed in a format similar to: .. code-block:: @@ -170,42 +169,39 @@ Upgrading ROCm ================================================= The upgrade procedure with the installer script is exactly the same as -:ref:`installing for first time use`. +:ref:`installing for first time use `. Installing ROCm packages ================================================= -To install use cases specific to your requirements, use the installer -``amdgpu-install`` as follows: +To install use cases specific to your requirements, use the installer (``amdgpu-install``) as follows: -- To install a single use case add it with the :code:`--usecase` option: +* To install a single use case, add it with the ``--usecase`` option: .. code-block:: bash sudo amdgpu-install --usecase=rocm -- For multiple use cases separate them with commas: +* For multiple use cases, separate them with commas: .. code-block:: bash sudo amdgpu-install --usecase=hiplibsdk,rocm -- For graphical workloads using the open-source driver add ``graphics``. For - example: +* For graphical workloads using the open-source driver, add ``graphics``. For example: .. code-block:: bash sudo amdgpu-install --usecase=graphics,rocm -- For graphical workloads using the proprietary driver add ``workstation``. For - example: +* For graphical workloads using the proprietary driver, add ``workstation``. For example: .. code-block:: bash sudo amdgpu-install --usecase=workstation,rocm -- To install LLVM ASAN (Address Sanitizer) instrumented binaries of packages - that support it add ``asan``. For example: +* To install LLVM AddressSanitizer (ASAN) instrumented binaries (for packages that support it), add + ``asan``. For example: .. code-block:: bash @@ -214,69 +210,61 @@ To install use cases specific to your requirements, use the installer Uninstalling ROCm ================================================= -To uninstall all ROCm packages and the kernel-mode driver the following commands -can be used. +To uninstall all ROCm packages and the kernel-mode driver, use the following commands. -- Uninstalling Single-Version Install +* Uninstalling single-version install .. code-block:: bash sudo amdgpu-install --uninstall -- Uninstalling a specific ROCm release +* Uninstalling a specific ROCm release .. code-block:: bash sudo amdgpu-install --uninstall --rocmrelease= -- Uninstalling all ROCm releases +* Uninstalling all ROCm releases .. code-block:: bash sudo amdgpu-install --uninstall --rocmrelease=all -Multi-versioned ROCm Installation +Multi-versioned ROCm installation ================================================= -By default (without the :code:`--rocmrelease` option) the installer script will install -packages in the single-version layout. - -For the multi-version ROCm installation you must use the installer script from -the latest release of ROCm that you wish to install. +By default (without the ``--rocmrelease`` option), the installer script installs packages in the +single-version layout. -**Example:** If you want to install ROCm releases 5.5.3, 5.6.1 and 5.7 -simultaneously, you are required to download the installer from the latest ROCm -release 5.7. +For the multi-version ROCm installation, you must use the installer script from the latest ROCm release +you want to install. -You must add the ROCm repositories manually for all ROCm releases you want to -install except the latest one. The ``amdgpu-install`` script automatically adds the -required repositories for the latest release. +**Example:** If you want to install ROCm releases 5.5.3, 5.6.1, and 5.7 simultaneously, you must +download the ROCm 5.7 installer. Then, you must manually add the ROCm repositories for all ROCm +releases you want to install, except for the latest one. The ``amdgpu-install`` script automatically adds +the required repositories for the latest release. -See the section "Register ROCm Packages" in :doc:`/how-to/native-install/index` -for :ref:`Ubuntu`. +Refer to :ref:`Register ROCm packages ` on the +:doc:`Ubuntu native installation <./native-install/ubuntu>` page. Additional options ================================================= -Unattended installation ------------------------------------------------------------------------- +* Unattended installation. -Adding ``-y`` as a parameter to ``amdgpu-install`` skips user prompts (for -automation). For example: + Adding ``-y`` as a parameter to ``amdgpu-install`` skips user prompts (for automation). For example: -.. code-block:: bash + .. code-block:: bash - amdgpu-install -y --usecase=rocm + amdgpu-install -y --usecase=rocm -Skipping kernel mode driver installation ------------------------------------------------------------------------- +* Skipping kernel mode driver installation. -The installer script tries to install the kernel mode driver along with the -requested use cases. This might be unnecessary as in the case of docker -containers or you may wish to keep a specific version when using multi-version -installation, and not have the last installed version overwrite the kernel mode -driver. + The installer script tries to install the kernel mode driver along with the requested use cases. This + might be unnecessary (as in the case of Docker containers) or you may want to keep a specific version + when using multi-version installation, and not have the last installed version overwrite the kernel + mode driver. -To skip the installation of the kernel-mode driver add the :code:`--no-dkms` option when -calling the installer script. + To skip the installation of the kernel-mode driver, add the ``--no-dkms`` option when calling the + installer script. diff --git a/docs/how-to/docker.rst b/docs/how-to/docker.rst index de2ccd3f..a5b370aa 100644 --- a/docs/how-to/docker.rst +++ b/docs/how-to/docker.rst @@ -93,19 +93,19 @@ For example, to expose the first and second GPU: Docker images in the ROCm ecosystem ======================================================= -Base images -------------------------------------------------------------------------------------------------- +The `ROCm Docker repository `_ hosts images useful for +building your own containers, leveraging ROCm. The built images are available on +`Docker Hub `_. In particular: + +* ``rocm/rocm-terminal`` is a small image with the prerequisites to build HIP applications, but does not + include any libraries. -The `ROCm Docker repository `_ hosts images useful for users -wishing to build their own containers leveraging ROCm. The built images are -available from `Docker Hub `_. In particular -``rocm/rocm-terminal`` is a small image with the prerequisites to build HIP -applications, but does not include any libraries. +* `ROCm dev images `_ provide a variety of OS + + ROCm versions, and are a great starting place for building applications Applications ------------------------------------------------------------------------------------------------- AMD provides pre-built images for various GPU-ready applications through -`Infinity Hub `_. -Examples for invoking each application and suggested parameters used for -benchmarking are also provided there. +`Infinity Hub `_. There, you'll also find examples +for invoking each application and suggested parameters used for benchmarking. diff --git a/docs/how-to/native-install/index.rst b/docs/how-to/native-install/index.rst index 406bd8ea..076daecf 100644 --- a/docs/how-to/native-install/index.rst +++ b/docs/how-to/native-install/index.rst @@ -12,25 +12,31 @@ Installation via native package manager .. grid-item-card:: Install - - :doc:`Ubuntu` - - :doc:`Red Hat Enterprise Linux` - - :doc:`SUSE Linux Enterprise` + * :doc:`Ubuntu <./ubuntu>` + * :doc:`RHEL <./rhel>` + * :doc:`SLES <./sles>` - .. grid-item-card:: Upgrade + .. grid-item-card:: Post-install - Instructions for upgrading an existing ROCm installation. + * :doc:`Post-install steps <./post-install>` - - :ref:`Ubuntu` + .. grid-item-card:: Upgrade - .. grid-item-card:: Uninstall + * :ref:`Ubuntu ` + * :ref:`RHEL ` + * :ref:`SLES ` - Steps for removing ROCm packages libraries and tools. + .. grid-item-card:: Uninstall - - :ref:`Ubuntu` + * :ref:`Ubuntu ` + * :ref:`RHEL ` + * :ref:`SLES ` .. grid-item-card:: Package manager integration - :link: package-manager-integration.html Required meta-packages for ROCm programming models. -See also: :doc:`/reference/system-requirements`. + * :doc:`Meta-packages <./package-manager-integration>` + +See also: :doc:`/reference/system-requirements`. If you encounter install issues, you can refer to the +:doc:`troubleshooting ` page. diff --git a/docs/how-to/native-install/install-faq.rst b/docs/how-to/native-install/install-faq.rst new file mode 100644 index 00000000..3e4cf24d --- /dev/null +++ b/docs/how-to/native-install/install-faq.rst @@ -0,0 +1,93 @@ +.. meta:: + :description: Frequently asked questions for install + :keywords: Linux, install, FAQ, ubuntu, RHEL, SUSE, AMD, ROCm + +.. _troubleshooting: + +************************************************************************************ +Installation Troubleshooting +************************************************************************************ + +Troubleshooting describes issues that some users encounter when installing the ROCm tools or libraries. + +Issue #1: Installation Methods +================================= + +As an example, the latest version of ROCm is 6.0.2, but the installation instructions result in release 6.0.0 being installed. + +**Solution:** You may have used the quick-start installation method which only installs the latest major release. Use one of the other available installation methods: + +* :doc:`Quick-start installation <../../tutorial/quick-start>` - Installs only the latest **major** release (i.e. 6.0.0, or 6.1.0) +* :doc:`Native package manager install method <./index>` - Installs the specified *major and minor* release version (i.e. 6.0.0, 6.0.2) +* :doc:`amdgpu-install method <../amdgpu-install>` - Installs the specified *major and minor* release version (i.e. 6.0.0, 6.0.2) + +Refer to `ROCm Issue #2422 `_ for additional details. + + +Issue #2: Install Prerequisites +================================== + +When installing, I see the following message: ``Problem: nothing provides perl-URI-Encode needed to be installed by ...`` + +**Solution:** Ensure that the :doc:`../prerequisites` are installed. There are prerequisite PERL packages required for SUSE. RHEL also requires Extra Packages for Enterprise Linux (EPEL) to be installed, which is also mentioned in prerequisites. Be sure to install those first, then repeat your installation steps. + +Refer to `ROCm Issue #1827 `_. + + +Issue #3: PATH variable +============================ + +After successfully installing ROCm, when I run ``rocminfo`` (or another ROCm tool) the command is not found. + +**Solution:** You may need to update your ``PATH`` environment variable as described in :doc:`./post-install`. + +Refer to `ROCm Issue #1607 `_. + + +Issue #4: C++ libraries +========================= + +When compiling HIP programs, I get a linking error for ``-lstdc++``, or ``fatal error: 'cmath' file not found``. + +**Solution:** You can install C++ libraries using your package manager. The following is an Ubuntu example: + +.. code-block:: bash + + sudo apt-get install libstdc++-12-dev + +Refer to `ROCm Issue #2031 `_. + + +.. _multi-gpu: + +Issue #5: Application hangs on Multi-GPU systems +================================================== + +Running on a system with multiple GPUs the application hangs with the GPU use at 100%, but without the expected GPU temperature buildup + +This issue often results in the following message in the application transcript: + +.. code-block:: shell + + NCCL WARN Missing "iommu=pt" from kernel command line which can lead to system instablity or hang! + +**Solution:** To resolve this issue add ``iommu=pt`` to ``GRUB_CMDLINE_LINUX_DEFAULT`` in ``/etc/default/grub``. Then run the following command: + +.. code-block:: shell + + sudo update-grub + +Reboot the system, and run the following command: + +.. code-block:: shell + + cat /proc/cmdline + +The returned information should reflect the addition of ``iommu``: + +.. code-block:: shell + + BOOT_IMAGE=/vmlinuz-5.15.0-101-generic root=/dev/mapper/ubuntu--vg-ubuntu--lv ro iommu=pt + +Refer to `RCCL Issue #1129 `_ for more information. + diff --git a/docs/how-to/native-install/rhel.rst b/docs/how-to/native-install/rhel.rst index bfd077ff..fc4afee4 100644 --- a/docs/how-to/native-install/rhel.rst +++ b/docs/how-to/native-install/rhel.rst @@ -18,9 +18,10 @@ Register kernel-mode driver .. datatemplate:nodata:: .. tab-set:: - {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} + {% for os_version in config.html_context['rhel_version_numbers'] %} + {% set os_major, _ = os_version.split('.') %} .. tab-item:: RHEL {{ os_version }} - :sync: rhel-{{ os_version }} rhel-{{ os_release }} + :sync: rhel-{{ os_version }} rhel-{{ os_major }} .. code-block:: bash :substitutions: @@ -69,11 +70,101 @@ Register ROCm packages .. include:: install-rocm-template.rst +.. _rhel-multi-install: + +Multi-version install +===================================================== + +Multi-version install is for the special case, when you need multiple versions of ROCm +on the same machine, not just the newest. If you just want to install the latest use +the steps in :ref:`rhel-register-repo` and :ref:`rhel-install`. + +Register kernel-mode driver +---------------------------------------------------------------------------------------------------------- + +.. datatemplate:nodata:: + + .. tab-set:: + {% for os_version in config.html_context['rhel_version_numbers'] %} + {% set os_major, _ = os_version.split('.') %} + .. tab-item:: RHEL {{ os_version }} + :sync: rhel-{{ os_version }} rhel-{{ os_major }} + + .. code-block:: bash + :substitutions: + + for ver in |rocm_multi_versions|; do + sudo tee /etc/yum.repos.d/amdgpu.repo < # For example: sudo zypper remove rocm - # Or for version specific packages: + # Or, for version specific packages: sudo zypper remove rocm|rocm_version| Uninstall ROCm packages @@ -130,7 +188,7 @@ Remove ROCm and AMDGPU repositories # # The name of the repositories can be listed with: sudo zypper repos - + # Then remove the 'ROCm' and 'amdgpu' repositories. # For example: sudo zypper removerepo ROCm-|rocm_version| diff --git a/docs/how-to/native-install/ubuntu.rst b/docs/how-to/native-install/ubuntu.rst index 393d60bf..09e1d51f 100644 --- a/docs/how-to/native-install/ubuntu.rst +++ b/docs/how-to/native-install/ubuntu.rst @@ -11,6 +11,8 @@ Ubuntu native installation Registering repositories ================================================= +.. _ubuntu-package-key: + Package signing key --------------------------------------------------------------------------- @@ -30,6 +32,7 @@ Download and convert the package signing key. .. _ubuntu-register-driver: .. note:: + The GPG key may change; ensure it is updated when installing a new release. If the key signature verification fails while updating, re-add the key from the ROCm to the apt repository as mentioned above. @@ -78,6 +81,7 @@ Add the ROCm repository. | sudo tee --append /etc/apt/sources.list.d/rocm.list echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' \ | sudo tee /etc/apt/preferences.d/rocm-pin-600 + sudo apt update {% endfor %} .. _ubuntu-install: @@ -102,6 +106,89 @@ Install ROCm packages Complete the :doc:`post-install`. +.. _ubuntu-multi-install: + +Multi-version install +================================================= + +Multi-version install is for the special case, when you need multiple versions of ROCm +on the same machine, not just the newest. If you just want to install the latest use +the steps in :ref:`ubuntu-register-repo` and :ref:`ubuntu-install`. + +Package signing key +--------------------------------------------------------------------------- + +This step is the same as previously described, follow the steps in :ref:`ubuntu-package-key`.. + +Register kernel-mode driver +--------------------------------------------------------------------------- + +Add the AMDGPU repository for the driver. + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} + .. tab-item:: Ubuntu {{ os_version }} + :sync: ubuntu-{{ os_version}} + + .. code-block:: bash + :substitutions: + + for ver in |rocm_multi_versions|; do + echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amdgpu/$ver/ubuntu {{ os_release }} main" \ + | sudo tee /etc/apt/sources.list.d/amdgpu.list + done + sudo apt update + {% endfor %} + +.. _ubuntu-multi-register-rocm: + +Register ROCm packages +--------------------------------------------------------------------------- + +Add the ROCm repository. + +.. datatemplate:nodata:: + + .. tab-set:: + {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} + .. tab-item:: Ubuntu {{ os_version }} + :sync: ubuntu-{{ os_version}} + + .. code-block:: bash + :substitutions: + + for ver in |rocm_multi_versions|; do + echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/$ver {{ os_release }} main" \ + | sudo tee --append /etc/apt/sources.list.d/rocm.list + done + echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' \ + | sudo tee /etc/apt/preferences.d/rocm-pin-600 + sudo apt update + {% endfor %} + +Installing +--------------------------------------------------------------------------- + +Install the kernel driver. + +.. code-block:: bash + + sudo apt install amdgpu-dkms + sudo reboot + +Install ROCm packages. + +.. code-block:: bash + :substitutions: + + for ver in |rocm_multi_versions|; do + sudo apt install rocm$ver + done + +Complete the :doc:`post-install`. + .. _ubuntu-upgrade: Upgrading diff --git a/docs/how-to/prerequisites.rst b/docs/how-to/prerequisites.rst index fb3bf62e..b97f1b4c 100644 --- a/docs/how-to/prerequisites.rst +++ b/docs/how-to/prerequisites.rst @@ -47,16 +47,17 @@ Before installing ROCm, complete the following prerequisites. Additional package repositories ========================================================== -On some distributions the ROCm packages depend on packages outside the default -package repositories. These extra repositories need to be enabled before -installation. Follow the instructions below based on your distributions. +On some distributions the ROCm packages depend on packages outside the default package +repositories. These extra repositories need to be enabled before installation. Use the following +instructions for your distribution. .. tab-set:: .. tab-item:: Ubuntu :sync: ubuntu-tab - All packages are available in the default Ubuntu repositories, therefore no additional repositories need to be added. + All packages are available in the default Ubuntu repositories, so you don't need to add additional + repositories. .. tab-item:: Red Hat Enterprise Linux :sync: rhel-tab @@ -66,13 +67,16 @@ installation. Follow the instructions below based on your distributions. .. datatemplate:nodata:: .. tab-set:: + {% for os_release in config.html_context['rhel_release_version_numbers'] %} + .. tab-item:: RHEL/OL {{ os_release }} .. code-block:: shell - wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_release }}.noarch.rpm - sudo rpm -ivh epel-release-latest-{{ os_release }}.noarch.rpm + wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_release }}.noarch.rpm + sudo rpm -ivh epel-release-latest-{{ os_release }}.noarch.rpm + {% endfor %} 2. Enable the CodeReady Linux Builder (CRB) repository. @@ -89,17 +93,21 @@ installation. Follow the instructions below based on your distributions. Add the Perl language repository. + .. note:: + We currently need to install the Perl module from SLES 15 SP5 as a workaround. The module was removed for SLES 15 SP4. + .. datatemplate:nodata:: .. tab-set:: {% for os_version in config.html_context['sles_version_numbers'] %} {% set os_release, os_sp = os_version.split('.') %} + .. tab-item:: SLES {{ os_version }} .. code-block:: shell - zypper addrepo https://download.opensuse.org/repositories/devel:/languages:/perl/{{ os_version }}/devel:languages:perl.repo + zypper addrepo https://download.opensuse.org/repositories/devel:/languages:/perl/15.5/devel:languages:perl.repo {% endfor %} @@ -107,7 +115,7 @@ Kernel headers and development packages ================================================================ The driver package uses -`DKMS (Dynamic Kernel Module Support) `_ +`Dynamic Kernel Module Support (DKMS) `_ to build the `amdgpu-dkms` module (driver) for the installed kernels. This requires the Linux kernel headers and modules to be installed for each. Usually these are automatically installed with the kernel, but if you have multiple kernel versions or you have downloaded the kernel images and not the kernel @@ -142,10 +150,8 @@ To install for the currently active kernel run the command corresponding to your Setting permissions for groups ================================================================ -This section provides steps to add any current user to a video group to access -GPU resources. -Use of the video group is recommended for all ROCm-supported operating -systems. +This section provides steps to add any current user to a video group to access GPU resources. We +recommend using the video group for all ROCm-supported operating systems. 1. To check the groups in your system, issue the following command: @@ -157,13 +163,12 @@ systems. .. code-block:: shell - sudo usermod -a -G render,video $LOGNAME + sudo usermod -a -G render,video $LOGNAME -To add all future users to the ``video`` and ``render`` groups by default, run -the following commands: + To add all future users to the ``video`` and ``render`` groups by default, run the following commands: -.. code-block:: shell + .. code-block:: shell - echo 'ADD_EXTRA_GROUPS=1' | sudo tee -a /etc/adduser.conf - echo 'EXTRA_GROUPS=video' | sudo tee -a /etc/adduser.conf - echo 'EXTRA_GROUPS=render' | sudo tee -a /etc/adduser.conf + echo 'ADD_EXTRA_GROUPS=1' | sudo tee -a /etc/adduser.conf + echo 'EXTRA_GROUPS=video' | sudo tee -a /etc/adduser.conf + echo 'EXTRA_GROUPS=render' | sudo tee -a /etc/adduser.conf diff --git a/docs/how-to/spack.rst b/docs/how-to/spack.rst index d6813bc5..731f2dde 100644 --- a/docs/how-to/spack.rst +++ b/docs/how-to/spack.rst @@ -18,7 +18,7 @@ versions and configuration options. Spack is also simple for package authors: pa in pure Python, and specs allow package authors to maintain a single file for many different builds of the same package. -ROCM packages in Spack +ROCm packages in Spack =================================================== .. csv-table:: diff --git a/docs/index.rst b/docs/index.rst index c6989b70..66036e83 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ complete instructions, refer to the following sections. .. grid:: 2 :gutter: 1 - .. grid-item-card:: Quick-start + .. grid-item-card:: Quick start :link: tutorial/quick-start :link-type: doc @@ -57,17 +57,15 @@ Additional resources .. grid:: 2 :gutter: 1 - .. grid-item-card:: Reference material + .. grid-item-card:: Reference - - :doc:`reference/system-requirements` - - :doc:`reference/docker-image-support-matrix` - - :doc:`reference/3rd-party-support-matrix` + * :doc:`reference/system-requirements` + * :doc:`reference/docker-image-support-matrix` + * :doc:`reference/3rd-party-support-matrix` - .. grid-item-card:: Tutorials + .. grid-item-card:: Troubleshooting and FAQ - - :doc:`how-to/3rd-party/magma-install` - - :doc:`how-to/3rd-party/pytorch-install` - - :doc:`how-to/3rd-party/tensorflow-install` + * :doc:`Troubleshooting ` .. grid-item-card:: Install diff --git a/docs/reference/3rd-party-support-matrix.rst b/docs/reference/3rd-party-support-matrix.rst index 232b1276..9936260d 100644 --- a/docs/reference/3rd-party-support-matrix.rst +++ b/docs/reference/3rd-party-support-matrix.rst @@ -25,41 +25,45 @@ TensorFlow. For TensorFlow the exact version follows the .`_ - `TensorFlow `_ - * - 5.0.2 - - 1.8, 1.9, 1.10 - - 2.6, 2.7, 2.8 + * - 6.1.x + - 1.13, 2.0, 2.1 + - 2.13, 2.14, 2.15 - * - 5.1.3 - - 1.9, 1.10, 1.11 - - 2.7, 2.8, 2.9 + * - 6.0.x + - 1.13, 2.0, 2.1 + - 2.12, 2.13, 2.14 - * - 5.2.x - - 1.10, 1.11, 1.12 - - 2.8, 2.9, 2.9 + * - 5.7.x + - 1.12.1, 1.13, 2.0, 2.1 + - 2.12, 2.13, 2.14 - * - 5.3.x - - 1.10.1, 1.11, 1.12.1, 1.13 - - 2.8, 2.9, 2.10 + * - 5.6.x + - 1.12.1, 1.13, 2.0, 2.1 + - 2.12, 2.13, 2.14 + + * - 5.5.x + - 1.11, 1.12.1, 1.13, 2.0 + - 2.10, 2.11, 2.12 * - 5.4.x - 1.10.1, 1.11, 1.12.1, 1.13 - 2.8, 2.9, 2.10, 2.11 - * - 5.5.x + * - 5.3.x - 1.10.1, 1.11, 1.12.1, 1.13 - - 2.10, 2.11, 2.13 + - 2.8, 2.9, 2.10 - * - 5.6.x - - 1.12.1, 1.13, 2.0 - - 2.12, 2.1 + * - 5.2.x + - 1.10, 1.11, 1.12 + - 2.7, 2.8, 2.9 - * - 5.7.x - - 1.12.1, 1.13, 2.0 - - 2.12, 2.13 + * - 5.1.3 + - 1.9, 1.10, 1.11 + - 2.7, 2.8, 2.9 - * - 6.0.x - - 1.13, 2.0, 2.1 - - 2.12, 2.13, 2.14 + * - 5.0.2 + - 1.8, 1.9, 1.10 + - 2.6, 2.7, 2.8 .. _communication-libraries: @@ -119,41 +123,45 @@ CUDA/NVIDIA HPC SDK alternatives. - Thrust / CUB - HPC SDK - * - 5.0.2 - - 1.14 - - 21.9 - - * - 5.1.3 - - 1.15 - - 22.1 - - * - 5.2.x - - 1.15 - - 22.2, 22.3 - - * - 5.3.x - - 1.16 - - 22.7 + * - 6.1.x + - 2.1.0 + - 22.9 - * - 5.4.x - - 1.16 + * - 6.0.x + - 2.0.1 - 22.9 - * - 5.5.x - - 1.17 + * - 5.7.x + - 1.17.2 - 22.9 * - 5.6.x - 1.17.2 - 22.9 - * - 5.7.x - - 1.17.2 + * - 5.5.x + - 1.17 - 22.9 - * - 6.0.x - - 2.0.1 + * - 5.4.x + - 1.16 - 22.9 + * - 5.3.x + - 1.16 + - 22.7 + + * - 5.2.x + - 1.15 + - 22.2, 22.3 + + * - 5.1.3 + - 1.15 + - 22.1 + + * - 5.0.2 + - 1.14 + - 21.9 + For the latest documentation of these libraries, refer to the ROCm :doc:`API libraries `. diff --git a/docs/reference/system-requirements.rst b/docs/reference/system-requirements.rst index b609f323..75feafad 100644 --- a/docs/reference/system-requirements.rst +++ b/docs/reference/system-requirements.rst @@ -23,8 +23,8 @@ GPU is not listed on this table, it's not officially supported by AMD. :widths: 50, 25, 25, 10 :header: "GPU", "Architecture", "LLVM target", "Support" - "AMD Instinct MI300X", "CDNA3", "gfx942", "✅" - "AMD Instinct MI300A", "CDNA3", "gfx942", "✅ :sup:`1`" + "AMD Instinct MI300X", "CDNA3", "gfx942", "✅ :sup:`1`" + "AMD Instinct MI300A", "CDNA3", "gfx942", "✅ :sup:`2`" "AMD Instinct MI250X", "CDNA2", "gfx90a", "✅" "AMD Instinct MI250", "CDNA2", "gfx90a", "✅" "AMD Instinct MI210", "CDNA2", "gfx90a", "✅" @@ -62,7 +62,12 @@ ROCm product. ❌: **Unsupported** - This configuration is not enabled in our software distributions. -:sup:`1` MI300A is currently not officially supported on RHEL 9.x. This will be added on a later date. +:sup:`1` MI300X is only supported on Ubuntu 22.04.4. + +:sup:`2` MI300A is supported on Ubuntu 22.04.4, RHEL 9.3, RHEL 8.9 and SLES 15 SP5. + +.. important:: + Systems with multiple GPUs may require ``iommu=pt`` to be set at boot time to prevent application hangs, as described in :doc:`Troubleshooting - Issue #5 <../how-to/native-install/install-faq>` .. _supported_distributions: @@ -79,18 +84,14 @@ AMD ROCm™ Software supports the following Linux distributions. "RHEL 9.2", "5.14.0-362", "✅" "RHEL 8.9", "4.18-513", "✅" "RHEL 8.8", "4.18-513", "✅" - "Oracle Linux 8.8", "5.15.0-101.103.2.1.el8uek.x86_64", "✅" "CentOS 7.9", "3.10", "✅" "SLES 15 SP5", "5.14.21-150500", "✅" "SLES 15 SP4", "5.14.21-150500", "✅" - "Ubuntu 22.04.4", "6.6", "✅ :sup:`2`" + "Ubuntu 22.04.4", "6.5", "✅" "Ubuntu 22.04.3", "6.2", "✅" - "Ubuntu 22.04.2", "5.19", "✅" "Ubuntu 20.04.6", "5.15", "✅" "Ubuntu 20.04.5", "5.15", "✅" -:sup:`2` Preview support for HWE kernels - Virtualization support ============================================= diff --git a/docs/reference/user-kernel-space-compat-matrix.rst b/docs/reference/user-kernel-space-compat-matrix.rst index 021de42b..8491c3f0 100644 --- a/docs/reference/user-kernel-space-compat-matrix.rst +++ b/docs/reference/user-kernel-space-compat-matrix.rst @@ -16,8 +16,9 @@ the compatibility combinations that are currently supported. :widths: 30, 70 :header: "KFD", "Tested user space versions" - "6.0.x", "5.6.x, 5.7.x" - "5.7.x", "5.5.x, 5.6.x, 6.0.x" + "6.1.x", "5.7.x, 6.0.x" + "6.0.x", "5.6.x, 5.7.x, 6.1.x" + "5.7.x", "5.5.x, 5.6.x, 6.0.x, 6.1.x" "5.6.x", "5.4.x, 5.5.x, 5.7.x, 6.0.x" "5.5.x", "5.3.x, 5.4.x, 5.6.x, 5.7.x" "5.4.x", "5.2.x, 5.3.x, 5.5.x, 5.6.x" diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 6c565199..2df3f922 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -5,7 +5,7 @@ root: index subtrees: - entries: - file: tutorial/quick-start - title: Quick-start install guide + title: Quick start install guide - file: how-to/prerequisites title: Prerequisites - file: tutorial/install-overview @@ -23,15 +23,17 @@ subtrees: - file: how-to/native-install/ubuntu title: Ubuntu - file: how-to/native-install/rhel - title: Red Hat Enterprise Linux + title: RHEL - file: how-to/native-install/sles - title: SUSE Linux Enterprise + title: SLES - file: how-to/native-install/post-install - title: Post-Install instructions + title: Post-install instructions - file: how-to/native-install/package-manager-integration title: Package manager integration + - file: how-to/native-install/install-faq + title: Troubleshooting -- caption: Tutorials +- caption: Install entries: - file: how-to/3rd-party/pytorch/index title: PyTorch @@ -59,7 +61,7 @@ subtrees: - file: how-to/docker title: Run Docker containers - file: how-to/spack - title: Introduction to Spack + title: Use Spack - caption: Reference entries: diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index e35cf773..178b92c7 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.8 # by the following command: # # pip-compile requirements.in @@ -49,6 +49,10 @@ idna==3.4 # via requests imagesize==1.4.1 # via sphinx +importlib-metadata==7.0.0 + # via sphinx +importlib-resources==6.1.1 + # via rocm-docs-core jinja2==3.1.2 # via # myst-parser @@ -154,3 +158,7 @@ urllib3==1.26.13 # via requests wrapt==1.14.1 # via deprecated +zipp==3.17.0 + # via + # importlib-metadata + # importlib-resources diff --git a/docs/tutorial/quick-start.rst b/docs/tutorial/quick-start.rst index 026f65bd..b04926f5 100644 --- a/docs/tutorial/quick-start.rst +++ b/docs/tutorial/quick-start.rst @@ -1,180 +1,145 @@ .. meta:: - :description: Quick-start install guide + :description: Quick start install guide :keywords: ROCm installation, AMD, ROCm, Package manager, AMDGPU .. _rocm-install-quick: ************************************************************* -Quick-start install guide +ROCm quick start install guide for Linux ************************************************************* -For a quick summary on installing ROCm on Linux, follow the steps listed on this page. If you want +For a quick summary on installing ROCm on Linux, choose your preferred operating +system and install method and follow the steps listed in the table. If you want more in-depth installation instructions, refer to :ref:`rocm-install-overview`. -To start, choose your preferred install method and operating system: - - -.. grid:: 2 - :gutter: 1 - - .. grid-item-card:: :ref:`rocm-package-man-quick` - - * :ref:`package-man-ubuntu` - * :ref:`package-man-rhel` - * :ref:`package-man-suse` - - .. grid-item-card:: :ref:`rocm-amdgpu-quick` - - * :ref:`amdgpu-ubuntu` - * :ref:`amdgpu-rhel` - * :ref:`amdgpu-suse` - -.. _rocm-package-man-quick: - -Native package manager -========================================== - -.. _package-man-ubuntu: - -Ubuntu ------------------------------------------------- - .. datatemplate:nodata:: .. tab-set:: - {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} - .. tab-item:: {{ os_version }} - :sync: ubuntu-{{ os_version}} - .. code-block:: bash - :substitutions: - - sudo apt install "linux-headers-$(uname -r)" "linux-modules-extra-$(uname -r)" - # See prerequisites. Adding current user to Video and Render groups - sudo usermod -a -G render,video $LOGNAME - wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb - sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb - sudo apt update - sudo apt install amdgpu-dkms - sudo apt install rocm - echo "Please reboot system for all settings to take effect." - {% endfor %} - -.. _package-man-rhel: - -Red Hat Enterprise Linux ------------------------------------------------------------------------------------- - -.. datatemplate:nodata:: - - .. tab-set:: - {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} - .. tab-item:: {{ os_version }} - :sync: rhel-{{ os_version }} rhel-{{ os_release }} - - .. code-block:: bash - :substitutions: - - wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_release }}.noarch.rpm - sudo rpm -ivh epel-release-latest-{{ os_release }}.noarch.rpm - sudo crb enable - sudo yum install kernel-headers kernel-devel - # See prerequisites. Adding current user to Video and Render groups - sudo usermod -a -G render,video $LOGNAME - sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_release }}.noarch.rpm - sudo yum clean all - sudo yum install amdgpu-dkms - sudo yum install rocm - echo "Please reboot system for all settings to take effect." - {% endfor %} - -.. _package-man-suse: - -SUSE Linux Enterprise Server ------------------------------------------------------------------------------------- - -.. datatemplate:nodata:: - - .. tab-set:: - {% for os_version in config.html_context['sles_version_numbers'] %} - {% set os_release, os_sp = os_version.split('.') %} - .. tab-item:: {{ os_version }} - :sync: sle-{{ os_version }} + .. tab-item:: Ubuntu - .. code-block:: bash - :substitutions: + .. tab-set:: - sudo zypper addrepo https://download.opensuse.org/repositories/devel:languages:perl/SLE_{{ os_release }}_SP{{ os_sp }}/devel:languages:perl.repo - sudo zypper install kernel-default-devel - # See prerequisites. Adding current user to Video and Render groups - sudo usermod -a -G render,video $LOGNAME - sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm - sudo zypper refresh - sudo zypper install amdgpu-dkms - sudo zypper install rocm - echo "Please reboot system for all settings to take effect." - {% endfor %} + {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} + .. tab-item:: {{ os_version }} -.. _rocm-amdgpu-quick: + .. tab-set:: -AMDGPU installer -================================================= + .. tab-item:: Native package manager + :sync: native-package-manager -.. _amdgpu-ubuntu: - -Ubuntu ------------------------------------------------------------------------------------- - -.. datatemplate:nodata:: - - .. tab-set:: - {% for (os_version, os_release) in config.html_context['ubuntu_version_numbers'] %} - .. tab-item:: {{ os_version }} - :sync: ubuntu-{{ os_version}} - - .. code-block:: bash - :substitutions: - - sudo apt update - wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb - sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb - sudo amdgpu-install --usecase=graphics,rocm - {% endfor %} - -.. _amdgpu-rhel: - -Red Hat Enterprise Linux ------------------------------------------------------------------------------------- - -.. datatemplate:nodata:: - - .. tab-set:: - {% for (os_release, os_version) in config.html_context['rhel_version_numbers'] %} - .. tab-item:: {{ os_version }} - :sync: rhel-{{ os_version }} rhel-{{ os_release }} - - .. code-block:: bash - :substitutions: - - sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_release }}.noarch.rpm - sudo amdgpu-install --usecase=graphics,rocm - {% endfor %} - -.. _amdgpu-suse: - -SUSE Linux Enterprise Server ------------------------------------------------------------------------------------- - -.. datatemplate:nodata:: - - .. tab-set:: - {% for os_version in config.html_context['sles_version_numbers'] %} - .. tab-item:: {{ os_version }} - :sync: sle-{{ os_version }} + .. code-block:: bash + :substitutions: - .. code-block:: bash - :substitutions: + sudo apt install "linux-headers-$(uname -r)" "linux-modules-extra-$(uname -r)" + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt update + sudo apt install amdgpu-dkms + sudo apt install rocm + echo "Please reboot system for all settings to take effect." - sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm - sudo amdgpu-install --usecase=graphics,rocm - {% endfor %} + .. tab-item:: AMDGPU installer + :sync: amdgpu-installer + + .. code-block:: bash + :substitutions: + + sudo apt install "linux-headers-$(uname -r)" "linux-modules-extra-$(uname -r)" + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + sudo apt update + wget https://repo.radeon.com/amdgpu-install/|amdgpu_version|/ubuntu/{{ os_release }}/amdgpu-install_|amdgpu_install_version|_all.deb + sudo apt install ./amdgpu-install_|amdgpu_install_version|_all.deb + sudo amdgpu-install --usecase=graphics,rocm + {% endfor %} + + .. tab-item:: Red Hat Enterprise Linux + + .. tab-set:: + + {% for os_version in config.html_context['rhel_version_numbers'] %} + {% set os_major, _ = os_version.split('.') %} + .. tab-item:: {{ os_version }} + + .. tab-set:: + + .. tab-item:: Native package manager + :sync: native-package-manager + + .. code-block:: bash + :substitutions: + + wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_major }}.noarch.rpm + sudo rpm -ivh epel-release-latest-{{ os_major }}.noarch.rpm + sudo crb enable + sudo yum install kernel-headers kernel-devel + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_major }}.noarch.rpm + sudo yum clean all + sudo yum install amdgpu-dkms + sudo yum install rocm + echo "Please reboot system for all settings to take effect." + + .. tab-item:: AMDGPU installer + :sync: amdgpu-installer + + .. code-block:: bash + :substitutions: + + wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ os_major }}.noarch.rpm + sudo rpm -ivh epel-release-latest-{{ os_major }}.noarch.rpm + sudo crb enable + sudo yum install kernel-headers kernel-devel + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + sudo yum install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/rhel/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.el{{ os_major }}.noarch.rpm + sudo amdgpu-install --usecase=graphics,rocm + {% endfor %} + + + .. tab-item:: SUSE Linux Enterprise Server + + .. tab-set:: + + {% for os_version in config.html_context['sles_version_numbers'] %} + .. tab-item:: {{ os_version }} + + .. tab-set:: + + .. tab-item:: Native package manager + :sync: native-package-manager + + .. code-block:: bash + :substitutions: + + {% if os_version == "15.4" %} + # Installing Perl module from SLES 15.5, as it was removed from 15.4 + sudo zypper addrepo https://download.opensuse.org/repositories/devel:/languages:/perl/15.5/devel:languages:perl.repo + {% else %} + sudo zypper addrepo https://download.opensuse.org/repositories/devel:languages:perl/{{ os_version}}/devel:languages:perl.repo + {% endif %} + sudo zypper install kernel-default-devel + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm + sudo zypper refresh + sudo zypper install amdgpu-dkms + sudo zypper install rocm + echo "Please reboot system for all settings to take effect." + + .. tab-item:: AMDGPU installer + :sync: amdgpu-installer + + .. code-block:: bash + :substitutions: + + {% if os_version == "15.4" %} + # Installing Perl module from SLES 15.5, as it was removed from 15.4 + sudo zypper addrepo https://download.opensuse.org/repositories/devel:/languages:/perl/15.5/devel:languages:perl.repo + {% else %} + sudo zypper addrepo https://download.opensuse.org/repositories/devel:languages:perl/{{ os_version}}/devel:languages:perl.repo + {% endif %} + sudo zypper install kernel-default-devel + sudo usermod -a -G render,video $LOGNAME # Adding current user to Video, Render groups. See prerequisites. + sudo zypper --no-gpg-checks install https://repo.radeon.com/amdgpu-install/|amdgpu_version|/sle/{{ os_version }}/amdgpu-install-|amdgpu_install_version|.noarch.rpm + sudo amdgpu-install --usecase=graphics,rocm + {% endfor %} From c74d76dadff5df6bf695072ecad1c1b645371c7c Mon Sep 17 00:00:00 2001 From: Peter Jun Park Date: Fri, 26 Apr 2024 14:17:36 -0400 Subject: [PATCH 15/17] recompile requirements --- docs/sphinx/requirements.txt | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index 178b92c7..e35cf773 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.8 +# This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile requirements.in @@ -49,10 +49,6 @@ idna==3.4 # via requests imagesize==1.4.1 # via sphinx -importlib-metadata==7.0.0 - # via sphinx -importlib-resources==6.1.1 - # via rocm-docs-core jinja2==3.1.2 # via # myst-parser @@ -158,7 +154,3 @@ urllib3==1.26.13 # via requests wrapt==1.14.1 # via deprecated -zipp==3.17.0 - # via - # importlib-metadata - # importlib-resources From 05eeb7fb248d7eebef0701eea6fb5f43d46ed8e7 Mon Sep 17 00:00:00 2001 From: Peter Jun Park Date: Fri, 26 Apr 2024 14:22:33 -0400 Subject: [PATCH 16/17] Fix TOC Fixes build error due to duplicate resources in TOC. Fixes wording --- docs/sphinx/_toc.yml.in | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 2df3f922..4caecdab 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -10,8 +10,6 @@ subtrees: title: Prerequisites - file: tutorial/install-overview title: Installation overview - - file: tutorial/install-overview - title: Installation overview - file: reference/system-requirements title: System requirements - file: how-to/amdgpu-install @@ -45,18 +43,16 @@ subtrees: title: PyTorch + Docker - - file: how-to/3rd-party/magma-install - title: Install Magma - file: how-to/3rd-party/pytorch-install-old - title: Install PyTorch + title: PyTorch - file: how-to/3rd-party/tensorflow-install title: TensorFlow - file: how-to/3rd-party/jax-install title: JAX - file: how-to/3rd-party/magma-install - title: Magma + title: MAGMA -- caption: How-to +- caption: How to entries: - file: how-to/docker title: Run Docker containers From 47e59c3fe448854ea368a7fabb9bd8950c80b1d5 Mon Sep 17 00:00:00 2001 From: Peter Jun Park Date: Fri, 26 Apr 2024 15:53:44 -0400 Subject: [PATCH 17/17] Fix spellchecking linting errors --- .../docker_examples/torch/dockerfile_from_dev_ubuntu | 2 +- docs/how-to/3rd-party/pytorch-install.rst | 2 +- docs/how-to/3rd-party/pytorch/docker.rst | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docker_examples/torch/dockerfile_from_dev_ubuntu b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu index 39df3f2b..a4ddc03d 100644 --- a/docs/docker_examples/torch/dockerfile_from_dev_ubuntu +++ b/docs/docker_examples/torch/dockerfile_from_dev_ubuntu @@ -19,7 +19,7 @@ RUN apt-get update \ RUN python3.11 -m venv venv ENV PATH=/venv/bin:$PATH -# Install Pytorch +# Install PyTorch RUN pip3 install torch==2.2.1 torchvision==0.17.1 --index-url https://download.pytorch.org/whl/rocm$ROCM_VERSION/ # Install additional python dependencies diff --git a/docs/how-to/3rd-party/pytorch-install.rst b/docs/how-to/3rd-party/pytorch-install.rst index 1b5d6d42..9405ba8b 100644 --- a/docs/how-to/3rd-party/pytorch-install.rst +++ b/docs/how-to/3rd-party/pytorch-install.rst @@ -64,7 +64,7 @@ to `pytorch.org/get-started/locally/ ` wheels command, you must select 'Linux', 'Python', 'pip', and 'ROCm' in the matrix. .. note:: - The available ROCm release varies between the 'Pytorch Build' of ``Stable`` or ``Nightly``. More recent releases are generally available through the Nightly builds. + The available ROCm release varies between the 'PyTorch Build' of ``Stable`` or ``Nightly``. More recent releases are generally available through the Nightly builds. 1. Choose one of the following three options: diff --git a/docs/how-to/3rd-party/pytorch/docker.rst b/docs/how-to/3rd-party/pytorch/docker.rst index 3729ccb6..79fce425 100644 --- a/docs/how-to/3rd-party/pytorch/docker.rst +++ b/docs/how-to/3rd-party/pytorch/docker.rst @@ -1,16 +1,16 @@ PyTorch+ROCm in Docker ======================= -Using Docker to run your PyTorch + ROCm application is one of the best ways to get consistent and reproducible environemnts. +Using Docker to run your PyTorch + ROCm application is one of the best ways to get consistent and reproducible environments. -Additional PyTorch Docker Args +Additional PyTorch Docker arguments ------------------------------- Regardless of which image you use or build, running PyTorch docker images requires several arguments in addition to those discussed in :ref:`docker-access-gpus-in-container`. * ``--ipc=host`` OR ``--shm-size=Xg`` - PyTorch uses shared memory to share data betwee processes (such as multithreaded data loaders). As such, you must increase the shared memory size, which defaults to 64M. This can be done in two ways: + PyTorch uses shared memory to share data between processes (such as multi-threaded data loaders). As such, you must increase the shared memory size, which defaults to 64M. This can be done in two ways: * ``--ipc=host`` shares the IPC directly from the host, which will allow the container access to all resources on the host. For most applications, this is sufficient. @@ -40,7 +40,7 @@ Alternatively, you can use the equivalent ``docker-compose.yaml``: ipc: host -Pre-Built PyTorch+ROCm Docker Images +Pre-built PyTorch+ROCm Docker images -------------------------------------- The easiest method to run PyTorch+ROCm is to use a pre-built image from `AMD ROCm on docker hub `_, which contain ROCm as well as PyTorch. You can select an image from either of the following sources, with your desired OS, ROCm, Python, and PyTorch versions. @@ -63,7 +63,7 @@ For example, to run the latest rocm/pytorch image, run: Custom Docker Images -------------------- -As is often the case, your specific requirements may not be met by one of the pre-built PyTorch+ROCm images. For example, you may need additional pythond dependencies, a different version of PyTorch, or even a completely different combination of OS, ROCm, Python, and PyTorch. +As is often the case, your specific requirements may not be met by one of the pre-built PyTorch+ROCm images. For example, you may need additional Python dependencies, a different version of PyTorch, or even a completely different combination of OS, ROCm, Python, and PyTorch. To meet these needs, you can build your own ROCm docker images. @@ -72,7 +72,7 @@ From ROCm dev container We provide several dev containers, which contain just the base OS + ROCm. These containers are a great place to start when building custom images, as you don't have to install ROCm into the image yourself. -* Select a base image that neets your needs. To find a list of base images, `search rocm/dev `_ on Docker Hub. +* Select a base image that meets your needs. To find a list of base images, `search rocm/dev `_ on Docker Hub. * Build your ``dockerfile`` * Install required python version