Skip to content

Commit 11baad6

Browse files
anisha-amdanisha-amd
authored
Docs: frameworks 25.10 - installation - DGL and llama.cpp (#618)
1 parent 649d9c6 commit 11baad6

File tree

7 files changed

+1104
-326
lines changed

7 files changed

+1104
-326
lines changed

‎docs/install/3rd-party/dgl-install.rst‎

Lines changed: 137 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ see :doc:`rocm:compatibility/ml-compatibility/dgl-compatibility`.
1616

1717
.. note::
1818

19-
DGL is supported on ROCm 6.4.0.
19+
DGL is supported on ROCm 7.0.0, 6.4.3, and 6.4.0. This topic provides installation
20+
instructions for ROCm 7.0.0 and 6.4.3. For ROCm 6.4.0, see :doc:`previous-versions/dgl-history`.
2021

2122
Install DGL
2223
================================================================================
@@ -25,6 +26,7 @@ To install DGL on ROCm, you have the following options:
2526

2627
- :ref:`Use the prebuilt Docker image <using-docker-with-dgl-pre-installed>` **(recommended)**
2728
- :ref:`Build your own docker image <build-dgl-rocm-docker-image>`
29+
- :ref:`Use a wheels package <dgl-wheels-package>`
2830

2931
.. _using-docker-with-dgl-pre-installed:
3032

@@ -36,12 +38,11 @@ The tested, prebuilt image includes DGL, PyTorch, ROCm, and other dependencies.
3638

3739
.. important::
3840

39-
To follow these instructions, input your chosen tag into ``<TAG>``. Example: ``dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.6.0``.
41+
To follow these instructions, input your chosen tag into ``<TAG>``. Example: ``dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.8.0``.
4042

41-
You can download Docker images for DGL with specific ROCm, PyTorch, Python and operating system versions.
43+
You can download Docker images for DGL with specific ROCm, PyTorch, Python, and operating system versions.
4244
See the available tags on `Docker Hub <https://hub.docker.com/r/rocm/dgl/tags>`_ and see :ref:`dgl-docker-support` below.
4345

44-
4546
1. Download your required public `DGL Docker image <https://hub.docker.com/r/rocm/dgl/tags>`_
4647

4748
.. code-block:: bash
@@ -52,78 +53,73 @@ The tested, prebuilt image includes DGL, PyTorch, ROCm, and other dependencies.
5253

5354
.. code-block:: bash
5455
55-
docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
56-
--device=/dev/kfd --device=/dev/dri --group-add video \
57-
--ipc=host --shm-size 8G rocm/dgl:<TAG>
56+
sudo docker run -it --network=host --device=/dev/kfd --device=/dev/dri \
57+
--group-add=video --ipc=host --cap-add=SYS_PTRACE --security-opt \
58+
seccomp=unconfined --shm-size 8G rocm/dgl:<TAG>
5859
5960
.. note::
6061

6162
This will automatically download the image if it does not exist on the host. You can also pass
6263
the ``-v`` argument to mount any data directories from the host onto the container.
6364

64-
6565
.. _dgl-docker-support:
6666

6767
Docker image support
6868
--------------------------------------------------------------------------------
6969

70-
AMD validates and publishes ready-made `DGL Docker images <https://hub.docker.com/r/rocm/dgl>`_
71-
with ROCm backends on Docker Hub. The following Docker image tags and associated inventories are
72-
validated for ROCm 6.4.0.
70+
AMD validates and publishes ready-made `DGL Docker images <https://hub.docker.com/r/rocm/dgl/tags>`_
71+
with ROCm backends on Docker Hub. The following Docker image tags and associated inventories are
72+
validated for their respective ROCm versions listed below.
7373

7474
.. tab-set::
7575

76-
.. tab-item:: PyTorch 2.6.0
76+
.. tab-item:: ROCm 7.0.0
7777

7878
.. tab-set::
7979

80-
.. tab-item:: Ubuntu 24.04
80+
.. tab-item:: PyTorch 2.8.0
8181

8282
Tag
83-
`rocm/dgl:dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.6.0 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.6.0/images/sha256-8ce2c3bcfaa137ab94a75f9e2ea711894748980f57417739138402a542dd5564>`_
83+
`rocm/dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.8.0 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.8.0/images/sha256-943698ddf54c22a7bcad2e5b4ff467752e29e4ba6d0c926789ae7b242cbd92dd>`_
8484

8585
Inventory
86-
* `ROCm 6.4.0 <https://repo.radeon.com/rocm/apt/6.4/>`_
87-
* `Python 3.12.9 <https://www.python.org/downloads/release/python-3129/>`_
88-
* `PyTorch 2.6.0 <https://github.com/ROCm/pytorch/tree/release/2.6>`_
89-
90-
.. tab-item:: PyTorch 2.4.1
86+
* `ROCm 7.0.0 <https://repo.radeon.com/rocm/apt/7.0/>`__
87+
* `Python 3.12.9 <https://www.python.org/downloads/release/python-3129/>`__
88+
* `PyTorch 2.8.0 <https://github.com/pytorch/pytorch/releases/tag/v2.8.0>`__
9189

92-
.. tab-set::
93-
94-
.. tab-item:: Ubuntu 24.04
90+
.. tab-item:: PyTorch 2.6.0
9591

9692
Tag
97-
`rocm/dgl:dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.4.1 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.4.1/images/sha256-cf1683283b8eeda867b690229c8091c5bbf1edb9f52e8fb3da437c49a612ebe4>`_
93+
`rocm/dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.6.0 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.6.0/images/sha256-b2ec286a035eb7d0a6aab069561914d21a3cac462281e9c024501ba5ccedfbf7>`__
9894

9995
Inventory
100-
* `ROCm 6.4.0 <https://repo.radeon.com/rocm/apt/6.4/>`_
101-
* `Python 3.12.9 <https://www.python.org/downloads/release/python-3129/>`_
102-
* `PyTorch 2.4.1 <https://github.com/ROCm/pytorch/tree/release/2.4>`_
96+
* `ROCm 7.0.0 <https://repo.radeon.com/rocm/apt/7.0/>`__
97+
* `Python 3.12.9 <https://www.python.org/downloads/release/python-3129/>`__
98+
* `PyTorch 2.6.0 <https://github.com/pytorch/pytorch/releases/tag/v2.6.0>`__
10399

104-
.. tab-item:: Ubuntu 22.04
100+
.. tab-item:: PyTorch 2.7.1
105101

106102
Tag
107-
`rocm/dgl:dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.4.1 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.4.1/images/sha256-4834f178c3614e2d09e89e32041db8984c456d45dfd20286e377ca8635686554>`_
103+
`rocm/dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu22.04_py3.10_pytorch_2.7.1 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4.0.amd0_rocm7.0.0_ubuntu22.04_py3.10_pytorch_2.7.1/images/sha256-d27aee16df922ccf0bcd9107bfcb6d20d34235445d456c637e33ca6f19d11a51>`_
108104

109105
Inventory
110-
* `ROCm 6.4.0 <https://repo.radeon.com/rocm/apt/6.4/>`_
111-
* `Python 3.10.16 <https://www.python.org/downloads/release/python-31016/>`_
112-
* `PyTorch 2.4.1 <https://github.com/ROCm/pytorch/tree/release/2.4>`_
106+
* `ROCm 7.0.0 <https://repo.radeon.com/rocm/apt/7.0/>`__
107+
* `Python 3.10.16 <https://www.python.org/downloads/release/python-31016/>`__
108+
* `PyTorch 2.7.1 <https://github.com/pytorch/pytorch/releases/tag/v2.7.1>`__
113109

114-
.. tab-item:: PyTorch 2.3.0
110+
.. tab-item:: ROCm 6.4.3
115111

116112
.. tab-set::
117113

118-
.. tab-item:: Ubuntu 22.04
114+
.. tab-item:: PyTorch 2.6.0
119115

120116
Tag
121-
`rocm/dgl:dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.3.0 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.3.0/images/sha256-88740a2c8ab4084b42b10c3c6ba984cab33dd3a044f479c6d7618e2b2cb05e69B>`_
117+
`rocm/dgl:dgl-2.4.0.amd0_rocm6.4.3_ubuntu24.04_py3.12_pytorch_2.6.0 <https://hub.docker.com/layers/rocm/dgl/dgl-2.4.0.amd0_rocm6.4.3_ubuntu24.04_py3.12_pytorch_2.6.0/images/sha256-f3ba6a3c9ec9f6c1cde28449dc9780e0c4c16c4140f4b23f158565fbfd422d6b>`_
122118

123119
Inventory
124-
* `ROCm 6.4.0 <https://repo.radeon.com/rocm/apt/6.4/>`_
125-
* `Python 3.10.16 <https://www.python.org/downloads/release/python-31016/>`_
126-
* `PyTorch 2.3.0 <https://github.com/ROCm/pytorch/tree/release/2.3>`_
120+
* `ROCm 6.4.3 <https://repo.radeon.com/rocm/apt/6.4.3/>`__
121+
* `Python 3.12.9 <https://www.python.org/downloads/release/python-3129/>`__
122+
* `PyTorch 2.6.0 <https://github.com/ROCm/pytorch/tree/release/2.6>`__
127123

128124
.. _build-dgl-rocm-docker-image:
129125

@@ -141,70 +137,120 @@ Build your own Docker image
141137

142138
.. tab-set::
143139

144-
.. tab-item:: DGL on Ubuntu 22.04 + ROCm 6.4 + Py 3.10 + PyTorch 2.4.1
140+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 7.0.0 + Py 3.12 + PyTorch 2.8.0
145141

146142
To build the Docker container, run the following command:
147143

148144
.. code-block:: bash
149145
150-
# DGL on Ubuntu 22.04 + ROCm 6.4 + Py 3.10 + PyTorch 2.4.1
146+
# DGL on Ubuntu 24.04 + ROCm 7.0.0 + Py 3.12 + PyTorch 2.8.0
151147
docker build \
152-
-t dgl:dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.4.1 \
153-
--build-arg BASE_IMAGE=rocm/pytorch:rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.4.1 \
154-
--build-arg ARG_CONDA_ENV=py_3.10 \
148+
-t dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.8.0 \
149+
--build-arg BASE_IMAGE=rocm/pytorch:rocm7.0_ubuntu24.04_py3.12_pytorch_release_2.8.0 \
155150
--build-arg ARG_MAX_JOBS=8 \
156151
--build-arg ARG_GPU_BUILD_TARGETS="gfx90a,gfx942" \
157-
-f Dockerfile.rocm \
152+
--build-arg ARG_DGL_ARTIFACTS_DIR="/artifacts" \
153+
-f docker/Dockerfile.ci_gpu_rocm \
158154
.
159155
160-
.. tab-item:: DGL on Ubuntu 22.04 + ROCm 6.4 + Py 3.10 + PyTorch 2.3.0
156+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 7.0.0 + Py 3.12 + PyTorch 2.6.0
161157

162158
To build the Docker container, run the following command:
163159

164160
.. code-block:: bash
165161
166-
# DGL on Ubuntu 22.04 + ROCm 6.4 + Py 3.10 + PyTorch 2.3.0
162+
# DGL on Ubuntu 24.04 + ROCm 7.0 + Py 3.12 + PyTorch 2.6.0
167163
docker build \
168-
-t dgl:dgl-2.4_rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.3.0 \
169-
--build-arg BASE_IMAGE=rocm/pytorch:rocm6.4_ubuntu22.04_py3.10_pytorch_release_2.3.0 \
170-
--build-arg ARG_CONDA_ENV=py_3.10 \
164+
-t dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu24.04_py3.12_pytorch_2.6.0 \
165+
--build-arg BASE_IMAGE=rocm/pytorch:rocm7.0_ubuntu24.04_py3.12_pytorch_release_2.6.0 \
171166
--build-arg ARG_MAX_JOBS=8 \
172167
--build-arg ARG_GPU_BUILD_TARGETS="gfx90a,gfx942" \
173-
-f Dockerfile.rocm \
168+
--build-arg ARG_DGL_ARTIFACTS_DIR="/artifacts" \
169+
-f docker/Dockerfile.ci_gpu_rocm \
174170
.
175171
176-
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 6.4 + Py 3.12 + PyTorch 2.4.1
172+
.. tab-item:: DGL on Ubuntu 22.04 + ROCm 7.0.0 + Py 3.10 + PyTorch 2.7.1
177173

178174
To build the Docker container, run the following command:
179175

180176
.. code-block:: bash
181177
182-
# DGL on Ubuntu 24.04 + ROCm 6.4 + Py 3.12 + PyTorch 2.4.1
178+
# DGL on Ubuntu 22.04 + ROCm 7.0.0 + Py 3.10 + PyTorch 2.7.1
183179
docker build \
184-
-t dgl:dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.4.1 \
185-
--build-arg BASE_IMAGE=rocm/pytorch:rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.4.1 \
186-
--build-arg ARG_CONDA_ENV=py_3.12 \
180+
-t dgl:dgl-2.4.0.amd0_rocm7.0.0_ubuntu22.04_py3.10_pytorch_2.7.1 \
181+
--build-arg BASE_IMAGE=rocm/pytorch:rocm7.0_ubuntu22.04_py3.10_pytorch_release_2.7.1 \
187182
--build-arg ARG_MAX_JOBS=8 \
188183
--build-arg ARG_GPU_BUILD_TARGETS="gfx90a,gfx942" \
189-
-f Dockerfile.rocm \
184+
--build-arg ARG_DGL_ARTIFACTS_DIR="/artifacts" \
185+
-f docker/Dockerfile.ci_gpu_rocm \
190186
.
191187
192-
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 6.4 + Py 3.12 + PyTorch 2.6.0
188+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 6.4.3 + Py 3.12 + PyTorch 2.6.0
193189

194190
To build the Docker container, run the following command:
195191

196192
.. code-block:: bash
197193
198-
# DGL on Ubuntu 24.04 + ROCm 6.4 + Py 3.12 + PyTorch 2.6.0
194+
# DGL on Ubuntu 24.04 + ROCm 6.4.3 + Py 3.12 + PyTorch 2.6.0
199195
docker build \
200-
-t dgl:dgl-2.4_rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.6.0 \
201-
--build-arg BASE_IMAGE=rocm/pytorch:rocm6.4_ubuntu24.04_py3.12_pytorch_release_2.6.0 \
196+
-t dgl:dgl-2.4.0.amd0_rocm6.4.3_ubuntu24.04_py3.12_pytorch_2.6.0 \
197+
--build-arg BASE_IMAGE=rocm/pytorch:rocm6.4.3_ubuntu24.04_py3.12_pytorch_release_2.6.0 \
202198
--build-arg ARG_CONDA_ENV=py_3.12 \
203199
--build-arg ARG_MAX_JOBS=8 \
204200
--build-arg ARG_GPU_BUILD_TARGETS="gfx90a,gfx942" \
205201
-f Dockerfile.rocm \
206202
.
207-
203+
204+
.. _dgl-wheels-package:
205+
206+
Use a wheels package
207+
--------------------------------------------------------------------------------
208+
209+
The DGL ``.whl`` packages are hosted on the AMD PyPI repository. Instead of manually downloading the files,
210+
you can simply install DGL using ``pip`` with the provided URL.
211+
This command will automatically download and install the appropriate ``.whl`` file.
212+
213+
.. tab-set::
214+
215+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 7.0.0 + Py 3.12 + PyTorch 2.8.0
216+
217+
To install using wheels, run the following command:
218+
219+
.. code-block:: bash
220+
221+
pip install https://pypi.amd.com/rocm-7.0.0/packages/amd-dgl/amd_dgl-2.4.0+amd0.torch2.8.0.rocm7.0.0.git64359f59.ubuntu24.4-cp312-cp312-linux_x86_64.whl
222+
223+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 7.0.0 + Py 3.12 + PyTorch 2.6.0
224+
225+
To install using wheels, run the following command:
226+
227+
.. code-block:: bash
228+
229+
pip install https://pypi.amd.com/rocm-7.0.0/packages/amd-dgl/amd_dgl-2.4.0+amd0.torch2.6.0.rocm7.0.0.git2e48b21f.ubuntu24.4-cp312-cp312-linux_x86_64.whl
230+
231+
.. tab-item:: DGL on Ubuntu 22.04 + ROCm 7.0.0 + Py 3.10 + PyTorch 2.7.1
232+
233+
To install using wheels, run the following command:
234+
235+
.. code-block:: bash
236+
237+
pip install https://pypi.amd.com/rocm-7.0.0/packages/amd-dgl/amd_dgl-2.4.0+amd0.torch2.7.1.rocm7.0.0.git698b58a9.ubuntu22.4-cp310-cp310-linux_x86_64.whl
238+
239+
.. tab-item:: DGL on Ubuntu 24.04 + ROCm 6.4.3 + Py 3.12 + PyTorch 2.6.0
240+
241+
To install using wheels, run the following command:
242+
243+
.. code-block:: bash
244+
245+
pip install https://pypi.amd.com/rocm-6.4.3/packages/amd-dgl/amd_dgl-2.4.0+amd0.torch2.6.0.gitdbfe118.ubuntu24.4-cp312-cp312-linux_x86_64.whl
246+
247+
After installing a ``.whl`` file, you can confirm that the package was installed successfully using:
248+
249+
.. code-block:: bash
250+
251+
pip show amd_dgl
252+
253+
208254
Test the DGL installation
209255
================================================================================
210256

@@ -227,16 +273,44 @@ To check for Python import:
227273
228274
python -c "import dgl; print('dgl import successful, version:', dgl.__version__)" || echo "Failed to import DGL"
229275
276+
Run tests for DGL
277+
--------------------------------------------------------------------------------
278+
279+
You can also run tests from the scripts folder at ``/src/dgl/``.
280+
These tests are only viable if you are using the above Docker containers or building Docker containers from source.
281+
282+
To run Python tests:
283+
284+
.. code-block:: bash
285+
286+
cd /src/dgl
287+
bash tests/scripts/task_unit_test_rocm.sh pytorch gpu
288+
289+
To run C++ tests:
290+
291+
.. code-block:: bash
292+
293+
cd /src/dgl
294+
bash tests/scripts/task_cpp_unit_test.sh
295+
296+
Estimated time: the tests usually take 10-15 minutes to run.
297+
230298
Run a DGL example
231299
================================================================================
232300

233-
Multiple use cases of DGL have been tested and verified.
234-
However, a recommended example follows a drug discovery pipeline using the ``SE3Transformer``.
235-
This detailed procedure and steps will be outlined in the `AMD ROCm blog <https://rocm.blogs.amd.com/>`_, where you can search for DGL examples.
301+
Multiple use cases of DGL have been tested and verified. However, a recommended
302+
example follows a drug discovery pipeline using the ``SE3Transformer``.
303+
For use cases and recommendations, refer to the `AMD ROCm blog <https://rocm.blogs.amd.com/>`__,
304+
where you can search for DGL examples and best practices to optimize your workloads on AMD GPUs.
236305

237306
Troubleshooting
238307
================================================================================
239308

240309
- **Unable to access Docker or GPU in user accounts?** Ensure the user is added to ``docker``, ``video``, and ``render`` groups. See :ref:`group_permissions`.
241310

242311
- **Profiling DGL workloads?** Use the PyTorch Profiler, as explained in :ref:`mi300x-pytorch-profiler` to profile GPU kernels on ROCm.
312+
313+
Previous versions
314+
===============================================================================
315+
See :doc:`previous-versions/dgl-history` to find documentation for previous releases
316+
of the ``ROCm/dgl`` Docker image.

0 commit comments

Comments
 (0)