[Perf] Tiles 4c: add Tiles16x16 proxy

[hughperkins]

Issue: #

Brief Summary

Summary

Introduces the public qd.simt.Tile16x16 proxy API and migrates all tests to use it, replacing the private _make_tile16x16() factory. Also simplifies kernel signatures by
reverting tile_size from a kernel parameter back to a local variable.

What's in this PR

New public API (_Tile16x16Proxy)

• qd.simt.Tile16x16.zeros(dtype=qd.f32) / qd.simt.Tile16x16.eye(dtype=qd.f64) — create tiles with explicit dtype
• qd.simt.Tile16x16.zeros() — omit dtype to use the runtime's default_fp
• qd.simt.Tile16x16.SIZE — tile dimension constant (16)
• Lazy-loaded via __getattr__ in simt/__init__.py to avoid circular imports
• CPU backend detection: raises QuadrantsSyntaxError with a clear message
  tile_size reverted from kernel parameter to local variable
• In tiles-4b, tile_size: qd.Template was added as an explicit kernel parameter (passed as _TILE at call sites) to avoid accessing qd.simt.Tile16x16.SIZE inside
  fastcache=True kernels
• This PR reverts that: all kernels now use tile_size = qd.simt.Tile16x16.SIZE as a local variable, and tile_size is removed from kernel signatures and call sites
• This simplifies every kernel signature and call site, and is validated by every test in the file passing
  Test migration to public API
• All ~32 existing kernel tests migrated from _make_tile16x16()/Tile() to qd.simt.Tile16x16.zeros()/eye()
• _make_tile16x16 import retained only for test_tile16_make_caching and test_tile16_solve_triangular_upper_raises
  17 new tests for the proxy API
• test_tile16_load_store_partial, test_tile16_load_store_partial_rows — partial column/row load-store
• test_tile16_syr_sub — symmetric rank-1 subtract via scalar elements
• test_tile16_potrf, test_tile16_potrf_then_trsm — Cholesky and combined Cholesky+trsm using eps_field and _EPS_VALS
• test_tile16_vec_proxy_syr_sub_2d/3d, test_tile16_vec_proxy_partial_rows, test_tile16_vec_proxy_multi_column_accumulate — vec proxy patterns with tensor_type
  parametrization
• test_tile16_f64_roundtrip_into_f32_array — f64 tile on f32 data
• test_tile16_raises_on_cpu — CPU backend error
• test_proxy_size_constant, test_simt_invalid_attr_raises — basic proxy attributes
• test_proxy_default_dtype, test_proxy_eye_explicit_dtype — dtype resolution
• test_proxy_in_func — proxy inside @qd.func
• test_proxy_default_dtype_survives_reinit — dtype correctness across qd.reset() cycles
  Docs updated to use qd.simt.Tile16x16 throughout (quick start, creating tiles, identity init, kernel structure, f64 support, method reference table). Added combined
  Cholesky+trsm example.
  Other
• is_from_quadrants_module in util.py: moved import types to top-level
• _make_tile16x16 docstring updated to recommend using the proxy
• Type stub (_Tile16x16Proto) added for pyright/IDE support

Good

• Users no longer need to import a private _make_tile16x16 factory — qd.simt.Tile16x16 is discoverable and documented
• Kernel signatures are simpler: no more tile_size: qd.Template parameter or _TILE at call sites
• qd.simt.Tile16x16.SIZE is accessed inside every kernel in the test suite (via tile_size = qd.simt.Tile16x16.SIZE), so the pattern is thoroughly exercised
• CPU backend gives a clear error message instead of a crash
• Default dtype support (zeros() without args) follows default_fp
• Extensive test coverage including edge cases like reset()/reinit() cycles
• Docs fully updated to match the new API

Bad

• qd.simt.Tile16x16 is a module-level singleton instance (not a class), so the purity checker's is_from_quadrants_module returns False for it — accessing
  qd.simt.Tile16x16.SIZE inside a fastcache=True kernel emits a non-fatal PURE.VIOLATION warning. This doesn't affect correctness or CI (warnings are not treated as
  errors), but is not fully clean. A future fix to is_from_quadrants_module to recognize proxy instances would eliminate this
• The _Tile16x16Proto type stub duplicates method signatures and will need manual upkeep if the tile API changes
• _make_tile16x16 and its cache are still the underlying mechanism — the proxy is a thin wrapper, not a replacement of the internals

copilot:summary

Walkthrough

copilot:walkthrough

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: def18a06e4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Reject Python backend in Tile16x16 backend guard

The backend check only rejects cpu/x64/arm64, so qd.init(qd.python) falls through even though this API is documented to require GPU backends. In that case qd.simt.Tile16x16.zeros() proceeds to build tile code that depends on subgroup intrinsics, which can fail later with low-level errors instead of the intended QuadrantsSyntaxError. Please include qd.python (or invert this to an explicit GPU allowlist) in the guard so unsupported backends are rejected consistently at the call site.

Useful? React with 👍 / 👎.

[claude]

