andes.cli module

ANDES command-line interface and argument parsers.


The main level of command-line interface.


Main command-line interface


Log the ANDES command-line preamble at the logging.INFO level

andes.main module

andes.main.config_logger(stream=True, file=True, stream_level=20, log_file='andes.log', log_path=None, file_level=10)[source]

Configure an ANDES logger with a FileHandler and a StreamHandler.

This function is called at the beginning of andes.main.main(). Updating stream_level and file_level is now supported.

stream : bool, optional

Create a StreamHandler for stdout if True. If False, the handler will not be created.

file : bool, optionsl

True if logging to log_file.

log_file : str, optional

Logg file name for FileHandler, 'andes.log' by default. If None, the FileHandler will not be created.

log_path : str, optional

Path to store the log file. By default, the path is generated by get_log_dir() in utils.misc.

stream_level : {10, 20, 30, 40, 50}, optional

StreamHandler verbosity level.

file_level : {10, 20, 30, 40, 50}, optional

FileHandler verbosity level.


TODO: show some demonstrations from CLI.

andes.main.doc(attribute=None, list_supported=False, config=False, **kwargs)[source]

Quick documentation from command-line.

andes.main.edit_conf(edit_config: Union[str, bool, None] = '')[source]

Edit the Andes config file which occurs first in the search path.

edit_config : bool

If True, try to open up an editor and edit the config file. Otherwise returns.


True is a config file is found and an editor is opened. False if edit_config is False.


Find the file paths of the FileHandlers.

andes.main.load(case, codegen=False, setup=True, use_input_path=True, **kwargs)[source]

Load a case and set up a system without running routine. Return a system.

Takes other kwargs recognizable by System, such as addfile, input_path, and no_putput.

case: str

Path to the test case

codegen : bool, optional

Call full System.prepare on the returned system. Set to True if one need to inspect pretty-print equations and run simulations.

setup : bool, optional

Call System.setup after loading

use_input_path : bool, optional

True to use the input_path argument to behave the same as

If one need to add devices in addition to these from the case
file, do ``setup=False`` and call ``System.add()`` to add devices.
When done, manually invoke ``setup()`` to set up the system.
andes.main.misc(edit_config='', save_config='', show_license=False, clean=True, recursive=False, overwrite=None, **kwargs)[source]

Miscellaneous commands.


Wrapper for the plot tool.

andes.main.prepare(quick=False, incremental=False, models=None, precompile=False, nomp=False, **kwargs)[source]

Run code generation.

full : bool

True to run full prep with formatted equations. Useful in interactive mode and during document generation.

ncpu : int

Number of cores to be used for parallel processing.

cli : bool

True to indicate running from CLI. It will set quick to True if not full.

precompile : bool

True to compile model function calls after code generation.

System object if cli is False; exit_code 0 otherwise.


The default behavior has changed since v1.0.8: when cli is True and full is not True, quick code generation will be used.


Print out Andes license to stdout.


Remove the outputs generated by Andes, including power flow reports _out.txt, time-domain list _out.lst and data _out.dat, eigenvalue analysis report _eig.txt.

recursive : bool

Recursively clean all subfolders


True is the function body executes with success. False otherwise., input_path='', verbose=20, mp_verbose=30, ncpu=2, pool=False, cli=False, codegen=False, shell=False, **kwargs)[source]

Entry point to run ANDES routines.

filename : str

file name (or pattern)

input_path : str, optional

input search path

verbose : int, 10 (DEBUG), 20 (INFO), 30 (WARNING), 40 (ERROR), 50 (CRITICAL)

Verbosity level. If config_logger is called prior to run, this option will be ignored.

mp_verbose : int

Verbosity level for multiprocessing tasks

ncpu : int, optional

Number of cpu cores to use in parallel

pool: bool, optional

Use Pool for multiprocessing to return a list of created Systems.


Other supported keyword arguments

cli : bool, optional

If is running from command-line. If True, returns exit code instead of System

codegen : bool, optional

Run full code generation for System before loading case. Only used for single test case.

shell : bool, optional

If True, enter IPython shell after routine.

System or exit_code

An instance of system (if cli == False) or an exit code otherwise..

andes.main.run_case(case, *, routine='pflow', profile=False, convert='', convert_all='', add_book=None, codegen=False, remove_pycapsule=False, **kwargs)[source]

Run single simulation case for the given full path. Use run instead of run_case whenever possible.

Argument input_path will not be prepended to case.

Arguments recognizable by load can be passed to run_case.

case : str

Full path to the test case

