# AMD MIGraphX
AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference.
>[!NOTE]
>The published documentation is available at [MIGraphX](https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/) 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](https://rocm.docs.amd.com/en/latest/contribute/contributing.html).
> [!NOTE]
> You must [install ROCm](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/index.html) 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](#compile-using-the-rocm-build-tool-rbuild): Uses
[rbuild](https://github.com/RadeonOpenCompute/rbuild) to install prerequisites, then you can build
the libraries with a single command.
* [CMake](#use-cmake-to-build-migraphx): Uses a script to install prerequisites, then you can use
CMake to build the source.
* [Docker](#use-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](https://github.com/RadeonOpenCompute/rocm-cmake) **required**
* [MIOpen](https://github.com/ROCmSoftwarePlatform/MIOpen) for running on the GPU
* [rocBLAS](https://github.com/ROCmSoftwarePlatform/rocBLAS) for running on the GPU
* [HIP](https://github.com/ROCm-Developer-Tools/HIP) for running on the GPU
* [Protobuf](https://github.com/google/protobuf) for reading [onnx](https://github.com/onnx/onnx)
files
* [Half](http://half.sourceforge.net/), an IEEE 754-based half-precision floating point library
* [pybind11](https://pybind11.readthedocs.io/en/stable/) for python bindings
* [JSON](https://github.com/nlohmann/json) for model serialization to json string format
* [MessagePack](https://msgpack.org/index.html) for model serialization to binary format
* [SQLite3](https://www.sqlite.org/index.html) to create database of kernels' tuning information or run queries on existing database
### Installing the ROCm build tool [rbuild](https://github.com/RadeonOpenCompute/rbuild).
1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`:
```bash
sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
```
2. Set up and activate python venv for rbuild:
```bash
python3 -m venv venv_rbuild
source venv_rbuild/bin/activate
```
3. Install [rbuild](https://github.com/RadeonOpenCompute/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](https://github.com/RadeonOpenCompute/rbuild).
1. Follow instructions in [installing rbuild](#installing-the-rocm-build-tool-rbuild)
2. 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
1. Follow instructions in [installing rbuild](#installing-the-rocm-build-tool)
2. 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`.
3. Go to the project folder and create a `build` directory:
```bash
mkdir build
cd build
```
4. 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`.
5. Build MIGraphX source code:
```cpp
make -j$(nproc)
```
You can verify this using:
```cpp
make -j$(nproc) check
```
6. Install MIGraphX libraries:
```cpp
make install
```
### Use Docker
The easiest way to set up the development environment is to use Docker. ROCm's
underlying drivers and libraries, known as "TheRock", now support multi-arch
packaging, meaning it only installs device-code packages for the GPU architecture
present on the system. Setting `GPU_ARCH` reduces the image size; leaving it
unset installs device code for all supported architectures, which is useful when
the same Docker image needs to run on different ROCm-supported GPUs.
1. With the Dockerfile, build a Docker image:
```bash
docker build -t migraphx .
```
or
```bash
docker build -t migraphx --build-arg GPU_ARCH=$(rocminfo | grep -o -m1 'gfx.*') .
```
2. 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
```
3. 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](#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
The default `Dockerfile` builds against ROCm 7.13 and newer using TheRock
(`amdrocm-*`) packages. To build against ROCm 7.2.x and older, use the legacy
dockerfile instead:
```bash
docker build -t migraphx:legacy -f tools/docker/legacy.dockerfile .
```
Alternative Dockerfiles are available under `tools/docker/`:
* `tools/docker/legacy.dockerfile` — ROCm 7.2.x and older (Ubuntu 22.04); use this when building against ROCm releases that predate TheRock packages
* `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](#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](http://www.stack.nl/~dimitri/doxygen/download.html) and [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core)
Run the steps below to build documentation locally. You can reuse the same venv from [installing rbuild](#installing-the-rocm-build-tool-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
```
## AI Tool Use Policy
Follow the [LLVM AI Tool Use Policy](https://llvm.org/docs/AIToolPolicy.html) for contributions that use AI.