🔴 test_tile16_syr_sub has two bugs: (1) the kernel uses 'for tid in range(tile_size)' and indexes vec_arr[tid], but in SIMT all 16 threads share the same loop counter, so this degenerates _ger_sub into subtracting a constant scalar rather than a rank-1 outer product — only the last iteration's result (R - v[15]^2 for every element) is stored, while the test expects R - np.outer(v, v); (2) the assertion hardcodes atol=_ATOLS[qd.f32] (1e-5) despite the test being parametrized over both qd.f32 and qd.f64, making the f64 tolerance 100,000x too lenient. Fix (1) by replacing 'for tid in range(tile_size)' with 'for _ in range(tile_size)' and adding tid = qd.simt.subgroup.invocation_id() inside the body (as in test_tile16_ger_sub); fix (2) by using atol=_ATOLS[qd_dtype].

Extended reasoning...

Bug 1 - wrong thread ID: loop variable used instead of subgroup.invocation_id()

In Quadrants SIMT execution, for tid in range(tile_size) creates a sequential range-for loop where the loop variable tid takes values 0, 1, ..., 15 identically on all 16 threads in each iteration. It is NOT a per-thread ID. The pattern used throughout the rest of the test file for per-thread IDs is:

for _ in range(tile_size):
    tid = qd.simt.subgroup.invocation_id()   # each thread gets its own lane ID

In test_tile16_syr_sub the kernel does:

for tid in range(tile_size):          # BUG: tid is loop counter, same for all threads
    t = qd.simt.Tile16x16.zeros(...)
    t[:] = mat_arr[...]
    t -= qd.outer(vec_arr[tid], vec_arr[tid])
    out_arr[...] = t

Step-by-step proof of incorrectness:

• Iteration tid=k: all 16 threads see the same loop counter k, so vec_arr[tid] = v[k] (a scalar broadcast to every thread).
• In _ger_sub(a, b) with a=b=v[k] for all threads: shuffle(b, j) returns v[k] for every j (all lanes hold the same b), so tile[i][j] -= v[k]*v[k] for all i,j - not an outer product.
• The tile is re-initialized from mat_arr at the start of each iteration, so only the last iteration (k=15) survives.
• Actual result stored: out_arr[i][j] = R[i][j] - v[15]^2 for all (i,j) - a constant shift.
• Expected: out_arr[i][j] = R[i][j] - v[i]*v[j] - a proper rank-1 update.

These are completely different operations for non-constant v. The test will fail at runtime. The correct pattern is identical to test_tile16_ger_sub (line ~405) and test_tile16_slice_ger_sub_via_outer (line ~657), both of which correctly use qd.simt.subgroup.invocation_id().

Bug 2 - hardcoded f32 tolerance for an f64-parametrized test

The assertion at the end of test_tile16_syr_sub:

np.testing.assert_allclose(out.to_numpy(), R - np.outer(v, v), atol=_ATOLS[qd.f32])

uses _ATOLS[qd.f32] = 1e-5 unconditionally, but the test is parametrized over _QD_DTYPES = [qd.f32, qd.f64]. When qd_dtype==qd.f64, the tolerance should be _ATOLS[qd.f64] = 1e-10 (100,000x tighter). Using the f32 tolerance for f64 means any precision regression larger than 1e-10 but smaller than 1e-5 in the f64 code path would go undetected - completely defeating the purpose of f64 parametrization.

The surrounding new tests (test_tile16_potrf, test_tile16_potrf_then_trsm) correctly use atol=_ATOLS[qd_dtype]. The fix is: atol=_ATOLS[qd_dtype].

[hughperkins]

from Opus:

The reviewer is right on point (2) but wrong on point (1).

Point (1) — for tid in range(tile_size) is NOT a bug. The reviewer is misunderstanding Quadrants' kernel model. In Quadrants/Taichi, the top-level for loop IS the
parallelization primitive — each iteration runs on a different thread. With block_dim=16 and for tid in range(16), each of the 16 threads gets its own tid value (0–15). It
does NOT mean all 16 threads share the same loop counter. So vec_arr[tid] gives each thread a different scalar, and qd.outer(vec_arr[tid], vec_arr[tid]) correctly computes the
rank-1 symmetric outer product.

You can verify this by looking at test_tile16_slice_ger_sub_via_outer, which does essentially the same thing — qd.outer(per_thread_scalar, per_thread_scalar) — and correctly
produces a rank-1 outer product.

That said, using for _ in range(tile_size) + tid = qd.simt.subgroup.invocation_id() would be more consistent with the convention used in every other test in the file. So the
suggested change is fine as a style improvement, just not a correctness fix.

Point (2) — atol=_ATOLS[qd.f32] is a real bug. The test is parametrized over qd_dtype (both f32 and f64), but the assertion hardcodes the f32 tolerance. Should be
atol=_ATOLS[qd_dtype]. This makes the f64 path 100,000x too lenient (1e-5 instead of 1e-10), so it would pass but wouldn't catch regressions.

I'd fix point (2) and optionally apply point (1) for stylistic consistency. Want me to make the changes?

[hughperkins]

Opus:

Done. Pushed commit 92ec118 to hp/tiles-4c — changed _ATOLS[qd.f32] to _ATOLS[qd_dtype] in test_tile16_syr_sub.

[erizmr]

Approving on the basis that I have reviewed the design and the public facing API, tests, and they look reasonable to me.

[hughperkins]

Thanks!