routine : str, ('pflow', 'tds', 'eig')

Computation routine to run

profile : bool, optional

True to enable profiler

convert : str, optional

Format name for case file conversion.

convert_all : str, optional

Format name for case file conversion, output sheets for all available devices.

add_book : str, optional

Name of the device to be added to an excel case as a new sheet.

codegen : bool, optional

True to run codegen

remove_pycapsule : bool, optional

True to remove pycapsule from C libraries. Useful when dill serialization is needed.

andes.main.save_conf(config_path=None, overwrite=None, **kwargs)[source]

Save the Andes config to a file at the path specified by save_config. The save action will not run if save_config = ''.

config_path : None or str, optional, ('' by default)

Path to the file to save the config file. If the path is an emtpy string, the save action will not run. Save to ~/.andes/andes.conf if None.


True is the save action is run. False otherwise.

andes.main.selftest(quick=False, **kwargs)[source]

Run unit tests.

andes.main.set_logger_level(lg, type_to_set, level)[source]

Set logging level for the given type of handler.

andes.plot module

The Andes plotting tool.

class andes.plot.TDSData(full_name=None, mode='file', dae=None, path=None)[source]

Bases: object

A data container for loading and plotting results from Andes time-domain simulation.

bqplot_data(xdata, ydata, *, xheader=None, yheader=None, xlabel=None, ylabel=None, left=None, right=None, ymin=None, ymax=None, legend=True, grid=False, fig=None, dpi=100, line_width=1.0, greyscale=False, savefig=None, save_format=None, title=None, **kwargs)[source]

Plot with bqplot. Experimental and incomplete.


Convert to pandas.DataFrame

export_csv(path=None, idx=None, header=None, formatted=False, sort_idx=True, fmt='%.18e')[source]

Export to a csv file.

path : str

path of the csv file to save

idx : None or array-like, optional

the indices of the variables to export. Export all by default

header : None or array-like, optional

customized header if not None. Use the names from the lst file by default

formatted : bool, optional

Use LaTeX-formatted header. Does not apply when using customized header

sort_idx : bool, optional

Sort by idx or not, # TODO: implement sort

fmt : str

cell formatter

find(query, exclude=None, formatted=False, idx_only=False)[source]

Return variable names and indices matching query.

query : str

The string for querying variables. Multiple conditions can be separated by comma without space.

exclude : str, optional

A string pattern to be excluded

formatted : bool, optional

True to return formatted names, False otherwise

idx_only : bool, optional

True if only return indices

(list, list)

(List of found indices, list of found names)


Get the internal plot_data function for the specified backend.

get_header(idx, formatted=False)[source]

Return a list of the variable names at the given indices.

idx : list or int

The indices of the variables to retrieve

formatted : bool

True to retrieve latex-formatted names, False for unformatted names


A list of variable names (headers)


Return the variable values at the given indices.

idx : list

The indicex of the variables to retrieve. idx=0 is for Time. Variable indices start at 1.


Variable data


Guess the event starting time from the input data by checking when the values start to change


Load from DAE time series


Load the lst file into internal data structures _idx, _fname, _uname, and counts the number of variables to nvars.

load_npy_or_csv(delimiter=', ')[source]

Load the npy, zpy or (the legacy) csv file into the internal data structure self._xy.

delimiter : str, optional

The delimiter for the case file. Default to comma.

panoview(mdl, *, ncols=3, vars=None, idx=None, a=None, figsize=None, **kwargs)[source]

Panoramic view of variables of a given model instance.

Select variables through vars. Select devices through idx or a, which has a higher priority.

This function also takes other arguments recognizable by self.plot.

mdl : ModelBase

Model instance

ncol : int

Number of columns

var : list of str

A list of variable names to display

idx : list

A list of device idx-es for showing

a : list of int

A list of device 0-based positions for showing

figsize : tuple

Figure size for plotting


To plot omega and delta of GENROUs GENROU_1 and GENROU_2:

                    vars=['omega', 'delta'],
                    idx=['GENROU_1', 'GENROU_2'])
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=100, 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)[source]

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.

(fig, ax)

Figure and axis handles for matplotlib backend.


Figure object for bqplot backend.

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)

plot_data(xdata, ydata, *, xheader=None, yheader=None, xlabel=None, ylabel=None, linestyles=None, left=None, right=None, ymin=None, ymax=None, legend=None, grid=False, fig=None, ax=None, latex=True, dpi=100, line_width=1.0, font_size=12, greyscale=False, savefig=None, save_format=None, show=True, title=None, hline1=None, hline2=None, vline1=None, hline=None, vline=None, vline2=None, set_xlim=True, set_ylim=True, autoscale=False, figsize=None, legend_bbox=None, legend_loc=None, legend_ncol=1, mask=True, color=None, **kwargs)[source]

