Scripted power system dynamic simulation and AC power-flow analysis from Python.

PyRAMSES is a Python interface to the RAMSES dynamic simulator — part of the STEPSS power system simulation platform. It covers the full simulation workflow: defining test cases, launching simulations, querying system state at runtime, and extracting and plotting results.

PyRAMSES enables scripted power system dynamic simulations from Python or Jupyter notebooks. It exposes the full capability of the RAMSES solver through a clean Python API, with pre-compiled binaries bundled — no separate solver installation required. The package also bundles the Helios AC power-flow engine (see Helios Power-Flow Interface below).

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

• 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
• Eigenanalysis support — export system Jacobian matrices for small-signal stability analysis
• Bundled binaries — pre-compiled RAMSES shared libraries (ramses.dll / ramses.so) for Windows and Linux, plus Helios power-flow libraries for Windows, Linux, and macOS
• AC power flow — the pyramses.helios module runs Helios power flows: solve, modify with redispatch, N-1 contingency screening, and file exports
• Scientific Python integration — works natively with NumPy, SciPy, Matplotlib, and Jupyter

Install PyRAMSES and all recommended dependencies via pip:

pip install jupyter ipython pyramses

Required dependencies (matplotlib, scipy, numpy, and — on Windows/Linux — mkl) are installed automatically.

Minimal installation (no plotting or notebook support):

pip install pyramses

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

On Linux, the following system libraries must be installed before running PyRAMSES:

sudo apt install libopenblas0 libgfortran5 libgomp1

These packages provide:

• libopenblas0 — OpenBLAS BLAS/LAPACK routines used by the solver
• libgfortran5 — GNU Fortran runtime required by the Fortran components of RAMSES
• libgomp1 — OpenMP runtime for multi-core parallel execution

On most desktop Linux distributions these are already present. If pyramses fails to import with a shared-library error, install the packages above and retry.

The free version is limited to 1000 buses and 2 OpenMP cores. See the License page for full terms.

import pyramses

# 1. Define the test case
case = pyramses.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 = pyramses.sim()
ram.execSim(case)              # run to completion

# 3. Extract and plot results
ext = pyramses.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 = pyramses.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()

PyRAMSES also bundles Helios, the STEPSS AC power-flow engine (successor of the Fortran PFC), exposed through the pyramses.helios module. Unlike the RAMSES classes, this interface uses PEP 8 snake_case naming. Pre-compiled libraries are bundled for Linux, Windows, and macOS.

from pyramses.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/.

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

• Overview
• Installation
• Power Flow with Helios
• API Reference
• Examples

Support:

• Issues: https://github.com/SPS-L/stepss-pyramses/issues
• Project page: https://sps-lab.org/project/pyramses/

PyRAMSES (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 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 pyramses.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.

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