Submodules

andes.cli module

andes.cli.create_parser()[source]

The main level of command-line interface.

andes.cli.main()[source]

Main command-line interface

andes.cli.preamble()[source]

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 a logger for the andes package with options for a FileHandler and a StreamHandler. This function is called at the beginning of andes.main.main().

Parameters:
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.

Returns
-------
None
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.

Parameters:
edit_config : bool

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

True is a config file is found and an editor is opened. False if edit_config is False.
andes.main.find_log_path(lg)[source]

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.

Parameters:
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 andes.main.run.

Warnings
-------
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]

Misc functions.

andes.main.plot(**kwargs)[source]

Wrapper for the plot tool.

andes.main.prepare(quick=False, incremental=False, cli=False, full=False, **kwargs)[source]

Run code generation.

Returns:
System object if cli is False; exit_code 0 otherwise.

Warning

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

andes.main.print_license()[source]

Print out Andes license to stdout.

andes.main.remove_output(recursive=False)[source]

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.

Parameters:
recursive : bool

Recursively clean all subfolders
Returns:
bool

True is the function body executes with success. False otherwise.
andes.main.run(filename, 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.

Parameters:
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

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.

kwargs

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.
Returns:
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.

Parameters:
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)[source]

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

Parameters:
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.
Returns:
bool

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.

data_to_df()[source]

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.

Parameters:
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.

Parameters:
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
Returns:
(list, list)

(List of found indices, list of found names)
get_call(backend=None)[source]

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.

Parameters:
idx : list or int

The indices of the variables to retrieve

formatted : bool

True to retrieve latex-formatted names, False for unformatted names
Returns:
list

A list of variable names (headers)
get_values(idx)[source]

Return the variable values at the given indices.

Parameters:
idx : list

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

Variable data
guess_event_time()[source]

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

load_dae()[source]

Load from DAE time series

load_lst()[source]

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

Returns:
None
load_npy_or_csv(delimiter=', ')[source]

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

Parameters:
delimiter : str, optional

The delimiter for the case file. Default to comma.
Returns:
None
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, fig=None, ax=None, backend=None, set_xlim=True, set_ylim=True, autoscale=False, legend_bbox=None, legend_loc=None, figsize=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.

Parameters:
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

fig

Existing figure object to draw the axis on.

ax

Existing axis object to draw the lines on.
Returns:
(fig, ax)

Figure and axis handles for matplotlib backend.

fig

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

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
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, vline2=None, set_xlim=True, set_ylim=True, autoscale=False, figsize=None, legend_bbox=None, legend_loc=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.

Parameters:
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.
Returns:
(fig, ax)

The figure and axis handles

Examples

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.

Parameters:
nrows : int

number of rows

ncols : int

number of cols

yidx

A list of BaseVar or index lists.
andes.plot.check_init(yval, yl)[source]

" Check initialization by comparing t=0 and t=end values for a flat run.

Warning

This function is deprecated as the initialization check feature is built into TDS. See TDS.test_initialization().

andes.plot.eig_plot(name, args)[source]
andes.plot.isfloat(value)[source]
andes.plot.isint(value)[source]
andes.plot.label_latexify(label)[source]

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

Parameters:
label : str

The label string to be converted to latex expression
Returns:
str

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

Parameters:
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.
andes.plot.scale_func(k)[source]

Return a lambda function that scales its input by k

Parameters:
k : float

The scaling factor of the returned lambda function

Returns
-------
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.

Parameters:
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
Returns:
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

andes.shared.set_latex()[source]

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

Returns:
bool

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, **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.

Notes

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.

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.

Returns:
OrderedDict
calc_pu_coeff()[source]

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.

Parameters:
method : str

Name of the model method to be called

models : OrderedDict, list, str

Models on which the method will be called

args

Positional arguments to be passed to the model method

kwargs

Keyword arguments to be passed to the model method
Returns:
The return value of the models in an OrderedDict
collect_ref()[source]

Collect indices into BackRef for all models.

connectivity(info=True)[source]

Perform connectivity check for system.

Parameters:
info : bool

True to log connectivity summary.
dill()[source]

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.

Notes

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.

Notes

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

fg_to_dae()[source]

Collect equation values into the DAE arrays.

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

find_devices()[source]

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.

Parameters:
flag : list, str

Flags to find

skip_zero : bool

Skip models with zero devices
Returns:
OrderedDict

model name : model instance

Warning

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

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

Set an ipysheet object back to model.

g_islands()[source]

Reset algebraic mismatches for islanded buses.

g_update(models: collections.OrderedDict)[source]

Call the algebraic equation update method for models in sequence.

Notes

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

get_config()[source]

Collect config data from models.

Returns:
dict

a dict containing the config from devices; class names are keys and configs in a dict are values.
get_ext_fg(model: collections.OrderedDict)[source]

Get the right-hand side of the external equations.

get_z(models: collections.OrderedDict)[source]

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

Returns:
numpy.array
import_groups()[source]

Import all groups classes defined in devices/group.py.

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

import_models()[source]

Import and instantiate models as System member attributes.

Models defined in models/__init__.py 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.

Examples

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()[source]

Import routines as defined in routines/__init__.py.

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

Examples

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.
j_islands()[source]

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.

Notes

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

l_update_eq(models: collections.OrderedDict)[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.

Parameters:
conf_path : None or str

Path to the config file. If is None, the function body will not run.
Returns:
configparse.ConfigParser
prepare(quick=False, incremental=False)[source]

Generate numerical functions from symbolically defined models.

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

Parameters:
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.

Warning

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.

Notes

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

Examples

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()
sys.prepare()
reload(case, **kwargs)[source]

Reload a new case in the same System object.

remove_pycapsule()[source]

Remove PyCapsule objects in solvers.

reset(force=False)[source]

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

Warning

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.

Parameters:
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.

Warning

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

set_address(models)[source]

Set addresses for differential and algebraic variables.

set_config(config=None)[source]

Set configuration for the System object.

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

set_dae_names(models)[source]

Set variable names for differential and algebraic variables, and discrete flags.

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

Set arrays (v and e) in internal variables.

Parameters:
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
setup()[source]

Set up system for studies.

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

store_adder_setter(models)[source]

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

store_existing()[source]

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_no_check_init(models)[source]

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.

Notes

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.

Parameters:
models : OrderedDict

model name : model instance

eps : float

The small time step size to use immediately before and after the event
Returns:
array-like

self.switch_times
summary()[source]

Print out system summary.

supported_models(export='plain')[source]

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

Returns:
str

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.

undill()[source]

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.

vars_to_dae(model)[source]

Copy variables values from models to System.dae.

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

vars_to_models()[source]

Copy variable values from System.dae to models.