Tutorial¶

ANDES can be used as a command-line tool or a library. The command-line interface (CLI) comes handy to run studies. As a library, it can be used interactively in the IPython shell or the Jupyter Notebook. This chapter describes the most common usages.

Please see the cheat sheet if you are looking for quick help.

Command Line Usage¶

Basic Usage¶

ANDES is invoked from the command line using the command andes. Running andes without any input is equal to andes -h or andes --help. It prints out a preamble with version and environment information and help commands:

    _           _         | Version 1.1.2
   /_\  _ _  __| |___ ___ | Python 3.7.6 on Linux, 09/05/2020 12:23:05 PM
  / _ \| ' \/ _` / -_|_-< |
 /_/ \_\_||_\__,_\___/__/ | This program comes with ABSOLUTELY NO WARRANTY.

usage: andes [-h] [-v {1,10,20,30,40,50}]
             {run,plot,doc,misc,prepare,selftest} ...

positional arguments:
  {run,plot,doc,misc,prepare,selftest}
                        [run] run simulation routine; [plot] plot simulation
                        results; [doc] quick documentation; [prepare] run the
                        symbolic-to-numeric preparation; [misc] miscellaneous
                        functions.

optional arguments:
  -h, --help            show this help message and exit
  -v {1,10,20,30,40,50}, --verbose {1,10,20,30,40,50}
                        Program logging level in 10-DEBUG, 20-INFO,
                        30-WARNING, 40-ERROR or 50-CRITICAL.

Note

If the andes command is not found, check if (1) the installation was successful, and (2) you have activated the environment where ANDES is installed.

The first level of commands are chosen from {run,plot,misc,prepare,selftest}. Each command contains a group of sub-commands, which can be looked up with -h. For example, use andes run -h to look up the sub-commands in run. The most commonly used commands will be explained in the following.

andes has an option for the program verbosity level, controlled by -v or --verbose. Accepted levels are the same as in the logging module: 10 - DEBUG, 20 - INFO, 30 - WARNING, 40 - ERROR, 50 - CRITICAL. To show debugging outputs, use -v 10.

andes selftest¶

After installation, it is encouraged to use andes selftest from the command line to test functionality. It might take a minute to run the full self-test suite. An example output looks like

test_docs (test_1st_system.TestCodegen) ... ok
test_alter_param (test_case.Test5Bus) ... ok
...
... (outputs are omitted)
...
test_pflow_mpc (test_pflow_matpower.TestMATPOWER) ... ok

----------------------------------------------------------------------
Ran 23 tests in 13.834s

OK

There may be more cases than what is shown above. Make sure that all tests have passed.

Warning

ANDES is getting updates frequently. After updating your copy, please run andes selftest to confirm the functionality. The command also makes sure the generated code is up to date. See andes prepare for more details on automatic code generation.

andes prepare¶

The symbolically defined models in ANDES need to be generated into numerical code for simulation. The code generation can be manually called with andes prepare. Generated code are stored in the folder .andes/calls.pkl in your home directory. In addition, andes selftest implicitly calls the code generation. If you are using ANDES as a package in the user mode, you won't need to call it again.

Option -q or --quick (enabled by default) can be used to speed up the code generation. It skips the generation of $\LaTeX$-formatted equations, which are only used in documentation and the interactive mode.

For developers, andes prepare needs to be called immediately following any model equation modification. Otherwise, simulation results will not reflect the new equations and will likely lead to an error. Option -i or --incremental, instead of -q, can be used to further speed up the code generation during model development. andes prepare -i only generates code for models with modified equations.

andes run¶

andes run is the entry point for power system analysis routines. andes run takes one positional argument, filename , along with other optional keyword arguments. filename is the test case path, either relative or absolute. Without other options, ANDES will run power flow calculation for the provided file.

Routine¶

Option -r or -routine is used for specifying the analysis routine, followed by the routine name. Available routine names include pflow, tds, eig. pflow for power flow, tds for time domain simulation, and eig for eigenvalue analysis. pflow is default even if -r is not given.

For example, to run time-domain simulation for kundur_full.xlsx in the current directory, run

andes run kundur_full.xlsx -r tds

The file is located at andes/cases/kundur/kundur_full.xlsx relative to the source code root folder. Use cd to change directory to that folder on your machine.

