westquant-bluequbit 0.1.0__tar.gz

westquant_bluequbit-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: westquant-bluequbit
+Version: 0.1.0
+Summary: WestQuant Execution Representation Scheduling on BlueQubit compute
+Author: WestQuant
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/WestQuantOpen/westquant-bluequbit
+Project-URL: Documentation, https://github.com/WestQuantOpen/westquant-bluequbit#readme
+Keywords: quantum,scheduling,optimization,bluequbit,representation,mps,pauli-path
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<2,>=1.24
+Provides-Extra: bluequbit
+Requires-Dist: bluequbit>=0.18; extra == "bluequbit"
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0; extra == "qiskit"
+Provides-Extra: all
+Requires-Dist: bluequbit>=0.18; extra == "all"
+Requires-Dist: qiskit>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# westquant-bluequbit
+
+**WestQuant Execution Representation Scheduling on BlueQubit compute.**
+
+WestQuant learns to map `(algorithm, circuit structure, accuracy target)` to `(representation, simulator, parameters)` on BlueQubit's multi-backend compute platform.
+
+```
+WestQuant
+    │
+circuit / problem
+    │
+┌───▼───────────┐
+│ Representation│
+│    Search     │
+└───┬───────────┘
+    │
+┌───┴───────────────┐
+│ Circuit rep        │  Execution rep
+│ gates/layout/basis  │  CPU / GPU / MPS / Pauli-path / QPU
+│ transpilation       │  bond dimension / truncation threshold
+└───┬───────────────┘
+    ▼
+BlueQubit
+    │
+    ▼
+cost / runtime / accuracy
+    │
+    ▼
+WQT training data
+```
+
+## Why not just a wrapper?
+
+BlueQubit exposes multiple ways to solve the same quantum computation: CPU, GPU, MPS (CPU/GPU), Pauli-path, and QPU. Each has tunable parameters (MPS bond dimension, Pauli-path truncation threshold, shots, transpilation level).
+
+This means WestQuant can search over:
+
+```
+a = (R_c, D, P, θ)
+```
+
+where `R_c` = circuit representation, `D` = device/simulator, `P` = preprocessing/transpilation, `θ` = simulator parameters.
+
+The optimization target is:
+
+```
+min(T, C, E)  subject to  E < ε
+```
+
+where `T` = runtime, `C` = cost, `E` = approximation error.
+
+## Installation
+
+```bash
+pip install westquant-bluequbit[bluequbit,qiskit]
+```
+
+## Quick Start
+
+```python
+from westquant_bluequbit import BlueQubitSearch
+
+search = BlueQubitSearch()
+
+result = search.optimize(
+    circuit,
+    objectives=["runtime", "cost", "error"],
+    devices=["cpu", "gpu", "mps.gpu", "pauli-path"],
+    mps_bond_dimensions=[4, 8, 16, 32, 64],
+    pauli_path_thresholds=[1e-1, 1e-3, 1e-5],
+)
+
+# Pareto-optimal execution configurations
+for config in result["pareto_front"]:
+    print(f"{config['device']}: {config['runtime_ms']:.0f}ms, ${config['cost']:.4f}")
+```
+
+## CLI
+
+```bash
+# Search across devices
+wq-bq search --circuit ghz --n-qubits 24 --devices cpu,gpu,mps.gpu
+
+# MPS bond dimension sweep
+wq-bq mps-sweep --circuit qaoa --n-qubits 28 --chi 4,8,16,32,64 --target-fidelity 0.999
+
+# Pauli-path truncation sweep
+wq-bq pps-sweep --circuit pauli --n-qubits 32 --thresholds 1e-1,1e-3,1e-5
+
+# Full benchmark suite
+wq-bq benchmark --families ghz,qft,qaoa,vqe,random,pauli --n-qubits 8,16,24 --devices cpu,gpu
+
+# Cost estimate
+wq-bq estimate --circuit ghz --n-qubits 32 --device mps.gpu
+```
+
+## Architecture
+
+### Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| `provider.py` | BlueQubit SDK wrapper with ledger tracking |
+| `executor.py` | Circuit execution with wall-clock timing |
+| `representation.py` | Circuit + execution representation dataclasses |
+| `device_search.py` | Multi-device Pareto search |
+| `mps_search.py` | MPS bond dimension sweep |
+| `pauli_path_search.py` | Pauli-path truncation threshold sweep |
+| `cost_model.py` | Learned cost/runtime prediction |
+| `verification.py` | Fidelity, JS divergence, TV distance |
+| `metrics.py` | Circuit features, Pareto front, hypervolume |
+| `training_data.py` | WQT policy record generation |
+| `cli.py` | Command-line interface |
+
+### Benchmark Suite
+
+| Family | What it tests |
+|--------|--------------|
+| GHZ | Low entanglement, ideal MPS candidate |
+| QFT | Dense global structure |
+| QAOA | Graph optimization |
+| VQE | Hardware-efficient ansatz |
+| Random Clifford | Stabilizer correctness baseline |
+| Random Universal | Generic hard simulation |
+| Pauli Evolution | Pauli-path relevant |
+
+Default qubit counts: 8, 12, 16, 20, 24, 28, 32, 36, 40.
+
+### WQT Training Data
+
+Each execution produces a policy record:
+
+```json
+{
+  "circuit_features": {"n_qubits": 24, "n_gates": 120, "n_2q_gates": 45, "depth": 30},
+  "representation": "mps.gpu_chi64",
+  "action": {"device": "mps.gpu", "options": {"mps_bond_dimension": 64}},
+  "prediction": {"estimated_runtime_ms": 820, "estimated_cost": 0.04},
+  "result": {"runtime_ms": 734, "cost": 0.037, "fidelity": 0.99991},
+  "reward": {"accuracy": 0.99991, "runtime": 734, "cost": 0.037}
+}
+```
+
+## Five WestQuant Experiments
+
+### A. Backend Router
+Learn `f(circuit) → {CPU, GPU, MPS, PPS}`. Which simulator representation is best for this circuit?
+
+### B. MPS Bond-Dimension Scheduler
+Search `χ ∈ {2, 4, 8, 16, 32, 64, 128}`. Measure `(χ, fidelity, runtime, cost)`. Learn `χ* = f(C, ε)`.
+
+### C. Pauli-Path Threshold Scheduler
+Search thresholds `10^{-1}` to `10^{-5}`. Get the accuracy-vs-compute curve.
+
+### D. Circuit Representation × Simulator Representation
+Not just `C → D`, but `(C, R) → (C', D)`. WestQuant changes gate decomposition, routing, basis — then selects the simulator. Same algorithm, different classical cost.
+
+### E. Learned Cost Model
+Compare BlueQubit's `estimate()` against actual runtime. Train `T̂_WQ(C, R, D)` — a representation-aware cost model.
+
+## BlueQubit Devices
+
+| Device | Cost | Use Case |
+|--------|------|----------|
+| `cpu` | Free | Small circuits, exact statevector |
+| `gpu` | $0.20/job | Medium circuits, fast exact simulation |
+| `mps.cpu` | Free | Large circuits, approximate |
+| `mps.gpu` | $0.20/job | Large circuits, fast approximate |
+| `pauli-path` | varies | Observable estimation, large circuits |
+| `quantum` | varies | Real QPU execution |
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [GitHub](https://github.com/WestQuantOpen/westquant-bluequbit)
+- [WestQuant Open](https://github.com/WestQuantOpen)
+- [BlueQubit](https://bluequbit.io)

westquant_bluequbit-0.1.0/README.md

@@ -0,0 +1,180 @@
+# westquant-bluequbit
+
+**WestQuant Execution Representation Scheduling on BlueQubit compute.**
+
+WestQuant learns to map `(algorithm, circuit structure, accuracy target)` to `(representation, simulator, parameters)` on BlueQubit's multi-backend compute platform.
+
+```
+WestQuant
+    │
+circuit / problem
+    │
+┌───▼───────────┐
+│ Representation│
+│    Search     │
+└───┬───────────┘
+    │
+┌───┴───────────────┐
+│ Circuit rep        │  Execution rep
+│ gates/layout/basis  │  CPU / GPU / MPS / Pauli-path / QPU
+│ transpilation       │  bond dimension / truncation threshold
+└───┬───────────────┘
+    ▼
+BlueQubit
+    │
+    ▼
+cost / runtime / accuracy
+    │
+    ▼
+WQT training data
+```
+
+## Why not just a wrapper?
+
+BlueQubit exposes multiple ways to solve the same quantum computation: CPU, GPU, MPS (CPU/GPU), Pauli-path, and QPU. Each has tunable parameters (MPS bond dimension, Pauli-path truncation threshold, shots, transpilation level).
+
+This means WestQuant can search over:
+
+```
+a = (R_c, D, P, θ)
+```
+
+where `R_c` = circuit representation, `D` = device/simulator, `P` = preprocessing/transpilation, `θ` = simulator parameters.
+
+The optimization target is:
+
+```
+min(T, C, E)  subject to  E < ε
+```
+
+where `T` = runtime, `C` = cost, `E` = approximation error.
+
+## Installation
+
+```bash
+pip install westquant-bluequbit[bluequbit,qiskit]
+```
+
+## Quick Start
+
+```python
+from westquant_bluequbit import BlueQubitSearch
+
+search = BlueQubitSearch()
+
+result = search.optimize(
+    circuit,
+    objectives=["runtime", "cost", "error"],
+    devices=["cpu", "gpu", "mps.gpu", "pauli-path"],
+    mps_bond_dimensions=[4, 8, 16, 32, 64],
+    pauli_path_thresholds=[1e-1, 1e-3, 1e-5],
+)
+
+# Pareto-optimal execution configurations
+for config in result["pareto_front"]:
+    print(f"{config['device']}: {config['runtime_ms']:.0f}ms, ${config['cost']:.4f}")
+```
+
+## CLI
+
+```bash
+# Search across devices
+wq-bq search --circuit ghz --n-qubits 24 --devices cpu,gpu,mps.gpu
+
+# MPS bond dimension sweep
+wq-bq mps-sweep --circuit qaoa --n-qubits 28 --chi 4,8,16,32,64 --target-fidelity 0.999
+
+# Pauli-path truncation sweep
+wq-bq pps-sweep --circuit pauli --n-qubits 32 --thresholds 1e-1,1e-3,1e-5
+
+# Full benchmark suite
+wq-bq benchmark --families ghz,qft,qaoa,vqe,random,pauli --n-qubits 8,16,24 --devices cpu,gpu
+
+# Cost estimate
+wq-bq estimate --circuit ghz --n-qubits 32 --device mps.gpu
+```
+
+## Architecture
+
+### Core Modules
+
+| Module | Purpose |
+|--------|---------|
+| `provider.py` | BlueQubit SDK wrapper with ledger tracking |
+| `executor.py` | Circuit execution with wall-clock timing |
+| `representation.py` | Circuit + execution representation dataclasses |
+| `device_search.py` | Multi-device Pareto search |
+| `mps_search.py` | MPS bond dimension sweep |
+| `pauli_path_search.py` | Pauli-path truncation threshold sweep |
+| `cost_model.py` | Learned cost/runtime prediction |
+| `verification.py` | Fidelity, JS divergence, TV distance |
+| `metrics.py` | Circuit features, Pareto front, hypervolume |
+| `training_data.py` | WQT policy record generation |
+| `cli.py` | Command-line interface |
+
+### Benchmark Suite
+
+| Family | What it tests |
+|--------|--------------|
+| GHZ | Low entanglement, ideal MPS candidate |
+| QFT | Dense global structure |
+| QAOA | Graph optimization |
+| VQE | Hardware-efficient ansatz |
+| Random Clifford | Stabilizer correctness baseline |
+| Random Universal | Generic hard simulation |
+| Pauli Evolution | Pauli-path relevant |
+
+Default qubit counts: 8, 12, 16, 20, 24, 28, 32, 36, 40.
+
+### WQT Training Data
+
+Each execution produces a policy record:
+
+```json
+{
+  "circuit_features": {"n_qubits": 24, "n_gates": 120, "n_2q_gates": 45, "depth": 30},
+  "representation": "mps.gpu_chi64",
+  "action": {"device": "mps.gpu", "options": {"mps_bond_dimension": 64}},
+  "prediction": {"estimated_runtime_ms": 820, "estimated_cost": 0.04},
+  "result": {"runtime_ms": 734, "cost": 0.037, "fidelity": 0.99991},
+  "reward": {"accuracy": 0.99991, "runtime": 734, "cost": 0.037}
+}
+```
+
+## Five WestQuant Experiments
+
+### A. Backend Router
+Learn `f(circuit) → {CPU, GPU, MPS, PPS}`. Which simulator representation is best for this circuit?
+
+### B. MPS Bond-Dimension Scheduler
+Search `χ ∈ {2, 4, 8, 16, 32, 64, 128}`. Measure `(χ, fidelity, runtime, cost)`. Learn `χ* = f(C, ε)`.
+
+### C. Pauli-Path Threshold Scheduler
+Search thresholds `10^{-1}` to `10^{-5}`. Get the accuracy-vs-compute curve.
+
+### D. Circuit Representation × Simulator Representation
+Not just `C → D`, but `(C, R) → (C', D)`. WestQuant changes gate decomposition, routing, basis — then selects the simulator. Same algorithm, different classical cost.
+
+### E. Learned Cost Model
+Compare BlueQubit's `estimate()` against actual runtime. Train `T̂_WQ(C, R, D)` — a representation-aware cost model.
+
+## BlueQubit Devices
+
+| Device | Cost | Use Case |
+|--------|------|----------|
+| `cpu` | Free | Small circuits, exact statevector |
+| `gpu` | $0.20/job | Medium circuits, fast exact simulation |
+| `mps.cpu` | Free | Large circuits, approximate |
+| `mps.gpu` | $0.20/job | Large circuits, fast approximate |
+| `pauli-path` | varies | Observable estimation, large circuits |
+| `quantum` | varies | Real QPU execution |
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [GitHub](https://github.com/WestQuantOpen/westquant-bluequbit)
+- [WestQuant Open](https://github.com/WestQuantOpen)
+- [BlueQubit](https://bluequbit.io)

westquant_bluequbit-0.1.0/benchmarks/ghz.py

@@ -0,0 +1,60 @@
+"""GHZ state benchmark circuits.
+
+Generates Greenberger-Horne-Zeilinger (GHZ) state preparation circuits,
+which place a register of qubits into the maximally entangled superposition
+
+    |0...0> + |1...1> / sqrt(2)
+
+via a Hadamard on qubit 0 followed by a chain of CNOT gates.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+__all__ = ["ghz_circuit", "ghz_family"]
+
+
+def ghz_circuit(n_qubits: int):
+    """Return a circuit preparing an ``n_qubits``-qubit GHZ state.
+
+    The circuit applies a Hadamard gate to qubit 0 and then a chain of
+    CNOT gates ``qubit[i] -> qubit[i + 1]`` for ``i`` in ``range(n_qubits - 1)``.
+
+    Parameters
+    ----------
+    n_qubits:
+        Number of qubits in the register. Must be at least 1.
+
+    Returns
+    -------
+    qiskit.QuantumCircuit
+        A circuit that prepares the GHZ state on ``n_qubits`` qubits.
+    """
+    if n_qubits < 1:
+        raise ValueError(f"n_qubits must be >= 1, got {n_qubits}")
+
+    from qiskit import QuantumCircuit
+
+    qc = QuantumCircuit(n_qubits, name=f"ghz_{n_qubits}")
+    qc.h(0)
+    for i in range(n_qubits - 1):
+        qc.cx(i, i + 1)
+    qc.measure_all()
+    return qc
+
+
+def ghz_family(n_qubits_list: Sequence[int]) -> list[tuple[str, "object"]]:
+    """Return a list of ``(name, circuit)`` GHZ circuits for each qubit count.
+
+    Parameters
+    ----------
+    n_qubits_list:
+        Iterable of qubit counts for which to build GHZ circuits.
+
+    Returns
+    -------
+    list[tuple[str, qiskit.QuantumCircuit]]
+        One ``(name, circuit)`` pair per requested qubit count.
+    """
+    return [(f"ghz_{n}", ghz_circuit(n)) for n in n_qubits_list]

westquant_bluequbit-0.1.0/benchmarks/pauli.py

@@ -0,0 +1,99 @@
+"""Trotterized Pauli-evolution benchmark circuits.
+
+Builds circuits that implement the time evolution under a sum of random
+Pauli operators using Qiskit's :class:`~qiskit.circuit.library.PauliEvolutionGate`
+(first-order Trotter synthesis). These circuits are representative of
+simulated quantum dynamics / chemistry workloads.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+__all__ = ["pauli_evolution_circuit", "pauli_family"]
+
+
+def pauli_evolution_circuit(n_qubits: int, n_paulis: int, time: float, seed: int):
+    """Return a Trotterized Pauli-evolution circuit.
+
+    A Hamiltonian is sampled as a sum of ``n_paulis`` random Pauli strings
+    (over ``I, X, Y, Z``) with random real coefficients in ``[-1, 1]``. The
+    circuit implements ``exp(-i * time * H)`` via first-order Trotterization.
+
+    Parameters
+    ----------
+    n_qubits:
+        Number of qubits. Must be at least 1.
+    n_paulis:
+        Number of random Pauli terms in the Hamiltonian. Must be at least 1.
+    time:
+        Evolution time (a non-negative float).
+    seed:
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    qiskit.QuantumCircuit
+        A Pauli-evolution circuit with measurements appended.
+    """
+    if n_qubits < 1:
+        raise ValueError(f"n_qubits must be >= 1, got {n_qubits}")
+    if n_paulis < 1:
+        raise ValueError(f"n_paulis must be >= 1, got {n_paulis}")
+    if time < 0:
+        raise ValueError(f"time must be >= 0, got {time}")
+
+    import numpy as np
+    from qiskit import QuantumCircuit
+    from qiskit.circuit.library import PauliEvolutionGate
+    from qiskit.quantum_info import SparsePauliOp
+
+    rng = np.random.default_rng(seed)
+    pauli_chars = np.array(["I", "X", "Y", "Z"])
+
+    terms: list[tuple[str, float]] = []
+    for _ in range(n_paulis):
+        # Qiskit Pauli strings are little-endian: rightmost char is qubit 0.
+        label = "".join(rng.choice(pauli_chars, size=n_qubits))
+        coeff = float(rng.uniform(-1.0, 1.0))
+        terms.append((label, coeff))
+
+    hamiltonian = SparsePauliOp.from_list(terms)
+    gate = PauliEvolutionGate(hamiltonian, time=time, label=f"pauli_evo_{n_qubits}")
+
+    qc = QuantumCircuit(n_qubits, name=f"pauli_{n_qubits}_m{n_paulis}")
+    qc.append(gate, range(n_qubits))
+    qc = qc.decompose()
+    qc.measure_all()
+    return qc
+
+
+def pauli_family(
+    n_qubits_list: Sequence[int], n_paulis_values: Sequence[int]
+) -> list[tuple[str, "object"]]:
+    """Return a list of ``(name, circuit)`` Pauli-evolution circuits.
+
+    For each qubit count in ``n_qubits_list`` and each term count in
+    ``n_paulis_values``, a Pauli-evolution circuit is generated with a fixed
+    evolution time and a seed derived from the qubit count and term count.
+
+    Parameters
+    ----------
+    n_qubits_list:
+        Iterable of qubit counts.
+    n_paulis_values:
+        Iterable of Hamiltonian term counts.
+
+    Returns
+    -------
+    list[tuple[str, qiskit.QuantumCircuit]]
+        One ``(name, circuit)`` pair per ``(n_qubits, n_paulis)`` combination.
+    """
+    circuits: list[tuple[str, object]] = []
+    for n in n_qubits_list:
+        for m in n_paulis_values:
+            name = f"pauli_{n}_m{m}"
+            circuits.append(
+                (name, pauli_evolution_circuit(n, m, time=0.5, seed=5000 + n + m))
+            )
+    return circuits

westquant_bluequbit-0.1.0/benchmarks/qaoa.py

@@ -0,0 +1,125 @@
+"""QAOA benchmark circuits for graph-optimization problems.
+
+Builds Quantum Approximate Optimization Algorithm (QAOA) circuits for a
+random Maximum-Weight Independent Set (MWIS)-like combinatorial problem
+defined on an Erdos-Renyi random graph.
+
+The cost Hamiltonian is
+
+    H_C = sum_{(i,j) in E} ZZ_{ij} - sum_{i in V} w_i Z_i
+
+where edges penalize two adjacent vertices both being selected and vertex
+weights reward selecting high-weight vertices. The mixer is the standard
+transverse-field ``sum_i X_i``.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+__all__ = ["qaoa_circuit", "qaoa_family"]
+
+
+def qaoa_circuit(n_qubits: int, p: int, graph_density: float, seed: int):
+    """Build a QAOA circuit for a random MWIS-like problem.
+
+    A random graph on ``n_qubits`` vertices is generated with the given
+    ``graph_density`` (probability of each edge). Each vertex is assigned a
+    random weight in ``[0, 1)``. The QAOA ansatz with ``p`` layers is then
+    constructed from the cost and mixer unitaries.
+
+    Parameters
+    ----------
+    n_qubits:
+        Number of qubits (graph vertices). Must be at least 2.
+    p:
+        Number of QAOA layers (repetitions of cost + mixer). Must be >= 1.
+    graph_density:
+        Edge probability in ``[0, 1]`` for the random graph.
+    seed:
+        Seed for the random graph and weights.
+
+    Returns
+    -------
+    qiskit.QuantumCircuit
+        A parameterized-free QAOA circuit (parameters fixed to deterministic
+        values derived from the seed) with measurements appended.
+    """
+    if n_qubits < 2:
+        raise ValueError(f"n_qubits must be >= 2, got {n_qubits}")
+    if p < 1:
+        raise ValueError(f"p must be >= 1, got {p}")
+    if not 0.0 <= graph_density <= 1.0:
+        raise ValueError(f"graph_density must be in [0, 1], got {graph_density}")
+
+    import numpy as np
+    from qiskit import QuantumCircuit
+
+    rng = np.random.default_rng(seed)
+
+    # Build the random graph as a list of edges.
+    edges: list[tuple[int, int]] = []
+    for i in range(n_qubits):
+        for j in range(i + 1, n_qubits):
+            if rng.random() < graph_density:
+                edges.append((i, j))
+
+    # Random vertex weights in [0, 1).
+    weights = rng.random(n_qubits)
+
+    # Deterministic but problem-dependent QAOA angles.
+    gammas = (np.pi / 4) * (np.arange(1, p + 1) / p)
+    betas = (np.pi / 4) * (np.arange(p, 0, -1) / p)
+
+    qc = QuantumCircuit(n_qubits, name=f"qaoa_{n_qubits}_p{p}")
+
+    # Initial uniform superposition.
+    qc.h(range(n_qubits))
+
+    for layer in range(p):
+        gamma = float(gammas[layer])
+        beta = float(betas[layer])
+
+        # Cost unitary: exp(-i gamma H_C).
+        # Edge terms: RZZ(2 * gamma) for each edge.
+        for i, j in edges:
+            qc.rzz(2.0 * gamma, i, j)
+        # Vertex terms: RZ(2 * w * gamma) for each vertex.
+        for i in range(n_qubits):
+            qc.rz(2.0 * float(weights[i]) * gamma, i)
+
+        # Mixer unitary: exp(-i beta sum_i X_i) -> RX(2 * beta) per qubit.
+        for i in range(n_qubits):
+            qc.rx(2.0 * beta, i)
+
+    qc.measure_all()
+    return qc
+
+
+def qaoa_family(
+    n_qubits_list: Sequence[int], p_values: Sequence[int]
+) -> list[tuple[str, "object"]]:
+    """Return a list of ``(name, circuit)`` QAOA circuits.
+
+    For each qubit count in ``n_qubits_list`` and each layer count in
+    ``p_values``, a QAOA circuit is generated with a fixed graph density and
+    a seed derived from the qubit count and ``p``.
+
+    Parameters
+    ----------
+    n_qubits_list:
+        Iterable of qubit counts (graph sizes).
+    p_values:
+        Iterable of QAOA layer counts.
+
+    Returns
+    -------
+    list[tuple[str, qiskit.QuantumCircuit]]
+        One ``(name, circuit)`` pair per ``(n_qubits, p)`` combination.
+    """
+    circuits: list[tuple[str, object]] = []
+    for n in n_qubits_list:
+        for p in p_values:
+            name = f"qaoa_{n}_p{p}"
+            circuits.append((name, qaoa_circuit(n, p, graph_density=0.5, seed=1000 + n + p)))
+    return circuits