Skip to content

Commit

Permalink
Merge pull request #3495 from ROCm/docsfor62
Browse files Browse the repository at this point in the history
Update latest documentation for new design
  • Loading branch information
mamaydeo authored Oct 2, 2024
2 parents 379310e + 45ddca5 commit 5e45a73
Show file tree
Hide file tree
Showing 11 changed files with 246 additions and 56 deletions.
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# AMD MIGraphX

AMD MIGraphX is AMD's graph inference engine, which accelerates machine learning model inference.
To use MIGraphX, you can install the binaries or build from source code. Refer to the following sections
for Ubuntu installation instructions (we'll provide instructions for other Linux distributions in the future).

> [!NOTE]
> You must [install ROCm](https://rocm.docs.amd.com/en/latest/deploy/linux/quick_start.html) before
>[!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
Expand All @@ -16,7 +17,7 @@ Install binaries using:
sudo apt update && sudo apt install -y migraphx
```

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

## Building from source
Expand Down
36 changes: 14 additions & 22 deletions docs/dev/contributing-to-migraphx.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,22 @@
.. _contributing-to-migraphx:

==========================
Contributing to MIGraphX
Developing for MIGraphX
==========================

This document explains the internal implementation of some commonly used MIGraphX APIs. You can utilize the information provided in this document and other documents under "Contributing to MIGraphX" section to contribute to the MIGraphX API implementation.
Here is how some basic operations in the MIGraphX framework are performed.
This document is intended for anyone who wants to contribute to MIGraphX. This document covers some basic operations that can be used to develop for MIGraphX. The complete source code for the example shown here can be found at `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_ on the MIGraphX repository.

Performing basic operations
More examples can be found on `the MIGraphX GitHub repository <https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx>`_.


Adding two literals
----------------------------

A program is a collection of modules, which are collections of instructions to be executed when calling :cpp:any:`eval <migraphx::internal::program::eval>`.
Each instruction has an associated :cpp:any:`operation <migraphx::internal::operation>` which represents the computation to be performed by the instruction.

The following code snippets demonstrate some basic operations using MIGraphX.

Adding literals
******************
We start with a snippet of the simple ``add_two_literals()`` function::

Here is a ``add_two_literals()`` function::

// create the program and get a pointer to the main module
migraphx::program p;
Expand Down Expand Up @@ -55,7 +53,7 @@ To compile the program for the GPU, move the file to ``test/gpu/`` directory and
#include <migraphx/gpu/target.hpp>

Adding Parameters
*******************
----------------------------

While the ``add_two_literals()`` function above demonstrates add operation on constant values ``1`` and ``2``,
the following program demonstrates how to pass a parameter (``x``) to a module using ``add_parameter()`` function .
Expand Down Expand Up @@ -86,7 +84,7 @@ To map the parameter ``x`` to an :cpp:any:`argument <migraphx::internal::argumen
EXPECT(result.at<int>() == 6);

Handling Tensor Data
**********************
----------------------------

The above two examples demonstrate scalar operations. To describe multi-dimensional tensors, use the :cpp:any:`shape <migraphx::internal::shape>` class to compute a simple convolution as shown below::

Expand Down Expand Up @@ -132,30 +130,24 @@ By default, the buffers are allocated on the CPU when compiling for CPU and on t
To locate the buffers on the CPU even when compiling for GPU, set the option ``offload_copy=true``.

Importing From ONNX
**********************
----------------------------

To make it convenient to use neural networks directly from other frameworks, MIGraphX ONNX parser allows you to build a :cpp:any:`program <migraphx::internal::program>` directly from an ONNX file.
For usage, refer to the ``parse_onnx()`` function below::

program p = migraphx::parse_onnx("model.onnx");
p.compile(migraphx::gpu::target{});

Sample programs
-----------------

You can find all the MIGraphX examples in the `Examples <https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx>`_ directory.

Build MIGraphX source code
****************************
Build this example
----------------------------

To build a sample program `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_, use:
Build the `ref_dev_examples.cpp <https://github.com/ROCm/AMDMIGraphX/blob/develop/test/ref_dev_examples.cpp>`_ example with this command:

make -j$(nproc) test_ref_dev_examples

This creates an executable file ``test_ref_dev_examples`` in the ``bin/`` of the build directory.
This creates the ``test_ref_dev_examples`` under ``bin/`` in the build directory.

To verify the build, use:

make -j$(nproc) check

For detailed instructions on building MIGraphX from source, refer to the `README <https://github.com/ROCm/AMDMIGraphX#readme>`_ file.
1 change: 1 addition & 0 deletions docs/dev/dev_intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ Developer Introduction
======================

MIGraphX provides an optimized execution engine for deep learning neural networks.

We will cover some simple operations in the MIGraphX framework here.
For a quick start guide to using MIGraphX, look in the examples directory: ``https://github.com/ROCmSoftwarePlatform/AMDMIGraphX/tree/develop/examples/migraphx``.

Expand Down
33 changes: 20 additions & 13 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,41 @@
.. _index:

===========================
AMD MIGraphX documentation
MIGraphX documentation
===========================

Welcome to the MIGraphX docs home page! To learn more, see :ref:`what-is-migraphx`.
MIGraphX is a graph inference engine and graph compiler. MIGraphX accelerates machine-learning models by leveraging several graph-level transformations and optimizations. These optimizations include:

Our documentation is structured as follows:
* Operator fusion
* Arithmetic simplifications
* Dead-code elimination
* Common subexpression elimination (CSE)
* Constant propagation

After optimization, MIGraphX generates code for AMD GPUs by calling various ROCm libraries to create the fastest combinations of HIP kernels.

The MIGraphX public repository is located at `https://github.com/ROCm/AMDMIGraphX/ <https://github.com/ROCm/AMDMIGraphX/>`_

.. grid:: 2
:gutter: 3

.. grid-item-card:: Reference
.. grid-item-card:: Install

* :doc:`Installing MIGraphX <./install/installing_with_package>`

.. grid-item-card:: Using the MIGraphX API

* :ref:`cpp-api-reference`
* :ref:`python-api-reference`
* :ref:`migraphx-driver`

.. grid-item-card:: Contribution
.. grid-item-card:: Contributing to the MIGraphX code base

* :ref:`contributing-to-migraphx`
* :doc:`Building MIGraphX <./install/building_migraphx>`
* :doc:`Developing for MIGraphX <./dev/contributing-to-migraphx>`

To contribute to the documentation refer to
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
`Contribute to ROCm documentation <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.

Licensing information can be found on the
`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

Index and search
==================

* :ref:`genindex`
* :ref:`search`
62 changes: 62 additions & 0 deletions docs/install/build_and_install_with_cmake.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
.. meta::
:description: Build and install MIGraphX using CMake
:keywords: build, install, MIGraphX, AMD, ROCm, CMake

********************************************************************
Build and install MIGraphX using CMake
********************************************************************

ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.

.. note::

This method for building MIGraphX requires using ``sudo``.


1. Install the dependencies:

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

If ``rbuild`` is not installed on your system, install it with:

.. code:: shell
pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
2. Create a build directory and change directory to it:

.. code:: shell
mkdir build
cd build
3. Configure CMake:

.. code:: shell
CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
4. Build MIGraphX source code:

.. code:: shell
make -j$(nproc)
You can verify this using:

.. code:: shell
make -j$(nproc) check
5. Install MIGraphX libraries:

.. code:: shell
make install
52 changes: 52 additions & 0 deletions docs/install/build_and_install_with_docker.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
.. meta::
:description: Installing MIGraphX using Docker
:keywords: install, MIGraphX, AMD, ROCm, Docker

********************************************************************
Installing MIGraphX using Docker
********************************************************************

ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.

.. note::

Docker commands are run using ``sudo``.

1. Build the Docker image. This command will install all the prerequisites required to install MIGraphX. Ensure that you are running this in the same directory as ``Dockerfile``.

.. code:: shell
sudo docker build -t migraphx .
2. Create and run the container. Once this command is run, you will be in the ``/code/AMDMIGraphX`` directory of a pseudo-tty.

.. code:: shell
sudo docker run --device='/dev/kfd' --device='/dev/dri' -v=`pwd`:/code/AMDMIGraphX -w /code/AMDMIGraphX --group-add video -it migraphx
3. In the ``/code/AMDMIGraphX``, create a ``build`` directory, then change directory to ``/code/AMDMIGraphX/build``:

.. code:: shell
mkdir build
cd build
4. Configure CMake:

.. code:: shell
CXX=/opt/rocm/llvm/bin/clang++ cmake .. -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
4. Build the MIGraphX libraries:

.. code:: shell
make -j$(nproc)
5. Install the libraries:

.. code:: shell
make install
32 changes: 32 additions & 0 deletions docs/install/build_and_install_with_rbuild.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
.. meta::
:description: Build and install MIGraphX using rbuild
:keywords: build, install, MIGraphX, AMD, ROCm, rbuild

********************************************************************
Build and install MIGraphX using rbuild
********************************************************************

ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.

.. note::

This method for building MIGraphX requires using ``sudo``.

1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`:

.. code:: shell
sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
2. Install `rbuild <https://github.com/RadeonOpenCompute/rbuild>`_:

.. code:: shell
pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
3. Build MIGraphX source code:

.. code:: shell
sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
32 changes: 32 additions & 0 deletions docs/install/building_migraphx.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
.. meta::
:description: Build and install MIGraphX
:keywords: build, install, MIGraphX, AMD, ROCm, rbuild, development, contributing

********************************************************************
Building MIGraphX
********************************************************************

ROCm must be installed prior to building MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on ROCm installation on Linux.

.. note::

This method for building MIGraphX requires using ``sudo``.

1. Install `rocm-cmake`, `pip3`, `rocblas`, and `miopen-hip`:

.. code:: shell
sudo apt install -y rocm-cmake python3-pip rocblas miopen-hip
2. Install `rbuild <https://github.com/RadeonOpenCompute/rbuild>`_:

.. code:: shell
pip3 install --prefix /usr/local https://github.com/RadeonOpenCompute/rbuild/archive/master.tar.gz
3. Build MIGraphX source code:

.. code:: shell
sudo rbuild build -d depend -B build -DGPU_TARGETS=$(/opt/rocm/bin/rocminfo | grep -o -m1 'gfx.*')
21 changes: 21 additions & 0 deletions docs/install/installing_with_package.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
.. meta::
:description: Installing MIGraphX using the package installer
:keywords: install, MIGraphX, AMD, ROCm, package installer

********************************************************************
Installing MIGraphX
********************************************************************

ROCm must be installed before installing MIGraphX. See `ROCm installation for Linux <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/>`_ for information on how to install ROCm on Linux.

Installing MIGraphX using the package installer is sufficient for users who want to use the MIGraphX API.

If you want to develop for MIGraphX and contribute to the source code, see `Building MIGraphX <https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/install/docs/install/building_migraphx.html>`_ and `Developing for MIGraphX <https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/dev/contributing-to-migraphx.html>`_

The package installer will install all the prerequisites needed for MIGraphX.

Use the following command to install MIGraphX:

.. code:: shell
sudo apt update && sudo apt install -y migraphx
Loading

0 comments on commit 5e45a73

Please sign in to comment.