Examples#

MathDx Tile provides two example suites: CUDA Tile C++ and cuTile Python. Examples with the same file name in both suites allow comparing the two languages. Some examples exist only in Python. Each example launches one or more Tile kernels and checks its numerical result.

The C++ examples are installed under examples/ in the MathDx Tile runtime archives.

Getting Started#

  1. The first kernel, presenting one transform and one factorization without surrounding machinery.

  2. fft_convolution_1d, the smallest complete fused kernel: a transform, a pointwise multiplication, and an inverse transform, without accessing global memory in between.

  3. cholesky_factor and cholesky_solve, each performing a single linear algebra call and illustrating the info convention.

  4. factor_reuse, which factors in one kernel and solves in another.

  5. fft_convolution_3d_split, which shows how a multi-dimensional transform is staged through global memory when one kernel is not sufficient.

  6. reg_least_squares and blocked_potrf, covering batched throughput, tile padding, and the blocking of a problem larger than a single call.

  7. filtered_backprojection_3d, a mixed application containing a Tile kernel and a SIMT kernel in the same translation unit, together with a fused Tile-only alternative.

  8. fft_autotuning, which sweeps the batch extent, the CTA size, and the occupancy hint, as described in Autotuning.

FFT Examples#

The C++ examples are located in cpp/cufftdx and the Python examples in python/fft. The C++ variants are validated against cuFFT, while the Python variants use direct or CuPy references.

Example

What it does

Routines exercised

fft_convolution_1d

Real 1D linear convolution in one fused kernel

rfft, irfft

fft_convolution_3d

8x8x8 complex convolution, all three axes in one kernel

fft, ifft

fft_convolution_3d_real

3D real convolution with rfft and irfft

fft, ifft, rfft, irfft

fft_convolution_3d_split

128³ convolution split into three kernels, staged through global memory

fft, ifft

fft_convolution_5d

8⁵ convolution, staged across five axes

fft, ifft

mixed_precision_fft_1d

Float input and output around a double-precision transform

fft

filtered_backprojection_3d

3D low-pass filtered backprojection, as separate Tile and SIMT kernels and as one fused Tile kernel

rfft, irfft

fft_autotuning

Sweeps the batch extent, the CTA size, and the occupancy hint for a batched 1D FFT, validating each candidate before timing it (Python only)

fft, suggested_tile_config

Linear Algebra Examples#

The C++ examples are located in cpp/cusolverdx and the Python examples in python/linalg. The simple group contains one example per routine, each solving a single system.

The C++ API divides these routines across two headers: triangular_solve, tril, and triu are declared in cublasdx_tile.hpp under cublasdx::tiles, and the remainder in cusolverdx_tile.hpp under cusolverdx::tiles. Python exposes all of them from nvmath.tile.linalg.

Example

What it does

Routines exercised

cholesky_factor

Factors a positive-definite matrix

cholesky_factor

cholesky_solve

Factors and solves a positive-definite system

cholesky_solve

lu_solve

Solves a general system with partial-pivot LU

lu_solve

factor_reuse

Factors once, then reuses the Cholesky and LU factors in separate kernels

cholesky_factor, cholesky_solve_using_factor, lu_factor, lu_solve_using_factor

modified_lu_factor

Computes a modified LU factorization

modified_lu_factor

qr

Factors a rectangular matrix, forms its thin Q, and applies the implicit Q to another matrix

qr_factor, qr_generate_q, qr_multiply_by_q

lq

Factors a wide matrix, generates Q explicitly, and applies the implicit Q to another matrix

lq_factor, lq_generate_q, lq_multiply_by_q

least_squares_solve

Solves one overdetermined problem twice, against a tall A and against the transpose of the equivalent wide matrix

least_squares_solve

tridiagonal_solve

Solves a diagonally dominant tridiagonal system

tridiagonal_solve

eig_hermitian

Computes eigenvalues and eigenvectors of a symmetric matrix

eig_hermitian

eig_hermitian_tridiagonal

Computes eigenvalues of a symmetric tridiagonal matrix

eig_hermitian_tridiagonal

generalized_eigh

Computes generalized symmetric-definite eigenvalues in one call, and again by reducing to a standard eigenproblem by hand

cholesky_factor, generalized_eig_hermitian, generalized_to_standard_eig_hermitian, eig_hermitian

svd

Computes the thin SVD of a rectangular matrix, with and without singular vectors

svd

svd_bidiagonal

Computes the singular values of a bidiagonal matrix

svd_bidiagonal

The advanced group contains larger examples that combine several routines. The two mirrored examples are batched with one block per problem and report throughput. The C++ versions additionally verify their results against the equivalent batched cuBLAS and cuSolver host APIs.

Example

What it does

Routines exercised

reg_least_squares

Solves 10000 regularized 100x8 least-squares problems two ways: a fused kernel that builds the normal equations with tile matmuls and factors them in registers, and a Householder QR on the augmented system

cholesky_solve, least_squares_solve

blocked_potrf

Factors 400 512x512 matrices, far too large for one solver call, by walking 32x32 tiles in a left-looking order

cholesky_factor, triangular_solve

sglang_ipm (Python only)

Solves one 24x42 SGLang MoE load-balancing problem with an affine-scaling interior-point method and a 16+8 blocked Cholesky

cholesky_factor, triangular_solve

Compression#

The C++ examples are in cpp/nvcompdx and the Python examples in python/compress. Each compresses four chunks, with one chunk per block, and verifies an exact round trip. The tile variants keep the data and payload in tiles within one kernel. The direct-memory variants use separate compression and decompression kernels, aligned payload slots, and per-chunk scratch slices; only the byte counts are tiles.

Example

Algorithm

Uncompressed data

Data and payload

lz4_tile

LZ4

uint8

Tiles

lz4_gmem

LZ4

uint8

Global memory

ans_tile

ANS

float16

Tiles

ans_gmem

ANS

float16

Global memory

For the minimal tile round trip and direct-memory kernel excerpts, see nvCOMPDx in Tile and Compression cutile-python API.

Building and Running#

C++ examples#

Configure the C++ example sources against an installed mathdx_tile package as follows:

cmake -S examples/cpp -B build/tile-examples \
  -DCMAKE_CUDA_COMPILER="$CUDACXX" \
  -DCUDAToolkit_ROOT=/path/to/cuda \
  -DCMAKE_PREFIX_PATH="$MATHDX_TILE"
cmake --build build/tile-examples
ctest --test-dir build/tile-examples --output-on-failure

A full CUDA toolkit is required in addition to the Tile toolchain. The advanced linear algebra examples link CUDA::cublas and CUDA::cusolver for their host references, and the FFT examples link cuFFT. A standard CUDA compiler cannot replace the Tile compiler, as it does not accept the Tile flags supplied by the mathdx_tile:: targets.

Python examples#

The Python examples require the packages listed in Requirements, together with cuda-core, NumPy, and CuPy. Any script may be run directly:

python examples/python/linalg/simple/cholesky_factor.py

Host arrays for the linear algebra and compression examples are NumPy arrays, with device buffers and streams provided by cuda.core. The FFT examples use CuPy device arrays.