CuTe-DSL API Overview

• CuTe-DSL API is a domain-specific library that provides programming-language-level access to hierarchical tensor layout representation and algebra for high-performance computing.
• It defines core abstractions—Layout, Axis, Tensor, and Partition—that enable composability and compile-time verification in rigorous tensor manipulations.
• Algebraic functions like compose, coalesce, and logical_divide facilitate seamless mapping of tensor transformations onto GPU architectures for deep learning applications.

CuTe-DSL API is a domain-specific library providing programming-language-level access to hierarchical tensor layout representation and algebra, as defined in the CuTe framework. Designed explicitly for high-performance computing and deep learning, CuTe-DSL exposes a concise set of Python classes and functions for rigorous layout manipulation, compile-time verification, and static analysis of complex tensor data layouts and thread arrangements. Its abstractions directly correspond to the mathematical constructs formalized in CuTe, mapping seamlessly onto the algebraic operations required to capture the data and thread mapping constraints of modern hardware such as GPU tensor cores (Cecka, 2 Mar 2026).

1. Core Abstractions

CuTe-DSL structures its API around four primary abstractions that mirror CuTe’s mathematical vocabulary for layouts and tensor mappings:

• Layout: Encapsulates a tensor layout function, parameterized by an HTuple shape $S$ and an HTuple stride $D$, exposing attributes like .shape, .stride, rank, depth, size, and the call operation $$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$.
• Axis (Tiler): Represents a tiler or axis partitioning construct, used as either an integer, tuple, or general Layout object, and corresponds to partitioning/indexing logic in layout algebra.
• Tensor: Binds a data accessor (pointer, iterator) and a Layout, exposing a conventional tensor interface. Element access computes the memory address via the associated layout function.
• Partition (Slice): Presents a view of a subtensor under a partial coordinate specification. Slicing is realized by partial evaluation, e.g., T[None, thr_id].

These abstractions enable composability and precise static analysis in tensor manipulation, providing the programmability and formal guarantees necessary in high-throughput GPU kernel development.

2. Layout Algebra and Core Functions

CuTe-DSL implements a suite of algebraic functions for rigorous manipulation of complex tensor layouts, each equipped with both a Python signature and a formal semantic mapping:

Function	Python Signature / Description	Algebraic Formula
coalesce	coalesce(layout, by_mode=False): flatten to minimal depth, preserving offsets.	$R = \text{Coalesce}(A)$
compose	compose(outer, inner): function composition, $R(c) = \text{outer}(\text{inner}(c))$.	$R = A \circ B$
right_inverse	right_inverse(layout): computes a right-pseudo-inverse $L^\dagger$.	$L(L^{\dagger}(k)) = k$
left_inverse	left_inverse(layout): computes a left-pseudo-inverse $L^\ddagger$.	$L^{\ddagger}(L(k)) = k$
complement	complement(layout, size=None): computes $D$0, the complement mapping on unused image offsets.	$D$1
logical_product	logical_product(tile, grid): tiles a layout across another grid as $D$2.	$D$3
logical_divide	logical_divide(data, tiler): partitions tensor into hits/misses per tiler.	$D$4
identity	identity(shape): returns identity layout on $D$5.	$D$6
is_compatible	is_compatible(A, B): shape/rank compatibility check.	$D$7
assert_match	assert_match(A, B): static check for layout mapping equality (throws on discrepancy).	$D$8

Each operation corresponds directly to a section and equations in the CuTe algebra, enabling rigorous transformation, verification, and partitioning of layouts.

3. Algebraic–DSL Correspondence

CuTe-DSL maintains a direct, formal correspondence between mathematical definitions and their concrete API implementations, allowing explicit expression of layout semantics:

Mathematical Notation	DSL API Expression
$D$9	Layout(shape=S, stride=D)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$0	coalesce(A)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$1	compose(A, B)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$2	right_inverse(L)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$3	left_inverse(L)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$4	complement(L, size=L.size)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$5	logical_product(A, B)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$6	logical_divide(A, B)
$$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$7	identity(shape)

This notational duality enables both algebraic derivation and executable code to co-exist in the same workflow, facilitating code generation and compile-time checks.

4. Practical Usage and Examples

CuTe-DSL supports advanced use cases through composable operators and high-level tensor constructs:

• Flat and Hierarchical Layouts: Both flat (row/col-major) and hierarchical/interleaved layouts are instantiated using nested tuples, e.g., Layout(shape=(2, (4,2)), stride=((2,4), 1)).
• Composition and Inversion: Composing layouts (e.g., compose(L1, L2)) enables chaining of mapping functions, and computing pseudo-inverses (right_inverse, left_inverse) provides coordinate-roundtripping required for verification and analysis.
• Tiling and Partitioning: Tensors can be divided into tiles or blocks with logical_divide, and tiled across grids using logical_product, matching the partitioning patterns of contemporary GPU algorithms.
• Compile-Time Verification: Methods like is_compatible and assert_match allow both coarse and fine-grained verification of that user-defined layouts exactly match hardware-prescribed requirements, with failures detected at module load/compile time.

Sample code: $R = \text{Coalesce}(A)$2 Layouts, tensors, and partitions are constructed and manipulated with algebraically vetted transformations, ensuring zero hidden runtime overhead.

5. Runtime Semantics and Execution

Internally, every Layout consists solely of two HTuples—the shape $$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$8 and stride $$\mathcal{L}(c) = \langle D, \text{idx2crd}(S, c) \rangle$$9—and layout application reduces to two integer operations:

• Coordinate decoding: $R = \text{Coalesce}(A)$0 as per equation 2.16.
• Offset calculation: $R = \text{Coalesce}(A)$1, where nat_c denotes the natural coordinate, per equation 2.10.

Operators such as compose, coalesce, and complement deterministically materialize new layouts in terms of these structures, reducing all runtime logic to integer arithmetic loops, predominantly involving modular arithmetic, division, and summation. In static scenarios (typical for tensor program kernels), all metadata is available at compile time, and the resulting code reduces to pure pointer arithmetic and dereferencing—equivalent to hand-crafted code but correctness- and layout-genericity-guaranteed.

6. Production Integration and Significance

CuTe-DSL underpins established production libraries including NVIDIA’s CUTLASS (v3/v4) and efforts such as FlashAttention-3, ensuring that high-performance kernels can be generated, verified, and compiled directly from modular, algebraic layout descriptions (Cecka, 2 Mar 2026). Patterns such as tiling, blocking, and partitioning for tensor cores or shared memory access are expressed with mathematical precision and genericity, scaling to both standard and specialized architectural constraints.

The API’s limited, composable primitive set—encompassing Layout, Tensor, compose, coalesce, inversion, complement, logical_divide, and logical_product—suffices to cover the full algebraic manipulation space demanded by modern GPU workloads, providing predictable semantics and compile-time safety without sacrificing hardware-level efficiency.