Skip to content

Port small-signal stability analysis to Python #1

Description

@apetros

Why

Small-signal stability analysis is available in STEPSS GUI but not in stepss.

The capability itself already lives in the engine rather than in either interface:
RAMSES performs it, triggered by the EIG disturbance record or the run_ssa C
entry, and computes eigenvalues, eigenvectors and participation factors of the
system at a chosen instant of a run. STEPSS GUI drives it from the second half of
its Analysis tab, with a results directory, a results basename, the analysis time
t, a real-part limit and a participation-factor threshold, plus save and load of
the dynamic Jacobian.

So this is an interface gap, not a missing feature. A user who scripts their
studies has to open the desktop application to get the eigenvalues of a run the
script just produced, which is the one thing the Python edition exists to avoid.

It is also the natural fit for Python: eigenvalues, damping ratios and
participation factors are matrices to plot and compare across a sweep, and the
edition already returns trajectories as NumPy arrays.

Shape

run_ssa is a C entry, so it can be reached the same way the rest of the engine
is, and the existing stepss.helios.HeliosSession is the precedent for wrapping a
C API on this side.

Worth settling in the design:

  • Return the spectrum as arrays rather than parsing the files the engine writes,
    so results are usable without touching disk. Eigenvalues, damping ratio and
    frequency per mode, and the participation factors as a matrix indexed by state.
  • Expose the same four controls the GUI does (analysis time, real-part limit,
    participation-factor threshold, results basename), since those are the engine's
    own parameters and diverging would make the two editions disagree.
  • Keep the dynamic Jacobian save/load, which is what makes a spectrum
    reproducible without re-simulating. Note that JAC (raw matrix export) and
    EIG (analysis of them) are separate features and both matter.
  • Decide whether analysis runs inside an existing sim() session or against a
    saved trajectory. The GUI does the former; scripts will want both.

Validation

stepss-eigenanalysis holds the reference spectra and the validation suite the
engine is checked against, and its tests need neither MATLAB nor a RAMSES licence.
Check the Python results against those rather than against a fresh run, so a
wrapper bug cannot be mistaken for engine behaviour.

Docs

user-guide/eigenanalysis.md in stepss-docs owns the method and settings, and
gui/interface.md describes the GUI controls. When this lands, the Python API
pages need the new surface and those two pages should link to it, so the site
stops implying the capability is GUI-only.

Note for the docs: MATLAB is not part of this. Support for small-signal analysis
through MATLAB was removed and no reference to it is to be reintroduced.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions