[ANN] Sparlectra.jl v0.8.2 – transparent AC power-flow and state estimation

Package Announcements
, , ,
1

[ANN] Sparlectra.jl – transparent AC power-flow and state estimation in Julia

Hi everyone,

I’d like to announce Sparlectra.jl, a Julia package for transparent power-system calculations, now at v0.8.2.

I originally developed Sparlectra to better understand power-system calculation methods by implementing them myself instead of only using black-box tools. Today I also use it for training and educational purposes, where it is useful to inspect the numerical steps, model assumptions, and solver diagnostics in detail.

Sparlectra is built around its own network and component model. Networks can be created directly in Julia by adding buses, lines, transformers, shunts, generators, loads, and controllers. MATPOWER support is included as a practical import and validation path: the format is simple, widely used, and provides useful reference cases for evaluating the implementation. It is not a dependency for building or studying networks with Sparlectra.

At the same time, Sparlectra is not limited to toy examples. The current implementation is sparse-matrix-oriented and is intended for both small educational grids and larger network studies.

What it does

Sparlectra focuses on inspectable algorithms rather than black-box solver behavior. The core is a rectangular complex-state Newton-Raphson AC power flow with explicit PV/PQ handling, Q-limit diagnostics, wrong-branch diagnostics, and sparse-matrix-oriented linear algebra. It also includes a nonlinear WLS state-estimation workflow.

Key capabilities:

  • Native network construction in Julia using Sparlectra’s own Net and component model
  • Rectangular Newton-Raphson AC power flow
  • PV/PQ bus switching with Q-limit and active-set diagnostics
  • Wrong-branch and convergence diagnostics for rectangular power-flow solutions
  • Optional MATPOWER case import for simple data exchange, reference cases, and validation
  • On-demand helpers for common MATPOWER test cases
  • π-equivalent branch models for lines, two-winding transformers, and three-winding transformers
  • Transformer tap and voltage-control experiments
  • Experimental nonlinear WLS state estimation with measurement helpers and residual inspection
  • PFModel / PFSolution interface for external solver integration

Current direction

There are several active and planned extensions. Some of the more interesting directions are optimization-oriented workflows, additional power-electronic network elements, and a cleaner framework-level entry point for studies and experiments.

The code base is also being refactored to separate the high-level workflow, import paths, solver execution, diagnostics, and output handling more clearly. The goal is to keep the package useful for learning and teaching while making it easier to extend for larger and more advanced grid studies.

Quick start

using Pkg
Pkg.add("Sparlectra")

using Sparlectra

status = Ref{Any}()

net = run_acpflow(;
    casefile = "case14.m",
    max_ite = 10,
    tol = 1e-6,
    verbose = 0,
    show_results = true,
    status_ref = status,
)

if hasproperty(status[], :outcome) && status[].outcome != :converged
    @warn "AC power flow did not converge" iterations = status[].iterations outcome = status[].outcome reason = status[].reason_text
end

This quick-start example uses a small MATPOWER reference case because it is easy to reproduce. The same solver can also be used with networks constructed directly in Julia using Sparlectra’s own network model.

Who is it for?

Sparlectra is intended for engineers, researchers, and students who want to understand, test, or extend Newton-Raphson power-flow and state-estimation algorithms without the numerical core being hidden. It can be used for education and training, but also for engineering-oriented experiments on larger networks.

The current focus is on solver mechanics, diagnostics, reproducibility, and transparent experimentation. Optimization workflows and additional network elements are part of the current development direction.

The package is still evolving, and some parts are intentionally experimental. Feedback is especially useful for larger test networks, transformer/tap-control behavior, power-electronic component models, state-estimation workflows, and import edge cases from simple exchange formats such as MATPOWER.

Feedback, bug reports, and contributions are very welcome.

Registered in the Julia General registry. Apache-2.0 license.

4 Likes