Simulate and Plot#

Import and Setting the Verbosity Level#

We first import the andes library and the get_case function that for loading test cases shipped with ANDES.

import andes

from andes.utils.paths import get_case

We can configure the verbosity level for logging (output messages) by passing a verbosity level (10-DEBUG, 20-INFO, 30-WARNING, 40-ERROR, 50-CRITICAL) to the stream_level argument of andes.main.config_logger(). Verbose level 10 is useful for getting debug output.

The logging level can be altered (as of v1.4.3) by calling config_logger again with new stream_level and file_level.


Note that the above andes.config_logger() is a shorthand to andes.main.config_logger().

If this step is omitted, the default INFO level (stream_level=20) will be used.

Run Time-Domain Simulation#

Run power flow by default#

get_case takes a relative path to ANDES_ROOT/andes/cases and returns the full path, where ANDES_ROOT is the root folder of ANDES. is the entrypoint function for loading files and running routines. It runs power flow by default and returns a System object.

Note: if default_config=True, the default concif will be used. To use your own config, remove default_config=True.

See the tutorial for saving and editing ANDES config.

ss ='kundur/kundur_full.xlsx'), default_config=True)
Working directory: "/home/hacui/repos/andes/examples"
> Loaded generated Python code in "/home/hacui/.andes/pycode".
Parsing input file "/home/hacui/repos/andes/andes/cases/kundur/kundur_full.xlsx"...
Input file parsed in 0.2775 seconds.
System internal structure set up in 0.0322 seconds.
-> System connectivity check results:
  No islanded bus detected.
  System is interconnected.
  Each island has a slack bus correctly defined and enabled.

-> Power flow calculation
           Numba: Off
   Sparse solver: KLU
 Solution method: NR method
Power flow initialized in 0.0039 seconds.
0: |F(x)| = 14.9282832
1: |F(x)| = 3.608627841
2: |F(x)| = 0.1701107882
3: |F(x)| = 0.002038626956
4: |F(x)| = 3.745104027e-07
Converged in 5 iterations in 0.0084 seconds.
Report saved to "kundur_full_out.txt" in 0.0020 seconds.
-> Single process finished in 0.5018 seconds.

Run time-domain simulation#

Run TDS by calling on the system. Note that the call must follow the power flow immediately.

The default simulation is for 20 seconds. To change if, change to the desired value. = 10  # simulate for 10 seconds
-> Time Domain Simulation Summary:
Sparse Solver: KLU
Simulation time: 0.0-10 s.
Fixed step size: h=33.33 ms. Shrink if not converged.
Initialization for dynamics completed in 0.0490 seconds.
Initialization was successful.
<Toggle 1>: Line.Line_8 status changed to 0 at t=2.0 sec.
Simulation completed in 0.5985 seconds.
Outputs to "kundur_full_out.lst" and "kundur_full_out.npz".
Outputs written in 0.0104 seconds.

To check if all operations completed successfully, check ss.exit_code. exit_code == 0 means that all operations were successful.

If not zero, exit_code indicates the number of errors caught. One will need to check output messages for errors.


Export and Plot Results#

If you are using ANDES interactively from Jupyter Notebook or IPython, at the end of a time-domain simulation. a plotter object ss.TDS.plt will automatically be created.

To check if that has been created successfully (in case the detection of an interactive environment fails), check the type of ss.TDS.plt.

<andes.plot.TDSData at 0x7fb229d9ff70>

If ss.TDS.plt is None, it can be manually loaded with ss.TDS.load_plotter(). Otherwise, load_plotter() can be safely skipped.


Exporting simulation data to csv#

To export simulation results to a CSV file, one can use ss.TDS.plt.export_csv(), which takes an optional argument of the file name.

If not provided, a default file name will be assigned.

CSV data saved to "/home/hacui/repos/andes/examples/kundur_full_out.csv".

Index-based Plotting#

plotter.plot() is the entry point for plotting. It is the backend of the command-line andes plot.

Before plotting, open the kundur_full_out.lst to find the indices (first column) for the variables to plot.

For example, if we want to plot all generator speed, which is the omega variable of GENROU. By inspect, we found the indices as 5, 6, 7, 8.

Pass them in a tuple or a list to ss.TDS.plt.plot.

fig, ax = ss.TDS.plt.plot((5, 6, 7, 8))

plot() returns a figure object and an axis object.

Find index by variable name#

plotter.find() is a method for finding indices based on variable name.

The first argument is the pattern to find. An optional argument exclude is the pattern to exclude. Regular expression is supported for both.

([5, 6, 7, 8],
 ['omega GENROU 1', 'omega GENROU 2', 'omega GENROU 3', 'omega GENROU 4'])
fig, ax = ss.TDS.plotter.plot(ss.TDS.plotter.find('omega')[0])

Plotting by variable#

Looking up indices from the lst file can be tedious.

Instead, one can pass a a variable in a model to ss.TDS.plt.plot. For example, to plot, do

