Docs: getting started and miscellaneous docs refactoring

docs/how-to/model-performance-tuning.rst

@@ -0,0 +1,129 @@
+.. meta::
+  :description: Tune MIGraphX model performance with environment variables
+  :keywords: MIGraphX, performance, tuning, environment variables, ROCm
+
+********************************************************************
+Tune model performance
+********************************************************************
+
+MIGraphX exposes environment variables that change compilation behavior and
+kernel selection at runtime. Set these variables before you compile or run a
+model to experiment with performance options without changing application
+code.
+
+For the complete list of environment variables, including developer-only
+tracing and debugging options, see
+:doc:`MIGraphX environment variables <../reference/MIGraphX-dev-env-vars>`.
+
+Set environment variables
+====================================================================
+
+Export a variable in your shell before running ``migraphx-driver`` or your
+application:
+
+.. code-block:: shell
+
+   export MIGRAPHX_SET_GEMM_PROVIDER=hipblaslt
+   /opt/rocm/bin/migraphx-driver perf model.onnx --onnx --gpu
+
+Replace ``model.onnx`` with your model path.
+
+Variables that take comma-separated lists must not include spaces between
+entries. Quote the value when your shell requires it.
+
+Common tuning variables
+====================================================================
+
+The following variables are the most commonly used for model performance
+tuning. Each entry describes accepted values and default behavior documented
+in the MIGraphX source tree.
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Environment variable
+     - Values
+   * - ``MIGRAPHX_GPU_OPTIONS``
+     - JSON object of backend options (for example, ``{convolution_layout:channels_last}``). Quotes around keys and values are optional. Unrecognized options are ignored.
+   * - ``MIGRAPHX_SET_GEMM_PROVIDER``
+     - ``hipblaslt`` or ``rocblas``. Default: ``rocblas`` on gfx90a; ``hipblaslt`` on all other architectures.
+   * - ``MIGRAPHX_ENABLE_GEMM_TUNING``
+     - ``1`` enables exhaustive GEMM tuning even when ``--exhaustive-tune`` is not set. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_ENABLE_HIP_GEMM_TUNING``
+     - ``1`` enables exhaustive hipBLASLt tuning. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_MLIR_TUNE_EXHAUSTIVE``
+     - ``1`` enables exhaustive MLIR tuning. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_MLIR_USE_SPECIFIC_OPS``
+     - Comma-separated list of operations (for example, ``attention``, ``convolution``, ``dot``, ``fused_dot``, ``fused_convolution``, ``fused``). Prefix an entry with ``~`` to negate it.
+   * - ``MIGRAPHX_DISABLE_MLIR``
+     - ``1`` disables rocMLIR. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_ENABLE_CK``
+     - ``1`` enables Composable Kernel. Use with ``MIGRAPHX_DISABLE_MLIR=1``.
+   * - ``MIGRAPHX_USE_FAST_SOFTMAX``
+     - ``1`` enables fast softmax optimization. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_ENABLE_LAYERNORM_FUSION``
+     - ``1`` enables layernorm fusion. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_FLASH_DECODING_ENABLED``
+     - ``1`` enables flash decoding for attention fusion. Default: ``0``.
+   * - ``MIGRAPHX_SKIP_BENCHMARKING``
+     - ``1`` skips kernel benchmarking and compiles with the first available solution. ``0`` returns to default behavior.
+
+Tuning examples
+====================================================================
+
+Select a GEMM provider
+--------------------------------------------------------------------
+
+Set the general matrix multiply (GEMM) provider before compilation:
+
+.. code-block:: shell
+
+   export MIGRAPHX_SET_GEMM_PROVIDER=hipblaslt
+   /opt/rocm/bin/migraphx-driver perf model.onnx --onnx --gpu
+
+Replace ``model.onnx`` with your model path.
+
+Enable exhaustive GEMM tuning
+--------------------------------------------------------------------
+
+Search for the fastest GEMM kernel configuration:
+
+.. code-block:: shell
+
+   export MIGRAPHX_ENABLE_GEMM_TUNING=1
+   /opt/rocm/bin/migraphx-driver perf model.onnx --onnx --gpu --exhaustive-tune
+
+You can also pass ``--exhaustive-tune`` on the command line. The environment
+variable enables exhaustive GEMM tuning even when that flag is omitted.
+
+Specify MLIR operations
+--------------------------------------------------------------------
+
+Force specific operations to lower through MLIR. The list is comma-separated:
+
+.. code-block:: shell
+
+   export MIGRAPHX_MLIR_USE_SPECIFIC_OPS=attention,dot
+   /opt/rocm/bin/migraphx-driver compile model.onnx --onnx --gpu --text
+
+Replace ``model.onnx`` with your model path.
+
+Measure the effect
+====================================================================
+
+Compare performance before and after changing a variable:
+
+.. code-block:: shell
+
+   /opt/rocm/bin/migraphx-driver perf model.onnx --onnx --gpu -n 50
+
+Replace ``model.onnx`` with your model path and adjust ``-n`` for the number
+of timing iterations.
+
+See also
+====================================================================
+
+* :doc:`MIGraphX driver <../migraphx-driver>` for ``perf`` and ``compile`` commands.
+* :doc:`MIGraphX environment variables <../reference/MIGraphX-dev-env-vars>` for
+  the full variable reference, including pass controls and compilation tracing.