Two output files, kundur_full_out.lst and kundur_full_out.npy will be created for variable names and values, respectively.

Likewise, to run eigenvalue analysis for kundur_full.xlsx, use

andes run kundur_full.xlsx -r eig

The eigenvalue report will be written in a text file named kundur_full_eig.txt.

Power flow¶

To perform a power flow study for test case named kundur_full.xlsx in the current directory, run

andes run kundur_full.xlsx

The full path to the case file is also accepted, for example,

andes run /home/user/andes/cases/kundur/kundur_full.xlsx

Power flow reports will be saved to the current directory in which andes is called. The power flow report contains four sections: a) system statistics, b) ac bus and dc node data, c) ac line data, and d) the initialized values of other algebraic variables and state variables.

Time-domain simulation¶

To run the time domain simulation (TDS) for kundur_full.xlsx, run

andes run kundur_full.xlsx -r tds

The output looks like:

Parsing input file </Users/user/repos/andes/tests/kundur_full.xlsx>
Input file kundur_full.xlsx parsed in 0.5425 second.
-> Power flow calculation with Newton Raphson method:
0: |F(x)| = 14.9283
1: |F(x)| = 3.60859
2: |F(x)| = 0.170093
3: |F(x)| = 0.00203827
4: |F(x)| = 3.76414e-07
Converged in 5 iterations in 0.0080 second.
Report saved to </Users/user/repos/andes/tests/kundur_full_out.txt> in 0.0036 second.
-> Time Domain Simulation:
Initialization tests passed.
Initialization successful in 0.0152 second.
  0%|                                                    | 0/100 [00:00<?, ?%/s]
  <Toggle 0>: Applying status toggle on Line idx=Line_8
100%|██████████████████████████████████████████| 100/100 [00:03<00:00, 28.99%/s]
Simulation completed in 3.4500 seconds.
TDS outputs saved in 0.0377 second.
-> Single process finished in 4.4310 seconds.

This execution first solves the power flow as a starting point. Next, the numerical integration simulates 20 seconds, during which a predefined breaker opens at 2 seconds.

TDS produces two output files by default: a NumPy data file ieee14_syn_out.npy and a variable name list file ieee14_syn_out.lst. The list file contains three columns: variable indices, variable name in plain text, and variable name in the $\LaTeX$ format. The variable indices are needed to plot the needed variable.

Disable output¶

The output files can be disabled with option --no-output or -n. It is useful when only computation is needed without saving the results.

Profiling¶

Profiling is useful for analyzing the computation time and code efficiency. Option --profile enables the profiling of ANDES execution. The profiling output will be written in two files in the current folder, one ending with _prof.txt and the other one with _prof.prof.

The text file can be opened with a text editor, and the .prof file can be visualized with snakeviz, which can be installed with pip install snakeviz.

If the output is disabled, profiling results will be printed to stdio.

Multiprocessing¶

ANDES takes multiple files inputs or wildcard. Multiprocessing will be triggered if more than one valid input files are found. For example, to run power flow for files with a prefix of case5 and a suffix (file extension) of .m, run

andes run case5*.m

Test cases that match the pattern, including case5.m and case57.m, will be processed.

Option --ncpu NCPU can be used to specify the maximum number of parallel processes. By default, all cores will be used. A small number can be specified to increase operation system responsiveness.

Format converter¶

ANDES recognizes a few input formats and can convert input systems into the xlsx format. This function is useful when one wants to use models that are unique in ANDES.

The command for converting is --convert (or -c), following the output format (only xlsx is currently supported). For example, to convert case5.m into the xlsx format, run

andes run case5.m --convert xlsx

The output messages will look like

Parsing input file </Users/user/repos/andes/cases/matpower/case5.m>
CASE5  Power flow data for modified 5 bus, 5 gen case based on PJM 5-bus system
Input file case5.m parsed in 0.0033 second.
xlsx file written to </Users/user/repos/andes/cases/matpower/case5.xlsx>
Converted file /Users/user/repos/andes/cases/matpower/case5.xlsx written in 0.5079 second.
-> Single process finished in 0.8765 second.

Note that --convert will only create sheets for existing models.

In case one wants to create template sheets to add models later, --convert-all can be used instead.

If one wants to add workbooks to an existing xlsx file, one can combine option --add-book ADD_BOOK (or -b ADD_BOOK), where ADD_BOOK can be a single model name or comma-separated model names (without any space). For example,

