Helios Power-Flow API

The stepss.helios module wraps Helios, the STEPSS AC power-flow engine. Pre-compiled libraries are bundled with the package for Windows, Linux, and macOS, so no separate installation is required.

Unlike the RAMSES classes (which follow the historical camelCase conventions), this module uses PEP 8 snake_case naming. Errors are raised as stepss.HeliosError, carrying the engine’s diagnostic message.

Basic Workflow

HeliosSession follows a load → (modify) → solve → query lifecycle and works as a context manager:

from stepss.helios import HeliosSession

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

    v, angle = pf.get_bus_voltage('1041')     # one bus (pu, rad)
    p, q = pf.get_branch_flow('1042-1044')    # from-end flow (MW, Mvar)

Solve diagnostics are available after solve(): pf.converged, pf.solver_status, pf.iterations, and pf.max_mismatch.

Solver Options

Options map to the $PARAM records of the data file and can be overridden after loading (loading overwrites them with the file’s values, so set options after load_file):

from stepss.helios import Option

pf.load_file('network.dat')
pf.set_option(Option.TOLAC, 0.001)     # MW
pf.set_option(Option.MAX_ITER, 30)
pf.solve()

Vectorized Results

Bulk getters return NumPy arrays indexed like the corresponding *_names() lists, with no text parsing needed:

v_pu, angle_rad = pf.get_bus_voltages()
p_load, q_load = pf.get_bus_loads()
p_from, q_from, p_to, q_to = pf.get_branch_flows()
p_gen, q_gen, status = pf.get_generator_outputs()

names = pf.bus_names()
print(f"lowest voltage: {v_pu.min():.4f} pu at {names[v_pu.argmin()]}")

Per-element dataclasses are available via get_bus_info(), get_branch_info(), and get_generator_info().

Modifying the System

Modifications accumulate an active-power imbalance that apply_changes() settles: connectivity check, redispatch onto the remaining generators, and a re-solve (the same workflow as the interactive modify menu). change_* methods apply increments; set_load() sets absolute values:

pf.trip_branch('1042-1044')
pf.change_load('1041', 50.0, 10.0)     # +50 MW, +10 Mvar
pf.set_generator_voltage('g6', 1.02)
pf.apply_changes()                     # redispatch + re-solve

pf.reset()                             # back to the state saved at load

Contingency Screening

Run automatic N-1 over selected equipment classes, or a Fortran-format contingency file (BT/GT/ST/HC actions). Each result is a dataclass with convergence, acceptance, voltage/loading extremes, and violation strings; the base case is untouched afterwards:

results = pf.run_contingencies(branches=True, generators=True,
                               v_min=0.95, v_max=1.05, overload=100.0)
for r in results:
    if not r.accepted:
        print(r.name, r.violations)

results = pf.run_contingencies(file='contingencies.txt')

Exporting Results

pf.write_dump('solved_case.dat')      # re-loadable data file
pf.write_voltrat('volt_rat.dat')      # LFRESV + TRANSFO records, RAMSES initial conditions
pf.write_matlab('system.m')           # operating point + Y-bus script
pf.write_diagram('template.svg', 'diagram.svg')

volt_rat.dat is the natural bridge to dynamic simulation: solve a power flow with Helios, export it, and pass it to a RAMSES case via case.addData('volt_rat.dat').

Runnable Examples

Five self-contained scripts ship in the repository under examples/helios/: basic solve, options and arrays, modify and re-solve, contingency screening, and exports.