Static and Transient Electric Power Systems Simulation
STEPSS is a power system simulation platform for dynamic studies of electrical grids. It is delivered in two editions, which drive the same engines and read the same data files:
| Edition | Distributed as | Use it for |
|---|---|---|
| STEPSS for Java, this repository | stepss.jar, a desktop application |
Interactive work: load a network, run it, plot curves, build models |
| STEPSS for Python | the stepss package, pip install stepss |
Scripting, parameter sweeps, and the scientific Python stack |
Neither edition wraps the other, and a case built in one runs unchanged in the other.
This one is a Java (Swing) desktop application. It bundles the complete simulation toolchain (RAMSES, Helios, CODEGEN, DYNGRAPH) into a single jar, so a network can be loaded, simulated statically and dynamically, and analysed without touching the command line. CODEGEN makes this the edition for building your own models: it is the one component the Python edition does not carry.
- Complete workflow in tabs: System Data, Observables, Power Flow Simulation, Dynamic Simulation, Analysis, and Codegen
- Bundled examples: File → Open Examples extracts a ready-to-run test system (Kundur two-area, IEEE Nordic, or the 5-bus tutorial) into your examples directory and fills in the case, so there is something to run on a fresh install
- Dynamic simulation: runs the bundled RAMSES engine on the loaded data and disturbance files
- Power flow: drives the bundled Helios power-flow engine
- Real-time plotting: fill in a run-time observable and a curve window opens with the run and follows the engine as it writes, one stacked panel per observable (bus voltages, machine speeds, branch flows, latency, phase-plane trajectories, wall time against simulation time, and more). It stops when the run does and stays open as a static chart, so two runs can be compared side by side. Zoom by dragging a box, reset from the toolbar, and save as PNG or CSV: that export is the route out for the phase-plane and latency observables, which exist only during a run and have no Extract Curves equivalent. Drawn by STEPSS itself: no external plotting program is needed or bundled
- Result extraction: Extract Curves drives the bundled DYNGRAPH over a saved trajectory and draws the result in a curve window of its own, one per extraction, so two extractions can be put side by side and compared. Zoom by dragging a box, reset with a double-click, and save the figure as PNG, SVG or CSV. Save gnuplot pair keeps that window's own
.curand.plt, which STEPSS writes but never reads, for plotting in gnuplot - Analysis tools: Jacobian matrix extraction, and small-signal stability analysis computed by the engine itself (see
examples/kundur-ssa/) - User models: the Codegen tab generates user-written model source with CODEGEN and compiles it into a custom simulator with gfortran
- Observable wizard: dialog for selecting buses, machines, shunts, branches, and injectors to record
- Integrated editing: opens data and disturbance files in the operating system's default editor
- Built-in help: online user guide, release notes, and update checker
- Light and dark themes: toggled from Tools → Dark theme, remembered between sessions, and applied to the title bar as well as the window; the window icon and the About lockup come in the variant that matches
- Cross-platform: Windows, Linux, and macOS (Apple Silicon), with menu shortcuts on each platform's own modifier
Requirements: 64-bit Java 11 or later (JRE to run, JDK to build), Apache Ant to build. Windows and Linux are x86_64; macOS is Apple Silicon (arm64) only, Intel Macs are not supported.
The prebuilt jar is published as a release artifact on the releases page, not committed to this repository: build/ and dist/ are untracked. Download it there if you just want to run STEPSS.
git clone https://github.com/SPS-L/stepss-java-ui.git
cd stepss-java-ui
ant jarThe build (a NetBeans/Ant project) produces dist/stepss.jar, a self-contained jar with the Commons Exec, Commons IO, FlatLaf and Batik libraries merged in (Batik brings xmlgraphics-commons and xml-apis-ext with it).
Building fetches the pinned RAMSES, Helios, DYNGRAPH, and CODEGEN binaries for all three platforms (ant fetch-payloads, run automatically as part of ant jar) from their releases in the SPS-L GitHub organisation. Those component repositories are private, so the first build needs network access and the gh CLI authenticated with SPS-L access (gh auth login); downloaded archives are checksum-verified against versions.properties and cached in payload-cache/, so later builds only need network again when a pinned version changes. CI authenticates the same way, through this repository's STEPSS_TOKEN secret, because Actions' default GITHUB_TOKEN is scoped to this repo alone and cannot reach the component repos.
It also fetches the pinned URAMSES kit and the three bundled example test systems (ant fetch-uramses, ant fetch-examples). Those repositories are public, so they come over plain HTTPS and need neither gh nor a token. Each is verified against a content manifest rather than the archive's own digest, because GitHub's generated source archives are not guaranteed byte-stable; the examples are additionally filtered down to the files src/my/stepss/examples/examples.properties names, and the build fails if a pinned release stops carrying one of them.
On macOS, the current RAMSES, DYNGRAPH, and CODEGEN builds are dynamically linked against gfortran and OpenBLAS; install them first with brew install gcc openblas. Statically linked builds that drop this requirement are expected from those projects.
Compiling custom models is optional and needs a Fortran toolchain on your machine: gfortran, GNU make, and OpenBLAS. On Debian/Ubuntu that is sudo apt install gfortran make libopenblas-dev; on macOS brew install gcc openblas; on Windows install MSYS2 and run pacman -S mingw-w64-x86_64-gcc-fortran mingw-w64-x86_64-openblas make (STEPSS looks in C:\msys64, or wherever MSYS2_ROOT points). The bundled module kits are gfortran-ABI-specific and each platform's default compiler matches its own kit; if yours does not, STEPSS reports the exact compiler version to install. Everything else in STEPSS works without any of this.
The window icon and the About lockup are PNGs in src/my/stepss/, rendered from the SVG sources in stepss-docs src/assets, in a light and a dark variant each. They are stored rasterised so that nothing renders vectors while the window is being built; the cost is that they go stale when the artwork changes, and the build does not notice. This used to buy something further, that no SVG library shipped at all, which stopped being true when Batik arrived to draw the one-line diagram. Re-export all fourteen with:
tools/refresh-marks.sh # expects ../stepss-docs/src/assets
tools/refresh-marks.sh /path/to/src/assets # or say where they areIt needs Inkscape, and that is not interchangeable with ImageMagick: convert -resize rasterises an SVG at the size the document declares and then scales the raster, which for the 295x100 lockup produces a visibly blurry enlargement. Inkscape rasterises the vectors at the size asked for. tools/chrome-harness.sh confirms every mark still resolves afterwards.
ant jar produces a jar you run with java -jar. ant bundle wraps that jar in a launcher, an icon and a Java runtime, so STEPSS installs and starts like an application and the machine it runs on needs no Java of its own:
ant bundle # the platform's installer: .deb, .msi or .dmg
ant bundle -Dbundle.type="--type app-image" # just the unpacked application directoryIt needs jpackage, which ships with JDK 14 and later, and it only ever builds for the platform it runs on. The three installers on a release therefore come from three CI runners rather than from one machine. The icon is packaging/stepss.png on Linux and packaging/stepss.ico on Windows, both rendered from the same stepss-docs source as the in-application marks; macOS needs a real .icns container, which only iconutil produces, so the release workflow builds one on the macOS runner and it is not committed.
The bundles are a second CI job, and nothing is published until all three of them finish. The release job creates the release as a draft, which creates no tag and is invisible to users; each runner attaches its installer to that draft; a final job publishes it and tells the two package managers. One runner failing means the draft is discarded and the run goes red, so there is no tag, no release and no partial set of installers, and re-running reuses the same version number. It used to publish first and attach afterwards, on the reasoning that a release carrying stepss.jar alone still beat no release; v3.74.17 is why it no longer does, having gone out with the Windows artifacts and neither the .deb nor the .dmg while apt went on serving the previous version.
The Linux .deb is the one bundle an archive serves rather than a person downloads, so packaging/linux overrides six of jpackage's own templates. What that buys, beyond the desktop menu entry: the RAMSES runtime libraries are declared as dependencies, the Fortran toolchain is a Recommends:, /usr/bin/stepss is a command you can type, and /usr/share/doc/stepss/copyright names each bundled component and the licence it travels under. jpackage can derive none of that, because it reads dependencies off the app image and the whole simulation toolchain is inside the jar as resources it extracts at run time.
tools/deb-harness.sh # install the built .deb in a clean containerIt needs Docker. Two failures are invisible without one: this machine has libgfortran and OpenBLAS installed for other reasons, and it has a desktop, so xdg-desktop-menu succeeds here and exits 3 on the servers, containers and WSL installs where users meet it. The harness installs the package for real, checks that ramses starts, and removes it again. It runs in CI before the .deb is attached to the draft, and the package is built on Ubuntu 24.04, which is therefore the oldest release it installs on.
The bundled runtime is the full JDK runtime rather than a trimmed jlink image. STEPSS extracts and runs native executables through Commons Exec, so what a module scan can see and what the application actually needs are different questions, and roughly 40MB is a fair price for removing a class of failure where the bundle starts and then cannot find a class.
Releases are cut automatically. RAMSES, Helios, DYNGRAPH and CODEGEN dispatch to this repository when they publish, and the run re-pins versions.properties and the matching resource names in Toolchain.java, rebuilds, verifies that the bundled toolchain extracts correctly, and drafts a release with stepss.jar attached for the bundle job to fill in and publish. (URAMSES does not dispatch: it only ever releases in response to a RAMSES release under the same tag, and the RAMSES dispatch covers both.) The notes list every component's pinned version, and embed the upstream release notes of the components that actually moved, since four of the five component repos are private and cannot be linked to usefully.
The bundled example test systems are re-pinned by the same run, but they never trigger one: they are reported as refreshed rather than changed, and only changed decides whether to publish. An example repository being tagged is not a reason to publish a new STEPSS, so a refreshed example rides along with the next release instead.
STEPSS checks for a newer release when it starts and says so on the banner across the top of the window, with a link to the release page. It never blocks startup on that check and says nothing when it cannot reach github.com. Turn it off under Tools → Check for updates at startup.
Nothing is published until the build and the toolchain check have both passed. The commit that re-pins the build is pushed immediately before the draft is created, and because a draft carries no tag (see Native installers for why the release is drafted rather than published outright), a run that fails leaves no tag and no release behind, and re-running it publishes under the same version number. Any failure opens an issue.
Release numbers follow the pinned RAMSES version, with a counter for releases driven by the other components: v3.55, then v3.55.1, v3.55.2, and so on until RAMSES itself moves.
Running the workflow by hand (Actions → Release → Run workflow) also picks up any new component releases first, then publishes regardless: that is how a change to the Java sources alone reaches a release.
To re-pin locally instead, run python3 -m tools.ci bump from the repository root (add --dry-run to see what would change without downloading or writing anything). It rewrites versions.properties and Toolchain.java together; editing only the former leaves the build naming the old asset, which ant jar catches.
java -jar dist/stepss.jarThen, in the GUI:
- Load the System data files (
.dat) in the System Data tab - Load the Disturbance file (
.dst) - Optionally, name a one-line diagram template (
.svg) in the same System Data tab: it carries placeholder codes, and every Run Power Flow fills them in with the solved values and opens the result in a window of its own (placeholder table in the user guide) - Select observables to record (Observables tab or the Observable dialog)
- Run the simulation from the Dynamic Simulation tab
- Plot results with Extract Curves, which opens a curve window of its own, or watch the run-time curves in the window that opens with the run
Run-time curves need a RAMSES release that writes a column map into the header of its observable file. Against an engine that does not, the window says so rather than drawing. Extract Curves is independent of this: it reads DYNGRAPH's output, which carries no header.
The jar embeds the toolchain executables for the platform it runs on and extracts them at runtime. RAMSES, Helios, DYNGRAPH, and CODEGEN are fetched from their pinned SPS-L releases at build time (see Installation) on all three platforms. Every toolchain payload now arrives that way: none is committed to this repository. The only binaries tracked here are the application's own icons and marks, and the third-party jars under lib/.
| Tool | Role | Windows | Linux | macOS (Apple Silicon) |
|---|---|---|---|---|
RAMSES (dynsim) |
Dynamic simulation | yes | yes | yes |
| Helios | Power flow | yes | yes | yes |
| DYNGRAPH | Curve extraction | yes | yes | yes |
| CODEGEN | Model generation | yes | yes | yes |
| Model compilation | Custom models | yes (MSYS2/MinGW) | yes (gfortran) | yes (Homebrew gcc) |
| Data file editing | OS default editor | yes | yes | yes |
DYNGRAPH is the same console program on all three platforms, and Extract Curves drives it without a terminal window: STEPSS reads the trajectory's observables with dyngraph --list, presents them in a selection dialog, drives the extraction through a generated command file (-t), and then draws the extracted curves itself. Running DYNGRAPH by hand, outside STEPSS, gives the console prompts.
The bundled RAMSES runs limited (up to 1000 buses, 2 cores) unless a LICENSE record is supplied among the data files. There is only one engine build; the limit is lifted by the licence the engine itself reads, not by a different binary, so STEPSS cannot tell which of the two you are running and does not claim to. The engine's own banner in the simulation output reports it.
On first run STEPSS shows the RAMSES licence and asks you to accept it. Declining exits.
In addition, the application distributes the following third-party Java libraries (merged into stepss.jar and shipped in dist/lib/), all under the Apache License 2.0: Apache Commons Exec, Apache Commons IO, FlatLaf, and Batik with its own dependencies xmlgraphics-commons and xml-apis-ext. FlatLaf is the look and feel; it renders the same on all three platforms, scales on HiDPI, and provides the dark theme offered under Tools → Dark theme. Because it is a multi-release jar, manifest.mf declares Multi-Release: true. Batik rasterises the annotated one-line diagram that every power flow run produces.
- STEPSS for Python: the
stepsspackage, Python interface for RAMSES - URAMSES: user models for stepss
- Installation guide: GUI and Java setup
- Quick start: running simulations from the GUI
- STEPSS documentation site: user guide, file formats, model reference
- In-app: Help → User Guide (opens stepss.sps-lab.org) and Help → Changelog (opens this repository's releases)
The Java source in this repository is under the Apache License 2.0. See LICENSE. Copyright © Petros Aristidou.
STEPSS taken as a whole is not, and should never be described that way: it is an umbrella over components under different licences, and the engines it bundles are not Apache 2.0.
| Component | Terms |
|---|---|
| This Java interface, and DYNGRAPH | Apache License 2.0 |
| RAMSES | Property of the University of Liège. Proprietary, free for non-commercial use only, and the free version is capped at 1000 buses and 2 cores |
| Helios, CODEGEN | Academic Public Licence: free for academic, research and educational use, commercial use by separate agreement |
| Bundled third-party libraries | Their own terms: KLU, Batik, Apache Commons Exec/IO, FlatLaf |
The authoritative statement of what governs what is the licence page. The table above is a summary of it and must not grow into a second copy. The licence text of each bundled component is embedded in the application and viewable from the About dialog.
Developed and maintained by the Sustainable Power Systems Laboratory (SPS-L) at the Cyprus University of Technology, under the direction of Dr. Petros Aristidou.
STEPSS was created by Dr. Petros Aristidou and Dr. Thierry Van Cutsem.