nvCOMPDx in Tile#

The nvCOMPDx Tile C++ API compresses and decompresses one-dimensional chunks inside a CUDA Tile kernel. Include nvcompdx_tile.hpp and link mathdx_tile::nvcompdx.

When compiling without CMake, also pass --expt-relaxed-constexpr and -I"<mathdx_tile root>/include/detail" for the bundled nvCOMPDx trait headers.

The equivalent Python interface is documented in Compression cutile-python API.

Note

ANS payloads use the nvCOMP 6.0 / nvCOMPDx 0.2.0 compressed chunk format and require a compatible decoder. They are incompatible with ANS streams from earlier nvCOMP/nvCOMPDx releases. Both LZ4 and ANS support uncompressed chunks up to 16 MiB.

See the nvCOMPDx release notes.

The compressed byte count is known only at runtime, so it cannot determine a tile extent. A tile output has a fixed capacity and a separate meaningful-byte count. Alternatively, pass global memory operands to read and write the chunk and payload directly. See Compression conventions for supported algorithms, element types, and sizing conventions.

Quick start#

This example compresses a 4096-element uint8 tile with ANS and decompresses it in the same kernel. The calls share one scratch buffer.

#include <algorithm>
#include <cstddef>
#include <cstdint>

#include "nvcompdx_tile.hpp"

namespace ct = cuda::tiles;
namespace cn = nvcompdx::tiles;

constexpr std::size_t chunk_bytes = 4096;

__tile_global__ void compression_round_trip_kernel(std::uint8_t* input, std::uint8_t* restored, void* scratch) {
    using chunk_shape = ct::shape<chunk_bytes>;
    auto source = ct::partition_view { ct::tensor_span { input, chunk_shape {} }, chunk_shape {} };
    auto destination = ct::partition_view { ct::tensor_span { restored, chunk_shape {} }, chunk_shape {} };

    auto [compressed, compressed_size] = cn::compress<cn::ans>(source.load(0), cn::scratch { scratch });
    destination.store(
        cn::decompress<std::uint8_t, chunk_bytes, cn::ans>(compressed, compressed_size, cn::scratch { scratch }), 0);
}

void launch_compression_round_trip(std::uint8_t* input, std::uint8_t* restored) {
    // The two calls run one after the other, so they can share one scratch.
    constexpr std::size_t scratch_bytes = std::max(cn::compress_scratch_size<cn::ans, std::uint8_t>(chunk_bytes),
                                                   cn::decompress_scratch_size<cn::ans, std::uint8_t>(chunk_bytes));
    void* scratch = nullptr;
    cudaMalloc(&scratch, scratch_bytes);
    compression_round_trip_kernel<<<1, 1>>>(input, restored, scratch);
    cudaFree(scratch);
}

The ans_gmem example processes four chunks of __half elements. Each block reads one chunk through a pointer, writes an aligned payload slot, and stores its compressed byte count. A second kernel loads that count and restores the original number of elements. The excerpt uses ct for cuda::tiles and cn for nvcompdx::tiles.

using element_t = __half;
constexpr cn::algorithm algorithm = cn::ans;
constexpr size_t chunks = 4;
constexpr size_t elements = 2048;
constexpr size_t chunk_bytes = elements * sizeof(element_t);
constexpr size_t compress_scratch_bytes = cn::compress_scratch_size<algorithm, element_t>(chunk_bytes);
constexpr size_t decompress_scratch_bytes = cn::decompress_scratch_size<algorithm, element_t>(chunk_bytes);
// Exact worst-case size per chunk. Padding keeps each slot aligned.
constexpr size_t capacity = cn::max_comp_chunk_size<algorithm>(chunk_bytes);
constexpr size_t slot_bytes = (capacity + cn::buffer_alignment() - 1) / cn::buffer_alignment() * cn::buffer_alignment();
static_assert(chunk_bytes % cn::buffer_alignment() == 0, "each chunk's input must stay aligned");
static_assert(compress_scratch_bytes % cn::scratch_alignment() == 0 &&
                  decompress_scratch_bytes % cn::scratch_alignment() == 0,
              "each chunk's scratch slices must stay aligned");

