Qbolt

Reproducible workspace for Quantathon CR 2026 Challenge 1: modelling Costa Rica's transmission network and benchmarking weighted Max-Cut with classical baselines and QAOA.

Evidence status: the ICE-backed 6-, 8-, 10-, and 12-node studies, QUBO/Ising verification, greedy, Goemans-Williamson, exhaustive search, preliminary local QAOA, and a preliminary multi-size comparison are available. These artifacts are exploratory evidence; they are not evidence of quantum advantage, convergence, or a Quantinuum H2 run.

Quick path

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r power-core/requirements.txt
python -m pytest

Regenerate the data and walkthrough figures from the repository root:

python data-analysis/scripts/build_weighted_graph.py
python data-analysis/scripts/build_regional_instance.py
python data-analysis/scripts/plot_regional_graph.py
python power-core/src/reports/generate_qubo_walkthrough.py
python power-core/src/reports/generate_ising_walkthrough.py
python power-core/src/reports/generate_qaoa_walkthrough.py
python power-core/src/benchmarks/reproduce_local.py

Documentation map

Goal	Documentation	Evidence or code
Read the complete Spanish route	Project reading guide	Data, formulation, benchmarks, figures, and limitations in order.
Verify source data and assumptions	Data analysis README · ICE reference (ES) · ICE reference (EN)	data-analysis/dataset/ and generated graph artifacts.
Inspect the six-node regional instance	Regional graph (ES)	regional_instance.json · regional_instance_graph.png.
Follow the QUBO formulation	QUBO (ES) · English	qubo_implementation.py.
Verify QUBO → Ising	Ising (ES) · English	Exhaustive six-node equivalence tests and ising.py.
Understand QAOA	QAOA (ES) · English	qaoa.py and adapters.
Review classical baselines	GW (ES) · English	Greedy, GW, and exact reference.
Interpret six-node benchmark results	Benchmark methodology · Preliminary results	results.json and charts.
Inspect size/depth comparison	Size/depth report	aggregate_preliminary.py, CSV/JSON, and ratio plot.
Inspect individual ICE-backed runs	6 nodes · 8 nodes · 10 nodes · 12 nodes	Confirmed transmission-line instances generated from the versioned ICE snapshot.
Inspect Nexus collection	Nexus dataset guide	nexus_maxcut_runs.json.
Check implementation setup	Power core README	Dependencies, source layout, commands, and limitations.
Check delivery constraints	Challenge skill	Reproducibility and reporting rules.

Experimental evidence

The benchmark family contains 6, 8, 10, and 12 substations connected only through confirmed ICE transmission lines. Each larger graph deterministically expands the documented six-node Guanacaste seed through its connected ICE frontier. Edge weight is summed nominal circuit voltage in kV: a transparent importance proxy, not capacity, power flow, impedance, failure risk, or a resilience metric.

Each size/depth configuration currently has one independent local QAOA run, so the study shows comparative behavior only; it does not provide uncertainty estimates or prove scaling.

Nexus integration submits through the Nexus API to a Selene StatevectorSimulator. It is cloud-hosted simulation, not Quantinuum H2 emulation or physical quantum hardware.

Reproducibility rules

• Regenerate JSON and PNG artifacts from scripts; do not edit them by hand.
• Preserve input digests, seeds, shots, depth p, optimizer status, and failures.
• Compare solvers on the identical graph and unchanged weights.
• Report approximation ratio (cut / OPT) rather than raw cut alone.
• Do not claim quantum advantage or superiority over Goemans-Williamson.

Repository layout

.
├── data-analysis/   # ICE validation and graph construction
├── power-core/      # QUBO, Ising, QAOA, classical solvers, reports, tests
│   ├── artifacts/   # Graph and benchmark evidence
│   ├── docs/        # Spanish and English walkthroughs
│   └── src/         # Solvers, benchmarks, experiments, and generators
└── skills/          # Challenge-specific delivery constraints

Documentation directory structure

power-core/docs/
├── english/                          # English documentation
│   ├── reference-ice-dataset.md      # ICE data provenance
│   ├── binary-variables-and-penalties.md
│   ├── synthetic-demand-provenance.md
│   ├── qubo/                          # QUBO formulation and walkthrough figures
│   ├── ising/                         # QUBO-to-Ising conversion and verification
│   └── qaoa/                          # QAOA formulation and execution pipeline
├── spanish/                          # Spanish documentation
│   ├── README.md                      # Reading route and main index
│   ├── reference-ice-dataset.md      # ICE data provenance
│   ├── binary-variables-and-penalties.md
│   ├── demanda-sintetica-procedencia.md
│   ├── regional-instance-graph.md    # Six-node regional instance
│   ├── benchmarks/                    # Benchmark methodology and results
│   │   ├── README.md
│   │   ├── nexus-run-dataset.md
│   │   └── evaluation/                # Evaluation contracts and templates
│   ├── qubo/                          # QUBO formulation and figures
│   ├── ising/                         # QUBO → Ising conversion and verification
│   └── qaoa/                          # QAOA formulation and execution pipeline
└── regional_instance_graph.png        # Shared regional-instance figure

Generated results and their explanations are stored in power-core/artifacts/; data-analysis documentation is maintained in data-analysis/README.md.