andes run kundur.raw -c -b Toggler

will convert file kundur.raw into an ANDES xlsx file (kundur.xlsx) and add a template workbook for Toggler.

Warning

With --add-book, the xlsx file will be overwritten. Any empty or non-existent models will be REMOVED.

PSS/E inputs¶

To work with PSS/E input files (.raw and .dyr), one need to provide the raw file as casefile and pass the dyr file to --addfile. For example, in andes/andes/cases/wecc, one can run the power flow using

andes run wecc.raw

and run a no-disturbance time-domain simulation using

andes run wecc.raw --addfile wecc_full.dyr -r tds

To create add a disturbance, there are two options. The recommended option is to convert the PSS/E data into an ANDES xlsx file, edit and run (see the previous subsection).

The alternative is to edit the dyr file and append lines customized for ANDES models. This is for advanced users after referring to andes/io/psse-dyr.yaml, at the end of which one can find the format of Toggler:

# === Custom Models ===
Toggler:
    inputs:
        - model
        - dev
        - t

To define two Togglers in the dyr file, one can append lines to the end of the file using, for example,

Line   'Toggler'  Line_2  1 /
Line   'Toggler'  Line_2  1.1 /

which is separated by spaces and ended with a slash. The second parameter is fixed to the model name quoted by a pair of single quotation marks, and the others correspond to the fields defined in the above``inputs``.

Note

When working with PSS/E data, the recommended practice is to edit model dynamic parameters directly in the dyr file so that the data can be easily used by other tools.

andes plot¶

andes plot is the command-line tool for plotting. It currently supports time-domain simulation data. Three positional arguments are required, and a dozen of optional arguments are supported.

positional arguments:

Argument Description

filename simulation output file name, which should end with out. File extension can be omitted.

x the X-axis variable index, typically 0 for Time

y Y-axis variable indices. Space-separated indices or a colon-separated range is accepted

For example, to plot the generator speed variable of synchronous generator 1 omega GENROU 0 versus time, read the indices of the variable (2) and time (0), run

andes plot kundur_full_out.lst 0 2

In this command, andes plot is the plotting command for TDS output files. kundur_full_out.lst is list file name. 0 is the index of Time for the x-axis. 2 is the index of omega GENROU 0. Note that for the the file name, either kundur_full_out.lst or kundur_full_out.npy works, as the program will automatically extract the file name.

The y-axis variabla indices can also be specified in the Python range fashion . For example, andes plot kundur_full_out.npy 0 2:21:6 will plot the variables at indices 2, 8, 14 and 20.

andes plot will attempt to render with $\LaTeX$ if dvipng program is in the search path. Figures rendered by $\LaTeX$ is considerably better in symbols quality but takes much longer time. In case $\LaTeX$ is available but fails (frequently happens on Windows), the option -d can be used to disable $\LaTeX$ rendering.

Other optional arguments are listed in the following.

optional arguments:

Argument	Description
optional arguments:
-h, --help	show this help message and exit
--xmin LEFT	minimum value for X axis
--xmax RIGHT	maximum value for X axis
--ymax YMAX	maximum value for Y axis
--ymin YMIN	minimum value for Y axis
--find FIND	find variable indices that matches the given pattern
--xargs XARGS	find variable indices and return as a list of arguments usable with "\| xargs andes plot"
--exclude EXCLUDE	pattern to exclude in find or xargs results
-x XLABEL, --xlabel XLABEL	x-axis label text
-y YLABEL, --ylabel YLABEL	y-axis label text
-s, --savefig	save figure. The default fault is png.
-format SAVE_FORMAT	format for savefig. Common formats such as png, pdf, jpg are supported
--dpi DPI	image resolution in dot per inch (DPI)
-g, --grid	grid on
--greyscale	greyscale on
-d, --no-latex	disable LaTeX formatting
-n, --no-show	do not show the plot window
--ytimes YTIMES	scale the y-axis values by YTIMES
-c, --tocsv	convert npy output to csv

andes doc¶

andes doc is a tool for quick lookup of model and routine documentation. It is intended as a quick way for documentation.

The basic usage of andes doc is to provide a model name or a routine name as the positional argument. For a model, it will print out model parameters, variables, and equations to the stdio. For a routine, it will print out fields in the Config file. If you are looking for full documentation, visit andes.readthedocs.io.

For example, to check the parameters for model Toggler, run

$ andes doc Toggler
Model <Toggler> in Group <TimedEvent>

    Time-based connectivity status toggler.

Parameters

 Name  |         Description          | Default | Unit |    Type    | Properties
-------+------------------------------+---------+------+------------+-----------
 u     | connection status            | 1       | bool | NumParam   |
 name  | device name                  |         |      | DataParam  |
 model | Model or Group of the device |         |      | DataParam  | mandatory
       | to control                   |         |      |            |
 dev   | idx of the device to control |         |      | IdxParam   | mandatory
 t     | switch time for connection   | -1      |      | TimerParam | mandatory
       | status                       |         |      |            |

To list all supported models, run

$ andes doc -l
Supported Groups and Models

     Group       |                   Models
-----------------+-------------------------------------------
 ACLine          | Line
 ACTopology      | Bus
 Collection      | Area
 DCLink          | Ground, R, L, C, RCp, RCs, RLs, RLCs, RLCp
 DCTopology      | Node
 Exciter         | EXDC2
 Experimental    | PI2
 FreqMeasurement | BusFreq, BusROCOF
 StaticACDC      | VSCShunt
 StaticGen       | PV, Slack
 StaticLoad      | PQ
 StaticShunt     | Shunt
 SynGen          | GENCLS, GENROU
 TimedEvent      | Toggler, Fault
 TurbineGov      | TG2, TGOV1

To view the Config fields for a routine, run

$ andes doc TDS
Config Fields in [TDS]

  Option   | Value |                  Info                  | Acceptable values
-----------+-------+----------------------------------------+-------------------
 sparselib | klu   | linear sparse solver name              | ('klu', 'umfpack')
 tol       | 0.000 | convergence tolerance                  | float
 t0        | 0     | simulation starting time               | >=0
 tf        | 20    | simulation ending time                 | >t0
 fixt      | 0     | use fixed step size (1) or variable    | (0, 1)
           |       | (0)                                    |
 shrinkt   | 1     | shrink step size for fixed method if   | (0, 1)
           |       | not converged                          |
 tstep     | 0.010 | the initial step step size             | float
 max_iter  | 15    | maximum number of iterations           | >=10

andes misc¶

andes misc contains miscellaneous functions, such as configuration and output cleaning.

Configuration¶

ANDES uses a configuration file to set runtime configs for the system routines, and models. --save-config saves all configs to a file. By default, it saves to ~/.andes/andes.conf file, where ~ is the path to your home directory.

With --edit-config, you can edit ANDES configuration handy. The command will automatically save the configuration to the default location if not exist. The shorter version --edit can be used instead asn Python automatically matches it with --edit-config.

You can pass an editor name to --edit, such as --edit vim. If the editor name is not provided, it will use the following defaults: - Microsoft Windows: notepad. - GNU/Linux: the $EDITOR environment variable, or vim if not exist.

For macOS users, the default is vim. If not familiar with vim, you can use nano with --edit nano or TextEdit with --edit "open -a TextEdit".

Cleanup¶

-C, --clean

Option to remove any generated files. Removes files with any of the following suffix: _out.txt (power flow report), _out.npy (time domain data), _out.lst (time domain variable list), and _eig.txt (eigenvalue report).

Interactive Usage¶

This section is a tutorial for using ANDES in an interactive environment. All interactive shells are supported, including Python shell, IPython, Jupyter Notebook and Jupyter Lab. The examples below uses Jupyter Notebook.

Note

All following blocks starting with >>> are Python code. They should be typed into a Python shell, IPython or Jupyter Notebook, not a Anaconda Prompt or shell.

Jupyter Notebook¶

Jupyter notebook is a convenient tool to run Python code and present results. Jupyter notebook can be installed with

conda install jupyter notebook

After the installation, change directory to the folder that you wish to store notebooks, then start the notebook with

jupyter notebook

A browser window should open automatically with the notebook browser loaded. To create a new notebook, use the "New" button at the top-right corner.

Import¶

Like other Python libraries, ANDES needs to be imported into an interactive Python environment.

>>> import andes
>>> andes.main.config_logger()

Verbosity¶

If you are debugging ANDES, you can enable debug messages with

