# cytosine-code/pac26_indexer_mqa_logits architecture

> Architecture diagram of the GitHub repository cytosine-code/pac26_indexer_mqa_logits, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cytosine-code/pac26_indexer_mqa_logits
- Repository: https://github.com/cytosine-code/pac26_indexer_mqa_logits

## Overview

This repository is a PAC 2026 benchmark program and optimized AArch64 implementation of paged MQA logits for compressed sparse attention. The principal workflow generates BF16 query/KV test data, invokes the SME/SVE kernel, measures throughput, and checks its output against a reference implementation. The documented kernel stages include query packing, page scheduling and K packing, SME scoring, and fused ReLU/head reduction; masking handles invalid output positions. Kernel internals are represented at a high level because the source excerpt is partial; probe programs are excluded as development tools.

Main entry points: [`testcase.h`](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h) (Generate test cases), [`main.cpp`](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/main.cpp) (Run benchmark), [`ref_mqa_logits.h`](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/ref_mqa_logits.h) (Reference logits), [`indexer_mqa_logits.h`](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h) (Pack queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Benchmark harness"]
  node_main["Run benchmark<br/>[main.cpp]"]
  node_logits["Output logits<br/>[main.cpp]"]
end

subgraph group_data["Test data"]
  node_testcases["Generate test cases<br/>[testcase.h]"]
  node_tensors["Tensor views<br/>[Tensor.h]"]
  node_allocator["NUMA allocator<br/>[allocator.h]"]
  node_query["Query vectors<br/>[testcase.h]"]
  node_kv["Paged KV cache<br/>[testcase.h]"]
  node_metadata["Weights and lengths<br/>[testcase.h]"]
end

subgraph group_kernel["Optimized kernel"]
  node_qpack["Pack queries"]
  node_schedule["Schedule pages"]
  node_kpack["Pack KV page"]
  node_score["SME page scores"]
  node_reduce["ReLU and reduce"]
  node_mask["Causal output mask"]
end

subgraph group_support["Reference and utilities"]
  node_reference["Reference logits<br/>[ref_mqa_logits.h]"]
  node_checks["Correctness checks<br/>[utils.h]"]
end

node_invocation(("Benchmark invocation"))

node_invocation -->|"starts"| node_main
node_main -->|"generates data"| node_testcases
node_testcases -->|"creates views"| node_tensors
node_testcases -->|"allocates"| node_allocator
node_testcases -->|"produces"| node_query
node_testcases -->|"produces"| node_kv
node_testcases -->|"produces"| node_metadata
node_main -->|"invokes kernel"| node_qpack
node_query -->|"packs"| node_qpack
node_metadata -->|"guides"| node_schedule
node_schedule -->|"dispatches pages"| node_kpack
node_kv -->|"reads pages"| node_kpack
node_qpack -->|"supplies packed Q"| node_score
node_kpack -->|"supplies packed K"| node_score
node_score -->|"provides scores"| node_reduce
node_metadata -->|"supplies weights"| node_reduce
node_reduce -->|"writes scores"| node_logits
node_metadata -->|"supplies limits"| node_mask
node_mask -->|"masks positions"| node_logits
node_main -->|"computes baseline"| node_reference
node_query -->|"reads"| node_reference
node_kv -->|"reads"| node_reference
node_metadata -->|"reads"| node_reference
node_reference -->|"provides baseline"| node_checks
node_logits -->|"provides result"| node_checks
node_main -->|"checks accuracy"| node_checks

click node_main "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/main.cpp"
click node_testcases "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h"
click node_tensors "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/Tensor.h"
click node_allocator "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/allocator.h"
click node_query "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h"
click node_kv "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h"
click node_metadata "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h"
click node_qpack "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_schedule "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_kpack "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_score "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_reduce "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_mask "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h"
click node_logits "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/main.cpp"
click node_reference "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/ref_mqa_logits.h"
click node_checks "https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/utils.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_logits toneBlue
class node_testcases,node_tensors,node_allocator,node_query,node_kv,node_metadata toneAmber
class node_qpack,node_schedule,node_kpack,node_score,node_reduce,node_mask toneMint
class node_reference,node_checks toneRose
class node_invocation toneIndigo
```

## Components

### Benchmark harness

- [Run benchmark](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/main.cpp): `main.cpp`
- [Output logits](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/main.cpp): `main.cpp`

### Test data

- [Generate test cases](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h): `testcase.h`
- [Tensor views](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/Tensor.h): `Tensor.h`
- [NUMA allocator](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/allocator.h): `allocator.h`
- [Query vectors](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h): `testcase.h`
- [Paged KV cache](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h): `testcase.h`
- [Weights and lengths](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/testcase.h): `testcase.h`

### Optimized kernel

- [Pack queries](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`
- [Schedule pages](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`
- [Pack KV page](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`
- [SME page scores](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`
- [ReLU and reduce](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`
- [Causal output mask](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/indexer_mqa_logits.h): `indexer_mqa_logits.h`

### Reference and utilities

- [Reference logits](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/ref_mqa_logits.h): `ref_mqa_logits.h`
- [Correctness checks](https://github.com/cytosine-code/pac26_indexer_mqa_logits/blob/main/utils.h): `utils.h`

### Other components

- **Benchmark invocation**

## Connections

- Benchmark invocation → Run benchmark: starts
- Run benchmark → Generate test cases: generates data
- Generate test cases → Tensor views: creates views
- Generate test cases → NUMA allocator: allocates
- Generate test cases → Query vectors: produces
- Generate test cases → Paged KV cache: produces
- Generate test cases → Weights and lengths: produces
- Run benchmark → Pack queries: invokes kernel
- Query vectors → Pack queries: packs
- Weights and lengths → Schedule pages: guides
- Schedule pages → Pack KV page: dispatches pages
- Paged KV cache → Pack KV page: reads pages
- Pack queries → SME page scores: supplies packed Q
- Pack KV page → SME page scores: supplies packed K
- SME page scores → ReLU and reduce: provides scores
- Weights and lengths → ReLU and reduce: supplies weights
- ReLU and reduce → Output logits: writes scores
- Weights and lengths → Causal output mask: supplies limits
- Causal output mask → Output logits: masks positions
- Run benchmark → Reference logits: computes baseline
- Query vectors → Reference logits: reads
- Paged KV cache → Reference logits: reads
- Weights and lengths → Reference logits: reads
- Reference logits → Correctness checks: provides baseline
- Output logits → Correctness checks: provides result
- Run benchmark → Correctness checks: checks accuracy