AMD MIGraphX

AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference.

[!NOTE]
The published documentation is available at MIGraphX in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the docs folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see Contribute to ROCm documentation.

[!NOTE]
You must install ROCm before
installing MIGraphX.

Installing from binaries

Install binaries using:

bash
sudo apt update && sudo apt install -y migraphx

Header files and libraries are installed under /opt/rocm-<version>, where <version> is the ROCm
version.

Building from source

You have three options for building from source:

ROCm build tool: Uses
rbuild to install prerequisites, then you can build
the libraries with a single command.
CMake: Uses a script to install prerequisites, then you can use
CMake to build the source.
Docker: Builds a Docker image with all prerequisites installed, then you can build the
MIGraphX sources inside a Docker container.

Build prerequisites

The following is a list of prerequisites for building MIGraphX.

ROCm CMake modules required
MIOpen for running on the GPU
rocBLAS for running on the GPU
HIP for running on the GPU
Protobuf for reading onnx
files
Half, an IEEE 754-based half-precision floating point library
pybind11 for python bindings
JSON for model serialization to json string format
MessagePack for model serialization to binary format
SQLite3 to create database of kernels' tuning information or run queries on existing database

Installing the ROCm build tool rbuild.

Install rocm-cmake, pip3, rocblas, and miopen-hip:

bash
sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip

Set up and activate python venv for rbuild:

bash
python3 -m venv venv_rbuild
source venv_rbuild/bin/activate

Install rbuild in the python venv:

bash
pip install https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz

[!NOTE]
You can deactivate the python virtual environment with deactivate.

Compile using the ROCm build tool rbuild.

Follow instructions in installing rbuild

Build MIGraphX source code:

bash
rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')

Once completed, all prerequisites are in the depend folder and MIGraphX is in the build directory.

[!NOTE]
If you get an rbuild: command not found error, it's because rbuild is installed in $HOME/.local/bin,
which is not in PATH. You can either export PATH as export PATH=$HOME/.local/bin:$PATH to add
the folder to PATH, or add the option --prefix /usr/local in the pip3 command when installing rbuild.

Use CMake to build MIGraphX

Follow instructions in installing rbuild
Install the prerequisites:
```
bash
rbuild prepare -d depend
```
This puts all the prerequisites are in depend the folder. They can be used in the cmake
configuration as -DCMAKE_PREFIX_PATH=depend.

If you have sudo access, as an alternative to the rbuild command, you can install the prerequisites
in the same way as a Dockerfile, by calling ./tools/install_prereqs.sh.

By default, all prerequisites are installed at the default location (/usr/local) and are accessible by all
users. For the default location, sudo is required to run the script. You can also specify a different
location using ./tools/install_prereqs.sh $custom_location.
Go to the project folder and create a build directory:
```
bash
mkdir build
cd build
```
Configure CMake. If the prerequisites are installed at the default location /usr/local, use:
```
bash
CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
```
Otherwise, you need to set -DCMAKE_PREFIX_PATH=$your_loc to configure CMake.

The default build type is Release. To build MIGraphX in debug mode, pass
-DCMAKE_BUILD_TYPE=Debug when configuring CMake:
```
bash
CXX=/opt/rocm/llvm/bin/clang++ cmake .. \
    -DCMAKE_BUILD_TYPE=Debug \
    -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
```
For optimized binaries with debug symbols, use -DCMAKE_BUILD_TYPE=RelWithDebInfo.

Build MIGraphX source code:

cpp
make -j$(nproc)

You can verify this using:

cpp
make -j$(nproc) check

Install MIGraphX libraries:
```
cpp
make install
```

Use Docker

The easiest way to set up the development environment is to use Docker.

With the Dockerfile, build a Docker image:
```
bash
    docker build -t migraphx .
```

Enter the development environment using docker run:

bash
    docker run --device='/dev/kfd' --device='/dev/dri' -v=`pwd`:/code/AMDMIGraphX -w /code/AMDMIGraphX --group-add video -it migraphx

In the Docker container, all required prerequisites are already installed, so you can go to the folder
/code/AMDMIGraphX and follow the steps (starting from 2) in the
Use CMake to build MIGraphX.

Using the MIGraphX Python module

To use MIGraphX's Python module, you can set PYTHONPATH or use the .deb package:

Setting PYTHONPATH:

bash
export PYTHONPATH=/opt/rocm/lib:$PYTHONPATH

Creating the deb package:
```
bash
make package
```
This provides the path for .deb package.

To install:
```
bash
dpkg -i <path_to_deb_file>
```

Calling MIGraphX APIs

To use MIGraphX's C/C++ API in your CMake project, you must set CMAKE_PREFIX_PATH to the
MIGraphX installation location and run:

cmake
find_package(migraphx)
target_link_libraries(myApp migraphx::c)

Where myApp is the CMake target in your project.

Other Dockerfiles

Alternative Dockerfiles are available under tools/docker/:

tools/docker/ubuntu_2404.dockerfile — Ubuntu 24.04 with ROCm 7.1.1
tools/docker/ubuntu_2204.dockerfile — Ubuntu 22.04 with ROCm 6.4.2

To build with one of these, use the -f flag. For example:

bash
docker build -t migraphx:2404 -f tools/docker/ubuntu_2404.dockerfile .

Then follow the same docker run and build steps described in the
Use Docker section.

Building for development

Using rbuild, you can install the dependencies for development with:

bash
rbuild develop -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')

This installs development dependencies in the deps directory and configures cmake to use those
dependencies in the build directory. You can change these directories by passing the --deps-dir and
--build-dir flags to the rbuild command:

bash
rbuild develop --build-dir build_rocm_55 --deps-dir /home/user/deps_dir

Building the documentation

HTML and PDF documentation can be built using:

cmake --build . --config Release --target doc OR make doc

This will build a local searchable web site inside the docs/html folder.

Documentation is built using Doxygen and rocm-docs-core

Run the steps below to build documentation locally. You can reuse the same venv from installing rbuild.

bash
cd docs

pip3 install -r sphinx/requirements.txt

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Depending on your setup sudo may be required for the pip install.

Formatting the code

All the code is formatted using clang-format. To format a file, use:

clang
clang-format-10 -style=file -i <path-to-source-file>

Also, githooks can be installed to format the code per-commit:

bash
./.githooks/install