stepss 3.70

What this edition bundles

pip install stepss is self-contained: no separate solver installation, no compiler, no licence server.

• RAMSES (RApid Multithreaded Simulation of Electric power Systems), the dynamic simulator. It simulates the evolution of a power system under the phasor approximation, using Backward Euler, Trapezoidal or BDF2 integration with OpenMP parallelism.

• Helios, the AC power-flow engine, solving by Newton-Raphson in polar coordinates. Exposed through the stepss.helios module (see Helios Power-Flow Interface below).

Pre-compiled shared libraries for Linux, Windows and macOS ship inside the wheel.

Choosing an edition

One capability lives only in the Java edition:

• CODEGEN, which translates user-written model descriptions into Fortran 2003 and compiles them into a custom simulator. Writing your own exciter, governor or injector needs the Java edition, or the CODEGEN toolchain directly.

Trajectory viewing exists in both editions, by different means. The Java edition launches DYNGRAPH, a separate viewer executable. This edition carries its own equivalent, written in Python on top of Matplotlib: extractor reads a .trj file into NumPy arrays, and curplot or a curve’s own .plot() draws them. The results stay in the process as ordinary arrays, so they can be sliced, compared across runs, or handed to any other Python library, and plotting is a method call rather than a separate program.

Everything else, running dynamic simulations and power flows against the same engines and data files, is available here.

Key Features

• Complete simulation workflow - define cases, run simulations, pause/continue, and extract results, all from Python

• Runtime interaction - query bus voltages, branch flows, and component observables while paused; inject disturbances on-the-fly

• Trajectory post-processing - extract and plot time-series results from Fortran binary trajectory files

• Parameter sweeps - script multiple simulations with varying parameters or disturbances

• Small-signal stability analysis - compute eigenvalues, damping ratios, participation factors and mode shapes in the engine, or export the system Jacobian and drive your own solver. See examples/eigenanalysis/ for an annotated walkthrough

• AC power flow - the stepss.helios module runs Helios power flows: solve, modify with redispatch, N-1 contingency screening, and file exports

• Shared data files - the same .dat, .dst and .obs files run in the Java edition, so a case can move between the two

• Scientific Python integration - works natively with NumPy, SciPy, Matplotlib, and Jupyter

Installation

Install stepss and all recommended dependencies via pip:

pip install jupyter ipython stepss

Required dependencies (matplotlib, scipy, and numpy) are installed automatically.

Minimal installation (no plotting or notebook support):

pip install stepss

Optional: Install Gnuplot to enable real-time observable plots during simulation. stepss will still work without it, but runtime plots will be disabled.

sudo apt install libopenblas0 libgfortran5 libgomp1

brew install openblas gcc

Quick Start

import stepss

# 1. Define the test case
case = stepss.cfg()
case.addData('dyn.dat')        # dynamic model data
case.addData('volt_rat.dat')   # power-flow initialisation
case.addData('settings.dat')   # solver settings
case.addDst('fault.dst')       # disturbance sequence
case.addObs('obs.dat')         # define observables to record
case.addTrj('output.trj')      # trajectory output file

# 2. Run simulation
ram = stepss.sim()
ram.execSim(case)              # run to completion

# 3. Extract and plot results
ext = stepss.extractor(case.getTrj())
ext.getBus('1041').mag.plot()  # bus voltage magnitude
ext.getSync('g1').S.plot()     # generator rotor speed

For interactive usage, pause/continue and on-the-fly disturbance injection is supported:

ram = stepss.sim()
ram.execSim(case, 0.0)                        # initialise, paused at t=0
ram.addDisturb(10.0, 'BREAKER SYNC_MACH g7 0')  # schedule generator trip
ram.contSim(ram.getInfTime())                 # run to end of time horizon
ram.endSim()

Helios Power-Flow Interface

Helios is the AC power-flow engine both editions use, exposed here through the stepss.helios module. Unlike the RAMSES classes, this interface uses PEP 8 snake_case naming.

from stepss.helios import HeliosSession

with HeliosSession() as pf:
    pf.load_file('network.dat')
    pf.solve()

    v, angle = pf.get_bus_voltage('1041')      # one bus
    v_all, angle_all = pf.get_bus_voltages()   # all buses (NumPy arrays)

    # modify the system and re-solve with redispatch
    pf.trip_branch('1042-1044')
    pf.change_load('1041', 50.0, 10.0)         # +50 MW, +10 Mvar
    pf.apply_changes()

    # N-1 contingency screening
    for result in pf.run_contingencies(branches=True, generators=True):
        print(result.name, result.accepted, result.violations)

    # export the operating point (e.g. as RAMSES initial conditions)
    pf.write_voltrat('volt_rat.dat')

Runnable examples live in examples/helios/.

Main Classes

Bundled Binaries Are CI-Managed

The native libraries under src/stepss/libs/ and the version record in src/stepss/_bundled.py are written by automation, not by hand. When RAMSES or Helios publishes a release, a workflow refreshes the affected libraries, bumps the patch version, and publishes a new stepss release only after the full test suite (including the Nordic voltage-collapse regression) passes on Linux, Windows and macOS.

Check what a given release bundles with:

python -c "import stepss; print(stepss.__ramses_version__, stepss.__helios_version__)"

Contributors should not edit those paths directly; a manual change is overwritten by the next sync.

Documentation

Full documentation is available at https://stepss.sps-lab.org/python/.

• Overview

• Installation

• Power Flow with Helios

• API Reference

• Examples

Support:

• Issues: https://github.com/SPS-L/stepss-python-ui/issues

• Project page: https://sps-lab.org/project/stepss/

License

stepss (the Python wrapper) is distributed under the Apache License 2.0 - see LICENSE.rst. Copyright © Petros Aristidou.

The RAMSES solver (the dynamic library bundled in this package) is proprietary software owned by the University of Liège and is distributed under the Academic Public License for the use of STEPSS: free for non-commercial use (teaching, academic research, personal purposes), with a limit of 1000 buses and 2 CPU cores. For commercial use or larger models, contact the authors. See the STEPSS License page for full terms.

The STEPSS-Helios power-flow library (libhelios_api, also bundled in this package and used by stepss.helios) is the property of Dr. Petros Aristidou, distributed under the STEPSS-Helios Academic Public License: free for non-commercial use; commercial use requires a license (info@sps-lab.org). See the NOTICE file for details.

Authors

Developed and maintained by the Sustainable Power Systems Laboratory (SPS-L) at the Cyprus University of Technology, under the direction of Dr. Petros Aristidou.

• Dr. Petros Aristidou - Cyprus University of Technology

• Dr. Thierry Van Cutsem - Emeritus, University of Liège