gridtwin.
Public repository
Interactive 3D substation in the browser with small transmission network digital twin. Open a circuit breaker on the single-line diagram or 3D substation and see an AC power flow redistribute the load, overload a line and, if you keep going, cascade into an outage.
Implementation of an educational model for the public IEEE 14-bus and IEEE 30-bus test cases which models a substation (replacing bus 4) as made up. Nothing here describes a real grid.
Opening the bus coupler, the overloaded line, the N-1 table and a cascade replay.
My home server currently has the demo running in a single container. It uses in-memory sessions and restarts once an hour. Whatever you switched will be lost upon restart. Recording from the repository, no sound.
Why I built it.
I work on software that renders single-line diagrams for high-voltage substations in the browser using Angular and diagram rendering. The underpinning technology is Quarkus on Java 21. I have developed the other half of this to model the electrical behaviour of these diagrams. Given an open breaker the solver can indicate which lines overload, how an outage spreads and where power goes.
I've also combined my domain knowledge, numerical methods (a sparse Newton-Raphson solver checked against MATPOWER), a Java back end and a 3D front end into a single project.
Try it in the demo.
Every visitor gets a twin of their own, so nobody opens a breaker under your hands.
- Bus coupler
- Open the bus coupler in the single-line diagram. Arrow keys move between equipment, and Enter or Space asks to operate a switch.
- Overloaded line
- Click on the line that turns red. The line state (loading, active power, reactive power, current and losses) is displayed by the inspector and also in the 3D substation.
- System load
- Drag the slider from 50 to 150 percent. All loads scale together and the slack absorbs the change.
- N-1
- Run N-1 and click a row of the table to preview that outage, without solving the network again.
- Cascade
- Run the cascade from the outage of line L2-4 and drag the scrubber to step through it.
- Interlocks
- Try to close an earthing switch on a live section. The interlock refuses and says why.
Three hard parts.
Each decision has its ADR in the repository, with the alternatives that lost.
Agreeing with MATPOWER.
The solver has to agree with MATPOWER to 1e-6 pu in voltage and 1e-4 degrees in angle. However, small modelling differences already break that. For example, where the tap sits on a transformer, whether reactive limits convert all violating generators at once, whether the slack generator is limited. I documented each of these conventions in an ADR and adopted MATPOWER’s. I created 4 N-1 reference files and 16 base case reference solutions using MATPOWER under GNU Octave in Docker.
The cost: reactive limits do not release again. A generator that hit its limit at 150% load stays a PQ bus for that solve.
Lost were a rectangular formulation (due to the solver being specified in polar form) and a distributed slack placed closer to operational practice and away from the reference data.
ADR 0004 on GitHubN-1 on a fork-join pool.
N-1 on IEEE 30 involves about 47 independent solves with no I/O, pure CPU computation. These are executed on a dedicated ForkJoinPool with one worker per core. Each task has its own solver with no data shared across other tasks except for read-only access. A property test verifies that the parallel execution produces the same result as sequential execution.
The cost: the application layer owns the pool’s lifecycle, from startup to shutdown.
Lost: virtual threads. A computing thread keeps its carrier busy like a platform thread and provides no additional throughput. Also parallelStream on the common pool, because a long N-1 run can starve the rest of the Quarkus process.
ADR 0009 on GitHubOne twin per session.
Every visitor gets a session of their own. A REST command is issued, the interlocks are run first, the network is solved once and the version incremented. The full state is sent over a WebSocket. Clients will ignore messages where the version is the same as or less than the current version they already have.
The cost: the server holds the state of every open session, up to a cap, and a restart drops them all.
What was lost: one shared twin (one visitor would open a breaker under another's hands and parallel end-to-end tests would interfere), and pushing diffs, since the state of these networks is a few kilobytes and a full snapshot allows reconnecting clients to avoid replay logic entirely.
ADR 0010 on GitHub
Numbers.
Only what the scripts in the repository measured.
- 8.23e-9 pu
- Among all scenarios tested, the worst deviation in voltage magnitude compared to MATPOWER 8.1 results from IEEE 14 and IEEE 30 systems at load factors 0.5, 1.0, 1.2 and 1.5 with and without reactive limits and all N-1 outages solved by MATPOWER. For the experiments the limit is 1e-6 pu.
- 0.67 ms
- Median IEEE 30 solve from a flat start, after 300 warm-up iterations and over 300 measured ones. Target: under 10 ms.
- 8.22 ms
- Median full N-1 on IEEE 30, 47 outages on 20 threads. 41.3 ms sequentially. Target: under 500 ms.
- 25.5 ms
- Median time from the confirm click to the rendered frame (including 3D scene and server round trip) on the integrated Iris Xe GPU running on Windows. Goal: below 100 ms.
- 165 fps
- The 3D scene under Windows on Iris Xe at 1080p with none of the 4,951 frames dropped at the panel refresh rate. The same GPU via WSL2 Direct3D 12 renders 46-52 fps so the 60 fps target is not achieved here.
- 99.0%
- Line coverage of the domain module, 97.5% overall. Plus 21 Cypress tests against the production jar and axe on six scenarios.
On laptop: Intel Core i7-12700H, 20 logical cores, 15 GB of memory. Linux 6.6 with WSL2. OpenJDK 21.0.12. Headless Chromium 148. GPU runs were repeated natively on Windows 11 using Chrome 154 on Iris Xe in the same laptop. There were other builds running concurrently which leads to some noise in the tails of the timing data.
The result files in bench/resultsWhat is not built.
When the scope grew, stretch goals were cut. Tests and correctness never were.
- IEEE 30 in the app
- IEEE 30 is solved, validated and benchmarked but lacks a substation and no UI entry. Therefore only IEEE 14 is offered in the demo.
- A fast decoupled power flow
- It would be a second solver to validate, and the current one is already fast enough for IEEE 30.
- State estimation
- Weighted least squares is not built. The time went to the validation against MATPOWER, the interlocks, the islands and keyboard operation of the diagram.
- Dynamics
- It is a steady-state, balanced model: no dynamics, no short-circuit calculations and no synchronism check when two live islands are joined.
- A real cascade
- A branch is tripped as soon as it exceeds 120% of its rating with no protection timing. A cascade will indicate the possible sequence of overload propagations but will predict nothing about a real grid.
- Keyboard in the 3D scene
- Equipment cannot be operated by keyboard inside the 3D canvas. Everything works in the diagram and the inspector.
What comes next.
First, a second substation for IEEE 30 with a network selector. Then the fast decoupled solver will be demonstrated with a comparison of speed and accuracy. Finally state estimation using noisy measurements will be shown.
ADR 0027: the stretch goals I did not buildTech
- Angular
- TypeScript
- RxJS
- SignalStore
- Three.js
- WebGL
- Java
- Quarkus
- REST API
- WebSockets
- Docker
- Cypress
- GitHub Actions
- Hexagonal architecture
Let's talk about the role.
Tell me about the team, the product and the stack.