{"slug": "pycute-reference-implementation-and-examples-of-the-cute-layout", "title": "PyCuTe: Reference implementation and examples of the CuTe Layout", "summary": "NVIDIA researcher Cris Cecka released PyCuTe, a pure-Python reference implementation of the CuTe layout algebra used in CUTLASS 3.x and the CuTe DSL, enabling learning, prototyping, and test-vector generation without a GPU. The library implements all operations from the CuTe Whitepaper, including coalesce, composition, complement, and logical_divide, with Python 3.10+ as the only hard requirement and no third-party dependencies for the core algebra.", "body_md": "**A pure-Python reference implementation of CuTe — the hierarchical\nlayout-and-tensor algebra at the heart of\nCUTLASS 3.x and the\nCuTe DSL.\nNo GPU required.**\n\nWhere C++ CuTe is a header-only template library tightly coupled to CUDA,\nPyCuTe is plain Python you can `import`\n\nfrom any script — making it the place to\n**learn** the algebra, **prototype** new transformations, and **generate test\nvectors** for the C++ and DSL implementations.\n\nIt implements the layout algebra from the CuTe Whitepaper — `coalesce`\n\n,\n`composition`\n\n, `complement`\n\n, `logical_divide`\n\n, `logical_product`\n\n,\n`right_inverse`\n\n, `left_inverse`\n\n, `nullspace`\n\n, `recast`\n\n, `layout_add`\n\n, and\n`greatest_common_domain`\n\n— over integer and coordinate (`ArithTuple`\n\n/basis)\nstrides, plus limited support for `F2`\n\n(XOR-swizzle) strides. A thin\n`Tensor`\n\n/`Accessor`\n\nlayer provides a reference data model.\n\nCris Cecka,\n\nCuTe Layout Representation and Algebra,[arXiv:2603.02298]. The Whitepaper is the authoritative source for every definition and post-condition; PyCuTe defers to it throughout.\n\nPyCuTe is installed in-place from a source checkout. Because many systems mark the system Python as externally managed (PEP 668), the recommended path is a virtual environment:\n\n```\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install -e .              # core layout algebra only (no third-party deps)\npip install -e \".[viz]\"       # + visualization helpers (svgwrite, tabulate)\npip install -e \".[test]\"      # + everything needed to run the test suite\n```\n\n**Python 3.10+** is the only hard requirement, and the core algebra has no\nthird-party dependencies. The optional extras add `svgwrite`\n\n/`tabulate`\n\n(`viz`\n\n), `sympy`\n\n(`symbolic`\n\n), and `pytest`\n\n(`test`\n\n); the `draw_latex`\n\nhelpers\nneed only a LaTeX install (e.g. TeX Live's `pdflatex`\n\n) for their PDF step. You\ncan also use the package straight from a repository checkout without installing\n— `import pycute`\n\nworks as long as the repo is on `PYTHONPATH`\n\n.\n\n```\n>>> from pycute import *\n\n>>> A = Layout((3, 4), (4, 1))   # 3x4 row-major matrix\n>>> A(2, 3)                      # call the layout on a coordinate\n11\n>>> A(11)                        # a 1-D coordinate works too\n11\n>>> size(A), rank(A)\n(12, 2)\n\n>>> coalesce(Layout((2, (1, 6)), (1, (6, 2))))\nLayout(12, 1)\n>>> composition(Layout(12), Layout((4, 3)))\nLayout((4, 3), (1, 4))\n>>> logical_divide(Layout(24), Layout(4, 2))\nLayout((4, (2, 3)), (2, (1, 8)))\n```\n\nBuild a `Tensor`\n\nand read/write data:\n\n```\n>>> T = make_tensor(Layout((4, 4), (4, 1)))   # 4x4 row-major\n>>> T[1, 2] = 42.0\n>>> T[1, 2]\n42.0\n```\n\nPrint or draw a layout (see [Visualization](#visualization)):\n\n``` python\n>>> from pycute.util import print_tensor, draw_svg\n>>> print_tensor(Layout((4, 8), (1, 4)))\n(4, 8):(1, 4)\n0     4     8     12    16    20    24    28\n1     5     9     13    17    21    25    29\n2     6     10    14    18    22    26    30\n3     7     11    15    19    23    27    31\n>>> draw_svg(Layout((4, 8), (1, 4)))\nSaved as layout.svg\n```\n\nThe whole of CuTe fits in one sentence:\n\nA\n\nis a function from coordinates to offsets, defined by a`Layout`\n\n(the coordinate(s) domain) and a`Shape`\n\n(how coordinates become offsets) of the same hierarchical profile.`Stride`\n\nThe stride is what turns a shape into a row-major, column-major, or arbitrarily nested map:\n\n| Layout | Description |\n|---|---|\n`Layout((4, 8), (8, 1))` |\n4×8 row-major |\n`Layout((4, 8), (1, 4))` |\n4×8 column-major |\n`Layout(((2, 4), 8), ((1, 16), 2))` |\nhierarchical (nested modes) |\n\nA small algebra combines layouts to express tiling, partitioning,\nvectorization, and layout analysis. Every operation is a pure function that\ntakes layouts and returns another `Layout`\n\n:\n\n— simplify to the fewest modes with the same map.`coalesce(A)`\n\n— functional composition; index`composition(A, B)`\n\n`A`\n\nthrough`B`\n\n.— the \"missing\" modes that fill out`complement(A)`\n\n`A`\n\n's codomain.— factor`logical_divide(A, T)`\n\n`A`\n\ninto tiles of shape`T`\n\n(tiling).— replicate`logical_product(A, B)`\n\n`A`\n\n's pattern across`B`\n\n(repetition).— invert and analyze maps.`right_inverse`\n\n/`left_inverse`\n\n/`nullspace`\n\nA ** Tensor** is a\n\n`Layout`\n\npaired with an **(e.g. a pointer): evaluating it at a coordinate evaluates the layout to an offset and dereferences the accessor at that offset. That short story is the whole of CuTe — everything else is a refinement or application of it. For the careful treatment of each piece, read the**\n\n`Accessor`\n\n[documentation](#documentation).\n\nStart with [ docs/index.md](/NVlabs/CuTe/blob/main/docs/index.md). The documentation builds up from\nhierarchical tuples to layouts to the full algebra, with runnable examples drawn\nfrom the unit tests:\n\n| File | Topic |\n|---|---|\n`docs/00_quickstart.md` |\n\n`docs/01_htuple.md`\n\n`docs/02_shape_stride.md`\n\n`Shape`\n\n, `Stride`\n\n, and the integer-modules strides live in`docs/03_layout.md`\n\n`Layout`\n\n: construction, evaluation, coordinates, slicing`docs/04_layout_algebra.md`\n\n`docs/05_tensor.md`\n\n`Tensor`\n\nand `Accessor`\n\n`docs/06_swizzle.md`\n\n`Swizzle`\n\nand `F2`\n\n-stride layouts`docs/07_visualization.md`\n\n`print_tensor`\n\n, `draw_svg`\n\n, `draw_latex`\n\n, and color functors`docs/08_api_reference.md`\n\nPyCuTe renders layouts as ASCII tables (`print_tensor`\n\n, `print_table`\n\n), colored\nSVGs (`draw_svg`\n\n, `draw_svg_tv`\n\n), or TikZ/PDF (`draw_latex`\n\n, `draw_latex_tv`\n\n—\nthe analogue of `cute::print_latex`\n\n). Every figure below is a plain PyCuTe\n`Layout`\n\ndrawn with `pycute.util`\n\n; regenerate them all with\n[ examples/readme_figures.py](/NVlabs/CuTe/blob/main/examples/readme_figures.py):\n\n```\npython -m examples.readme_figures   # writes docs/images/*.svg  (needs the viz extra)\n```\n\n**A layout is a shape plus a stride.** The same 8×8 shape with two different\nstrides gives a row-major or a column-major map; each cell is labeled with its\noffset and colored by `offset % 8`\n\n:\n\n`Layout((8,8),(8,1))` Row-major |\n`Layout((8,8),(1,8))` Column-major |\n`Layout(((4,2), (2,4)), ((1,32), (4,8)))` Blocked |\n\n**Thread-value layouts.** `draw_svg_tv`\n\nshows how a warp's `(thread, value)`\n\npairs tile a matrix — here the C-accumulator of an SM80 `16×8`\n\nMMA, colored by\nthread. This is precisely the partitioning the layout algebra produces:\n\n`Layout(((4,8),(2,2)), ((32,1),(16,8)))`\n\n(tid, vid) → (m, n) in a 16×8 tile\n\n**Swizzles are just F2 strides.** Coloring a shared-memory tile by bank\n(\n\n`bank_color_8x`\n\n) makes conflicts visible. A row-major tile stores every column\nin a single bank (vertical stripes → 8-way conflict); swapping the integer\nstrides for `F2`\n\n(XOR) strides permutes each row so that every column spans all\n8 banks — conflict-free — with no special-casing in the algebra:`Layout((8,8),(F2(1),F2(9)))` Swizzled Column-major |\n`Layout((8,8),(F2(9),F2(1)))` Swizzled Row-major |\n\nSee [ docs/07_visualization.md](/NVlabs/CuTe/blob/main/docs/07_visualization.md) for every drawer, the\n\n`(r, g, b)`\n\ncolor-functor catalog (`index_grey_8x`\n\n, `bank_color_32x`\n\n,\n`thread_color_8x`\n\n, …), and the LaTeX/PDF output.\n\n```\npycute/\n├── docs/       # documentation (start at docs/index.md); figures in docs/images/\n├── examples/   # standalone scripts (einsum, TV-layout, README figures)\n├── test/       # pytest unit tests (one test_*.py per operation)\n└── pycute/     # the importable package\n    └── util/   # optional printing and visualization helpers\n```\n\nThe suite uses [pytest](https://docs.pytest.org). Install the `test`\n\nextra\n(see [Installation](#installation)) and run it from the repository root:\n\n```\npytest                                # the whole suite, quiet\npytest --log-cli-level DEBUG          # with live logging\npytest test/test_coalesce.py          # a single module\npytest -k coalesce                    # tests matching a keyword\n```\n\n-\nCris Cecka.\n\n*CuTe Layout Representation and Algebra.*[arXiv:2603.02298](https://arxiv.org/abs/2603.02298) -\nJack Carlisle, Jay Shah, Reuben Stern, Paul VanKoughnett.\n\n*Categorical Foundations for CuTe Layouts.*[arXiv:2601.05972](https://arxiv.org/abs/2601.05972) -\nYang Shi, U. N. Niranjan, Animashree Anandkumar, Cris Cecka.\n\n*Tensor Contractions with Extended BLAS Kernels on CPU and GPU.*[HiPC 2016, pp. 193–202](https://ieeexplore.ieee.org/document/7839684) -\nBastian Hagedorn, Bin Fan, Hanfeng Chen, Cris Cecka, Michael Garland, Vinod Grover.\n\n*Graphene: An IR for Optimized Tensor Computations on GPUs.*[ASPLOS 2023, pp. 302–313](https://dl.acm.org/doi/10.1145/3582016.3582018) -\n[NVIDIA CUTLASS / CuTe (C++)](https://github.com/NVIDIA/cutlass)— the original C++ implementation. -\n[NVIDIA CuTe DSL](https://docs.nvidia.com/cutlass/latest/media/docs/pythonDSL/overview.html)— the Python DSL that JIT-compiles CuTe kernels.\n\nCopyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0", "url": "https://wpnews.pro/news/pycute-reference-implementation-and-examples-of-the-cute-layout", "canonical_source": "https://github.com/NVlabs/CuTe", "published_at": "2026-07-29 21:06:16+00:00", "updated_at": "2026-07-29 21:22:44.850602+00:00", "lang": "en", "topics": ["artificial-intelligence", "machine-learning", "developer-tools"], "entities": ["Cris Cecka", "NVIDIA", "CUTLASS", "CuTe", "PyCuTe", "CuTe Whitepaper"], "alternates": {"html": "https://wpnews.pro/news/pycute-reference-implementation-and-examples-of-the-cute-layout", "markdown": "https://wpnews.pro/news/pycute-reference-implementation-and-examples-of-the-cute-layout.md", "text": "https://wpnews.pro/news/pycute-reference-implementation-and-examples-of-the-cute-layout.txt", "jsonld": "https://wpnews.pro/news/pycute-reference-implementation-and-examples-of-the-cute-layout.jsonld"}}