<!-- examples/cuda-checklist/README.md -->

# CUDA checklist check programs

## histogram.cu

Compiles the two histogram kernels shown on the privatization concept page and checks each against a CPU histogram, bin by bin. It checks correct output only. Nothing is timed, so it says nothing about speed.

- `histogram_basic`: one thread per value, each doing `atomicAdd` on the global histogram.
- `histogram_privatized`: each block counts a contiguous slice of the input into a shared-memory copy, then adds every bin of the copy to the global histogram.

### Inputs checked

n = 2^20 values, 256 threads per block, and every combination of:

- 7 or 256 bins.
- `even` input, where value i goes to bin `i % bins`, or `skewed` input, where an even i goes to bin 0 and an odd i goes to bin `((i - 1) / 2) % bins`.
- 64, 256, 1024 or 4096 blocks for the privatized kernel. Each must divide n, because each block takes a slice of `n / blocks` values. The program rejects a block count that does not divide n and exits 1.

The basic kernel does not depend on the block count, so it runs once per bins and input pair. That gives 4 lines such as `bins=7 input=even basic=ok`, followed by 4 lines per pair such as `bins=7 input=even blocks=256 longest=149797 privatized=ok`, where `longest` is the count of the busiest bin. The output has 20 lines in all (4 basic and 16 privatized).

Exit status: 0 when every case matches the CPU histogram, 1 on any mismatch or a block count that does not divide n, and 2 on a CUDA error reported by the `CHECK` macro.

### Build and run

From the repository root:

```bash
mkdir -p /tmp/cuda-checklist && /usr/local/cuda/bin/nvcc -O2 -arch=sm_86 -o /tmp/cuda-checklist/histogram examples/cuda-checklist/histogram.cu && /tmp/cuda-checklist/histogram
```

The binary stays outside the repository. Do not commit it.

### Last run

- Date: 2026-11-18
- GPU: NVIDIA RTX A6000, compute capability 8.6
- CUDA: `nvcc` release 12.3, V12.3.52
- Result: 4 of 4 basic lines and 16 of 16 privatized lines ok, exit status 0
- Source: `histogram.cu`, sha256 `b2b8323f0ac89a8f3c081d374330ddf27f3793d31fabc320f923e3666d463e31`

### Page code

The code fences on the privatization page must match the regions marked `// region: basic-histogram` and `// region: privatized-histogram` in `histogram.cu`. `test/cudaChecklistSources.test.mjs` checks this and the source hashes above, so edit the kernels here first and copy them to the page.

## coarsening.cu

Compiles the two matrix-multiply kernels shown on the thread coarsening concept page and checks each against a CPU triple loop, element by element. It checks correct output only. Nothing is timed, so it says nothing about speed.

- `matmul_tiled`: one 32 x 32 block per 32 x 32 output tile, with an A tile and a B tile in shared memory.
- `matmul_coarsened<COARSE>`: one block per `COARSE` neighboring output tiles in a row. In each phase it loads the A tile once, then loads one B tile at a time for each output tile. Shared memory is two 32 x 32 float tiles (8 KB) for every `COARSE`.

### Inputs checked

Square matrices of width 512 and 1024, with 32 x 32 thread blocks, and these kernels for each width: `matmul_tiled`, then `matmul_coarsened<C>` for C in {1, 2, 4, 8, 16}. That gives 12 lines such as `width=1024 kernel=coarsened factor=8 ok` (2 widths x 6 kernels).

Both matrices hold integers from {-2, -1, 0, 1, 2}, drawn by a fixed-seed linear congruential generator. Every product and every partial sum is then an integer of magnitude at most 4 x 1024 = 4096, which `float` holds exactly in any summation order. The GPU result is therefore compared with the CPU result using `==`, with no tolerance. The output buffer is filled with 0xFF bytes, which read as NaN, before each launch, so an element a kernel fails to write counts as a mismatch.

Launch preconditions: the width must be a multiple of 32 for `matmul_tiled`, and a multiple of 32 x `COARSE` for `matmul_coarsened<COARSE>`, whose grid is `dim3(width / (32 * COARSE), width / 32)`. The program checks these on the host and exits 1 with a message if one fails.

Exit status: 0 when every case matches the CPU result, 1 on any mismatch or a failed launch precondition, and 2 on a CUDA error reported by the `CHECK` macro.

### Build and run

From the repository root:

```bash
mkdir -p /tmp/cuda-checklist && /usr/local/cuda/bin/nvcc -O2 -arch=sm_86 -o /tmp/cuda-checklist/coarsening examples/cuda-checklist/coarsening.cu && /tmp/cuda-checklist/coarsening
```

The binary stays outside the repository. Do not commit it.

### Last run

- Date: 2026-11-18
- GPU: NVIDIA RTX A6000, compute capability 8.6
- CUDA: `nvcc` release 12.3, V12.3.52
- Result: 12 of 12 lines ok, exit status 0
- Source: `coarsening.cu`, sha256 `308cc5f3d09564095cfcdf5c9d923d1a749ca6687c95114b4aac4cddb6d5372a`

### Register and shared memory use (compile output)

The page quotes the per-thread register counts that `ptxas` reports for these kernels. This is compile output, not a measurement of time. From the repository root:

```bash
mkdir -p /tmp/cuda-checklist && /usr/local/cuda/bin/nvcc -O2 -arch=sm_86 -Xptxas -v -c -o /tmp/cuda-checklist/coarsening.o examples/cuda-checklist/coarsening.cu 2>&1 | grep -E "Compiling|registers"
```

Run on 2026-11-18 with `nvcc` release 12.3, V12.3.52, for sm_86 (the RTX A6000). `ptxas` reports, for each kernel:

| Kernel                 | Registers per thread | Shared memory |
| ---------------------- | -------------------- | ------------- |
| `matmul_tiled`         | 36                   | 8,192 bytes   |
| `matmul_coarsened<1>`  | 36                   | 8,192 bytes   |
| `matmul_coarsened<2>`  | 40                   | 8,192 bytes   |
| `matmul_coarsened<4>`  | 40                   | 8,192 bytes   |
| `matmul_coarsened<8>`  | 40                   | 8,192 bytes   |
| `matmul_coarsened<16>` | 40                   | 8,192 bytes   |

Other architectures and compiler versions can report different counts.

### Page code

The code fences on the thread coarsening page must match the regions marked `// region: tiled-matmul` and `// region: coarsened-matmul` in `coarsening.cu`. `test/cudaChecklistSources.test.mjs` checks this and the source hashes above, so edit the kernels here first and copy them to the page.
