Skip to content

About

Power-system analysis in Julia: AC power flow, IEC 60909 short circuit, N-1 contingency, Scenarios (n-2), WLS state estimation, CGMES and MATPOWER round-trip.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

17 stars

Watchers

0 watching

Forks

Sparlectra.jl

Power-system analysis in Julia: AC and DC power flow, quasi-static time series, WLS state estimation with tap estimation, IEC 60909 short circuit, scenarios and N-1 contingency; import of CGMES, MATPOWER, PowSyBl IIDM, DTF and SCF, export of CGMES, MATPOWER and SCF.

Documentation Version License: Apache-2.0 Julia SBOM: SPDX

Nothing in Sparlectra is a black box: model construction, Jacobian assembly, PV/PQ switching and convergence are visible at runtime. Besides the rectangular Newton-Raphson solver there is a DC power flow and the analytic APSLF backend (AnalyticLoadFlow.jl). Runs are deterministic, configuration-driven and machine-readable. Suited for grid studies, solver development and teaching.

The full capability list is in the feature matrix.


Workshops

The workshop notebooks run in Jupyter or VS Code. The Web UI installer has a workshop mode (--workshops): one command installs Julia (if missing), Sparlectra, IJulia and the notebooks into ~/sparlectra-workshops and starts Jupyter.

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/Welthulk/Sparlectra.jl/main/tools/install_webui.sh | sh -s -- --workshops

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Welthulk/Sparlectra.jl/main/tools/install_webui.bat -OutFile install_webui.bat; .\install_webui.bat --workshops

Options: --dir <folder> for another folder, --rev <branch> for Sparlectra from a branch instead of the registered release, --no-start to set up only. Without a Jupyter installation IJulia offers to install one. In VS Code, open the folder and select the kernel "Sparlectra workshops ( )": every workshop folder gets its own kernel, named after the folder with a short hash of its path, and the installer prints the name. Running the command again updates Sparlectra and the notebooks; a notebook you changed is kept next to the new copy as <name>.ipynb.<date>-<time>.bak.

The Web UI itself has no workshop button. If you already have the Web UI (a copy from the one-line install or a git checkout), set up the workshops from its folder; --path . takes Sparlectra from that folder, so the notebooks match the version you run:

julia tools/install_workshops.jl --path .

On Windows: julia tools\install_workshops.jl --path .. The options above apply here as well.

Notebook File
Tour, basic: first network, model editing, Q-limits, slack types, OLTC and Q(U) control workshop_tour.ipynb
Tour, advanced: remote voltage control, HVDC link, state estimation, FACTS incl. UPFC, N-1, threaded sweeps workshop_tour_advanced.ipynb
Transformer control: parallel units, master/slave groups, CGMES RegulatingControl workshop_tour_control.ipynb
Foreign formats: CGMES (anatomy of a delivery, bus-branch and node-breaker import, SV validation, export round trip), PowSyBl IIDM compared with OpenLoadFlow, a DTF deck with its outage records workshop_tour_cgmes.ipynb
Slack types and short circuit: ideal, external grid, distributed slack, IEC 60909-0 currents workshop_slack_short_circuit.ipynb
Distributed slack: participation weights, normalization, fallback workshop_distributed_slack.ipynb
Transformer taps: OLTC, PST, X(α) characteristic, 3WT star equivalent workshop_transformers.ipynb
FACTS flow control: TCSC to UPFC workshop_series_compensation.ipynb
Scenarios and N-1 screening workshop_scenarios.ipynb
QSTS: a day on sp_case14, snapshot run and sequential run with tap and bank controllers workshop_qsts.ipynb
State estimation: measurement sets, observability, WLS, bad data workshop_state_estimation.ipynb
SE bad data and parameter estimation: normalized residuals, sequential elimination, robust estimation, shunt estimation workshop_se_diagnostics.ipynb
SE taps, phasors and topology: J and its degrees of freedom, tap estimation, PMU phasors, topology errors, islands workshop_se_taps.ipynb
APSLF: analytic power-series solver on a Sparlectra model, convergence radius as a loadability margin, hybrid start workshop_apslf.ipynb