>>> andes.main.config_logger(stream_level=10)

The stream_level uses the same verbosity levels (see Basic Usage) as for the command-line. If not explicitly enabled, the default level 20 (INFO) will apply.

Warning

The verbosity level can only be set once. To set a different level, restart the Python kernel.

Making a System¶

Before running studies, a "System" object needs to be create to hold the system data. The System object can be created by passing the path to the case file the entrypoint function. For example, to run the file kundur_full.xlsx in the same directory as the notebook, use

>>> ss = andes.run('kundur_full.xlsx')

This function will parse the input file, run the power flow, and return the system as an object. Outputs will look like

Parsing input file </Users/user/notebooks/kundur/kundur_full.xlsx>
Input file kundur_full.xlsx parsed in 0.4172 second.
-> Power flow calculation with Newton Raphson method:
0: |F(x)| = 14.9283
1: |F(x)| = 3.60859
2: |F(x)| = 0.170093
3: |F(x)| = 0.00203827
4: |F(x)| = 3.76414e-07
Converged in 5 iterations in 0.0222 second.
Report saved to </Users/user/notebooks/kundur_full_out.txt> in 0.0015 second.
-> Single process finished in 0.4677 second.

In this example, ss is an instance of andes.System. It contains member attributes for models, routines, and numerical DAE.

Naming convention for the System attributes are as follows

Model attributes share the same name as class names. For example, ss.Bus is the Bus instance.
Routine attributes share the same name as class names. For example, ss.PFlow and ss.TDS are the routine instances.
The numerical DAE instance is in lower case ss.dae.

To work with PSS/E inputs, refer to notebook Example 2.

Output path¶

By default, outputs will be saved to the folder where Python is run (or where the notebook is run). In case you need to organize outputs, a path prefix can be passed to andes.run() through output_path. For example,

>>> ss = andes.run('kundur_full.xlsx', output_path='outputs/')

will put outputs into folder outputs relative to the current path. You can also supply an absolute path to output_path.

No output¶

Outputs can be disabled by passing output_path=True to andes.run(). This is useful when one wants to test code without looking at results. For example, do

>>> ss = andes.run('kundur_full.xlsx', no_output=True)

Inspecting Parameter¶

DataFrame¶

Parameters for the loaded system can be easily inspected in Jupyter Notebook using Pandas.

Input parameters for each model instance is returned by the as_df() function. For example, to view the input parameters for Bus, use

>>> ss.Bus.as_df()

A table will be printed with the columns being each parameter and the rows being Bus instances. Parameter in the table is the same as the input file without per-unit conversion.

Parameters have been converted to per unit values under system base. To view the per unit values, use the as_df_in() attribute. For example, to view the system-base per unit value of GENROU, use

>>> ss.GENROU.as_df_in()

Dict¶

In case you need the parameters in dict, use as_dict(). Values returned by as_dict() are system-base per unit values. To retrieve the input data, use as_dict(vin=True).

For example, to retrieve the original input data of GENROU's, use

>>> ss.GENROU.as_dict(vin=True)

Running Studies¶

Three routines are currently supported: PFlow, TDS and EIG. Each routine provides a run() method to execute. The System instance contains member attributes having the same names. For example, to run the time-domain simulation for ss, use

>>> ss.TDS.run()

Checking Exit Code¶

andes.System contains field exit_code for checking if error occurred in run time. A normal completion without error should always have exit_code == 0. One should read output messages carefully and check the exit code, which is particularly useful for batch simulations.

Error may occur in any phase - data parsing, power flow, or simulation. To diagnose, split the simulation steps and check the outputs from each one.

Plotting TDS Results¶

TDS comes with a plotting utility for interactive usage. After running the simulation, a plotter attributed will be created for TDS. To use the plotter, provide the attribute instance of the variable to plot. For example, to plot all the generator speed, use

>>> ss.TDS.plotter.plot(ss.GENROU.omega)

Note

If you see the error

AttributeError: 'NoneType' object has no attribute 'plot'

You will need to manually load plotter with

>>> ss.TDS.load_plotter()

Optional indices is accepted to choose the specific elements to plot. It can be passed as a tuple to the a argument

>>> ss.TDS.plotter.plot(ss.GENROU.omega, a=(0, ))

In the above example, the speed of the "zero-th" generator will be plotted.

Scaling¶

