stepss 3.77__tar.gz → 3.78__tar.gz

{stepss-3.77/stepss.egg-info → stepss-3.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepss
-Version: 3.77
+Version: 3.78
 Summary: Python interface to the STEPSS power-system simulation platform.
 Home-page: https://stepss.sps-lab.org
 Author: Petros Aristidou
@@ -84,6 +84,7 @@ 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
+- **Live monitoring** - ``stepss.monitor`` steps a running simulation and plots the quantities you choose as they are computed
 - **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
@@ -103,7 +104,7 @@ Minimal installation (no plotting or notebook support)::
 
    pip install stepss
 
-**Optional:** Install `Gnuplot <http://www.gnuplot.info/>`_ to enable real-time observable plots during simulation. stepss will still work without it, but runtime plots will be disabled.
+**Live plots:** ``stepss.monitor`` draws chosen quantities while a simulation runs. It uses matplotlib, which pip installs above, so nothing further is needed.
 
 Linux System Prerequisites
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

{stepss-3.77 → stepss-3.78}/stepss/__init__.py

@@ -12,6 +12,7 @@ Public API exported by this package:
 - :class:`~stepss.extractor.extractor` - parse Fortran binary trajectory files post-simulation.
 - :class:`~stepss.extractor.cur` - lightweight NamedTuple holding a (time, value, msg) timeseries.
 - :func:`~stepss.extractor.curplot` - plot one or more :class:`cur` objects on a single axes.
+- :class:`~stepss.live.monitor` - plot chosen quantities while a simulation runs.
 - :class:`~stepss.helios.HeliosSession` - run AC power flows with the Helios engine.
 - :class:`~stepss.globals.HeliosError` - exception raised by Helios calls.
 
@@ -23,7 +24,7 @@ Module-level flags set at import time:
 """
 
 __package_name__ = "stepss"
-__version__ = '3.77'
+__version__ = '3.78'
 __author__ = "Petros Aristidou"
 __copyright__ = "Petros Aristidou"
 __license__ = "Apache-2.0"
@@ -37,12 +38,13 @@ from .cases import cfg
 from .globals import HeliosError
 from .simulator import sim
 from .extractor import extractor, curplot, cur
+from .live import monitor
 from . import helios
 from .helios import HeliosSession
 from ._bundled import RAMSES_VERSION as __ramses_version__
 from ._bundled import HELIOS_VERSION as __helios_version__
 
-__all__ = ["cfg", "sim", "extractor", "cur", "curplot", "helios",
+__all__ = ["cfg", "sim", "extractor", "cur", "curplot", "monitor", "helios",
            "HeliosSession", "HeliosError"]
 
 # No gnuplot probe. This package has always plotted with matplotlib, through

{stepss-3.77 → stepss-3.78}/stepss/_bundled.py

@@ -9,5 +9,5 @@ RAMSES_VERSION is also what the stepss version number is built from, so the
 leading components of __version__ always name the library bundled here.
 """
 
-RAMSES_VERSION = "v3.77"
+RAMSES_VERSION = "v3.78"
 HELIOS_VERSION = "v1.4.1"

{stepss-3.77 → stepss-3.78}/stepss/cases.py

@@ -15,6 +15,48 @@ from .globals import RAMSESError, CustomWarning
 warnings.showwarning = CustomWarning
 
 
+def _dstProblem(dstfile):
+    """Return None if *dstfile* can drive a run, or a sentence saying what is wrong.
+
+    Mirrors what the engine itself accepts. A blank line, or one opening with
+    ``#`` or ``!``, is a comment. Every other line is a record whose first field
+    is a time and whose remainder is the description, and the run ends at the
+    first record whose description carries ``STOP``.
+
+    :param str dstfile: path to the disturbance file to check.
+    :returns: None when the file is usable, otherwise the reason it is not.
+    :rtype: str or None
+    """
+    records = 0
+    untimed = False
+    try:
+        with open(dstfile, 'r', encoding='utf-8', errors='replace') as records_file:
+            for line in records_file:
+                text = line.strip()
+                if not text or text[0] in '#!':
+                    continue
+                _, space, description = text.partition(' ')
+                if not space:
+                    # The engine refuses a record with fewer than two fields.
+                    # Noting a bare STOP separately turns "no STOP record" into
+                    # a sentence the reader can act on, with STOP on screen.
+                    untimed = untimed or 'STOP' in text
+                    continue
+                records += 1
+                if 'STOP' in description:
+                    return None
+    except IOError as e:
+        return 'RAMSES: The disturbance file %s could not be read: %s' % (dstfile, e)
+
+    if untimed:
+        return ('RAMSES: The disturbance file %s has a STOP without a time. Every '
+                'record starts with its time, as in "240.0 STOP".' % dstfile)
+    if records == 0:
+        return 'RAMSES: The disturbance file %s has no disturbance records.' % dstfile
+    return ('RAMSES: The disturbance file %s has no STOP record. A dynamic simulation '
+            'ends at its STOP time, so add a line such as "240.0 STOP".' % dstfile)
+
+
 class cfg(object):
     """Simulation case configuration.
 
@@ -174,8 +216,16 @@ class cfg(object):
 
         .. warning:: If *userFile* already exists it will be overwritten.
         """
-        if not self._dataset or not self._dstset:
-            raise RAMSESError('Dataset and disturbance set cannot be empty.')
+        if not self._dataset:
+            raise RAMSESError('RAMSES: No data file is set. A case needs at least one.')
+        if not self._dstset:
+            raise RAMSESError('RAMSES: No disturbance file is set. A dynamic simulation '
+                              'needs one, ending in a STOP record.')
+        # Re-checked here rather than trusted from addDst: the file can be
+        # edited, or replaced, between being attached and being run.
+        problem = _dstProblem(self._dstset[0])
+        if problem:
+            raise RAMSESError(problem)
 
         cmdFile = ""
 
@@ -534,11 +584,15 @@ class cfg(object):
 
         .. warning:: A disturbance file must be provided before the simulation can start.
         """
-        if os.path.isfile(dstfile):
-            del self._dstset[:]
-            self._dstset.append(dstfile)
-        else:
+        if not os.path.isfile(dstfile):
             raise IOError('RAMSES: The dstfile %s does not exist or is not valid.' % (dstfile))
+        # Checked before the case is touched, so a rejected file never replaces
+        # a working one.
+        problem = _dstProblem(dstfile)
+        if problem:
+            raise RAMSESError(problem)
+        del self._dstset[:]
+        self._dstset.append(dstfile)
 
     def getDst(self):
         """Get disturbance

{stepss-3.77 → stepss-3.78}/stepss/globals.py

@@ -95,32 +95,6 @@ class HeliosError(Exception):
     pass
 
 
-def __which(program):
-    """Locate a program on the system PATH, similar to the Unix ``which`` command.
-
-    :param str program: executable name (with or without full path)
-    :returns: full path to the executable if found and executable, otherwise ``None``
-    :rtype: str or None
-    """
-
-    def is_exe(fpath):
-        """Return True if *fpath* is a regular file and is executable."""
-        return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
-
-    fpath, fname = os.path.split(program)
-    if fpath:
-        if is_exe(program):
-            return program
-    else:
-        for path in os.environ.get("PATH", "").split(os.pathsep):
-            path = path.strip('"')
-            exe_file = os.path.join(path, program)
-            if is_exe(exe_file):
-                return exe_file
-
-    return None
-
-
 def silentremove(filename):
     """Delete a file, silently ignoring the case where it does not exist.
 

stepss-3.78/stepss/live.py

@@ -0,0 +1,477 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Live plotting of a running RAMSES simulation.
+
+Provides :class:`monitor`, which steps a simulation forward in slices, reads
+the chosen quantities out of the engine at every pause, and redraws a stacked
+matplotlib figure as the run proceeds.
+
+The engine is polled in process, through the same accessors a script would
+call by hand (:meth:`~stepss.simulator.sim.getBusVolt`,
+:meth:`~stepss.simulator.sim.getObs` and the rest): no file is read and
+nothing is piped anywhere. Run-time observables declared with
+:meth:`~stepss.cases.cfg.addRunObs` are a separate mechanism, in which the
+engine writes a curve file of its own; the two are independent and may be used
+together.
+
+One panel per observable, stacked and sharing the time axis.
+
+:Example:
+
+>>> import stepss
+>>> ram = stepss.sim()
+>>> case = stepss.cfg('cmd.txt')
+>>> ram.execSim(case, 0.0)                    # initialise, pause at t = 0
+>>> mon = stepss.monitor(ram, ['BV 4044', 'MS g6'])
+>>> curves = mon.run(step=0.5)                # run to the end of the scenario
+>>> stepss.curplot(curves)                    # replot the same data afterwards
+"""
+
+import time
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .extractor import cur
+
+# Backends that render to a file and have no window to update. Live redraw is
+# skipped on these; sampling and the final figure are unaffected, so
+# monitor.savefig() produces the same chart a window would have shown. The list
+# is matplotlib's own set of non-interactive built-ins, copied rather than
+# imported: matplotlib.rcsetup.non_interactive_bk is deprecated since 3.9 and
+# removed in 3.11, and this package supports matplotlib 3.0 upwards. A backend
+# missing from the list is treated as interactive, which costs a draw call that
+# does nothing.
+_STATIC_BACKENDS = frozenset(['agg', 'cairo', 'pdf', 'pgf', 'ps', 'svg', 'template'])
+
+# Sim-time comparisons. RAMSES pauses at the first internal step at or after
+# the requested time, so equality is never exact.
+_EPS = 1e-9
+
+# Branch quantity -> (index into getBranchPow, description, unit).
+_BRANCH_POW = {
+    'BPO': (0, 'active power at the origin', 'MW'),
+    'BQO': (1, 'reactive power at the origin', 'Mvar'),
+    'BPE': (2, 'active power at the extremity', 'MW'),
+    'BQE': (3, 'reactive power at the extremity', 'Mvar'),
+}
+
+
+def _canDraw():
+    """Return True if the active matplotlib backend can update a live window.
+
+    :returns: False for the file-only backends, True otherwise.
+    :rtype: bool
+    """
+    name = matplotlib.get_backend().lower()
+    if name.startswith('module://'):
+        # Jupyter's inline backend emits a static image per draw and cannot
+        # animate one; ipympl and the nbagg family can.
+        return 'inline' not in name
+    return name not in _STATIC_BACKENDS
+
+
+class _Clock(object):
+    """Wall-clock seconds elapsed since the first sample.
+
+    Backs the ``RT`` descriptor: plotted against simulated time it shows how
+    far the simulation runs behind, or ahead of, real time.
+    """
+
+    def __init__(self):
+        self._start = None
+
+    def __call__(self, ram):
+        """Return seconds elapsed, starting the clock on the first call.
+
+        :param ram: the simulator instance (unused).
+        :returns: elapsed wall-clock time in seconds.
+        :rtype: float
+        """
+        now = time.monotonic()
+        if self._start is None:
+            self._start = now
+        return now - self._start
+
+
+def _namedObs(comp_type, comp_name, obs_name):
+    """Return a reader for one named engine observable.
+
+    :param str comp_type: component type accepted by :meth:`~stepss.simulator.sim.getObs`.
+    :param str comp_name: component name.
+    :param str obs_name: observable name.
+    :returns: a callable taking the simulator and returning a float.
+    :rtype: callable
+    """
+
+    def read(ram):
+        return ram.getObs(comp_type, comp_name, obs_name)[0]
+
+    return read
+
+
+def _branchPow(branch_name, index):
+    """Return a reader for one field of :meth:`~stepss.simulator.sim.getBranchPow`.
+
+    :param str branch_name: branch name.
+    :param int index: 0 to 3, selecting p_orig, q_orig, p_extr or q_extr.
+    :returns: a callable taking the simulator and returning a float.
+    :rtype: callable
+    """
+
+    def read(ram):
+        return ram.getBranchPow([branch_name])[0][index]
+
+    return read
+
+
+def _expect(descriptor, args, count):
+    """Raise unless *args* holds exactly *count* items.
+
+    :param str descriptor: the descriptor being parsed, for the message.
+    :param list args: the fields following the descriptor code.
+    :param int count: the number of fields the code takes.
+    :raises ValueError: if the count does not match.
+    """
+    if len(args) != count:
+        raise ValueError(
+            "RAMSES: the observable descriptor '%s' takes %i field(s) after the code, got %i"
+            % (descriptor, count, len(args)))
+
+
+def _parse(descriptor):
+    """Turn one descriptor string into a label, a unit and a reader.
+
+    The vocabulary is tabulated in :class:`monitor`.
+
+    :param str descriptor: the descriptor to parse.
+    :returns: ``(label, unit, reader)``; *unit* is empty when the engine does
+              not define one.
+    :rtype: tuple
+    :raises ValueError: if the descriptor is empty, unknown, or carries the
+                        wrong number of fields.
+    """
+    fields = descriptor.split()
+    if not fields:
+        raise ValueError('RAMSES: the observable descriptor is empty')
+    code = fields[0].upper()
+    args = fields[1:]
+
+    if code == 'RT':
+        return 'elapsed real time', 's', _Clock()
+
+    if code == 'BV':
+        _expect(descriptor, args, 1)
+        name = args[0]
+        return '%s: voltage magnitude' % name, 'pu', lambda ram: ram.getBusVolt([name])[0]
+
+    if code == 'BA':
+        _expect(descriptor, args, 1)
+        name = args[0]
+        return '%s: voltage phase' % name, 'deg', lambda ram: ram.getBusPha([name])[0]
+
+    if code == 'MS':
+        _expect(descriptor, args, 1)
+        name = args[0]
+        return '%s: machine speed' % name, 'pu', _namedObs('SYN', name, 'Omega')
+
+    if code in _BRANCH_POW:
+        _expect(descriptor, args, 1)
+        name = args[0]
+        index, what, unit = _BRANCH_POW[code]
+        return '%s: %s' % (name, what), unit, _branchPow(name, index)
+
+    if code in ('ON', 'TO'):
+        _expect(descriptor, args, 2)
+        name, obs_name = args
+        comp_type = 'INJ' if code == 'ON' else 'TWOP'
+        return '%s: %s' % (name, obs_name), '', _namedObs(comp_type, name, obs_name)
+
+    if code == 'OBS':
+        _expect(descriptor, args, 3)
+        comp_type, name, obs_name = args
+        return '%s: %s' % (name, obs_name), '', _namedObs(comp_type.upper(), name, obs_name)
+
+    raise ValueError(
+        "RAMSES: unknown observable descriptor '%s'. Expected one of "
+        "BV, BA, MS, BPO, BQO, BPE, BQE, ON, TO, OBS or RT." % descriptor)
+
+
+def _isPair(item):
+    """Return True if *item* is a ``(label, callable)`` observable spec."""
+    return (isinstance(item, (tuple, list)) and len(item) == 2
+            and isinstance(item[0], str) and callable(item[1]))
+
+
+def _reader(item):
+    """Turn one observable spec into a label, a unit and a reader.
+
+    :param item: a descriptor string, a ``(label, callable)`` pair, or a bare
+                 callable taking the simulator and returning a float.
+    :returns: ``(label, unit, reader)``.
+    :rtype: tuple
+    :raises ValueError: if the spec is of none of those forms.
+    """
+    if isinstance(item, str):
+        return _parse(item)
+    if _isPair(item):
+        return item[0], '', item[1]
+    if callable(item):
+        return getattr(item, '__name__', 'observable'), '', item
+    raise ValueError(
+        'RAMSES: an observable must be a descriptor string, a (label, callable) '
+        'pair or a callable, not %s' % type(item).__name__)
+
+
+def _asList(observables):
+    """Normalise the *observables* argument to a list of specs."""
+    if isinstance(observables, str) or callable(observables) or _isPair(observables):
+        return [observables]
+    return list(observables)
+
+
+class monitor(object):
+    """Plot chosen quantities of a RAMSES simulation while it runs.
+
+    The simulation must already be initialised and paused, which
+    :meth:`~stepss.simulator.sim.execSim` does when given a *pause* time.
+    :meth:`run` then advances it in slices, sampling and redrawing at each
+    pause, and returns the collected curves.
+
+    Each observable gets its own panel; the panels are stacked and share the
+    time axis.
+
+    **Instance attributes:**
+
+    - ``figure`` (*matplotlib.figure.Figure* or *None*): the chart, or None
+      when built with ``show=False``.
+    - ``axes`` (*list*): one axes per observable, top to bottom.
+
+    :param ram: the simulator driving the run.
+    :type ram: :class:`stepss.sim`
+    :param observables: what to plot: descriptor strings such as ``'BV 4044'``
+                        (tabulated below), ``(label,
+                        callable)`` pairs, or bare callables taking the
+                        simulator and returning a float. A single spec need
+                        not be wrapped in a list.
+    :param str title: figure title, or None for none.
+    :param float refresh: minimum wall-clock seconds between redraws. Samples
+                          are never skipped, only draws; 0 redraws at every
+                          sample.
+    :param bool show: False builds no figure at all and only collects data.
+    :raises ValueError: if *observables* is empty or holds a spec that cannot
+                        be read.
+
+    **Descriptors.** The vocabulary is the one :meth:`~stepss.cases.cfg.addRunObs` uses, plus
+    ``BA`` and the generic ``OBS`` escape hatch:
+
+    ==================  =========================================  ======
+    Descriptor          Quantity                                   Unit
+    ==================  =========================================  ======
+    ``BV BUS``          voltage magnitude of a bus                  pu
+    ``BA BUS``          voltage phase of a bus                      deg
+    ``MS SYN``          speed of a synchronous machine              pu
+    ``BPO BRANCH``      active power at the branch origin           MW
+    ``BQO BRANCH``      reactive power at the branch origin         Mvar
+    ``BPE BRANCH``      active power at the branch extremity        MW
+    ``BQE BRANCH``      reactive power at the branch extremity      Mvar
+    ``ON INJ OBS``      named observable of an injector             engine
+    ``TO TWOP OBS``     named observable of a two-port              engine
+    ``OBS TYPE NAME O`` named observable of any component type      engine
+    ``RT RT``           elapsed wall-clock time                     s
+    ==================  =========================================  ======
+
+
+    :Example:
+
+    >>> import stepss
+    >>> ram = stepss.sim()
+    >>> case = stepss.cfg('cmd.txt')
+    >>> ram.execSim(case, 0.0)
+    >>> mon = stepss.monitor(ram, ['BV 4044', 'MS g6', 'RT RT'], title='Nordic')
+    >>> mon.run(step=0.5)
+    >>> mon.savefig('run.png')
+
+    .. note:: The buffers survive a failed run: if the engine raises part way
+              through, the samples taken up to that point are still available
+              from :meth:`curves`.
+    """
+
+    def __init__(self, ram, observables, title=None, refresh=0.2, show=True):
+        specs = _asList(observables)
+        if not specs:
+            raise ValueError('RAMSES: a monitor needs at least one observable')
+
+        self._ram = ram
+        self._refresh = float(refresh)
+        self._labels = []
+        self._units = []
+        self._readers = []
+        for spec in specs:
+            label, unit, read = _reader(spec)
+            self._labels.append('%s (%s)' % (label, unit) if unit else label)
+            self._units.append(unit)
+            self._readers.append(read)
+
+        self._time = []
+        self._values = [[] for _ in self._readers]
+        self._lines = []
+        self._lastDraw = None
+        self._wasInteractive = None
+        self._drawing = False
+        self.figure = None
+        self.axes = []
+        if show:
+            self._openFigure(title)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+        return False
+
+    def _openFigure(self, title):
+        """Build the stacked figure, one panel per observable.
+
+        :param str title: figure title, or None.
+        """
+        count = len(self._readers)
+        self.figure, grid = plt.subplots(count, 1, sharex=True, squeeze=False,
+                                         figsize=(8.0, 1.0 + 2.0 * count))
+        self.axes = [row[0] for row in grid]
+        for axes, label, unit in zip(self.axes, self._labels, self._units):
+            line, = axes.plot([], [])
+            self._lines.append(line)
+            axes.set_title(label, loc='left', fontsize='small')
+            axes.set_ylabel(unit)
+            axes.grid(True)
+        self.axes[-1].set_xlabel('time (s)')
+        if title:
+            self.figure.suptitle(title)
+        self.figure.tight_layout()
+
+        self._drawing = _canDraw()
+        if self._drawing:
+            self._wasInteractive = plt.isinteractive()
+            plt.ion()
+            self.figure.show()
+
+    def sample(self):
+        """Read every observable once, at the current simulated time.
+
+        Called by :meth:`run` at each pause. Call it directly when driving the
+        simulation yourself.
+
+        :returns: None.
+        """
+        self._time.append(self._ram.getSimTime())
+        for values, read in zip(self._values, self._readers):
+            values.append(read(self._ram))
+
+    def refresh(self, force=False):
+        """Push the samples into the figure and redraw it.
+
+        Does nothing when the monitor was built with ``show=False``. A draw
+        that falls inside the *refresh* interval is skipped unless *force*.
+
+        :param bool force: redraw regardless of the interval.
+        :returns: None.
+        """
+        if self.figure is None:
+            return
+        if self._drawing and not plt.fignum_exists(self.figure.number):
+            self._drawing = False  # the window was closed; keep sampling
+        now = time.monotonic()
+        if not force and self._lastDraw is not None and now - self._lastDraw < self._refresh:
+            return
+        self._lastDraw = now
+        for line, values, axes in zip(self._lines, self._values, self.axes):
+            line.set_data(self._time, values)
+            axes.relim()
+            axes.autoscale_view()
+        if self._drawing:
+            self.figure.canvas.draw_idle()
+            self.figure.canvas.flush_events()
+
+    def run(self, step=1.0, until=None):
+        """Advance the simulation in slices, sampling and redrawing at each pause.
+
+        Returns when the engine reports the end of the scenario, when *until*
+        is reached, or when a slice fails to advance the simulated time.
+
+        :param float step: simulated seconds per slice.
+        :param until: simulated time to stop at, or None to run to the end of
+                      the disturbance scenario.
+        :type until: float or None
+        :returns: one curve per observable.
+        :rtype: list of :class:`stepss.cur`
+        :raises ValueError: if *step* is not positive.
+        :raises RAMSESError: propagated from the engine. The samples taken
+                             before the failure remain available from
+                             :meth:`curves`.
+        """
+        if step <= 0.0:
+            raise ValueError('RAMSES: monitor.run needs a positive step, got %r' % step)
+
+        self.sample()
+        self.refresh(force=True)
+        try:
+            while not self._ram.getEndSim():
+                start = self._ram.getSimTime()
+                if until is not None and start >= until - _EPS:
+                    break
+                target = start + step
+                if until is not None:
+                    target = min(target, until)
+                self._ram.contSim(target)
+                self.sample()
+                self.refresh()
+                if self._ram.getSimTime() <= start + _EPS:
+                    break  # the scenario is over; the engine is not advancing
+        finally:
+            self.refresh(force=True)
+        return self.curves()
+
+    def curves(self):
+        """Return everything sampled so far.
+
+        :returns: one :class:`stepss.cur` per observable, in the order given
+                  to the constructor, all sharing the same time array.
+        :rtype: list of :class:`stepss.cur`
+        """
+        times = np.asarray(self._time, dtype=float)
+        return [cur(times, np.asarray(values, dtype=float), label)
+                for values, label in zip(self._values, self._labels)]
+
+    def savefig(self, fname, **kwargs):
+        """Redraw and write the figure to a file.
+
+        :param fname: path or file object, passed to
+                      :meth:`matplotlib.figure.Figure.savefig`.
+        :param kwargs: forwarded to :meth:`~matplotlib.figure.Figure.savefig`.
+        :returns: None.
+        :raises RuntimeError: if the monitor was built with ``show=False``.
+        """
+        if self.figure is None:
+            raise RuntimeError('RAMSES: this monitor has no figure (show=False)')
+        self.refresh(force=True)
+        self.figure.savefig(fname, **kwargs)
+
+    def close(self):
+        """Close the figure and restore matplotlib's interactive mode.
+
+        The collected samples are unaffected: :meth:`curves` keeps working.
+
+        :returns: None.
+        """
+        if self.figure is not None:
+            plt.close(self.figure)
+            self.figure = None
+            self.axes = []
+            self._lines = []
+        if self._wasInteractive is False:
+            plt.ioff()
+        self._wasInteractive = None
+        self._drawing = False

{stepss-3.77 → stepss-3.78/stepss.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepss
-Version: 3.77
+Version: 3.78
 Summary: Python interface to the STEPSS power-system simulation platform.
 Home-page: https://stepss.sps-lab.org
 Author: Petros Aristidou
@@ -84,6 +84,7 @@ 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
+- **Live monitoring** - ``stepss.monitor`` steps a running simulation and plots the quantities you choose as they are computed
 - **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
@@ -103,7 +104,7 @@ Minimal installation (no plotting or notebook support)::
 
    pip install stepss
 
-**Optional:** Install `Gnuplot <http://www.gnuplot.info/>`_ to enable real-time observable plots during simulation. stepss will still work without it, but runtime plots will be disabled.
+**Live plots:** ``stepss.monitor`` draws chosen quantities while a simulation runs. It uses matplotlib, which pip installs above, so nothing further is needed.
 
 Linux System Prerequisites
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

{stepss-3.77 → stepss-3.78}/stepss.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ stepss/cases.py
 stepss/extractor.py
 stepss/globals.py
 stepss/helios.py
+stepss/live.py
 stepss/simulator.py
 stepss.egg-info/PKG-INFO
 stepss.egg-info/SOURCES.txt