GridIQ

Official entry — Rigetti Energy Grid Optimization Hackathon (Hardware, Advanced track)

We solve the Maximum Power Energy Section (MPES) problem by casting it as a weighted MaxCut graph optimisation and benchmarking two parallel hybrid quantum-classical pipelines. Both pipelines converge at a shared post-processing step, making comparisons clean and auditable. The main notebook for running is notebooks/GridIQ_Pipeline_1.ipynb (includes hardware runs) .

Hardware status Pipeline 1 — Q-volution (Louvain subgraphs + light-cone QAOA preconditioning) has been fully executed on the Rigetti Ankaa-3 QPU, achieving ω = 0.9603 on Problem B. IBM exact-simulator and noisy-simulator results are also reported across 33 configurations. Pipeline 2 — Community / MCWS delivers the best overall simulation score (ω = 0.9763) but results are simulation-only at this time. Hardware execution is the immediate next step.

Team

Name	GitHub
Dr. Monalisa S. Roy	@monalisasroy
Dr. Matteo Piccolini	@matteo-piccolini
Mr. Md. Saad Bhatti	@saadbhattii
Mr. Priyansh Bhavsar	@Athleity

Competition page: https://aqora.io/competitions/energy-grid-optimization Dataset (Zenodo): https://doi.org/10.5281/zenodo.18329641

What this project does
Before you start — what you need
Step-by-step setup
Running the pipeline
CLI reference — every option explained
Understanding the output
Dataset setup
How the pipelines work
Repository map — every file explained
Running on quantum hardware
Running tests
Results at a glance
Competition requirements coverage
Limitations
References and glossary
Troubleshooting

What this project does

We are given two electrical grid graphs — Problem A (21 nodes) and Problem B (180 nodes) — where nodes are grid components (busbars, substations) and edges are transmission lines with positive weights. The goal is to partition the nodes into two groups to maximise the total weight of edges that cross between them. This is called weighted MaxCut, and it corresponds to the MPES (Maximum Power Energy Section) objective:

$$C(\vec{z}) = \frac{1}{4} \sum_{(i,j) \in E} w_{ij} \bigl(1 - z_i z_j\bigr), \quad z_i \in {-1, +1}$$

Problem B is too large for naive one-qubit-per-node QAOA on any near-term quantum device. Our solution:

Decompose the graph into small overlapping subgraphs (patches).
Run QAOA on each patch to estimate how pairs of nodes want to align.
Assemble those estimates into a global correlation matrix Z.
Feed Z into a classical solver to find the final partition.

We implement two independent decomposition strategies and compare their results side by side:

	Pipeline 1	Pipeline 2
Name	Louvain / Light-cone QAOA preconditioning	Community-aware MCWS
Decomposition	Louvain community subgraphs or per-edge light-cone patches	Modularity communities (MCWS warm start)
Hardware status	Validated on Rigetti Ankaa-3 QPU, IBM simulators + hardware	Simulation results only — hardware runs planned
Best result (Problem B)	ω = 0.9731 (IBM exact sim, light-cone + SDP)	ω = 0.9763 (sim, MCWS + SA refinement)

Before you start — what you need

Requirement	Version	Notes
Python	3.10 or newer	Check with `python --version`
pip	any recent	Comes with Python
Git	any	For cloning; not strictly required

No quantum hardware or Qiskit needed. The default simulator runs entirely on your laptop using numpy. Quantum SDK support (Qiskit, pyQuil) is available as an optional install.

Step-by-step setup

1. Get the code

Option A — Git (recommended)

git clone <REPO_URL>
cd GridIQ

Option B — Download ZIP

On GitHub, click the green Code button → Download ZIP
Unzip the file
Open a terminal and cd into the GridIQ folder

2. Create an isolated Python environment

This keeps GridIQ's dependencies separate from anything else on your system. Strongly recommended.

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

You should see (.venv) at the start of your terminal prompt. Run all subsequent commands with this active.

3. Install core dependencies

pip install -e .

This installs numpy, networkx, scipy, and matplotlib — everything needed to run the full pipeline with the built-in numpy simulator. No Qiskit, no pyQuil, no dataset download required at this stage.

Optional extras (install only what you need):

pip install -e .[ibm] # adds Qiskit + qiskit-aer for IBM hardware
pip install -e .[rigetti] # adds pyQuil for Rigetti hardware
pip install -e .[community] # adds python-louvain for better community detection
pip install -e .[dev] # adds pytest + linting tools
pip install -e .[all] # installs everything above

4. Verify the install

python main.py --dataset problem_a --pipeline all --dry-run

You should see a config summary printed and [dry-run] Config validated. Exiting. — no errors. If this works, you are ready to run.

Running the pipeline

There are two entry points. Use run_full_pipeline.py for normal use.

Quickest possible run — both pipelines, Problem A

python run_full_pipeline.py --dataset problem_a --pipeline all --verbose

This takes about 3–5 seconds on a laptop. It uses a synthetic graph automatically if you have not downloaded the real dataset (see Dataset setup). Results and plots are saved to results_out/.

Common usage examples

Run both pipelines on Problem A, default settings:

python run_full_pipeline.py --dataset problem_a --pipeline all

Run both pipelines on Problem B:

python run_full_pipeline.py --dataset problem_b --pipeline all --results-dir results_out_b

Run only the Q-volution / Louvain pipeline (Pipeline 1 — hardware-validated):

python run_full_pipeline.py --dataset problem_a --pipeline qvolution --verbose

Run only the Community MCWS pipeline (Pipeline 2 — simulation only):

python run_full_pipeline.py --dataset problem_a --pipeline community --verbose

Higher quality run — more shots, deeper QAOA, more SA restarts:

python run_full_pipeline.py \
--dataset problem_a --pipeline all \
--p 2 --shots 4096 --opt-shots 1024 \
--sa-reads 50 --sa-sweeps 2000 \
--verbose

Change the classical solver to Burer-Monteiro:

python run_full_pipeline.py --dataset problem_a --pipeline all --solver BM

Use edge-union patches for the community pipeline:

python run_full_pipeline.py \
--dataset problem_b --pipeline community \
--patch-family edge_union --p 2 --verbose

Validate a config without running anything (dry-run):

python main.py --dataset problem_b --pipeline qvolution \
--sdk IBM --mode exact_simulator --solver SA --dry-run

Reproducible run with fixed seed:

python run_full_pipeline.py --dataset problem_a --pipeline all --seed 42

CLI reference — every option explained

Both run_full_pipeline.py and main.py accept the same options.

Dataset and pipeline selection

Flag	Choices	Default	What it does
`--dataset`	`problem_a`, `problem_b`	`problem_a`	Which competition graph to load. Problem A = 21 nodes, Problem B = 180 nodes.
`--pipeline`	`qvolution`, `community`, `all`	`all`	Which decomposition strategy to use. `all` runs both and compares them.

QAOA settings

Flag	Type	Default	What it does
`--p`	int	`1`	QAOA circuit depth (number of alternating layers). Higher = potentially better quality, much slower. Start with 1.
`--shots`	int	`512`	Number of measurement samples collected per patch circuit to estimate the ZZ correlation matrix. Higher = less statistical noise, slower.
`--opt-shots`	int	`128`	Shots used during CVaR parameter optimisation. Can be lower than `--shots` to speed up optimisation.
`--cvar-alpha`	float	`0.5`	CVaR confidence level. Lower values (e.g. 0.1) focus on only the best shots, which can improve performance on noisy hardware.

Classical solver (applied to the ZZ matrix)

Flag	Choices / Type	Default	What it does
`--solver`	`SA`, `BM`, `one_exchange`	`SA`	Which classical solver to apply after assembling the ZZ matrix. SA = Simulated Annealing. BM = Burer-Monteiro SDP. `one_exchange` = greedy NetworkX heuristic.
`--sa-reads`	int	`20`	Number of independent SA restarts. More = better chance of finding optimum, slower.
`--sa-sweeps`	int	`600`	SA steps per restart. More = more thorough search per restart.
`--bm-rank`	int	`3`	Internal rank of the Burer-Monteiro relaxation (only used when `--solver BM`).
`--bm-restarts`	int	`10`	Number of BM restarts (only used when `--solver BM`).

Backend / hardware

Flag	Choices	Default	What it does
`--sdk`	`IBM`, `RIGETTI`	`IBM`	Quantum SDK to use. The built-in numpy simulator does not depend on this; it matters only when connecting to real hardware.
`--mode`	`exact_simulator`, `noisy_simulator`, `quantum_hardware`	`exact_simulator`	Execution mode. `exact_simulator` uses the built-in numpy simulator. `noisy_simulator` requires Qiskit + an IBM backend. `quantum_hardware` requires credentials (see Running on quantum hardware).
`--device`	string	`ibm_brisbane`	Hardware device name (only relevant when `--mode quantum_hardware`).

Community pipeline options