A lambda function can be passed to argument ycalc to scale the values. This is useful to convert a per-unit variable to nominal. For example, to plot generator speed in Hertz, use

>>> ss.TDS.plotter.plot(ss.GENROU.omega, a=(0, ),
                        ycalc=lambda x: 60*x,
                        )

Formatting¶

A few formatting arguments are supported:

grid = True to turn on grid display
greyscale = True to switch to greyscale
ylabel takes a string for the y-axis label

Extracting Data¶

One can extract data from ANDES for custom plotting. Variable names can be extracted from the following fields of ss.dae:

Un-formatted names (non-LaTeX):

x_name: state variable names
y_name: algebraic variable names
xy_name: state variable names followed by algebraic ones

LaTeX-formatted names:

x_tex_name: state variable names
y_tex_name: algebraic variable names
xy_tex_name: state variable names followed by algebraic ones

These lists only contain the variable names used in the current analysis routine. If you only ran power flow, ss.dae.y_name will only contain the power flow algebraic variables, and ss.dae.x_name will likely be empty. After initializing time-domain simulation, these lists will be extended to include all variables used by TDS.

In case you want to extract the discontinuous flags from TDS, you can set store_z to 1 in the config file under section [TDS]. When enabled, discontinuous flag names will be populated at

ss.dae.z_name: discontinuous flag names
ss.dae.z_tex_name: LaTeX-formatted discontinuous flag names

If not enabled, both lists will be empty.

Power flow solutions¶

The full power flow solutions are stored at ss.dae.xy after running power flow (and before initializing dynamic models). You can extract values from ss.dae.xy, which corresponds to the names in ss.dae.xy_name or ss.dae.xy_tex_name.

If you want to extract variables from a particular model, for example, bus voltages, you can directly access the v field of that variable

>>> import numpy as np
>>> voltages = np.array(ss.Bus.v.v)

which stores a copy of the bus voltage values. Note that the first v is the voltage variable of Bus, and the second v stands for value. It is important to make a copy by using np.array() to avoid accidental changes to the solutions.

If you want to extract bus voltage phase angles, do

>>> angle = np.array(ss.Bus.a.v)

where a is the field name for voltage angle.

To find out names of variables in a model, refer to andes_doc.

Time-domain data¶

Time-domain simulation data will be ready when simulation completes. It is stored in ss.dae.ts, which has the following fields:

txyz: a two-dimensional array. The first column is time stamps, and the following are variables. Each row contains all variables for that time step.
t: all time stamps.
x: all state variables (one column per variable).
y: all algebraic variables (one column per variable).
z: all discontinuous flags (if enabled, one column per flag).

If you want the output in pandas DataFrame, call

ss.dae.ts.unpack(df=True)

Dataframes are stored in the following fields of ss.dae.ts:

df: dataframe for states and algebraic variables
df_z: dataframe for discontinuous flags (if enabled)

For both dataframes, time is the index column, and each column correspond to one variable.

Pretty Print of Equations¶

Each ANDES models offers pretty print of $\LaTeX$-formatted equations in the jupyter notebook environment.

To use this feature, symbolic equations need to be generated in the current session using

import andes
ss = andes.System()
ss.prepare()

Or, more concisely, one can do

import andes
ss = andes.prepare()

This process may take a few minutes to complete. To save time, you can selectively generate it only for interested models. For example, to generate for the classical generator model GENCLS, do

import andes
ss = andes.System()
ss.GENROU.prepare()

Once done, equations can be viewed by accessing ss.<ModelName>.syms.<PrintName>, where <ModelName> is the model name, and <PrintName> is the equation or Jacobian name.

Note

Pretty print only works for the particular System instance whose prepare() method is called. In the above example, pretty print only works for ss after calling prepare().

Supported equation names include the following:

xy: variables in the order of State, ExtState, Algeb and ExtAlgeb
f: the right-hand side of differential equations $T \dot{\mathbf{x}} = \mathbf{f}$
g: implicit algebraic equations $0 = \mathbf{g}$
df: derivatives of f over all variables xy
dg: derivatives of g over all variables xy
s: the value equations for ConstService

For example, to print the algebraic equations of model GENCLS, one can use ss.GENCLS.syms.g.

Finding Help¶

General help¶

To find help on a Python class, method, or function, use the built-in help() function. For example, to check how the get method of GENROU should be called, do

