Add gate-batched cache-local runner across SIMD backends

[xxie24]

build_gate_batch.sh

Gate-batched, cache-local simulation on the CPU

Idea

A state-vector simulator is memory-bound. qsim's standard runner makes one full
pass over the state for every fused gate. This PR adds a runner that groups the
circuit into batches of up to K gates and applies each batch to one
cache-sized slice of the state (a tile) at a time, while that slice is in
fast memory. The state is read and written once per batch instead of once per
gate.

K varies from batch to batch. A batch takes as many upcoming gates as the tile
can hold, meaning every qubit they act on fits in the tile. For example,
circuit_q30 runs 1,617 raw gates in 29 batches, about 56 gates per batch.

standard:    gate 1 → full pass │ gate 2 → full pass │ ... │ gate g → full pass
gate batch:  [swap pass] + for each tile: load → gates 1..K → store   (per batch)

A tile is 2^L amplitudes, sized for L2 (L = 19 by default). For each batch, the
planner picks gates whose qubits fit in L positions. One swap pass then moves
those qubits into the low L index bits, so every tile is a contiguous slice.

amplitude index bits:   n-1 ........ L │ L-1 ........ lane │ lane-1 ... 0
                        outside tile   │ tile (remappable) │ SIMD lanes

The lane bits are fixed because the swap kernel moves whole SIMD lane groups.
QubitLayout records which logical qubit sits at each physical position, and
the original order is restored at the end.

Parallelism

Tiles are independent within a batch, so each worker takes a whole tile and
applies all K gates to it:

batch b:   tile 0 │ tile 1 │ tile 2 │ ... │ tile 2^(n-L)-1
              ↓        ↓        ↓               ↓
           thread   thread   thread   ...    (OpenMP, dynamic scheduling)
  or:      team     team     team     ...    (two SMT siblings split each gate)

• Independent threads: each OpenMP thread takes one tile at a time and runs
  qsim's single-threaded SIMD simulator on it while it stays in that core's L2.
  Dynamic scheduling balances fast and slow cores.
• SMT teams (Linux): the two hardware threads of a core form a team, pinned
  once per run. The team shares one tile, so the tile is in L2 once, not twice.
  The siblings split each gate's work and meet at a barrier before the next
  gate.

Swap passes run over the whole state, not per tile, with OpenMP threads over
contiguous spans.

For small states, the tile shrinks so that every thread still has tiles to
work on, and the planner's lookahead shrinks with it so that planning does not
dominate.

Structure

The pipeline is written against a small backend interface; this PR provides
the CPU backend.

gate_batch_runner.h        GateBatchRunner<IO, Fuser, Backend>
  planner, remap bookkeeping, per-batch fusion, restore
  qubit_layout.h           QubitLayout, QubitMappedState, QubitSwap
             │
             │  Backend interface
             │
run_qsim_gate_batch.h      CpuGateBatchBackend, QSimGateBatchRunner
 ├ qubit_remap.h           swap passes
 ├ qsim SIMD simulator     applied to each tile
 └ cpu_thread_topology.h   SMT sibling teams

The backend owns the state memory and provides:

struct Parameter;                  // merged into the runner's Parameter
kDefaultTileQubits, kDefaultEvictionFloor, kMaxGateQubits
TileQubits(), RequestedTileQubits(), LaneQubits()
Prepare()                          // validate options, set up threads
ApplySwaps(swaps)                  // one pass of disjoint bit-pair swaps
ExecuteBatch(gates)                // every gate on every tile
Synchronize()                      // wait for queued work

The CPU backend reuses qsim's existing AVX-512/AVX2/SSE/NEON/basic simulators
on each tile.

Entry point:

QSimGateBatchRunner<IO, Fuser, Factory>::Run(param, factory, circuit, state)

A QubitMappedState overload skips the final restore. App:
qsim_gate_batch.cc.

Outside the new files, vectorspace.h now interleaves state memory across NUMA
nodes on Linux.

