Skip to content

Readme_PyRAPS_SS.md

Latest commit

 

History

History
165 lines (106 loc) · 5.81 KB

Readme_PyRAPS_SS.md

File metadata and controls

165 lines (106 loc) · 5.81 KB
Raw

09-2026

Copyright 2026, Battelle Energy Alliance, LLC, ALL RIGHTS RESERVED

Authors: Soumyadeep Nag, Shafiul Alam

PyRAPS Steady-State Hydro Derating

PyRAPS_SS.py applies a altered-head operating condition to selected hydroelectric generators in a loaded PSS®E case. It recalculates their active-power limits, alters generation for a selected group of generators, redispatches eligible generators, solves the power flow, and saves the modified case.

What the script does

  1. Reads all in-service generators from the active PSS®E case.
  2. Reads governor information, generator redispatch eligibility, and the list of hydro units to derate from three CSV files.
  3. Calculates each generator's effective maximum power for the specified per-unit head H0.
  4. Derates each listed, in-service hydro unit.
  5. Limits hydropower generation to 95% of the new maximum when its original output exceeds the derated maximum, leaving headroom for losses and response.
  6. Redispatches eligible online generators in proportion to their upward or downward reserve.
  7. Runs a full-Newton power flow.
  8. If the swing generator exceeds its effective maximum, performs another proportional redispatch and solves the power flow again.
  9. Writes a generator reserve report and, following successful solutions, saves the modified PSS®E case.

Requirements

  • A compatible installation of Siemens PSS®E with Python support
  • The PSS®E psspy module available in the Python environment
  • Python's built-in csv module
  • An active PSS®E case with the required network data and dynamic models already loaded

The script does not initialize PSS®E, open a .sav case, or load a .dyr file. Run it only after those steps have been completed by the calling script, an IDE environment, or the PSS®E GUI.

Configuration

Edit the values near the top of PyRAPS_SS.py:

# Desired head level in per unit
H0 = 0.9

# Input files
bsl_file = 'baseload.csv'
trate_file = 'gov_and_trate.csv'
derating_file = 'Affected_generators.csv'

H0 = 0.9 represents a head equal to 90% of the reference head.

The output case name is set near the end of the script:

file = "HS_NW_CAL90.sav"

All relative file paths are resolved from the process's current working directory.

Input files

Each CSV must contain a header row. The script uses fixed column positions, so retain the expected ordering even if the header names differ.

gov_and_trate.csv

Maps each supported governor model to the relative PSS®E CON index containing its turbine rating. This is done according to the PSSE model library. This can be updated if required.

Example:

governor_model,trate_con_number
HYGOV,5
HYG3U1,10

The actual model names and indices must match the dynamic models used in the active case. If a governor is not listed, the script does not apply a governor-based turbine-rating constraint.

baseload.csv

Identifies machines that may participate in redispatch.

A baseload flag of 0 makes an online generator eligible for redispatch. Other values exclude it. Machine IDs must match PSS®E IDs after surrounding spaces are removed.

Example:

bus_number,bus_name,machine_id,baseload_flag
101,PLANT_A,1,0
205,PLANT_B,2,1

Affected_generators.csv

Lists the hydro machines whose available power is to be derated.

Example:

record,bus_number,bus_name,machine_id
1,301,HYDRO_A,1
2,302,HYDRO_B,1

Derating equations

For most hydro governor models, the derated maximum is:

$$ P_{\max,new}=P_{\max,old}H_0^{3/2} $$

For an HYG3U1 governor, the script reads g_max, qnl, and At from the model's dynamic constants and uses:

$$ P_{\max,new}=P_{\max,old}A_t\left(g_{max}H_0^{3/2}-q_{nl}H_0\right) $$

This is done to maintain compatibility with the dynamic data adjustment. For the dynamic file only HYG3U1 models have H0 as an input parameter and hence are the only units that recieve a new H0. Consequently, their maximum power must be estimated taking into account their dynamic data + steady-state data or this will cause initialization errors.

The new maximum is not allowed below the existing PMIN. If the original generation exceeds the new maximum, generation is set to 95% of the new maximum and then checked against PMIN.

Running the script

Place the script and its input CSV files in the working directory, load the required steady-state and dynamic data into PSS®E, and then run:

python PyRAPS_SS.py

It can also be executed from the PSS®E GUI after the appropriate case and dynamic data are loaded (prefered method).

Outputs

reserve_report.csv

Created each time adjustgen() runs. It contains:

  • bus number (the column is currently labeled bus name);
  • generator ID;
  • upward and downward reserve before redispatch;
  • old and new generator output; and
  • effective maximum and minimum power.

If redispatch is called a second time for swing-bus correction, this file is overwritten and therefore contains only the most recent redispatch pass.

NEW_CASE.sav

The modified PSS®E case. It is saved only when both power-flow solutions converge.

The console also reports derated machines, convergence status, upward reserve, total PMAX change, total generation change, the swing-bus number, and the saved-case name.

Important operating notes

  • Check that all bus numbers and machine IDs in the CSV files exactly match the active case.
  • Confirm every governor-to-CON mapping against the applicable dynamic-model documentation.
  • The script does not explicitly act on nonzero PSS®E error codes returned by most API calls; review the PSS®E log for missing machines, models, or invalid values.
  • Proportional upward redispatch uses only eligible generators with more than 10 MW of upward reserve and positive initial output.

Files

PyRAPS_SS.py
baseload.csv
gov_and_trate.csv
Affected_generators.csv