__tile_global__ void ans_gmem_compress_kernel(element_t* input,
                                              std::uint8_t* payload,
                                              unsigned long long* sizes,
                                              std::uint8_t* scratch_base) {
    const unsigned int chunk = ct::bid().x;
    const auto size = cn::compress<algorithm, elements>(input + chunk * elements,
                                                        payload + chunk * slot_bytes,
                                                        cn::scratch { scratch_base + chunk * compress_scratch_bytes });
    ct::store(sizes + chunk, size);
}

__tile_global__ void ans_gmem_decompress_kernel(std::uint8_t* payload,
                                                unsigned long long* sizes,
                                                element_t* restored,
                                                std::uint8_t* scratch_base) {
    const unsigned int chunk = ct::bid().x;
    cn::decompress<element_t, elements, algorithm>(payload + chunk * slot_bytes,
                                                   ct::load(sizes + chunk),
                                                   restored + chunk * elements,
                                                   cn::scratch { scratch_base + chunk * decompress_scratch_bytes });
}

Allocate chunks * slot_bytes payload bytes, chunks unsigned long long counts, and chunks slices of each direction’s scratch size. Launch each kernel with <<<chunks, 1>>> in the same stream. See Examples for the complete program and the LZ4 variant.

Scratch memory#

Every call takes per-call global memory scratch, which the caller allocates and passes as cn::scratch{pointer}. compress_scratch_size<A, T>(bytes) and decompress_scratch_size<A, T>(bytes) return the size for each direction. The size depends on the algorithm, element type, and chunk size.

Concurrent calls need disjoint scratch slices of at least that size. Each slice’s base must satisfy scratch_alignment(); pad the stride to that alignment when needed.

Shared-memory scratch is not exposed: the Tile APIs size, allocate and pass whatever shared memory nvCOMPDx needs.

Inputs, outputs and alignment#

Each call’s input and output is independently a tile or a global memory pointer:

  • Tile input: compress<A>(tile, scratch) reads a (N) tile. decompress<T, N, A>(tile, size, scratch) reads a (K) uint8 tile.

  • Pointer input: compress<A, N>(const T*, scratch) and decompress<T, N, A>(const std::uint8_t*, size, scratch) read the chunk in place.

  • Tile output: compress returns [bytes, count]: a comp_tile_size<A>(bytes)-byte tile, of which only count bytes are meaningful. decompress returns the restored (N) tile.

  • Pointer output: pass a std::uint8_t* payload (at least max_comp_chunk_size<A>(bytes) bytes) or a T* destination (N elements) before scratch. The call writes it in place and returns only a rank-0 uint64 byte count: compressed bytes for compress, restored bytes for decompress (N * sizeof(T)).

Pointer inputs and outputs must be aligned to buffer_alignment() (16 bytes). Tiles have no alignment requirement. When several chunks share one buffer, the caller pads every slot so each chunk’s base stays aligned, e.g. a payload stride of max_comp_chunk_size<A>(bytes) rounded up to a multiple of buffer_alignment(). Global scratch is always passed as cn::scratch{pointer}, aligned to scratch_alignment(). cudaMalloc bases satisfy both alignments.

Behavior is undefined if a compression input holds fewer than N elements, a compression output holds fewer than max_comp_chunk_size<A>(bytes) bytes, a decompression input holds fewer than size compressed bytes, or a decompression output holds fewer than N elements. Decompression must use the original algorithm, element type, and element count. Decompressing corrupt input is also undefined behavior.

C++ API reference#

enum class nvcompdx::tiles::algorithm#

Compression algorithm selected for a Tile operation.

Values:

enumerator lz4#

General-purpose byte-level LZ4 compression.

enumerator ans#

Asymmetric numeral systems entropy compression.