Flag	Choices	Default	What it does
`--patch-family`	`community`, `edge_union`, `node_cover`, `all`	`community`	Which type of patches to use in the community pipeline. `community` = modularity communities. `edge_union` = light-cone patches. `node_cover` = greedy cover. `all` = run all three.

Misc

Flag	Type	Default	What it does
`--seed`	int	`12345`	Random seed. Fix this to get reproducible results across runs.
`--results-dir`	path	`results_out/`	Where to save JSON results and plots. Created automatically.
`--verbose`	flag	off	Print detailed step-by-step progress. Recommended during development.
`--dry-run`	flag	off	(`main.py` only) Validate the config and print a summary, then exit without running anything.

Understanding the output

After a run, everything is saved to --results-dir (default: results_out/).

Terminal output

Pipeline MPES_q MPES_c α_q α_c Deltaα% ZZcov% Time(s)
---------------------------------------------------------------------------
qvolution 2458.62 2651.73 0.8940 0.9643 -7.28 100.0 0.49
community 1847.59 2598.89 0.6719 0.9450 -28.91 75.0 0.11

Column	Meaning
`MPES_q`	Final MPES score of the quantum-preconditioned solution
`MPES_c`	Final MPES score of the classical baseline (same solver, no quantum preconditioning)
`α_q`	Approximation ratio of quantum solution: `MPES_q / C*`
`α_c`	Approximation ratio of classical baseline
`Deltaα%`	Percentage improvement of quantum over classical
`ZZcov%`	Fraction of graph edges covered by at least one patch (100% = full coverage)
`Time(s)`	Wall-clock time for that pipeline

Files saved

results_out/
benchmark_results.json ← all run data; append-only across runs
plots/
01_approx_ratio_comparison.png ← α_q vs α_c side by side
02_mpes_scores.png ← raw MPES values
03_runtime_breakdown.png ← time per pipeline step
04_zz_heatmap_qvolution.png ← ZZ matrix visualised
04_zz_heatmap_community.png
05_graph_qvolution.png ← graph coloured by partition
05_graph_community.png
06_convergence_scatter.png ← MPES vs runtime scatter
07_timing_pie.png ← time split by stage
08_zz_coverage.png ← edge coverage per pipeline
results_table.txt ← plain-text version of terminal table

Dataset setup

Option A — automatic (no download, works immediately)

If no parquet files are found in dataset/, the pipeline auto-generates a synthetic weighted graph with the same number of nodes and edges as the real instance and adjusts C* accordingly. This is the default. Use this for development and testing.

Option B — real competition data

Go to: https://doi.org/10.5281/zenodo.18329641
Download the two parquet files
Place them here — names must match exactly: GridIQ/ dataset/ problem_a.parquet problem_b.parquet
Re-run. The loader detects them automatically.

Option C — Aqora remote streaming

pip install aqora-cli

If local files are absent, the loader falls back to streaming directly from: aqora://rigetti/energy-grid-optimization-problem-{a|b}/v0.0.0

How the pipelines work

Both pipelines solve the same problem and both end at the same step. Think of them as two different ways of breaking the large graph into manageable pieces before running QAOA.

Problem graph G (180 nodes for Problem B)




PIPELINE 1 PIPELINE 2
Louvain / Light-cone Community-aware MCWS
Hardware-validated Simulation only
(IBM + Rigetti Ankaa-3) (hardware runs planned)

Decomposition options: Decomposition:
- Louvain-g communities - Modularity communities
- Per-edge light-cones (MCWS warm start z^0)
- decode (Rigetti) 
Up to 226 subcircuits, 9 patches, 93% edge coverage
max 14 qubits each 

CVaR-QAOA per subcircuit Boundary-conditioned QAOA
Optimise γ, β via COBYLA per community patch (2.3 ms total)
SWAP strategy on hardware 




CONVERGENCE POINT 
gridiq/quantum/zz_matrix.py
Assemble global ZZ correlation matrix Z^(p)
Z_ij = z_i z_j from per-patch shot samples
(one |V|×|V| matrix, shared by both pipelines)


Classical solver on preconditioned graph
Edge weights w_ij replaced by Z_ij^(p)
Solvers: SA / Burer-Monteiro (SDP) / one_exchange


Evaluate C(z) on original weights
Compare α_quantum vs α_classical
Save results + generate 8 plots

The key insight: QAOA does not directly give us the answer. It gives us a correlation signal — which pairs of nodes want to be on the same side or opposite sides. The classical solver uses those signals as a preconditioner to find a better partition than it would find starting cold. The convergence point (gridiq/quantum/zz_matrix.py) is where both pipelines hand off their quantum information to the shared classical stage.