Results

8-physical-core/16-vCPU c4-standard-16 Intel Xeon Platinum 8581C VM:

Configuration	CPU allocation	Total (s)	Gate application (s)	Remap (s)	Speedup vs 8-core base
Base runner	8 physical cores	17.980	—	—	1.00x
Gate-batch, physical only	8 independent workers	9.297	6.319	2.976	1.93x
Gate-batch, ordinary SMT	16 independent workers	9.257	6.762	2.493	1.94x
Gate-batch, team SMT	8 two-sibling teams	8.523	5.930	2.592	2.11x

Limitations

• Supports any matrix gate (CNOT, CZ, SWAP, fSim, …). Not yet supported:
  ControlledGate operations (the c prefix in circuit files), measurements
  and channels.
• The correctness tests are not yet registered with Make/Bazel (follow-up).

[gemini-code-assist]

Code Review

This pull request introduces a gate-batched cache-local simulation runner (QSimGateBatchRunner) along with qubit remapping and layout utilities (QubitLayout, QubitMappedState, and ApplyBitPairSwaps) to optimize simulation performance. It also adds a benchmark application (qsim_gate_batch) and updates the build configurations. Feedback was provided to relax an assertion in run_qsim_gate_batch.h that would otherwise cause failures for small circuits where the number of qubits is less than the SIMD chunk size.

[gemini-code-assist]

The assertion assert(partition_.block_qubits >= chunk_qubits_); will fail for small circuits where the number of qubits is less than the SIMD chunk size (e.g., a 2-qubit circuit on an AVX-512 backend where chunk_qubits_ is 4). Since cache blocking is not required for circuits that fit entirely within a single SIMD chunk, we should relax this assertion to allow block_qubits to be smaller than chunk_qubits_ when the total number of state qubits is also smaller than chunk_qubits_.

Suggested change

	assert(partition_.block_qubits >= chunk_qubits_);
	assert(partition_.block_qubits >= std::min(chunk_qubits_, partition_.num_state_qubits));

[mhucka]

@xxie24 Thank you for this work. I know it's still a draft PR, but I wanted to mention that a recent failure in the CI workflow has now been fixed. I took the liberty of updating your branch to have the latest changes (I hope that's okay), and now the PR passes all the Ci tests.

[xxie24]

@xxie24 Thank you for this work. I know it's still a draft PR, but I wanted to mention that a recent failure in the CI workflow has now been fixed. I took the liberty of updating your branch to have the latest changes (I hope that's okay), and now the PR passes all the Ci tests.

cool. thanks.

[xxie24]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a proposal-faithful gate-batched cache-local simulation runner (qsim_gate_batch) along with CPU topology discovery, qubit remapping, and NUMA interleaving support. Feedback on the changes highlights a critical buffer over-read vulnerability in the NUMA interleaving syscall, a performance degradation risk in the SMT barrier spin loop due to a lack of pause/yield instructions, and a missing validation check for num_threads when inner_threads is not active.

[gemini-code-assist]

If param_.inner_threads <= 1, ValidateParameters returns true early without validating param_.num_threads. If param_.num_threads is 0, this can cause undefined behavior or crashes in OpenMP parallel regions (e.g., #pragma omp parallel num_threads(0)). We should validate that param_.num_threads > 0 before the early return.

Suggested change

	bool ValidateParameters() const {
	if (param_.max_fused_size < 2) {
	IO::errorf("qsim_gate_batch: max_fused_size must be at least 2.\n");
	return false;
	}
	if (param_.inner_threads <= 1) return true;
	bool ValidateParameters() const {
	if (param_.max_fused_size < 2) {
	IO::errorf("qsim_gate_batch: max_fused_size must be at least 2.\n");
	return false;
	}
	if (param_.num_threads == 0) {
	IO::errorf("qsim_gate_batch: num_threads must be greater than 0.\n");
	return false;
	}
	if (param_.inner_threads <= 1) return true;