using nvcompdx::tiles::size_tile = ct::tile<unsigned long long, ct::shape<>>#

Rank-0 tile carrying a byte count (compressed or uncompressed size).

constexpr algorithm nvcompdx::tiles::lz4 = algorithm::lz4#

LZ4 algorithm value.

constexpr algorithm nvcompdx::tiles::ans = algorithm::ans#

ANS algorithm value.

constexpr size_t nvcompdx::tiles::scratch_alignment_v = scratch_alignment()#
template<algorithm A, typename T>
constexpr size_t nvcompdx::tiles::max_uncomp_chunk_size(
)#

The largest chunk the algorithm accepts for the element type, in bytes.

Returns:

Maximum uncompressed chunk size in bytes.

template<algorithm A>
constexpr size_t nvcompdx::tiles::max_comp_chunk_size(
size_t uncomp_bytes,
)#

Worst-case compressed bytes for uncomp_bytes of input.

Parameters:

uncomp_bytes – Uncompressed chunk size in bytes.

Returns:

Worst-case compressed size in bytes.

template<algorithm A>
constexpr size_t nvcompdx::tiles::comp_tile_size(
size_t uncomp_bytes,
)#

The compressed tile length returned by compress(). This is the power-of-two ceiling of the worst-case size because tile extents are powers of two.

Parameters:

uncomp_bytes – Uncompressed chunk size in bytes.

Returns:

Compressed byte-tile extent.

template<algorithm A, typename T>
constexpr size_t nvcompdx::tiles::compress_scratch_size(
size_t uncomp_bytes,
)#

Per-call global-memory scratch bytes compression requires. Chunks need disjoint scratch, so a batched kernel strides by this.

Parameters:

uncomp_bytes – Uncompressed chunk size in bytes.

Returns:

Required global scratch size in bytes.

template<algorithm A, typename T>
constexpr size_t nvcompdx::tiles::decompress_scratch_size(
size_t uncomp_bytes,
)#

Per-call global-memory scratch bytes decompression requires. Chunks need disjoint scratch, so a batched kernel strides by this.

Parameters:

uncomp_bytes – Uncompressed chunk size in bytes.

Returns:

Required global scratch size in bytes.

constexpr size_t nvcompdx::tiles::scratch_alignment()#

Required alignment of every global-scratch base address, in both directions.

Returns:

Required scratch alignment in bytes.

constexpr size_t nvcompdx::tiles::buffer_alignment()#

Required alignment of global-memory data and payload pointers.

Returns:

Required buffer alignment in bytes.

template<algorithm A, typename T, size_t N>
auto nvcompdx::tiles::compress(
ct::tile<T, ct::shape<N>> chunk,
scratch scratch_space,
)#

Compress one chunk: (compressed bytes, compressed byte count). Only the first compressed_size bytes of the power-of-two-sized tile are meaningful.

Parameters:
  • chunk – Input tile with shape (N).

  • scratch_space – This call’s private global scratch.

Returns:

(compressed, compressed_size), where compressed is a uint8 tile with shape (comp_tile_size<A>(N * sizeof(T))) and compressed_size is a rank-0 uint64 tile.

template<typename T, size_t N, algorithm A, size_t K>
auto nvcompdx::tiles::decompress(
ct::tile<std::uint8_t, ct::shape<K>> compressed,
size_tile comp_size,
scratch scratch_space,
)#

Decompress one chunk of N elements of T. N must equal the element count the payload was compressed from.

Parameters:
  • compressed – Compressed uint8 tile with shape (K).

  • comp_size – Meaningful compressed byte count in a rank-0 uint64 tile.

  • scratch_space – This call’s private global scratch.

Returns:

Restored tile of T elements with shape (N).

template<typename T, size_t N, algorithm A, size_t K>
auto nvcompdx::tiles::decompress(
ct::tile<std::uint8_t, ct::shape<K>> compressed,
unsigned long long comp_size,
scratch scratch_space,
)#