Pipeline 1 (Louvain / light-cone) has been executed end-to-end on the Rigetti Ankaa-3 QPU and IBM hardware backends. Pipeline 2 (Community MCWS) currently reports simulation results only. Hardware execution is planned as next steps.

Repository map — every file explained

GridIQ/

run_full_pipeline.py ← PRIMARY ENTRY POINT
Run this to execute both pipelines, generate
all plots, and save results to JSON.

main.py ← CONFIG / DRY-RUN ENTRY POINT
Use --dry-run to validate settings without running.
Also the entry point when imported as a module.

pyproject.toml ← Package definition and dependency list.
pip install -e . reads this file.

Makefile ← Shortcuts for common commands.
make run-a, make test, make run-b-full, etc.

.gitignore ← Tells Git which files NOT to track
(results, datasets, secrets, pycache).

dataset/
README.md ← Instructions for placing real parquet files here.
Drop problem_a.parquet and problem_b.parquet here.

notebooks/
Q-volution_2026.ipynb ← Original development notebook (light-cone pipeline).
Kept for reference and interactive exploration.
GridIQ_community.ipynb ← Original development notebook (community pipeline).
Kept for reference and interactive exploration.
README.md ← Explains how notebooks map to the Python package.

gridiq/ ← The actual Python package (importable as `gridiq`)

data/
loader.py ← Loads parquet files or falls back to synthetic.
synthetic.py ← Generates synthetic graphs for offline development.

graph/
objective.py ← The MPES objective C(z), approx ratio, resource
estimation. Single source of truth for scoring.
decomposition.py ← All decomposition strategies:
light_cone_decomposition (Q-volution)
louvain_g_decomposition (alternative)
community_patches, edge_union_patches,
node_cover_patches (community pipeline)

pipelines/
qvolution.py ← Q-volution pipeline as a Python class.
Implements all 10 steps from the notebook.
community.py ← Community (MCWS) pipeline as a Python class.
Implements all 10 steps from the notebook.

quantum/
circuit.py ← Pure-numpy exact statevector QAOA simulator.
No Qiskit required. Handles patches <= 14 qubits.
Also contains run_patch_qaoa_statevector().
optimise.py ← CVaR parameter optimisation using scipy COBYLA.
zz_matrix.py ← CONVERGENCE POINT 
Takes per-patch shot samples from either pipeline
and assembles the global ZZ correlation matrix.
Shared by both pipelines — this is where they meet.

classical/
mcws.py ← Modularity-Coarsened Warm Start (community pipeline).
Also contains local_search() and
simulated_annealing() for classical baselines.
solvers.py ← SA, BM, one_exchange solvers applied to Z matrix.
solve() dispatches to whichever solver is configured.

results/
io.py ← Append-only JSON results store. Each run adds one
entry; duplicate run keys are replaced in-place.
plots.py ← Generates all 8 plot types from results data.

utils/
config.py ← Converts CLI args into the unified CONFIG dict.
Also validates and prints config summaries.
timing.py ← Timer context manager used throughout the code.

results_out/ ← Auto-created when you run the pipeline.
Listed in .gitignore — not committed to Git.
benchmark_results.json
plots/ ← 8 PNG plots per run

tests/
test_smoke.py ← 9 unit and integration tests. Run with pytest.
All pass with no quantum SDK and no dataset.

Running on quantum hardware

IBM (Qiskit)

pip install -e .[ibm]

Set up your IBM Quantum credentials (one-time):

python -c "from qiskit_ibm_runtime import QiskitRuntimeService; \
QiskitRuntimeService.save_account(channel='ibm_quantum', token='YOUR_TOKEN')"

Run:

python run_full_pipeline.py \
--dataset problem_a --pipeline qvolution \
--sdk IBM --mode quantum_hardware --device ibm_brisbane \
--p 1 --shots 4096

Rigetti (pyQuil)

Rigetti hardware requires Docker running locally (quilc + QVM) and QCS credentials.

pip install -e .[rigetti]
# Start services:
docker run -d -p 5555:5555 rigetti/quilc -R
docker run -d -p 5000:5000 rigetti/qvm -S

Run:

python run_full_pipeline.py \
--dataset problem_a --pipeline qvolution \
--sdk RIGETTI --mode quantum_hardware \
--p 1 --shots 1000

