Subpackages¶
Submodules¶
andes.cli module¶
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
. IfFalse
, 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. IfNone
, 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
ifedit_config
is False.
-
andes.main.
load
(case, codegen=False, setup=True, **kwargs)[source]¶ Load a case and set up a system without running routine. Return a system.
Takes other kwargs recognizable by
System
, such asaddfile
,input_path
, andno_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
- 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.
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.
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 ofrun_case
whenever possible.Arguments recognizable by
load
can be passed torun_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 ifsave_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.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, latex=True, dpi=150, line_width=1.0, greyscale=False, savefig=None, save_format=None, title=None, **kwargs)[source]¶ Plot with
bqplot
. Experimental and incomplete.
-
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_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_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=150, 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, **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
True to save to png figure file
- 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)
- 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=150, 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, 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=150, 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
andylabels
, if provided, must have the same length asyidxes
.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.
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, ), tocsv=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
- tocsv : 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.system module¶
System class for power system data and methods
-
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 atsystem.PFlow
, and the numerical DAE instance is atsystem.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
-
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 packagedill
.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_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.
-
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 dictionarySystem.models
with model names as keys and the corresponding instances as values.Examples
system.Bus
stores the Bus object, andsystem.GENCLS
stores the classical generator object,system.models['Bus']
points the same instance assystem.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, andSystem.TDS
andSystem.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_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.
-
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()
-
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_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_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 OrderedDictSystem.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
-
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.
-
undill
()[source]¶ Deserialize the function calls from
~/.andes/calls.pkl
withdill
.If no change is made to models, future calls to
prepare()
can be replaced withundill()
for acceleration.