Plot lines for the supplied data and options.

This functions takes xdata and ydata values. If you provide variable indices instead of values, use plot().

See the argument lists of plot() for more.

xdata : array-like

An array-like object containing the values for the x-axis variable

ydata : array

An array containing the values of each variables for the y-axis variable. The row of ydata must match the row of xdata. Each column correspondings to a variable.

mask : bool

If enabled (1), when specifying axis limits, only data in the limits will be used for plotting to optimize for autoscaling. It is done through an index mask.

(fig, ax)

The figure and axis handles


To plot the results of arithmetic calculation of variables, retrieve the values, do the calculation, and plot with plot_data.

>>> v = ss.dae.ts.y[:, ss.PVD1.v.a]
>>> Ipcmd = ss.dae.ts.y[:, ss.PVD1.Ipcmd_y.a]
>>> t = ss.dae.ts.t
>>> ss.TDS.plt.plot_data(t, v * Ipcmd,
>>>                      xlabel='Time [s]',
>>>                      ylabel='Ipcmd [pu]')
plotn(nrows: int, ncols: int, yidxes, xidxes=None, *, dpi=100, titles=None, a=None, figsize=None, xlabel=None, ylabel=None, sharex=None, sharey=None, show=True, xlabel_offs=(0.5, 0.01), ylabel_offs=(0.05, 0.5), hspace=0.2, wspace=0.2, **kwargs)[source]

Plot multiple subfigures in one figure.

Parameters xidxes, a, xlabels and ylabels, if provided, must have the same length as yidxes.

nrows : int

number of rows

ncols : int

number of cols


A list of BaseVar or index lists.

andes.plot.eig_plot(name, args)[source]

Convert a label to latex format by appending surrounding $ and escaping spaces

label : str

The label string to be converted to latex expression


A string with $ surrounding

andes.plot.parse_y(y, upper, lower=0)[source]

Parse command-line input for Y indices and return a list of indices

y : Union[List, Set, Tuple]
Input for Y indices. Could be single item (with or without colon), or

multiple items

upper : int

Upper limit. In the return list y, y[i] <= uppwer.

lower : int

Lower limit. In the return list y, y[i] >= lower.


Return a lambda function that scales its input by k

k : float

The scaling factor of the returned lambda function

Lambda function
andes.plot.tdsplot(filename, y, x=(0, ), to_csv=False, find=None, xargs=None, exclude=None, **kwargs)[source]

TDS plot main function based on the new TDSData class.

filename : str

Path to the ANDES TDS output data file. Works without extension.

x : list or int, optional

The index for the x-axis variable. x=0 by default for time

y : list or int

The indices for the y-axis variable

to_csv : bool

True if need to export to a csv file

find : str, optional

if not none, specify the variable name to find

xargs : str, optional

similar to find, but return the result indices with file name, x idx name for xargs

exclude : str, optional

variable name pattern to exclude

TDSData object

andes.shared module

Shared constants and delayed imports.

This module imports shared libraries either directly or with LazyImport.

LazyImport shall only be used to imported


Enables LaTeX for matplotlib based on the with_latex option and dvipng availability.


True for LaTeX on, False for off

andes.system module

System class for power system data and methods

class andes.system.ExistingModels[source]

Bases: object

Storage class for existing models

class andes.system.System(case: Optional[str] = None, name: Optional[str] = None, config: Optional[Dict[KT, VT]] = None, config_path: Optional[str] = None, default_config: Optional[bool] = False, options: Optional[Dict[KT, VT]] = None, no_undill: Optional[bool] = False, **kwargs)[source]

Bases: object

System contains models and routines for modeling and simulation.

System contains a several special OrderedDict member attributes for housekeeping. These attributes include models, groups, routines and calls for loaded models, groups, analysis routines, and generated numerical function calls, respectively.

no_undill : bool, optional

True to disable the call to System.undill() at the end of object creation. False by default.


System stores model and routine instances as attributes. Model and routine attribute names are the same as their class names. For example, Bus is stored at system.Bus, the power flow calculation routine is at system.PFlow, and the numerical DAE instance is at system.dae. See attributes for the list of attributes.

dae : andes.variables.dae.DAE

Numerical DAE storage

files : andes.variables.fileman.FileMan