The scalar-size overload, for sizes carried as plain values rather than the tile compress() returns.

Parameters:
  • compressed – Compressed uint8 tile with shape (K).

  • comp_size – Meaningful compressed byte count as a scalar.

  • scratch_space – This call’s private global scratch.

Returns:

Restored tile of T elements with shape (N).

template<algorithm A, size_t N, typename T>
auto nvcompdx::tiles::compress(
const T *data,
scratch scratch_space,
)#

Compress N elements read in place from global memory: (compressed bytes, compressed byte count), as the tile overload.

The <A, T, N> spelling of the pointer-input compress() calls, matching the tile overloads. <A, N> with T deduced also works.

Parameters:
  • data – Pointer to the N-element chunk, aligned to buffer_alignment().

  • scratch_space – This call’s private global scratch.

template<algorithm A, typename T, size_t N>
size_tile nvcompdx::tiles::compress(
ct::tile<T, ct::shape<N>> chunk,
std::uint8_t *compressed,
scratch scratch_space,
)#

Compress one chunk into global memory. Returns the compressed byte count.

Parameters:
  • chunk – Input tile with shape (N).

  • compressed – Destination of at least max_comp_chunk_size<A>(N * sizeof(T)) bytes, aligned to buffer_alignment(). Pad per-chunk slots of a shared buffer to keep every base aligned.

  • scratch_space – This call’s private global scratch.

template<algorithm A, size_t N, typename T>
size_tile nvcompdx::tiles::compress(
const T *data,
std::uint8_t *compressed,
scratch scratch_space,
)#

Compress N elements from global memory into global memory. Returns the compressed byte count.

template<typename T, size_t N, algorithm A>
auto nvcompdx::tiles::decompress(
const std::uint8_t *compressed,
size_tile comp_size,
scratch scratch_space,
)#

Decompress one chunk read in place from global memory into a tile.

Parameters:
  • compressed – Pointer to the payload, aligned to buffer_alignment().

  • comp_size – Meaningful compressed byte count.

  • scratch_space – This call’s private global scratch.

Returns:

Restored tile of T elements with shape (N).

template<typename T, size_t N, algorithm A, size_t K>
size_tile nvcompdx::tiles::decompress(
ct::tile<std::uint8_t, ct::shape<K>> compressed,
size_tile comp_size,
T *data,
scratch scratch_space,
)#

Decompress one chunk into global memory. Returns the restored byte count.

Parameters:
  • compressed – Compressed uint8 tile with shape (K).

  • comp_size – Meaningful compressed byte count.

  • data – Destination of N elements, aligned to buffer_alignment(). N must equal the element count the payload was compressed from.

  • scratch_space – This call’s private global scratch.

template<typename T, size_t N, algorithm A>
size_tile nvcompdx::tiles::decompress(
const std::uint8_t *compressed,
size_tile comp_size,
T *data,
scratch scratch_space,
)#

Decompress one chunk from global memory into global memory. Returns the restored byte count.

template<typename T, size_t N, algorithm A>
auto nvcompdx::tiles::decompress(
const std::uint8_t *compressed,
unsigned long long comp_size,
scratch scratch_space,
)#

The scalar-size overloads of the global-memory decompress() calls above.

template<typename T, size_t N, algorithm A, size_t K>
size_tile nvcompdx::tiles::decompress(
ct::tile<std::uint8_t, ct::shape<K>> compressed,
unsigned long long comp_size,
T *data,
scratch scratch_space,
)#
template<typename T, size_t N, algorithm A>
size_tile nvcompdx::tiles::decompress(
const std::uint8_t *compressed,
unsigned long long comp_size,
T *data,
scratch scratch_space,
)#
struct scratch#
#include <nvcompdx_tile.hpp>

Private global scratch for one call: compress_scratch_size<A, T>(bytes) or decompress_scratch_size<A, T>(bytes) bytes aligned to scratch_alignment(). A distinct type, so a scratch pointer can never bind where a data pointer belongs.