Skip to content

10-minute quickstart

Install

pip install qugrid  # core: NumPy, SciPy, matplotlib, pandas — no quantum SDK

Or with uv: uv add qugrid. Optional stacks come as extras: qugrid[qiskit], qugrid[dwave], qugrid[pennylane], qugrid[pandapower], or qugrid[all].

Check the install:

qugrid doctor

Solve your first problem — three lines

Controlled islanding of the WSCC 9-bus system: after a disturbance, split the grid into two self-sufficient islands, cutting as little capacity as possible while keeping generation and load balanced inside each island.

import qugrid as qg

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

solve() built a QUBO (one binary variable per bus), ran the QAOA algorithm on the built-in statevector simulator, decoded the best measured bitstring back into an islanding plan, and compared it against the exact optimum, which it computed by enumeration because the problem is small enough.

Read the result

result.decoded          # engineering answer: island sets, cut lines, MW imbalance
result.feasible         # original constraints satisfied?
result.gap()            # relative distance to the classical optimum (0.0 = optimal)
result.success_probability()  # chance one measurement returns the best state
result.resources        # qubits, runtime, optimizer iterations

Two habits this library will keep reinforcing: judge the decoded engineering answer, not the bitstring; and never report a quantum number without the classical reference that ships in the same Result.

See it

import matplotlib.pyplot as plt

qg.viz.use_style()
d = result.decoded
qg.viz.plot_network(qg.cases.case9(), islands=d["islands"], cut_edges=d["cut_lines"])
plt.savefig("islands.png", dpi=150, bbox_inches="tight")

Try the other solvers on the same problem

prob = qg.problems.Islanding(qg.cases.case9())
for s in ("exact", "sa", "qaoa"):
    r = qg.solve(prob, solver=s, seed=0)
    print(f"{s:6s} objective={r.objective:10.3f} gap={r.gap():.2e} feasible={r.feasible}")

Same problem object, three solvers, one comparison — that is the library's core loop.

Or run everything at once

qugrid demo --save islands.png

Next