qugrid 0.1.0

Quantum computing for power system research: from a MATPOWER case to a quantum algorithm in three lines.

import qugrid as qg

result = qg.solve(qg.problems.Islanding(qg.cases.case9()), solver="qaoa", seed=0)
print(result.summary())

QuGrid result | solver=qaoa | Islanding(n=9)
  objective          27.0512
  feasible           yes
  gap vs reference   0%
  P(optimum)         0.010
  n_cut              2
  island_power_mw    (10.3, -5.0)
  islands_connected  (True, True)
  resources          wall_time_s=0.37, n_qubits=9, p=2, evaluations=1200, restarts=3, seed=0

Engineering units, the same-run classical reference, and the honest success probability — in the first screenful. QuGrid is for power system researchers who want to study quantum algorithms without leaving their field's tools, units, and standards of evidence — and for quantum researchers who want grid problems formulated the way power engineers will actually review them.

English · 中文 · Documentation · 10-min quickstart · 十分钟上手

Why this library exists

Between MATPOWER/pandapower and Qiskit/Ocean/PennyLane there is a gap where research quality goes to die: hand-rolled QUBO encodings with undocumented penalty weights, results reported as Ising energies instead of megawatts, and comparisons that quietly omit the classical solver the field actually uses. QuGrid closes that gap with three layers, each honest about what it does:

1. Power problems speak engineering units. UnitCommitment, Islanding, PMUPlacement, EconomicDispatchQUBO, dc_power_flow, N-1 screening_dataset, wind scenarios — built on a Network class that keeps MATPOWER column semantics, loads MATPOWER .m files directly, converts from pandapower, and bundles seven standard test cases (PJM 5-bus to IEEE 118-bus).
2. Encodings are exact, tested algebra: QUBO ⇄ Ising with pinned conventions, a QUBOBuilder with exact squared-penalty expansion for your own formulations, LinearSystemProblem with power-of-two padding and Hermitian dilation. The test suite enforces all of it at 1e-9.
3. Solvers run on a pure-NumPy statevector core — QAOA, VQE, HHL, VQLS, fidelity quantum kernels, a quantum Boltzmann machine — with zero quantum SDK dependencies, next to the classical baselines every claim must face: exact enumeration, seeded simulated annealing, LU, Newton–Raphson. The same problem objects export to Qiskit, D-Wave Ocean, and PennyLane when you want vendor stacks or hardware.

Every solver returns the same Result: the decoded engineering answer, feasibility of the original constraints (not the penalty proxy), the gap() to a classical reference computed in the same run, the success probability even an ideal noise-free device would face, and the resource bill.

Sixty seconds of evidence

Controlled islanding of the WSCC 9-bus system. The exact QUBO optimum opens 2 lines and leaves island imbalances of +10.3 / −5.0 MW; QAOA at depth 2 finds the same plan:

HHL on DC power flow, with the two numbers most papers do not print together — the error and what each digit of precision costs in postselection probability:

Numbers from the self-validating example scripts (each script asserts its own claims and exits nonzero if one stops holding):

Install

pip install qugrid          # core: NumPy, SciPy, matplotlib, pandas — no quantum SDK
pip install "qugrid[all]"   # + qiskit, dwave, pennylane, pandapower adapters
qugrid demo                 # 30-second end-to-end check

Choose your on-ramp

Five executed notebooks take you from zero quantum knowledge to running your own studies — notebooks/01_hello_qugrid (15 min) through 05_qml_for_screening (30 min), markdown-heavy, every term defined in power system vocabulary first. The learning paths page sequences them for each background.

The example zoo

Ten single-file studies in examples/, in the spirit of CleanRL: self-contained, seeded, finished in minutes on a laptop, self-validating, each with its classical baseline in the same file. Copy one, swap in your case file, and you have the skeleton of a paper's experiment section.

The honesty box

No quantum device today beats tuned classical solvers on any power system problem, and this library will never imply otherwise. DC power flow is solved by sparse LU in microseconds; national-scale unit commitment is solved by MIP nightly. What QuGrid makes easy is the research that is real in 2026: encoding costs, error anatomy, resource scaling, algorithm behavior under discretization — always with the classical baseline in the same table. The honest benchmarking guide is the six-rule version of this paragraph; the API enforces most of it by default.

Positioning

• Qiskit Optimization, OpenQAOA, D-Wave Ocean operate on abstract optimization models with no grid semantics. QuGrid owns what happens before (credible grid formulations, documented penalty weights, discretization accounting) and after (decoding to MW, feasibility of the real constraints, field-standard baselines) — and exports to all three in one call.
• MATPOWER and pandapower stay the source of truth for grid data and classical power flow; QuGrid consumes their formats rather than replacing them.
• CleanRL and Tianshou inspired the shape: a small tested core plus single-file, self-validating research scripts.

Citing

If QuGrid supports your research, cite it via CITATION.cff (GitHub's "Cite this repository" button) — and cite the algorithm papers referenced in each solver's docstring; HHL, QAOA, VQLS, and the quantum power flow literature are their authors' contributions, not this library's.

Contributing

The highest-value contribution is a problem formulation from your own research: one file, one test, and every solver, benchmark, and plot in the library applies to it automatically. See CONTRIBUTING.md and the formulation proposal template.

License

MIT. Bundled test case data derives from MATPOWER test cases (BSD 3-clause).