fig, ax = ss.TDS.plt.plot(

To plot a subset of the variables, pass the 0-indexed selection indices in a tuple through argument a of ss.TDS.plt.plot. For example, to plot the 0-th and the 3-th, do

fig, ax = ss.TDS.plt.plot(, a=(0, 3))

Adding curves to an existing figure#

Plotting curves into an existing figure allows easy comparison of results. It can be done by passing a figure and an axis object of plot().

For example, to plot the speed of the second generator (a=1) on the figure above, do

fig, ax = ss.TDS.plt.plot(, a=(1, ), fig=fig, ax=ax, linestyles=['-.'])
<Figure size 432x288 with 0 Axes>

Y-axis label#

fig, ax = ss.TDS.plotter.plot((5, 6, 7, 8), ylabel='Generator speed [p.u.]')

Legend names (yheader)#

fig, ax = ss.TDS.plotter.plot((5, 6, 7, 8), ylabel='Generator speed [p.u.]', 
                              yheader=['Spd 1', 'Spd 2', 'Spd 3', 'Spd 4'])

Note that the number of elements passed to yheader should match the number of variables. yheader only applies to new curves and cannot be used to modify existing legends.


A lambda functino can be passed to ycalc to scale the value. To scale the frequency from per unit to 60 Hz nominal values, use

fig, ax = ss.TDS.plotter.plot((5, 6, 7, 8), ycalc=lambda x: 60 * x)

Greyscale and Grid#

fig, ax = ss.TDS.plotter.plot((5, 6, 7, 8),
                              ycalc=lambda x: 60 * x,

Save figure#

Pass savefig = True to save the figure to a png file.

fig, ax = ss.TDS.plotter.plot((5, 6, 7, 8), savefig=True)
Figure saved to "kundur_full_out_1.png".

Additional arguments#

plotter.plot takes addition arguments. To check additional arguments, please use help or refer to the source code.

Help on method plot in module andes.plot:

plot(yidx, xidx=(0,), *, a=None, ytimes=None, ycalc=None, left=None, right=None, ymin=None, ymax=None, xlabel=None, ylabel=None, xheader=None, yheader=None, legend=None, grid=False, greyscale=False, latex=True, dpi=80, line_width=1.0, font_size=12, savefig=None, save_format=None, show=True, title=None, linestyles=None, use_bqplot=False, hline1=None, hline2=None, vline1=None, vline2=None, hline=None, vline=None, fig=None, ax=None, backend=None, set_xlim=True, set_ylim=True, autoscale=False, legend_bbox=None, legend_loc=None, legend_ncol=1, figsize=None, color=None, **kwargs) method of andes.plot.TDSData instance
    Entry function for plotting.
    This function retrieves the x and y values based on the `xidx` and
    `yidx` inputs, applies scaling functions `ytimes` and `ycalc` sequentially,
    and delegates the plotting to the backend.
    yidx : list or int
        The indices for the y-axis variables
    xidx : tuple or int, optional
        The index for the x-axis variable
    a : tuple or list, optional
        The 0-indexed sub-indices into `yidx` to plot.
    ytimes : float, optional
        A scaling factor to apply to all y values.
    left : float
        The starting value of the x axis
    right : float
        The ending value of the x axis
    ymin : float
        The minimum value of the y axis
    ymax : float
        The maximum value of the y axis
    ylabel : str
        Text label for the y axis
    yheader : list
        A list containing the variable names for the y-axis variable
    title : str
        Title string to be shown at the top
        Existing figure object to draw the axis on.
        Existing axis object to draw the lines on.
    Other Parameters
    ycalc: callable, optional
        A callable to apply to all y values after scaling with `ytimes`.
    xlabel : str
        Text label for the x axis
    xheader : list
        A list containing the variable names for the x-axis variable
    legend : bool
        True to show legend and False otherwise
    legend_ncol : int
        Number of columns in legend
    legend_bbox : tuple of two floats
        legend box to anchor
    grid : bool
        True to show grid and False otherwise
    latex : bool
        True to enable latex and False to disable
    greyscale : bool
        True to use greyscale, False otherwise
    savefig : bool or str
        True to save to png figure file.
        str is treated as the output file name.
    save_format : str
        File extension string (pdf, png or jpg) for the savefig format
    dpi : int
        Dots per inch for screen print or save.
        `savefig` uses a minimum of 200 dpi
    line_width : float
        Plot line width
    font_size : float
        Text font size (labels and legends)
    figsize : tuple
        Figure size passed when creating new figure
    show : bool
        True to show the image
    backend : str or None
        `bqplot` to use the bqplot backend in notebook.
        None for matplotlib.
    hline1: float, optional
        Dashed horizontal line 1
    hline2: float, optional
        Dashed horizontal line 2
    vline1: float, optional
        Dashed horizontal line 1
    vline2: float, optional
        Dashed vertical line 2
    hline: float or Iterable
        y-axis location of horizontal line(s)
    vline: float or Iterable
        x-axis location of vertical line(s)
    (fig, ax)
        Figure and axis handles for matplotlib backend.
        Figure object for bqplot backend.


! andes misc -C
"/home/hacui/repos/andes/examples/kundur_full_out.npz" removed.
"/home/hacui/repos/andes/examples/kundur_full_out.txt" removed.
"/home/hacui/repos/andes/examples/kundur_full_out.lst" removed.
"/home/hacui/repos/andes/examples/kundur_full_out.csv" removed.
!rm kundur_full_out_1.png