The Problem

C++ CuTe is a header-only template library tightly coupled to CUDA, which makes it hard to learn, prototype, or test outside a GPU environment. Developers working on CUTLASS layouts need a reference implementation that runs anywhere.

What This Does

PyCuTe is a pure-Python implementation of the CuTe layout algebra — coalesce, composition, complement, logical_divide, logical_product, right_inverse, left_inverse, nullspace, recast, layout_add, and greatest_common_domain — over integer and coordinate (ArithTuple/basis) strides, plus limited F2 (XOR-swizzle) support. A thin Tensor/Accessor layer in pycute/tensor.py and pycute/accessor.py provides a reference data model.

The core algebra in pycute/ has no third-party dependencies and requires only Python 3.10+. Optional extras add visualization (svgwrite, tabulate), symbolic math (sympy), and testing (pytest). The docs/ folder contains a full tutorial series (00_quickstart.md through 08_api_reference.md).

How It Is Wired

The single entry point is main in examples/readme_figures.py:26, which reaches 50 functions and touches the filesystem via os.makedirs — the only external effect traced. The repository is a library, not a service; there is no database, network, or long-running process.

Control flow centers on pycute/layout.py, defining is_layout, _set, _coshape, and __call__. The internal call graph shows Layout called from 153 places, E from 44, is_tuple from 42, size from 39. The test suite drives most of this: test_composition_coords calls E 69 times and Layout 68 times; test_coalesce_f2 calls F2 62 times.

The module graph has a hub: pycute/__init__.py is imported by 30 modules and sits inside a 10-module circular dependency. Changing it has a wide blast radius. pycute/layout.py is called from 28 files and defines the core Layout type; pycute/shape.py provides shape, size, rank, depth; pycute/atuple.py and pycute/htuple.py define the tuple types and their operations; pycute/algebra.py owns the layout transformations. pycute/swizzle.py handles F2 XOR-swizzle strides.

How To Use It

python3 -m venv .venv
source .venv/bin/activate

pip install -e .              # core layout algebra only (no third-party deps)
pip install -e ".[viz]"       # + visualization helpers (svgwrite, tabulate)
pip install -e ".[test]"      # + everything needed to run the test suite

Run tests with pytest from the repo root. The README documents these commands; no lockfile exists, so installs are not fully reproducible.

Real-World Use

from pycute import *

# Build a tiled layout for a 128x128 GEMM, 32x32 tile
tile = Layout((32, 32), (1, 32))
A = make_tensor(tile, (128, 128))
# Verify the layout algebra
assert coalesce(Layout((2, (1, 6)), (1, (6, 2)))) == Layout(12, 1)

Code Health & Issues

Static analysis found 28 findings (21 high, 7 medium) across 6 kinds:

  • High - Import cycle — pycute/__init__.py, pycute/typedefs.py, pycute/htuple.py participate in a 10-module circular dependency. Breaking it requires extracting shared types or deferring imports.
  • High - Hub module — pycute/__init__.py is imported by 30 modules; changes there have a high blast radius.
  • High - Deep nesting — pycute/layout.py, pycute/shape.py, pycute/swizzle.py reach indentation depth 9; control flow is hard to follow.
  • Medium - Broad exception handling — pycute/typedefs.py uses Exception-wide except clauses.
  • Medium - Duplicated code — 5 repeated 6-line blocks across pycute/util/draw_latex.py and pycute/util/draw_svg.py.
  • Medium - High branching density — examples/einsum.py has 31 branch points over 80 lines.

SDLC gaps: no CI/CD pipeline, no lockfile, no Dependabot/Renovate configuration. The repo has tests, a license, and no committed secrets.

The Bottom Line

A solid, dependency-free reference implementation of the CuTe algebra with good documentation and a real test suite. The import cycle and hub module make pycute/__init__.py risky to change. Use it for learning, prototyping, or generating test vectors for CUTLASS — not for production GPU work.