docs/how-to/model-validation.rst

@@ -0,0 +1,159 @@
+.. meta::
+  :description: Validate MIGraphX model outputs
+  :keywords: MIGraphX, validation, verify, environment variables, ROCm
+
+********************************************************************
+Validate model outputs
+********************************************************************
+
+Use MIGraphX validation tools to compare GPU or CPU target output against the
+reference implementation. Validation helps confirm that compilation and
+quantization changes produce numerically consistent results.
+
+Validate with migraphx-driver
+====================================================================
+
+The ``verify`` command compiles your model for the reference and target
+backends, runs both, and checks that outputs match within configured
+tolerances. See :doc:`MIGraphX driver <../migraphx-driver>` for full command
+documentation.
+
+Basic verification
+--------------------------------------------------------------------
+
+Verify an ONNX model against the default target:
+
+.. code-block:: shell
+
+   /opt/rocm/bin/migraphx-driver verify model.onnx --onnx
+
+Replace ``model.onnx`` with your model path.
+
+Verify on GPU with tolerance settings
+--------------------------------------------------------------------
+
+Set absolute tolerance (``atol``), relative tolerance (``rtol``), and
+root-mean-square tolerance (``rms-tol``) when comparing outputs:
+
+.. code-block:: shell
+
+   /opt/rocm/bin/migraphx-driver verify model.onnx --onnx --gpu \
+       --atol 1e-5 --rtol 1e-5 --rms-tol 0.001
+
+Replace ``model.onnx`` with your model path. Default tolerance values are
+``0.001`` for ``atol``, ``rtol``, and ``rms-tol``.
+
+Verify after quantization
+--------------------------------------------------------------------
+
+Check that fp16 quantization preserves accuracy within your tolerances:
+
+.. code-block:: shell
+
+   /opt/rocm/bin/migraphx-driver verify model.onnx --onnx --gpu --fp16 \
+       --atol 1e-3 --rtol 1e-3
+
+Replace ``model.onnx`` with your model path.
+
+Additional verify options
+--------------------------------------------------------------------
+
+The driver supports these validation-related options:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - ``--per-instruction`` or ``-i``
+     - Verifies each instruction individually.
+   * - ``--reduce`` or ``-r``
+     - Reduces the program and verifies the reduced graph.
+   * - ``--atol``
+     - Sets tolerance for elementwise absolute difference (default: ``0.001``).
+   * - ``--rtol``
+     - Sets tolerance for elementwise relative difference (default: ``0.001``).
+   * - ``--rms-tol``
+     - Sets tolerance for root-mean-square error (default: ``0.001``).
+
+Validation environment variables
+====================================================================
+
+Set these environment variables before running ``migraphx-driver verify`` or
+your application to adjust validation behavior.
+
+Output comparison
+--------------------------------------------------------------------
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Environment variable
+     - Values
+   * - ``MIGRAPHX_VERIFY_ENABLE_ALLCLOSE``
+     - ``1`` verifies range tolerance using ``allclose``. ``0`` returns to default behavior.
+   * - ``MIGRAPHX_VERIFY_DUMP_DIFF``
+     - ``1`` writes test output and reference output when they differ. ``0`` returns to default behavior.
+
+Example:
+
+.. code-block:: shell
+
+   export MIGRAPHX_VERIFY_DUMP_DIFF=1
+   /opt/rocm/bin/migraphx-driver verify model.onnx --onnx --gpu
+
+Replace ``model.onnx`` with your model path.
+
+Testing and debugging
+--------------------------------------------------------------------
+
+These variables apply when running MIGraphX verify tests or debugging
+validation failures during development:
+
+.. list-table::
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Environment variable
+     - Values
+   * - ``MIGRAPHX_TRACE_TEST``
+     - ``1`` prints reference and target programs even when verify tests pass.
+   * - ``MIGRAPHX_TRACE_TEST_COMPILE``
+     - ``cpu`` or ``gpu`` turns on compile tracing for verify tests on the given target. Cannot be used with ``MIGRAPHX_TRACE_COMPILE``.
+   * - ``MIGRAPHX_DUMP_TEST``
+     - ``1`` writes the model under verification to an MXR file.
+
+Example:
+
+.. code-block:: shell
+
+   export MIGRAPHX_VERIFY_DUMP_DIFF=1
+   export MIGRAPHX_TRACE_TEST=1
+   /opt/rocm/bin/migraphx-driver verify model.onnx --onnx --gpu
+
+Replace ``model.onnx`` with your model path.
+
+Graph validation during development
+--------------------------------------------------------------------
+
+When developing passes or matchers, enable module validation after pattern
+matches:
+
+.. code-block:: shell
+
+   export MIGRAPHX_VALIDATE_MATCHES=1
+
+See :doc:`MIGraphX environment variables <../reference/MIGraphX-dev-env-vars>`
+for the complete list of validation, testing, and tracing variables.
+
+See also
+====================================================================
+
+* :doc:`MIGraphX driver <../migraphx-driver>` for the ``verify`` command and
+  tolerance options.
+* :doc:`Precision support <../reference/MIGraphX-data-type-support>` for
+  supported data types when validating quantized models.
+* :doc:`Tune model performance <./model-performance-tuning>` when adjusting
+  compilation options that can affect numerical output.