File path storage

config : andes.core.Config

System config storage

models : OrderedDict

model name and instance pairs

groups : OrderedDict

group name and instance pairs

routines : OrderedDict

routine name and instance pairs

add(model, param_dict=None, **kwargs)[source]

Add a device instance for an existing model.

This methods calls the add method of model and registers the device idx to group.

as_dict(vin=False, skip_empty=True)[source]

Return system data as a dict where the keys are model names and values are dicts. Each dict has parameter names as keys and corresponding data in an array as values.


Perform per unit value conversion.

This function calculates the per unit conversion factors, stores input parameters to vin, and perform the conversion.

call_models(method: str, models: collections.OrderedDict, *args, **kwargs)[source]

Call methods on the given models.

method : str

Name of the model method to be called

models : OrderedDict, list, str

Models on which the method will be called


Positional arguments to be passed to the model method


Keyword arguments to be passed to the model method

The return value of the models in an OrderedDict

Collect indices into BackRef for all models.


Perform connectivity check for system.

info : bool

True to log connectivity summary.


Serialize generated numerical functions in System.calls with package dill.

The serialized file will be stored to ~/.andes/calls.pkl, where ~ is the home directory path.


This function sets dill.settings['recurse'] = True to serialize the function calls recursively.

e_clear(models: collections.OrderedDict)[source]

Clear equation arrays in DAE and model variables.

This step must be called before calling f_update or g_update to flush existing values.

f_update(models: collections.OrderedDict)[source]

Call the differential equation update method for models in sequence.


Updated equation values remain in models and have not been collected into DAE at the end of this step.


Collect equation values into the DAE arrays.

Additionally, the function resets the differential equations associated with variables pegged by anti-windup limiters.


Add dependent devices for all model based on DeviceFinder.

find_models(flag: Union[str, Tuple, None], skip_zero: bool = True)[source]

Find models with at least one of the flags as True.

flag : list, str

Flags to find

skip_zero : bool

Skip models with zero devices


model name : model instance


Checking the number of devices has been centralized into this function. models passed to most System calls must be retrieved from here.


Fixes addressing issues after loading a snapshot.

This function properly sets v and e of internal variables as views of the corresponding DAE arrays.

Inputs will be refreshed for each model.

from_ipysheet(model: str, sheet, vin: bool = False)[source]

Set an ipysheet object back to model.


Reset algebraic mismatches for islanded buses.

g_update(models: collections.OrderedDict)[source]

Call the algebraic equation update method for models in sequence.


Like f_update, updated values have not collected into DAE at the end of the step.


Collect config data from models.


a dict containing the config from devices; class names are keys and configs in a dict are values.

get_z(models: collections.OrderedDict)[source]

Get all discrete status flags in a numpy array. Values are written to dae.z in place.


Import all groups classes defined in devices/

Groups will be stored as instances with the name as class names. All groups will be stored to dictionary System.groups.


Import and instantiate models as System member attributes.

Models defined in models/ will be instantiated sequentially as attributes with the same name as the class name. In addition, all models will be stored in dictionary System.models with model names as keys and the corresponding instances as values.


system.Bus stores the Bus object, and system.GENCLS stores the classical generator object,

system.models['Bus'] points the same instance as system.Bus.


Import routines as defined in routines/

Routines will be stored as instances with the name as class names. All groups will be stored to dictionary System.groups.


System.PFlow is the power flow routine instance, and System.TDS and System.EIG are time-domain analysis and eigenvalue analysis routines, respectively.

init(models: collections.OrderedDict, routine: str)[source]

Initialize the variables for each of the specified models.

For each model, the initialization procedure is:

  • Get values for all ExtService.
  • Call the model init() method, which initializes internal variables.
  • Copy variables to DAE and then back to the model.

Set gy diagonals to eps for a and v variables of islanded buses.

j_update(models: collections.OrderedDict, info=None)[source]

Call the Jacobian update method for models in sequence.

The procedure is - Restore the sparsity pattern with andes.variables.dae.DAE.restore_sparse() - For each sparse matrix in (fx, fy, gx, gy), evaluate the Jacobian function calls and add values.


Updated Jacobians are immediately reflected in the DAE sparse matrices (fx, fy, gx, gy).

l_update_eq(models: collections.OrderedDict, init=False)[source]

Update equation-dependent limiter discrete components by calling l_check_eq of models. Force set equations after evaluating equations.

This function is must be called after differential equation updates.

l_update_var(models: collections.OrderedDict, niter=None, err=None)[source]

