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 theBus
instance. - Routine attributes share the same name as class names. For example,
ss.PFlow
andss.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 displaygreyscale = True
to switch to greyscaleylabel
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 namesy_name
: algebraic variable namesxy_name
: state variable names followed by algebraic ones
LaTeX-formatted names:
x_tex_name
: state variable namesy_tex_name
: algebraic variable namesxy_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 namesss.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 variablesdf_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 ExtAlgebf
: the right-hand side of differential equations \(T \dot{\mathbf{x}} = \mathbf{f}\)g
: implicit algebraic equations \(0 = \mathbf{g}\)df
: derivatives off
over all variablesxy
dg
: derivatives ofg
over all variablesxy
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 theuid
.idx
is the unique instance index for referencing. An uniqueidx
should be provided explicitly for each instance. Accepted types foridx
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 aValueError
- 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)