docs/index.rst

@@ -13,17 +13,28 @@ It compiles trained models from end-to-end to optimize for inference performance
 
 The MIGraphX public repository is located at `https://github.com/ROCm/AMDMIGraphX/ <https://github.com/ROCm/AMDMIGraphX/>`__.
 
-You can integrate MIGraphX with PyTorch worflows by using the Torch-MIGraphX library.
+You can integrate MIGraphX with PyTorch workflows by using the Torch-MIGraphX library.
 The public repository is located at `https://github.com/ROCm/torch_migraphx/ <https://github.com/ROCm/torch_migraphx/>`__.
 
 .. grid:: 2
   :gutter: 3
 
+  .. grid-item-card:: Getting started
+
+    * :doc:`Get started with MIGraphX <./tutorials/getting-started>`
+    * :doc:`Parse, load, and save a model <./tutorials/parse-load-save-tutorial>`
+
   .. grid-item-card:: Install
 
     * :doc:`MIGraphX on ROCm installation <./install/install-migraphx>`
+    * :doc:`Install MIGraphX with Docker <./install/install-docker>`
     * :doc:`Torch-MIGraphX installation <./install/install-torch-migraphx>`
 
+  .. grid-item-card:: How-to
+
+    * :doc:`Tune model performance <./how-to/model-performance-tuning>`
+    * :doc:`Validate model outputs <./how-to/model-validation>`
+
   .. grid-item-card:: Conceptual
 
     * :doc:`Deep learning compilation with MIGraphX <./conceptual/deep-learning-compilation>`