Update variable-based limiter discrete states by calling l_update_var of models.

This function is must be called before any equation evaluation.

Retrieve values for ExtParam for the given models.

static load_config(conf_path=None)[source]

Load config from an rc-formatted file.

conf_path : None or str

Path to the config file. If is None, the function body will not run.

precompile(models: Optional[collections.OrderedDict] = None, nomp: bool = False, ncpu: int = 2)[source]

Trigger precompilation for the given models.

Arguments are the same as prepare.

prepare(quick=False, incremental=False, models=None, nomp=False, ncpu=2)[source]

Generate numerical functions from symbolically defined models.

All procedures in this function must be independent of test case.

quick : bool, optional

True to skip pretty-print generation to reduce code generation time.

incremental : bool, optional

True to generate only for modified models, incrementally.

models : list, OrderedDict, None

List or OrderedList of models to prepare

nomp : bool

True to disable multiprocessing


Generated lambda functions will be serialized to file, but pretty prints (SymPy objects) can only exist in the System instance on which prepare is called.


Option incremental compares the md5 checksum of all var and service strings, and only regenerate for updated models.


If one needs to print out LaTeX-formatted equations in a Jupyter Notebook, one need to generate such equations with

import andes
sys = andes.prepare()

Alternatively, one can explicitly create a System and generate the code

import andes
sys = andes.System()
reload(case, **kwargs)[source]

Reload a new case in the same System object.


Remove PyCapsule objects in solvers.


Reset to the state after reading data and setup (before power flow).


If TDS is initialized, reset will lead to unpredictable state.

s_update_post(models: collections.OrderedDict)[source]

Update variable services by calling s_update_post of models.

This function is called at the end of System.init().

s_update_var(models: collections.OrderedDict)[source]

Update variable services by calling s_update_var of models.

This function is must be called before any equation evaluation after limiter update function l_update_var.

save_config(file_path=None, overwrite=False)[source]

Save all system, model, and routine configurations to an rc-formatted file.

file_path : str, optional

path to the configuration file default to ~/andes/andes.rc.

overwrite : bool, optional

If file exists, True to overwrite without confirmation. Otherwise prompt for confirmation.


Saved config is loaded back and populated at system instance creation time. Configs from the config file takes precedence over default config values.


Set addresses for differential and algebraic variables.


Set configuration for the System object.

Config for models are routines are passed directly to their constructors.


Set variable names for differential and algebraic variables, right-hand side of external equations, and discrete flags.

set_var_arrays(models, inplace=True, alloc=True)[source]

Set arrays (v and e) for internal variables to access dae arrays in place.

This function needs to be called after de-serializing a System object, where the internal variables are incorrectly assigned new memory.

models : OrderedDict, list, Model, optional

Models to execute.

inplace : bool

True to retrieve arrays that share memory with dae

alloc : bool

True to allocate for arrays internally


Set up system for studies.

This function is to be called after adding all device data.


Store non-inplace adders and setters for variables and equations.


Store existing models in System.existing.

TODO: Models with TimerParam will need to be stored anyway. This will allow adding switches on the fly.


Store differential variables with check_init == False.

store_sparse_pattern(models: collections.OrderedDict)[source]

Collect and store the sparsity pattern of Jacobian matrices.

This is a runtime function specific to cases.


For gy matrix, always make sure the diagonal is reserved. It is a safeguard if the modeling user omitted the diagonal term in the equations.

store_switch_times(models, eps=0.0001)[source]

Store event switching time in a sorted Numpy array in System.switch_times and an OrderedDict System.switch_dict.

System.switch_dict has keys as event times and values as the OrderedDict of model names and instances associated with the event.

models : OrderedDict

model name : model instance

eps : float

The small time step size to use immediately before and after the event




Print out system summary.


Return the support group names and model names in a table.


A table-formatted string for the groups and models

switch_action(models: collections.OrderedDict)[source]

Invoke the actions associated with switch times.

Switch actions will be disabled if flat=True is passed to system.

to_ipysheet(model: str, vin: bool = False)[source]

Return an ipysheet object for editing in Jupyter Notebook.


Deserialize the function calls from ~/.andes/calls.pkl with dill.

If no change is made to models, future calls to prepare() can be replaced with undill() for acceleration.


Copy variables values from models to System.dae.

This function clears DAE.x and DAE.y and collects values from models.


Copy variable values from System.dae to models.


Helper function to load pycode from .andes.


Helper function for reloading an existing module and its submodules.

It is used to reload the pycode module after regenerating code.