The notebooks are generated from docs/lit/ and are also part of the documentation.


Installation

Sparlectra is two packages in one repository: the library Sparlectra (registered) and the application SparlectraApp under app/ (service API, Web UI, sysimage build).

Library:

using Pkg
Pkg.add("Sparlectra")

Application (Web UI), from a checkout:

git clone https://github.com/Welthulk/Sparlectra.jl.git Sparlectra
cd Sparlectra
julia --project=. start_webui.jl

The first start installs and compiles and reports the time. Scripts that use the service API run with julia --project=app. Other REPL setups, sysimage use and embedding: integration guide.

Web UI: one-line install

Installs Julia if missing, downloads the latest tagged release into Sparlectra/ in the current directory, and starts the Web UI.

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/Welthulk/Sparlectra.jl/main/tools/install_webui.sh | sh

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Welthulk/Sparlectra.jl/main/tools/install_webui.bat -OutFile install_webui.bat; .\install_webui.bat

Important

This downloads and runs a script. If you prefer to read it first: install_webui.sh, install_webui.bat.

The installer offers a desktop shortcut; re-running it updates the copy. Options and unattended installs: Web UI. From a checkout, ./start_webui.sh or start_webui.bat starts the Web UI directly.

Julia compiles on first use; a sysimage removes that wait.

SBOM and download verification

Every release ships an SPDX SBOM and SHA256SUMS; Pkg.add verifies the registry tree hash. Details and security contact: SECURITY.md.


Quick start

run_sparlectra runs the whole chain: import, configuration, control loops, solve, report.

using Sparlectra

# ensure_casefile downloads case14.m if it is not present locally
case_path = ensure_casefile("case14.m")

result = run_sparlectra(
    casefile = basename(case_path),
    path = dirname(case_path),
)

println(result.outcome)
println(result.iterations)
println(result.final_mismatch)

A CGMES model: diagnose, import, solve, compare with the delivered SV profile. The example uses the CGMES demo files shipped with the package:

using Sparlectra

demo    = joinpath(pkgdir(Sparlectra), "data", "cgmes_demo", "sp_case14")
summary = summarizeCGMES(path = demo)
result  = importCGMES(path = demo)
runpf!(result.net, 30, 1e-8, 0)

cmp = compareWithSV(result)
@show cmp.max_dvm

For an ENTSO-E delivery of your own, path takes a folder, ZIP files or XML files, for example path = ["grid.zip", "boundary.zip"].

Embedding Sparlectra in your own tooling (scripts, sysimage, API): integration guide.


Local Web UI

Case management, run history and results in the browser. Cases can be taken from the local cache, uploaded (MATPOWER, DTF, CGMES ZIP, PowSyBl IIDM .xiidm) or fetched by name; three PowSyBl networks ship under data/powsybl. IIDM files are read in Julia, no Python is needed.

Sparlectra Web UI: case, settings, run and result

Every run file opens in the browser: CSV as a sortable table, Markdown rendered.

Sparlectra Web UI: CSV table, measurement verdict and Markdown report of a run

A QSTS run shows its controllers, switching counts and a time-series chart per element.

Sparlectra Web UI: QSTS run with time-series chart


Documentation

Full documentation: https://welthulk.github.io/Sparlectra.jl/


Contributing

Bug reports, test networks and import edge cases (CGMES, MATPOWER, DTF, PowSyBl IIDM) are welcome. Questions: Discussions. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md first.

Sponsors

SOPTIM AG

The development of Sparlectra.jl is supported by SOPTIM AG, Aachen, Germany.

Citing

@software{sparlectra_jl,
  title  = {Sparlectra.jl: A Power-Flow and State-Estimation Framework in Julia},
  author = {Schmitz, Udo},
  year   = {2026},
  url    = {https://github.com/Welthulk/Sparlectra.jl}
}

License

Apache License 2.0, see LICENSE.

About

Power-system analysis in Julia: AC power flow, IEC 60909 short circuit, N-1 contingency, Scenarios (n-2), WLS state estimation, CGMES and MATPOWER round-trip.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

17 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages