Skip to main content
`Ctrl`+`K`

# Using hipBLAS clients

There are two client executables that can be used with hipBLAS. They are:

- hipblas-bench

- hipblas-test

These two clients can be built by following the instructions in Installing and building for Linux. After building, the hipBLAS clients can be found in the `hipBLAS/build/release/clients/staging` directory. See the next two sections for a brief explanation and usage notes for each hipBLAS client.

## hipblas-bench

hipblas-bench is used to measure performance and verify the correctness of hipBLAS functions.

It has a command line interface. For usage information, run this command:

    ./hipblas-bench --help

This example measures the performance of SGEMM:

    ./hipblas-bench -f gemm -r f32_r --transposeA N --transposeB N -m 4096 -n 4096 -k 4096 --alpha 1 --lda 4096 --ldb 4096 --beta 0 --ldc 4096

On a system using an AMD Vega 20 GPU, the previous command displays a performance of 11941.5 Gflops, as shown in the output below:

    transA,transB,M,N,K,alpha,lda,ldb,beta,ldc,hipblas-Gflops,us
    N,N,4096,4096,4096,1,4096,4096,0,4096,11941.5,11509.4

A helpful way of finding the parameters that can be used with `./hipblas-bench -f gemm` is to turn on logging by setting the environment variable `ROCBLAS_LAYER=2`. For example, if you run this command:

    ROCBLAS_LAYER=2 ./hipblas-bench -f gemm -i 1 -j 0

It logs the following information:

    ./rocblas-bench -f gemm -r f32_r --transposeA N --transposeB N -m 128 -n 128 -k 128 --alpha 1 --lda 128 --ldb 128 --beta 0 --ldc 128

You can copy and change the above command. For example, to change the datatype to IEEE 64-bit and the size to 2048, follow this example:

    ./hipblas-bench -f gemm -r f64_r --transposeA N --transposeB N -m 2048 -n 2048 -k 2048 --alpha 1 --lda 2048 --ldb 2048 --beta 0 --ldc 2048

Logging affects performance, so only use it to log the command of interest, then run the command without logging enabled to measure performance.

Note

hipblas-bench also provides the flag `-v 1` for correctness checks.

If multiple arguments or functions need to be benchmarked, hipblas-bench supports data-driven benchmarks using a YAML-format specification file.

    ./hipblas-bench --yaml <file>.yaml

For example, `hipblas_smoke.yaml` is a YAML file used to run a smoke test. However, other examples can be found in the rocBLAS GitHub repository.

## hipblas-test

hipblas-test is used to perform hipBLAS unit tests. It uses the GoogleTest framework.

To run the hipBLAS tests, use this command:

    ./hipblas-test

To run a subset of tests, provide an optional filter. For example, to run only the `axpy` function tests from the command line, use:

    ./hibblas-test --gtest_filter=*axpy*

The pattern for `--gtest_filter` is:

    --gtest_filter=POSTIVE_PATTERNS[-NEGATIVE_PATTERNS]

If specific function arguments or multiple functions need to be tested, hipblas-test provides support for data-driven testing using a YAML-format test specification file.

    ./hipblas-test --yaml <file>.yaml

As an example, `hipblas_smoke.yaml` is a YAML file that is used to run a smoke test. Other examples can be found in the rocBLAS GitHub repository. YAML-based tests list function parameter values in the test name, which can be also used for test filtering using the `gtest_filter` argument. To run the provided smoke test, use this command:

    ./hipblas-test --yaml hipblas_smoke.yaml