Iterate Centroids Score

---
description: Run the long-horizon centroid-score kernel iterate loop autonomously — design 4 variants, JIT-compile, benchmark, generate reports, analyse, repeat. Stops after --max-iterations batches (default 3).
argument-hint: [--max-iterations <N>] [--q <Q>] [--num-gpus <G>]
---

You are now running the **centroid-score kernel iterate loop**
autonomously. Do not ask for confirmation between steps; execute each
step in sequence and loop until the iteration budget is reached.

Unlike `/iterate`, this loop tunes the *centroid-scoring kernel* used
inside the block-sparse-attention indexer — the kernel that, given a
batch of Q rows and a table of block centroids, scores each request's
candidate pages so the downstream `topk_output` can pick survivors.
Iteration is fast (single GPU, seconds-to-minutes per variant) and
produces a `(geomean speedup, max abs error, per-regime + per-batch
speedup tables)` report per variant.

## Step 0 — parse arguments and activate conda env

Parse `$ARGUMENTS` for `--max-iterations <N>` (default: 3),
`--q <Q>` (default: 4 — `NUM_Q_HEADS`, the Q-axis this session tunes
for), and `--num-gpus <G>` (default: 4 — the batch size, so behavior
matches the historical single-wave run).

- `Q` is the number of query heads every kernel in this session is
  tuned for; it picks the working folder
  `vortex_torch/kernels/centroid_score/q_${Q}/` and is passed to
  `benchmark.py --num-q-heads` so reports use the same axis. One
  `/iterate_centroids_score` session targets a single `Q`; spin
  separate sessions for separate Q values.
- `NUM_GPUS` is the **maximum** number of free GPUs the loop will
  consume per batch *and* the maximum batch size when it exceeds 4:
  - `NUM_GPUS <= 4` → batch = 4 (fixed), the loop runs `⌈4 / NUM_GPUS⌉`
    sequential waves on the cap-sized GPU pool. Floor of 4 keeps the
    "≥1 novelty slot + sweep slots" composition rule intact.
  - `NUM_GPUS > 4`  → batch = `NUM_GPUS`, fully parallel (or waves of
    however many GPUs are actually free if `free_gpus.sh` returns
    fewer than `NUM_GPUS`).

```bash
MAX_ITER=3
Q=4
NUM_GPUS=4
NEXT=
for arg in $ARGUMENTS; do
  case "$NEXT" in
    max-iterations) MAX_ITER=$arg; NEXT= ;;
    q)              Q=$arg;        NEXT= ;;
    num-gpus)       NUM_GPUS=$arg; NEXT= ;;
    *) case "$arg" in
         --max-iterations) NEXT=max-iterations ;;
         --q)              NEXT=q ;;
         --num-gpus)       NEXT=num-gpus ;;
       esac ;;
  esac
done
# Batch size floors at 4; expands with NUM_GPUS when bigger.
BATCH_SIZE=4
[ "$NUM_GPUS" -gt "$BATCH_SIZE" ] && BATCH_SIZE=$NUM_GPUS
echo "max_iterations=$MAX_ITER  q=$Q  num_gpus=$NUM_GPUS  batch_size=$BATCH_SIZE"

Activate the conda environment:

CONDA_BASE=$(conda info --base 2>/dev/null || echo /root/anaconda3)
source "$CONDA_BASE/etc/profile.d/conda.sh"
conda activate vortex_v1
python -c "import sys; print(sys.executable)"

Step 1 — pick your tag and read context (once per session)

Your <tag> is a sanitized lowercase form of your model name (e.g. claude_sonnet_4_6, claude_opus_4_7). Create the per-Q, per-tag artifact dirs if they don't exist, and scaffold an empty memory_centroid_score.md from the template below on first use of this Q:

TAG=<your_tag>
QROOT=vortex_torch/kernels/centroid_score/q_${Q}
mkdir -p "$QROOT/sources/$TAG" "$QROOT/reports/$TAG"
# Make the q_${Q}/ tree importable as a Python package.
[ -f "$QROOT/__init__.py" ]                    || : > "$QROOT/__init__.py"
[ -f "$QROOT/sources/__init__.py" ]            || : > "$QROOT/sources/__init__.py"
[ -f "$QROOT/sources/$TAG/__init__.py" ]       || : > "$QROOT/sources/$TAG/__init__.py"

if [ ! -f "$QROOT/memory_centroid_score.md" ]; then
  cat > "$QROOT/memory_centroid_score.md" <<EOF
# memory_centroid_score.md — q=${Q}

Persistent state for \`/iterate_centroids_score --q ${Q}\`. Read at
the start of every session; mutate on every batch launch and every
batch completion. The conversation evaporates; this file does not.

The two reference kernels (against which all proposals are measured)
live at:
- Triton baseline — \`vortex_torch/kernels/centroid_score/baseline.py\`
  (\`.workload_size = 64\`, num_warps=8, num_stages=2; specialises to
  any \`num_q_heads\` via \`tl.constexpr\`).
- CUDA reference  — \`vortex_torch/kernels/centroid_score/baseline_cuda.py\`
  (one block per workload, one thread per page; not perf-tuned).

Submission contract (every proposal MUST satisfy):
\`\`\`python
def centroid_score(q, centroids, ctx, out) -> out
centroid_score.workload_size = <tile>   # positive int
\`\`\`
Implementation language is free — Triton or CUDA-C (compile via
\`cuda_loader.load_cuda_kernel\`). The ctx is sliced to the kernel's
\`.workload_size\`; baseline and proposal can use different tiles.
Submissions in this folder MUST be tuned for **\`num_q_heads=${Q}\`**
(other Q values get their own \`q_*\` bucket).

Benchmark protocol (per proposal): 200 stratified samples over
5 page-distribution regimes (\`N(256,64)\` … \`N(4096,1024)\`) × 5
batch sizes (\`{1,4,16,32,64}\`), \`n_blocks=16384\`, \`head_dim=128\`,
\`num_q_heads=${Q}\`. Reports land at
\`vortex_torch/kernels/centroid_score/q_${Q}/reports/<tag>/<batch_X_idY>.md\`.

Quality bar: **max |err| ≤ 0.1** vs the Triton baseline output
across the sweep (≈ a few bf16 ulps at values around 1.0). Anything
above that is structurally broken — log it in §4 and do not promote.
Speedup is geomean of \`baseline_ms / proposal_ms\`.

---

## §1 RUNNING

In-flight batches. One row per launch; remove the row when the
batch lands (move its summary to §2). If a row sits here at session
start, resume waiting on it before launching anything new.

| tag | batch | launched_at | gpu | variants | status |
| --- | ----- | ----------- | --- | -------- | ------ |
| _none_ | | | | | |

---

## §2 Completed batches

One subsection per completed batch (newest first). Each contains
the per-variant comparison table and a 1–3 sentence takeaway.

--