help(ss.GENROU.get)

In Jupyter notebook, this can be simplified into ?ss.GENROU.get or ss.GENROU.get?.

Model docs¶

Model docs can be shown by printing the return of doc(). For example, to check the docs of GENCLS, do

print(ss.GENCLS.doc())

It is the same as calling andes doc GENCLS from the command line.

Notebook Examples¶

Check out more examples in Jupyter Notebook in the examples folder of the repository at here. You can run the examples in a live Jupyter Notebook online using Binder.

I/O Formats¶

Input Formats¶

ANDES currently supports the following input formats:

ANDES Excel (.xlsx)
PSS/E RAW (.raw) and DYR (.dyr)
MATPOWER (.m)

ANDES xlsx Format¶

The ANDES xlsx format is a newly introduced format since v0.8.0. This format uses Microsoft Excel for conveniently viewing and editing model parameters. You can use LibreOffice or WPS Office alternatively to Microsoft Excel.

xlsx Format Definition¶

The ANDES xlsx format contains multiple workbooks (tabs at the bottom). Each workbook contains the parameters of all instances of the model, whose name is the workbook name. The first row in a worksheet is used for the names of parameters available to the model. Starting from the second row, each row corresponds to an instance with the parameters in the corresponding columns. An example of the Bus workbook is shown in the following.

A few columns are used across all models, including uid, idx, name and u.

uid is an internally generated unique instance index. This column can be left empty if the xlsx file is being manually created. Exporting the xlsx file with --convert will automatically assign the uid.
idx is the unique instance index for referencing. An unique idx should be provided explicitly for each instance. Accepted types for idx include numbers and strings without spaces.
name is the instance name.
u is the connectivity status of the instance. Accepted values are 0 and 1. Unexpected behaviors may occur if other numerical values are assigned.

As mentioned above, idx is the unique index for an instance to be referenced. For example, a PQ instance can reference a Bus instance so that the PQ is connected to the Bus. This is done through providing the idx of the desired bus as the bus parameter of the PQ.

In the example PQ workbook shown above, there are two PQ instances on buses with idx being 7 and 8, respectively.

Convert to xlsx¶

Please refer to the the --convert command for converting a recognized file to xlsx. See format converter for more detail.

Data Consistency¶

Input data needs to have consistent types for idx. Both string and numerical types are allowed for idx, but the original type and the referencing type must be the same. Suppose we have a bus and a connected PQ. The Bus device may use 1 or '1' as its idx, as long as the PQ device uses the same value for its bus parameter.

The ANDES xlsx reader will try to convert data into numerical types when possible. This is especially relevant when the input idx is string literal of numbers, the exported file will have them converted to numbers. The conversion does not affect the consistency of data.

Parameter Check¶

The following parameter checks are applied after converting input values to array:

Any NaN values will raise a ValueError
Any inf will be replaced with $10^{8}$, and -inf will be replaced with $-10^{8}$.

Cheatsheet¶

A cheatsheet is available for quick lookup of supported commands.

View the PDF version at

https://www.cheatography.com//cuihantao/cheat-sheets/andes-for-power-system-simulation/pdf/

Make Documentation¶

The documentation can be made locally into a variety of formats. To make HTML documentation, change directory to docs, and do

make html

After a minute, HTML documentation will be saved to docs/build/html with the index page being index.html.

A list of supported formats is as follows. Note that some format require additional compiler or library

html        to make standalone HTML files
dirhtml     to make HTML files named index.html in directories
singlehtml  to make a single large HTML file
pickle      to make pickle files
json        to make JSON files
htmlhelp    to make HTML files and an HTML help project
qthelp      to make HTML files and a qthelp project
devhelp     to make HTML files and a Devhelp project
epub        to make an epub
latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf    to make LaTeX and PDF files (default pdflatex)
latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
text        to make text files
man         to make manual pages
texinfo     to make Texinfo files
info        to make Texinfo files and run them through makeinfo
gettext     to make PO message catalogs
changes     to make an overview of all changed/added/deprecated items
xml         to make Docutils-native XML files
pseudoxml   to make pseudoxml-XML files for display purposes
linkcheck   to check all external links for integrity
doctest     to run all doctests embedded in the documentation (if enabled)
coverage    to run coverage check of the documentation (if enabled)