I built GridLens: a power system study tool that finds the outage your base-case load flow misses

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

GridLens is a browser-based power system analysis tool. You enter a grid as two editable tables (bus data and line data) or upload a CSV. One click on Solve runs a full study suite and shows the results in tabs:

Tab	What it does
Load flow	Bus voltages, angles and injections, per-line P/Q flows and losses, a voltage profile checked against 0.95 / 1.10 pu limits, and a Newton-Raphson convergence plot
Network diagram	The grid drawn as a graph. Bus voltages are labelled, line thickness scales with MW flow, and arrows show power direction
Method comparison	The same case run through Newton-Raphson, Fast Decoupled and Gauss-Seidel
N-1 contingency	Every line is removed in turn, the case is re-solved, and outages are ranked worst first
Export	CSVs of bus results, line flows, N-1 results and the fault table, a figures.zip PNG bundle, and the current input tables

A short-circuit study and an AI-written report (a local open-weight model summarises the results in plain English) sit alongside these, and each can be toggled on or off in the sidebar. A summary strip under the Solve button shows convergence status, slack power, total generation and load, losses (as MW and % of load), and min/max voltage with the bus where each occurs. A red N-1 violations badge appears when a contingency breaks limits.

Inputs are plain per-unit tables.

• Bus table: Type (Slack / PV / PQ), V setpoint or start guess, Pg, Qg, Pd, Qd.
• Line table: From, To, R, X and total line-charging B, split B/2 at each end.

Other features: Quick / Standard / Advanced modes, a preset case dropdown, downloadable CSV templates, a dark theme, and a help tooltip on every control.

Who would pay: small power consultancies, solar and microgrid installers, and industrial plant engineers who need quick feasibility and contingency checks but can't justify a commercial license. University power-systems labs are a second market.

Problem it solves: commercial tools are expensive and heavy. Free scripts give you matrices and no interpretation. GridLens gives you the solve, the safety check and the explanation in one place.

A result that shows why N-1 matters

On the built-in 5-bus demo, the base case looks healthy: it converges, min voltage is 1.011 pu at bus 5, and losses are 4.6 MW (2.8% of the 165 MW load). But the N-1 study shows that losing line 2-5 drops bus 5 to 0.8975 pu, well below the 0.95 limit. It's the only outage that causes a violation, and a base-case solve alone would never show it.

The ranking also separates two kinds of "worst". Losing line 1-2 causes no voltage violation, but losses jump to 0.1667 pu (16.7 MW), about 3.6 times the base case. GridLens shows both views, so you can tell which outages threaten voltage and which are just expensive to run.

Demo

📹 Watch the GridLens demo

Walkthrough of the 5-bus demo case (base 100 MVA):

1. Setup: bus 1 is the slack at 1.06 pu, bus 2 is a PV bus at 1.04 pu with 0.4 pu generation and 0.2 + j0.1 pu load, and buses 3, 4 and 5 are PQ load buses (0.45, 0.40 and 0.60 pu real power). There are 7 lines.
2. Solve: Newton-Raphson converges in 3 iterations at tol 1e-8. The slack supplies 129.6 MW, bus 2 supplies 40 MW, total generation is 169.6 MW against 165.0 MW of load, so losses are 4.6 MW.
3. Bus results: voltage falls smoothly from 1.060 pu at bus 1 to 1.011 pu at bus 5, with the angle reaching −6.09° at bus 5.
4. Line flows: the heaviest corridor is 1→2 at about 89 MW, followed by 2→5 at 55 MW. Both ends of every line are reported, so you can see the loss per line.
5. Convergence: the max mismatch drops below 1e-8 in three steps, the quadratic convergence Newton-Raphson should show.
6. Network diagram: bus voltages on the nodes, MW flows on the lines, and arrows showing direction. Line 4-5 carries only 6 MW, because that part of the grid is nearly balanced.
7. Method comparison: all three solvers land on the same answer.

Method	Converged	Iterations	Loss (MW)	Min V (pu)
Newton-Raphson	✅	3	4.6289	1.0107
Fast Decoupled	✅	7	4.6289	1.0107
Gauss-Seidel	✅	43	4.6287	1.0107

Gauss-Seidel needs 43 iterations to NR's 3. Its loss differs in the fourth decimal because it uses its own, looser default tolerance.

1. N-1: the ranked outage table described above.
2. Export: every table and figure can be downloaded for reports.

Code

haki-overflow / GridLens

CAPSA — Power System Analysis

A Python tool that solves an N-bus power system and turns the results into something readable: load flow by three classical methods, an N-1 contingency sweep, a three-phase fault study, and plots plus a plain-English summary. It was built for Hacktoberfest and uses only open-source libraries and open-weight models: the solver does every calculation, and a local Gemma model served by LM Studio only explains the numbers it is given.

Features

• Three load flow methods: Newton-Raphson, Fast Decoupled (XB), Gauss-Seidel.
• Two editable presets: 5-bus demo and IEEE 14-bus.
• N-1 contingency sweep: each line removed in turn, case re-solved, ranked worst-first.
• Three-phase fault analysis at every bus via the Zbus matrix.
• Network diagram coloured by bus voltage, plus voltage-profile and post-fault charts.
• Method comparison table (convergence, iterations, loss, minimum voltage).
• Optional report written by a local Gemma model via LM Studio, given only the solver's numbers.

…

View on GitHub

How I Built It

App layer: Python and Streamlit. The bus and line tables are editable data grids, so users can change a load or a line impedance and re-solve immediately.

Numerics: the three load-flow methods are implemented from scratch: Newton-Raphson, Fast Decoupled and Gauss-Seidel. Each one reports convergence status and iteration count, so the method comparison is honest. The N-1 study re-runs the Newton-Raphson solver once per line outage and ranks the results by number of violations, then by minimum voltage. The short-circuit module produces the fault table.

Plots: Matplotlib for the voltage profile with limit lines, the log-scale convergence history, and the flow-weighted network diagram. All figures can be bundled into a zip.

Open-source AI: the report is written by Gemma running locally through LM Studio. After a solve, GridLens passes the numerical results to the model (convergence, losses, voltage extremes, the N-1 ranking, the fault table), and the model writes an engineer-readable summary. The numbers come from the solvers and the model only does the explaining, so it can't invent results.

Dev workflow: built with opencode, with a project-context file so the agent kept the architecture in mind between sessions. The code is split into separate modules (solvers, contingency, short circuit, plotting, report) to keep it easy to debug.

Why Does Open Innovation Matter?

Network models are sensitive. Utilities and industrial plants usually can't send grid topology and load data to a third-party API. Because the report model is open-weight and runs locally, the AI feature works on confidential data, offline, with no per-token cost.

A closed API would have blocked the people most likely to pay: the privacy problem rules out the customers, and per-call pricing makes a cheap side-hustle tier hard to offer. With open weights, anyone can also swap in a different model or adapt one to their own reporting style, without waiting for a vendor.

The same idea applies to the solvers: the code is open, so an engineer can read exactly how Newton-Raphson and the contingency ranking are computed and verify it against a textbook. That matters in a field where you have to trust the numbers.