Practical note: Problem A (21 nodes) and individual patches from Problem B are realistic hardware targets. Running QAOA on the full Problem B graph (180 qubits) without decomposition is not feasible on near-term devices.

Running tests

pip install -e .[dev]
pytest tests/ -v

All 9 tests pass with no quantum SDK and no dataset. They cover:

Module imports
MPES objective correctness
Light-cone decomposition
ZZ matrix assembly
SA solver on a small graph
CLI dry-run (end-to-end config validation)

To run a single test:

pytest tests/test_smoke.py::test_mpes_triangle -v

Results at a glance

All scores are on Problem B (|V| = 180, |E| = 226), evaluated on the original MPES objective. C* = 7,099.57 (Dupont et al., arXiv:2502.18570). ω = C(z) / C*.

Classical baselines

Method	Cut C(z)	ω	Time (s)
Local search (vanilla)	6,564.68	0.9247	0.04
Simulated annealing (vanilla)	6,777.50	0.9546	1.05

Pipeline 1 — Louvain / Light-cone QAOA preconditioning Hardware-validated

All Pipeline 1 results use a classical SDP solver on the ZZ matrix. IBM tQ = CPU wall-clock (not QPU latency). Rigetti Ankaa-3 tQ includes gate execution, readout, and queue time. SWAP strategy active for noisy/hardware IBM runs; CVaR α in {0.3, 0.5}.

Backend	Decomposition	Cut C(z)	ω	tQ (s)	tC (s)
IBM exact sim.	light-cone	6,908.79	0.9731	63.4	1.7
IBM noisy sim.	Louvain-g	6,829.04	0.9619	23.5	2.5
IBM noisy sim.	light-cone	6,831.47	0.9622	98.4	1.2
Rigetti Ankaa-3 QPU	Louvain-g	6,818.02	0.9603	830.9	1.6
Rigetti exact sim. (QVM)	decode	6,750.79	0.9509	517.6	2.8

Headline numbers:

Best simulation: 6,908.79 (ω = 0.9731) — IBM exact sim, light-cone + SDP — +5.2% over vanilla LS, +1.9% over vanilla SA
Best hardware: 6,818.02 (ω = 0.9603) — Rigetti Ankaa-3 QPU, Louvain-g + SDP — +3.8% over vanilla SA
Fastest competitive result: ω = 0.9619 in only 23.5 s quantum time (IBM noisy, Louvain-g)
226 subcircuits (light-cone), max 14 qubits per circuit at p=1; 33 configurations benchmarked across IBM + Rigetti

Pipeline 2 — Community-aware MCWS Simulation only

Note: all Pipeline 2 results below are simulation results only. Hardware execution is planned and in progress. QAOA quantum time: 2.3 ms total (9 patches, 210/226 edges covered = 93%, p=1).

Method	Cut C(z)	ω	tQ (s)	tC (s)
Community warm start + local search	6,917.13	0.9743	—	0.04
Community warm start + sim. annealing	6,917.13	0.9743	—	1.08
Precondition only + local search	6,917.13	0.9743	0.002	0.03
Precondition only + sim. annealing	6,915.92	0.9741	0.002	0.98
Precondition + refine + local search	6,917.13	0.9743	0.002	0.06
Precondition + refine + sim. annealing	6,931.49	0.9763	0.002	1.01

Headline numbers (simulation only):

Best result: 6,931.49 (ω = 0.9763) — MCWS precondition + SA refinement — +5.6% over vanilla LS, +2.3% over vanilla SA
Exceptionally low quantum overhead (2.3 ms), making it a strong candidate for near-term hardware once ported

Reference optima

Instance	C*	Notes
Problem A	3,728.413221	Exact — brute-force over all 2^2^1 = 2,097,152 configurations
Problem B	7,099.57	Best known for the 180-node subproblem (Dupont et al.)

Competition requirements coverage

The Rigetti track requests four deliverables. GridIQ addresses them as follows:

Requirement	Where in GridIQ
1. Resource estimation	`gridiq/graph/objective.py` → `resource_estimation()` prints qubit count, gate depth, CNOT scaling for naive QAOA at any circuit depth p. Shown automatically in terminal output under `[2] Resource est`.
2. Optimisation (Problem B too large)	Pipeline 1 decomposes Problem B into up to 226 subcircuits of <= 14 qubits each (light-cone) or 10–20 subcircuits (Louvain-g). Pipeline 2 uses 9 community patches covering 93% of edges. Both fit within near-term hardware budgets.
3. Benchmarking	Every run produces a side-by-side table of α_quantum vs α_classical with explicit runtime, shot counts, and solver settings. 33 Pipeline 1 configurations benchmarked across IBM + Rigetti. Results stored in `benchmark_results.json`.
4. Hardware execution	Pipeline 1 has been executed on the Rigetti Ankaa-3 QPU (ω = 0.9603, +3.8% over vanilla SA) and on IBM noisy/hardware backends. Pipeline 2 results are simulation only — hardware execution is planned.

Limitations

ZZ matrix coverage: if a patch family does not cover all graph edges, some entries in Z remain zero. The community pipeline may cover fewer edges than the light-cone pipeline (shown as ZZcov% in results). Consider --patch-family edge_union for better coverage.
Statevector simulator scale: the built-in numpy simulator handles patches up to 14 qubits (2^1^4 = 16,384 amplitudes). Larger patches are skipped (random fallback) unless you use Qiskit Aer with GPU support.
QAOA quality: performance is sensitive to initial angles, shot count, and circuit depth. CVaR helps but does not guarantee global optimum.
Classical solver is the workhorse: QAOA acts as a preconditioner. The final quality depends heavily on the classical solver budget (--sa-reads, --sa-sweeps).

References and glossary

References

Paper / Resource	Link
Competition page	https://aqora.io/competitions/energy-grid-optimization
Dataset (Zenodo)	https://doi.org/10.5281/zenodo.18329641
Dupont et al. — Quantum Preconditioning	https://arxiv.org/abs/2502.18570
Rigetti QCS documentation	https://docs.rigetti.com/qcs
pyQuil documentation	https://pyquil-docs.rigetti.com/en/stable/
NetworkX one_exchange	https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.approximation.maxcut.one_exchange.html

Glossary

Term	Meaning
MPES	Maximum Power Energy Section — the competition's robustness metric, modelled here as weighted MaxCut.
MaxCut	Graph partition problem: put each node in one of two groups to maximise the total weight of edges crossing between groups.
QAOA	Quantum Approximate Optimisation Algorithm — a variational quantum circuit that alternates between a problem Hamiltonian and a mixing Hamiltonian, parameterised by angles γ and β.
CVaR	Conditional Value at Risk — a loss function that focuses on only the best fraction α of measurement outcomes, improving optimisation convergence on noisy devices.
ZZ matrix	Z^(p): an N×N matrix of pairwise spin correlators z_i z_j estimated from QAOA shot samples. The convergence point of both pipelines.
Quantum preconditioning	The technique (Dupont et al.) of replacing edge weights with ZZ correlators before running a classical solver, so the solver inherits quantum-derived structure.
Light-cone decomposition	Build one subgraph per graph edge by taking the p-hop neighbourhood of both endpoint nodes. Used by the Q-volution pipeline.
MCWS	Modularity-Coarsened Warm Start — detect communities, solve MaxCut inside each, stitch into a global assignment. Used as the Community pipeline's starting point.
Patch	A small induced subgraph on which a single QAOA circuit is run. Size is bounded by the hardware qubit budget.
Approximation ratio α	C(z) / C* — fraction of the best known solution achieved. In (0, 1]; higher is better.
QCS	Quantum Cloud Services — Rigetti's platform for running circuits on real QPUs.
C*	Best known objective value for a given instance. Problem A: 3728.41 (exact). Problem B: 7099.57 (best known).

Troubleshooting

pip install -e . fails

pip install --upgrade pip setuptools
pip install -e .

ModuleNotFoundError: No module named 'gridiq' Make sure you are running commands from inside the GridIQ/ folder with your virtual environment active ((.venv) should be visible in your prompt).

FileNotFoundError about the dataset This is expected if you have not downloaded the real parquet files. The pipeline uses a synthetic graph automatically — you do not need to do anything.

ValueError: Patch too large or very slow runs Reduce the patch size by using the community pipeline with --patch-family community, or lower --p to 1.

Plots folder is empty Install matplotlib: pip install matplotlib, then re-run.

pytest command not found

pip install -e .[dev]
pytest tests/ -v

Rigetti Docker connection error Make sure both containers are running:

docker run -d -p 5555:5555 rigetti/quilc -R
docker run -d -p 5000:5000 rigetti/qvm -S

IBM authentication error Re-save your credentials:

python -c "from qiskit_ibm_runtime import QiskitRuntimeService; \
QiskitRuntimeService.save_account(channel='ibm_quantum', token='YOUR_TOKEN', overwrite=True)"

Built With

jupyter-notebook
makefile
python