ANL-CEEESA/powersas.m
1
0
Fork 0
mirror of https://github.com/ANL-CEEESA/powersas.m.git synced 2025-12-06 01:48:52 -06:00
Code Issues Packages Projects Releases Wiki Activity

change new read-the-docs template

Browse Source
This commit is contained in:
Yang Liu
2023-02-20 21:49:06 -05:00
parent 13018d08e7
commit b0d1c6fabb
62 changed files with 4650 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Makefile Normal file
View File

@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = "-W" # This flag turns warnings into errors.
SPHINXBUILD = sphinx-build
SPHINXPROJ = PackagingScientificPython
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

36
docs/make.bat Normal file
View File

@@ -0,0 +1,36 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
set SPHINXPROJ=PackagingScientificPython
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

17
docs/requirements-rtd.txt Normal file
View File

@@ -0,0 +1,17 @@
cvxopt
numpy
scipy
sympy
pandas
matplotlib
openpyxl
xlsxwriter
dill
pathos
tqdm
pyyaml
coloredlogs
ipython
numpydoc
sphinx-copybutton
sphinx_rtd_theme

0
docs/source/_static/.placeholder Normal file
View File

54
docs/source/andes.rst Normal file
View File

@@ -0,0 +1,54 @@
Subpackages
===========
.. toctree::
moduledoc/andes.core
moduledoc/andes.io
moduledoc/andes.models
moduledoc/andes.routines
moduledoc/andes.utils
moduledoc/andes.variables
Submodules
==========
andes.cli module
----------------
.. automodule:: andes.cli
:members:
:undoc-members:
:show-inheritance:
andes.main module
-----------------
.. automodule:: andes.main
:members:
:undoc-members:
:show-inheritance:
andes.plot module
-----------------
.. automodule:: andes.plot
:members:
:undoc-members:
:show-inheritance:
andes.shared module
-------------------
.. automodule:: andes.shared
:members:
:undoc-members:
:show-inheritance:
andes.system module
-------------------
.. automodule:: andes.system
:members:
:undoc-members:
:show-inheritance:

405
docs/source/cases.rst Normal file
View File

@@ -0,0 +1,405 @@
.. _cases:
***********************
Test Cases and Parsers
***********************
Directory
=========
ANDES comes with several test cases in the ``andes/cases/`` folder.
Currently, the Kundur's 2-area system, IEEE 14-bus system,
NPCC 140-bus system, and the WECC 179-bus system has been verified
against DSATools TSAT.
The test case library will continue to build as more models get implemented.
A tree view of the test directory is as follows. ::
cases/
├── 5bus/
│ └── pjm5bus.xlsx
├── GBnetwork/
│ ├── GBnetwork.m
│ ├── GBnetwork.xlsx
│ └── README.md
├── ieee14/
│ ├── ieee14.dyr
│ └── ieee14.raw
├── kundur/
│ ├── kundur.raw
│ ├── kundur_aw.xlsx
│ ├── kundur_coi.xlsx
│ ├── kundur_coi_empty.xlsx
│ ├── kundur_esdc2a.xlsx
│ ├── kundur_esst3a.xlsx
│ ├── kundur_exdc2_zero_tb.xlsx
│ ├── kundur_exst1.xlsx
│ ├── kundur_freq.xlsx
│ ├── kundur_full.dyr
│ ├── kundur_full.xlsx
│ ├── kundur_gentrip.xlsx
│ ├── kundur_ieeeg1.xlsx
│ ├── kundur_ieeest.xlsx
│ ├── kundur_sexs.xlsx
│ └── kundur_st2cut.xlsx
├── matpower/
│ ├── case118.m
│ ├── case14.m
│ ├── case300.m
│ └── case5.m
├── nordic44/
│ ├── N44_BC.dyr
│ ├── N44_BC.raw
│ └── README.md
├── npcc/
│ ├── npcc.raw
│ └── npcc_full.dyr
├── wecc/
│ ├── wecc.raw
│ ├── wecc.xlsx
│ ├── wecc_full.dyr
│ ├── wecc_gencls.dyr
└── wscc9/
├── wscc9.raw
└── wscc9.xlsx
MATPOWER Cases
==============================
MATPOWER cases has been tested in ANDES for power flow calculation.
All following cases are calculated with the provided initial values
using the full Newton-Raphson iterative approach.
The numerical library used for sparse matrix factorization is KLU.
In addition, Jacobians are updated in place ``spmatrix.ipadd``.
Computations are performed on macOS 10.15.4 with i9-9980H, 16 GB
2400 MHz DDR4, running ANDES 0.9.1, CVXOPT 1.2.4 and NumPy 1.18.1.
The statistics of convergence, number of iterations, and solution time
(including equation evaluation, Jacobian, and factorization time) are
reported in the following table.
The computation time may vary depending on operating system and hardware.
+--------------------------+------------+-----------------+----------+
| File Name | Converged? | # of Iterations | Time [s] |
+==========================+============+=================+==========+
| case30.m | 1 | 3 | 0.012 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg500.m | 1 | 3 | 0.019 |
+--------------------------+------------+-----------------+----------+
| case13659pegase.m | 1 | 5 | 0.531 |
+--------------------------+------------+-----------------+----------+
| case9Q.m | 1 | 3 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg200.m | 1 | 2 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case24_ieee_rts.m | 1 | 4 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case300.m | 1 | 5 | 0.026 |
+--------------------------+------------+-----------------+----------+
| case6495rte.m | 1 | 5 | 0.204 |
+--------------------------+------------+-----------------+----------+
| case39.m | 1 | 1 | 0.009 |
+--------------------------+------------+-----------------+----------+
| case18.m | 1 | 4 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case_RTS_GMLC.m | 1 | 3 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case1951rte.m | 1 | 3 | 0.047 |
+--------------------------+------------+-----------------+----------+
| case6ww.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case5.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case69.m | 1 | 3 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case6515rte.m | 1 | 4 | 0.168 |
+--------------------------+------------+-----------------+----------+
| case2383wp.m | 1 | 6 | 0.084 |
+--------------------------+------------+-----------------+----------+
| case30Q.m | 1 | 3 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case2868rte.m | 1 | 4 | 0.074 |
+--------------------------+------------+-----------------+----------+
| case1354pegase.m | 1 | 4 | 0.047 |
+--------------------------+------------+-----------------+----------+
| case2848rte.m | 1 | 3 | 0.063 |
+--------------------------+------------+-----------------+----------+
| case4_dist.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case6470rte.m | 1 | 4 | 0.175 |
+--------------------------+------------+-----------------+----------+
| case2746wp.m | 1 | 4 | 0.074 |
+--------------------------+------------+-----------------+----------+
| case_SyntheticUSA.m | 1 | 21 | 11.120 |
+--------------------------+------------+-----------------+----------+
| case118.m | 1 | 3 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case30pwl.m | 1 | 3 | 0.021 |
+--------------------------+------------+-----------------+----------+
| case57.m | 1 | 3 | 0.017 |
+--------------------------+------------+-----------------+----------+
| case89pegase.m | 1 | 5 | 0.024 |
+--------------------------+------------+-----------------+----------+
| case6468rte.m | 1 | 6 | 0.232 |
+--------------------------+------------+-----------------+----------+
| case2746wop.m | 1 | 4 | 0.075 |
+--------------------------+------------+-----------------+----------+
| case85.m | 1 | 3 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case22.m | 1 | 2 | 0.008 |
+--------------------------+------------+-----------------+----------+
| case4gs.m | 1 | 3 | 0.012 |
+--------------------------+------------+-----------------+----------+
| case14.m | 1 | 2 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg10k.m | 1 | 4 | 0.251 |
+--------------------------+------------+-----------------+----------+
| case2869pegase.m | 1 | 6 | 0.136 |
+--------------------------+------------+-----------------+----------+
| case_ieee30.m | 1 | 2 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case2737sop.m | 1 | 5 | 0.087 |
+--------------------------+------------+-----------------+----------+
| case9target.m | 1 | 5 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case1888rte.m | 1 | 2 | 0.037 |
+--------------------------+------------+-----------------+----------+
| case145.m | 1 | 3 | 0.018 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg2000.m | 1 | 3 | 0.059 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg70k.m | 1 | 15 | 7.043 |
+--------------------------+------------+-----------------+----------+
| case9241pegase.m | 1 | 6 | 0.497 |
+--------------------------+------------+-----------------+----------+
| case9.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case141.m | 1 | 3 | 0.012 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg25k.m | 1 | 7 | 1.040 |
+--------------------------+------------+-----------------+----------+
| case118.m | 1 | 3 | 0.015 |
+--------------------------+------------+-----------------+----------+
| case1354pegase.m | 1 | 4 | 0.048 |
+--------------------------+------------+-----------------+----------+
| case13659pegase.m | 1 | 5 | 0.523 |
+--------------------------+------------+-----------------+----------+
| case14.m | 1 | 2 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case141.m | 1 | 3 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case145.m | 1 | 3 | 0.017 |
+--------------------------+------------+-----------------+----------+
| case18.m | 1 | 4 | 0.012 |
+--------------------------+------------+-----------------+----------+
| case1888rte.m | 1 | 2 | 0.037 |
+--------------------------+------------+-----------------+----------+
| case1951rte.m | 1 | 3 | 0.052 |
+--------------------------+------------+-----------------+----------+
| case22.m | 1 | 2 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case2383wp.m | 1 | 6 | 0.086 |
+--------------------------+------------+-----------------+----------+
| case24_ieee_rts.m | 1 | 4 | 0.015 |
+--------------------------+------------+-----------------+----------+
| case2736sp.m | 1 | 4 | 0.074 |
+--------------------------+------------+-----------------+----------+
| case2737sop.m | 1 | 5 | 0.108 |
+--------------------------+------------+-----------------+----------+
| case2746wop.m | 1 | 4 | 0.093 |
+--------------------------+------------+-----------------+----------+
| case2746wp.m | 1 | 4 | 0.089 |
+--------------------------+------------+-----------------+----------+
| case2848rte.m | 1 | 3 | 0.065 |
+--------------------------+------------+-----------------+----------+
| case2868rte.m | 1 | 4 | 0.079 |
+--------------------------+------------+-----------------+----------+
| case2869pegase.m | 1 | 6 | 0.137 |
+--------------------------+------------+-----------------+----------+
| case30.m | 1 | 3 | 0.033 |
+--------------------------+------------+-----------------+----------+
| case300.m | 1 | 5 | 0.102 |
+--------------------------+------------+-----------------+----------+
| case30Q.m | 1 | 3 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case30pwl.m | 1 | 3 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case39.m | 1 | 1 | 0.008 |
+--------------------------+------------+-----------------+----------+
| case4_dist.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case4gs.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case5.m | 1 | 3 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case57.m | 1 | 3 | 0.015 |
+--------------------------+------------+-----------------+----------+
| case6468rte.m | 1 | 6 | 0.229 |
+--------------------------+------------+-----------------+----------+
| case6470rte.m | 1 | 4 | 0.170 |
+--------------------------+------------+-----------------+----------+
| case6495rte.m | 1 | 5 | 0.198 |
+--------------------------+------------+-----------------+----------+
| case6515rte.m | 1 | 4 | 0.169 |
+--------------------------+------------+-----------------+----------+
| case69.m | 1 | 3 | 0.012 |
+--------------------------+------------+-----------------+----------+
| case6ww.m | 1 | 3 | 0.011 |
+--------------------------+------------+-----------------+----------+
| case85.m | 1 | 3 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case89pegase.m | 1 | 5 | 0.020 |
+--------------------------+------------+-----------------+----------+
| case9.m | 1 | 3 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case9241pegase.m | 1 | 6 | 0.487 |
+--------------------------+------------+-----------------+----------+
| case9Q.m | 1 | 3 | 0.013 |
+--------------------------+------------+-----------------+----------+
| case9target.m | 1 | 5 | 0.015 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg10k.m | 1 | 4 | 0.257 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg200.m | 1 | 2 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg2000.m | 1 | 3 | 0.058 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg25k.m | 1 | 7 | 1.118 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg500.m | 1 | 3 | 0.027 |
+--------------------------+------------+-----------------+----------+
| case_ACTIVSg70k.m | 1 | 15 | 6.931 |
+--------------------------+------------+-----------------+----------+
| case_RTS_GMLC.m | 1 | 3 | 0.014 |
+--------------------------+------------+-----------------+----------+
| case_SyntheticUSA.m | 1 | 21 | 11.103 |
+--------------------------+------------+-----------------+----------+
| case_ieee30.m | 1 | 2 | 0.010 |
+--------------------------+------------+-----------------+----------+
| case3375wp.m | 0 | - | 0.061 |
+--------------------------+------------+-----------------+----------+
| case33bw.m | 0 | - | 0.007 |
+--------------------------+------------+-----------------+----------+
| case3120sp.m | 0 | - | 0.037 |
+--------------------------+------------+-----------------+----------+
| case3012wp.m | 0 | - | 0.082 |
+--------------------------+------------+-----------------+----------+
| case3120sp.m | 0 | - | 0.039 |
+--------------------------+------------+-----------------+----------+
| case3375wp.m | 0 | - | 0.059 |
+--------------------------+------------+-----------------+----------+
| case33bw.m | 0 | - | 0.007 |
+--------------------------+------------+-----------------+----------+
PSS/E Dyr Parser
================
ANDES supporting parsing PSS/E dynamic files in the format of ``.dyr``.
Support new dynamic models can be added by editing the input and output
conversion definition file in ``andes/io/psse-dyr.yaml``,
which is in the standard YAML format.
To add support for a new dynamic model, it is recommended to start with
an existing model of similar functionality.
Consider a ``GENCLS`` entry in a dyr file. The entry looks like ::
1 'GENCLS' 1 13.0000 0.000000 /
where the fields are in the order of bus index, model name,
generator index on the bus, inertia (H) and damping coefficient (D).
The input-output conversion definition for GENCLS is as follows ::
GENCLS:
destination: GENCLS
inputs:
- BUS
- ID
- H
- D
find:
gen:
StaticGen:
bus: BUS
subidx: ID
get:
u:
StaticGen:
src: u
idx: gen
Sn:
StaticGen:
src: Sn
idx: gen
Vn:
Bus:
src: Vn
idx: BUS
ra:
StaticGen:
src: ra
idx: gen
xs:
StaticGen:
src: xs
idx: gen
outputs:
u: u
bus: BUS
gen: gen
Sn: Sn
Vn: Vn
D: D
M: "GENCLS.H; lambda x: 2 * x"
ra: ra
xd1: xs
It begins with a base-level definition of the model name to be parsed from the
dyr file, namely, ``GENCLS``. Five directives can be defined for each model:
``destination``, ``inputs``, ``outputs``, ``find`` and ``get``.
Note that ``find`` and ``get`` are optional, but the other three are mandatory.
- ``destination`` is ANDES model to which the original PSS/E model will be
converted. In this case, the ANDES model have the same name ``GENCLS``.
- ``inputs`` is a list of the parameter names for the PSS/E data.
Arbitrary names can be used, but it is recommended to use the same notation
following the PSS/E manual.
- ``outputs`` is a dictionary where the keys are the ANDES model parameter and
the values are the input parameter or lambda functions that processes the inputs
(see notes below).
- ``find`` is a dictionary with the keys being the temporary parameter name to store
the ``idx`` of
external devices and the values being the criteria to locate the devices.
In the example above, ``GENCLS`` will try to find the ``idx`` of ``StaticGen``
with ``bus == BUS`` and the ``subidx == ID``, where ``BUS`` and ``ID`` are from
the dyr file.
- ``get`` is a dictionary with each key being a temporary parameter name for storing
an external parameter and each value being the criteria to find the external parameter.
In the example above, a temporary parameter ``u`` is the ``u`` parameter of ``StaticGen``
whose ``idx == gen``. Note that ``gen`` is the ``idx`` of ``StaticGen`` retrieved
in the above ``find`` section.
For the ``inputs`` section, one will need to skip the model name
because for any model, the second field is always the model name.
That is why for ``GENCLS`` below, we only list four input parameters. ::
1 'GENCLS' 1 13.0000 0.000000 /
For the ``outputs`` section, the order can be arbitrary, but it is recommended
to follow the input order as much as possible for maintainability.
In particular, the right-hand-side of the outputs can be either an input parameter name
or an anonymous expression that processes the input parameters.
For the example of GENCLS, since ANDES internally uses the parameter of ``M = 2H``,
the input ``H`` needs to be multiplied by 2.
It is done by the following ::
M: "GENCLS.H; lambda x: 2 * x"
where the left-hand-side is the output parameter name (destination ANDES model parameter name),
and the right-hand-side is arguments and the lambda function separated by semi-colon, all in a
pair of double quotation marks.
Multiple arguments are accepted and should be separated by comma.
Arguments can come from the same model or another model.
In the case of the same model, the model name can be neglected, namely, by writing
``M: "H; lambda x: 2 * x"``.

210
docs/source/conf.py Normal file
View File

@@ -0,0 +1,210 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# ANDES documentation build configuration file, created by
# sphinx-quickstart on Thu Jun 28 12:35:56 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.githubpages',
'sphinx.ext.intersphinx',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'IPython.sphinxext.ipython_directive',
'IPython.sphinxext.ipython_console_highlighting',
'matplotlib.sphinxext.plot_directive',
'numpydoc',
'sphinx_copybutton',
]
# Configuration options for plot_directive. See:
# https://github.com/matplotlib/matplotlib/blob/f3ed922d935751e08494e5fb5311d3050a3b637b/lib/matplotlib/sphinxext/plot_directive.py#L81
plot_html_show_source_link = False
plot_html_show_formats = False
# Generate the API documentation when building
autosummary_generate = True
numpydoc_show_class_members = False
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'ANDES'
copyright = '2021, Hantao Cui'
author = 'Hantao Cui'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
import andes
# The short X.Y version.
version = andes.__version__
# The full version, including alpha/beta/rc tags.
release = andes.__version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
import sphinx_rtd_theme
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'andes'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
'preamble': r'\DeclareUnicodeCharacter{2588}{-}',
'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
'pointsize': '11pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'andes.tex', 'ANDES Manual',
'Hantao Cui', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'andes', 'ANDES Manual',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'andes', 'ANDES Manual',
author, 'andes', 'Python Software for Symbolic Power System Modeling and Numerical Analysis',
'Miscellaneous'),
]
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('https://docs.python.org/3/', None),
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
'matplotlib': ('https://matplotlib.org', None),
}
# Favorite icon
html_favicon = 'images/curent.ico'
# Disable smartquotes to display double dashes correctly
smartquotes = False
# import and execute model reference generation script
exec(open("modelref.py").read())

23
docs/source/copyright.rst Normal file
View File

@@ -0,0 +1,23 @@
.. role:: raw-html(raw)
:format: html
*******
License
*******
GNU Public License v3
*********************
| Copyright :raw-html:`©` 2015-2020 Hantao Cui.
ANDES is free software; you can redistribute it and/or modify it under
the terms of the
`GNU General Public License <http://www.gnu.org/licenses/gpl-3.0.html>`_
as published by the Free Software Foundation; either version 3 of the
License, or (at your option) any later version.
ANDES is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the
`GNU General Public License <http://www.gnu.org/licenses/gpl-3.0.html>`_
for more details.

51
docs/source/faq.rst Normal file
View File

@@ -0,0 +1,51 @@
.. _faq:
**************************
Frequently Asked Questions
**************************
General
=======
Q: What is the Hybrid Symbolic-Numeric Framework in ANDES?
A: It is a modeling and simulation framework that uses symbolic computation for descriptive
modeling and code generation for fast numerical simulation.
The goal of the framework is to reduce the programming efforts associated with implementing
complex models and automate the research workflow of modeling, simulation, and documentation.
The framework reduces the modeling efforts from two aspects:
(1) allowing modeling by typing in equations, and (2) allowing modeling using modularized
control blocks and discontinuous components.
One only needs to describe the model using equations and blocks without having to write the
numerical code to implement the computation.
The framework automatically generate symbolic expressions, computes partial derivatives,
and generates vectorized numerical code.
Modeling
========
Admittance matrix
-----------------
Q: Where to find the line admittance matrix?
A: ANDES does not build line admittance matrix for computing
line power injections. Instead, line power injections are
computed as vectors on the two line terminal. This approach
generalizes line as a power injection model.
Q: Without admittance matrix, how to switch out lines?
A: Lines can be switched out and in by using ``Toggler``.
See the example in ``cases/kundur/kundur_full.xlsx``.
One does not need to manually trigger a Jacobian matrix rebuild
because ``Toggler`` automatically triggers it using the new
connectivity status.
Reference of the existing model
-------------------------------
Q: Is there any further reference of the existing model?
A: Most of them can be found online, such as ESIG and PowerWorld.

BIN
docs/source/images/curent.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/source/images/diagrams/ieeest.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/source/images/example-kundur/efd.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/source/images/example-kundur/omega.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
docs/source/images/example-npcc/omega.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

BIN
docs/source/images/example-tgov1/tgov1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/source/images/example-tgov1/tgov1_class.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 249 KiB

BIN
docs/source/images/example-tgov1/tgov1_eqns.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/source/images/example-wecc/omega.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

BIN
docs/source/images/misc/doc-screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

BIN
docs/source/images/misc/ieeeg1-screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 135 KiB

BIN
docs/source/images/sponsors/curent.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/source/images/sponsors/doe.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/source/images/sponsors/inl.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

BIN
docs/source/images/sponsors/llnl.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/source/images/sponsors/nsf.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
docs/source/images/tutorial/xlsx-bus.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 562 KiB

BIN
docs/source/images/tutorial/xlsx-pq.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 434 KiB

98
docs/source/index.rst Normal file
View File

@@ -0,0 +1,98 @@
.. ANDES documentation master file, created by
sphinx-quickstart on Thu Jun 21 11:11:34 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. raw:: html
<embed>
<h1 style="letter-spacing: 0.4em; font-size: 2.5em !important;
margin-bottom: 0; padding-bottom: 0"> ANDES </h1>
<p style="color: #00746F; font-variant: small-caps; font-weight: bold;
margin-bottom: 2em">
Python Software for Symbolic Power System Modeling and Numerical Analysis</p>
</embed>
****
Home
****
ANDES is a Python-based free software package for power system simulation, control and analysis.
It establishes a unique **hybrid symbolic-numeric framework** for modeling differential algebraic
equations (DAEs) for numerical analysis. Main features of ANDES include
* a unique hybrid symbolic-numeric approach to modeling and simulation that enables descriptive DAE modeling and
automatic numerical code generation
* a rich library of transfer functions and discontinuous components (including limiters, dead-bands, and
saturation) available for prototyping models, which can be readily instantiated as multiple devices for
system analysis
* industry-grade second-generation renewable models (solar PV, type 3 and type 4 wind),
distributed PV and energy storage model
* comes with the Newton method for power flow calculation, the implicit trapezoidal method for time-domain
simulation, and full eigenvalue calculation
* strictly verified models with commercial software. ANDES obtains identical time-domain simulation results for
IEEE 14-bus and NPCC system with GENROU and multiple controller models. See the verification link for details.
* developed with performance in mind. While written in Python, ANDES comes with a performance package and can
finish a 20-second transient simulation of a 2000-bus system in a few seconds on a typical desktop computer
* out-of-the-box PSS/E raw and dyr file support for available models. Once a model is developed, inputs from a
dyr file can be readily supported
* an always up-to-date equation documentation of implemented models
ANDES is currently under active development. To get involved,
* Follow the tutorial at
`https://andes.readthedocs.io <https://andes.readthedocs.io/en/stable/tutorial.html>`_
* Checkout the Notebook examples in the
`examples folder <https://github.com/cuihantao/andes/tree/master/examples>`_
* Try ANDES in Jupyter Notebook
`with Binder <https://mybinder.org/v2/gh/cuihantao/andes/master>`_
* Download the PDF manual at
`download <https://andes.readthedocs.io/_/downloads/en/stable/pdf/>`_
* Report issues in the
`GitHub issues page <https://github.com/cuihantao/andes/issues>`_
* Learn version control with
`the command-line git <https://git-scm.com/docs/gittutorial>`_ or
`GitHub Desktop <https://help.github.com/en/desktop/getting-started-with-github-desktop>`_
* If you are looking to develop models, read the
`Modeling Cookbook <https://andes.readthedocs.io/en/stable/modeling.html>`_
This work was supported in part by the Engineering Research Center Program of
the National Science Foundation and the Department of Energy under NSF Award
Number EEC-1041877 and the `CURENT <https://curent.utk.edu>`_ Industry Partnership Program.
**ANDES is made open source as part of the CURENT Large Scale Testbed project.**
ANDES is developed and actively maintained by `Hantao Cui <https://cui.eecps.com>`_.
See the GitHub repository for a full list of contributors.
.. toctree::
:caption: ANDES Manual
:maxdepth: 3
:hidden:
install.rst
tutorial.rst
modeling.rst
cases.rst
modelref.rst
configref.rst
faq.rst
troubleshooting.rst
misc.rst
release-notes.rst
copyright.rst
.. toctree::
:hidden:
:caption: API References
:maxdepth: 3
andes.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

195
docs/source/install.rst Normal file
View File

@@ -0,0 +1,195 @@
.. _install:
*************************
Installation
*************************
ANDES can be installed in Python 3.6+.
Please follow the installation guide carefully.
Environment
===========
Setting Up Miniconda
--------------------
We recommend the Miniconda distribution that includes the conda package manager and Python.
Downloaded and install the latest Miniconda (x64, with Python 3)
from https://conda.io/miniconda.html.
Step 1: Open terminal (on Linux or maxOS) or `Anaconda Prompt` (on Windows, **not the cmd
program!!**).
Make sure you are in a conda environment - you should see ``(base)`` prepended to the
command-line prompt, such as ``(base) C:\Users\user>``.
Create a conda environment for ANDES (recommended)
.. code:: bash
conda create --name andes python=3.7
Activate the new environment with
.. code:: bash
conda activate andes
You will need to activate the ``andes`` environment every time in a new Anaconda Prompt or
shell.
Step 2: Add the ``conda-forge`` channel and set it as default
.. code:: bash
conda config --add channels conda-forge
conda config --set channel_priority flexible
If these steps complete without an error, continue to `Install Andes`_.
Existing Python Environment (Advanced)
--------------------------------------
This is for advanced user only and is **not recommended on Microsoft Windows**.
Please skip it if you have set up a Conda environment.
Instead of using Conda, if you prefer an existing Python environment,
you can install ANDES with `pip`:
.. code:: bash
python3 -m pip install andes
If you see a `Permission denied` error, you will need to
install the packages locally with `--user`
Install ANDES
=============
ANDES can be installed in the user mode and the development mode.
- If you want to use ANDES without modifying the source code, install it in the `User Mode`_.
- If you want to develop models or routine, install it in the `Development Mode`_.
User Mode
---------
.. warning ::
Please skip this section and install ANDES in the `Development Mode`_
if you want to modify ANDES code or receive unreleased development
updates.
The User Model installation will install the latest stable version.
In the Anaconda environment, run
.. code:: bash
conda install andes
You will be prompted to confirm the installation,
This command installs ANDES into the active environment, which should be called ``andes`` if
you followed all the above steps.
.. note::
To use ``andes``, you will need to activate the ``andes`` environment every time in a new Anaconda Prompt or
shell.
Development Mode
----------------
This is for users who want to hack into the code and, for example, develop new models or routines.
The usage of ANDES is the same in development mode as in user mode.
In addition, changes to source code will be reflected immediately without re-installation.
Step 1: Get ANDES source code
As a developer, you are strongly encouraged to clone the source code using ``git``
from either your fork or the original repository:
.. code:: bash
git clone https://github.com/cuihantao/andes
In this way, you can easily update to the latest source code using ``git``.
Alternatively, you can download the ANDES source code from
https://github.com/cuihantao/andes and extract all files to the path of your choice.
Although this will work, this is not recommended since tracking changes and pushing back code
would be painful.
Step 2: Install dependencies
In the Anaconda environment, use ``cd`` to change directory to the ANDES root folder.
Install dependencies with
.. code:: bash
conda install --file requirements.txt
conda install --file requirements-dev.txt
Step 3: Install ANDES in the development mode using
.. code:: bash
python3 -m pip install -e .
Note the dot at the end. Pip will take care of the rest.
Updating ANDES
==============
Regular ANDES updates will be pushed to both ``conda-forge`` and Python package index.
It is recommended to use the latest version for bug fixes and new features.
We also recommended you to check the :ref:`ReleaseNotes` before updating to stay informed
of changes that might break your downstream code.
Depending you how you installed ANDES, you will use one of the following ways to upgrade.
If you installed it from conda (most common for users), run
.. code:: bash
conda install -c conda-forge --yes andes
If you install it from PyPI (namely, through ``pip``), run
.. code:: bash
python3 -m pip install --yes andes
If you installed ANDES from source code (in the `Development Mode`_),
and the source was cloned using ``git``,
you can use ``git pull`` to pull in changes from remote. However, if your source
code was downloaded, you will have to download the new source code again and manually
overwrite the existing one.
In rare cases, after updating the source code, command-line ``andes`` will complain
about missing dependency. If this ever happens, it means the new ANDES has introduced
new dependencies. In such cases, reinstall andes in the development mode to fix.
Change directory to the ANDES source code folder that contains ``setup.py`` and run
.. code:: bash
python3 -m pip install -e .
Performance Packages
====================
.. note::
Performance packages can be safely skipped and will not affect the
functionality of ANDES.
KVXOPT
------
KVXOPT is a fork of the CVXOPT with KLU by Uriel Sandoval (@sanurielf).
KVXOPT interfaces to KLU, which is
roughly 20% faster than UMFPACK for circuit simulations based on our testing.
KVXOPT contains inplace add and set functions for sparse matrix
contributed by CURENT.
These inplace functions significantly speed up large-scale system simulations.
To install ``KVXOPT`` run
.. code:: bash
python -m pip install kvxopt

112
docs/source/misc.rst Normal file
View File

@@ -0,0 +1,112 @@
.. _misc:
**********************
Miscellaneous
**********************
Notes
=====
Modeling Blocks
---------------
State Freeze
````````````
State freeze is used by converter controllers during fault transients
to fix a variable at the pre-fault values. The concept of state freeze
is applicable to both state or algebraic variables.
For example, in the renewable energy electric control model (REECA),
the proportional-integral controllers for reactive power error and voltage
error are subject to state freeze when voltage dip is observed.
The internal and output states should be frozen when the freeze signal
turns one and freed when the signal turns back to zero.
Freezing a state variable can be easily implemented by multiplying the freeze
signal with the right-hand side (RHS) of the differential equation:
.. math ::
T \dot{x} = (1 - z_f) \times f(x)
where :math:`f(x)` is the original RHS of the differential equation,
and :math:`z_f` is the freeze signal. When :math:`z_f` becomes zero
the differential equation will evaluate to zero, making the increment
zero.
Freezing an algebraic variable is more complicate to implement.
One might consider a similar solution to freezing a differential variable
by constructing a piecewise equation, for example,
.. math::
0 = (1 - z_f)\times g(y)
where :math:`g(y)` is the original RHS of the algebraic equation.
One might also need to add a small value to the diagonals of ``dae.gy``
associated with the algebraic variable to avoid singularity.
The rationale behind this implementation is to zero out the algebraic
equation mismatch and thus stop incremental correction:
in the frozen state, since :math:`z_f` switches to zero,
the algebraic increment should be forced to zero.
This method, however, would not work when a dishonest Newton method is
used.
If the Jacobian matrix is not updated after :math:`z_f` switches to one,
in the row associated with the equation, the derivatives will remain the
same. For the algebraic equation of the PI controller given by
.. math::
0 = (K_p u + x_i) - y
where :math:`K_p` is the proportional gain, :math:`u` is the input,
:math:`x_I` is the integrator output, and :math:`y` is the PI controller
output, the derivatives w.r.t :math:`u`, :math:`x_i` and :math:`y` are
nonzero in the pre-frozen state. These derivative corrects :math:`y`
following the changes of :math:`u` and :math:`x`.
Although :math:`x` has been frozen, if the Jacobian is not rebuilt,
correction will still be made due to the change of :math:`u`.
Since this equation is linear, only one iteration is needed to let
:math:`y` track the changes of :math:`u`.
For nonlinear algebraic variables, this approach will likely give wrong
results, since the residual is pegged at zero.
To correctly freeze an algebraic variable, the freezing signal needs to
be passed to an ``EventFlag``, which will set an ``custom_event`` flag
if any input changes.
``EventFlag`` is a ``VarService`` that will be evaluated at each
iteration after discrete components and before equations.
Per Unit System
==============================
The bases for AC system are
- :math:`S_b^{ac}`: three-phase power in MVA. By default, :math:`S_b^{ac}=100 MVA` (in ``System.config.mva``).
- :math:`V_b^{ac}`: phase-to-phase voltage in kV.
- :math:`I_b^{ac}`: current base :math:`I_b^{ac} = \frac{S_b^{ac}} {\sqrt{3} V_b^{ac}}`
The bases for DC system are
- :math:`S_b^{dc}`: power in MVA. It is assumed to be the same as :math:`S_b^{ac}`.
- :math:`V_b^{dc}`: voltage in kV.
Some device parameters with specific properties are per unit values under the corresponding
device base ``Sn`` and ``Vn`` (if applicable).
These properties are documented in :py:mod:`andes.core.param.NumParam`.
After setting up the system, these parameters will be converted to the system base MVA
as specified in the config file (100 MVA by default).
The parameter values in the system base will be stored in the ``v`` attribute of the ``NumParam``,
and the original inputs in the device base will be stored to the ``vin`` attribute.
Values in the ``v`` attribute is what get utilized in computation.
Writing new values directly to ``vin`` will not affect the values in ``v`` afterwards.
Profiling Import
========================================
To speed up the command-line program, import profiling is used to breakdown the program loading time.
With tool ``profimp``, ``andes`` can be profiled with ``profimp "import andes" --html > andes_import.htm``. The
report can be viewed in any web browser.

1424
docs/source/modeling.rst Normal file
View File

File diff suppressed because it is too large Load Diff

58
docs/source/modelref.py Normal file
View File

@@ -0,0 +1,58 @@
"""
This file is used to generate reStructuredText tables for Group and Model references.
"""
import os
import andes
if not (os.path.isfile('modelref.rst') and os.path.isfile('configref.rst')):
ss = andes.prepare(nomp=True)
# write the top-level index file
out = ''
out += '.. _modelref:\n\n'
out += '****************\n'
out += 'Model References\n'
out += '****************\n'
out += '\n'
out += ss.supported_models(export='rest')
out += '\n'
out += '.. toctree ::\n'
out += ' :maxdepth: 2\n'
out += '\n'
file_tpl = ' groupdoc/{}\n'
for group in ss.groups.values():
out += file_tpl.format(group.class_name)
with open('modelref.rst', 'w') as f:
f.write(out)
# write individual files
os.makedirs('groupdoc', exist_ok=True)
for group in ss.groups.values():
with open(f'groupdoc/{group.class_name}.rst', 'w') as f:
f.write(group.doc_all(export='rest'))
# Config Reference Section
out = ''
out += '.. _configref:\n\n'
out += '*****************\n'
out += 'Config References\n'
out += '*****************\n'
out += '\n'
out += ss.config.doc(export='rest', target=True, symbol=False)
for r in ss.routines.values():
out += r.config.doc(export='rest', target=True, symbol=False)
with open('configref.rst', 'w') as f:
f.write(out)

78
docs/source/moduledoc/andes.core.rst Normal file
View File

@@ -0,0 +1,78 @@
andes.core package
==================
Submodules
----------
andes.core.block module
-----------------------
.. automodule:: andes.core.block
:members:
:undoc-members:
:show-inheritance:
andes.core.discrete module
--------------------------
.. automodule:: andes.core.discrete
:members:
:undoc-members:
:show-inheritance:
andes.core.model module
-----------------------
.. automodule:: andes.core.model
:members:
:undoc-members:
:show-inheritance:
andes.core.param module
-----------------------
.. automodule:: andes.core.param
:members:
:undoc-members:
:show-inheritance:
andes.core.service module
-------------------------
.. automodule:: andes.core.service
:members:
:undoc-members:
:show-inheritance:
andes.core.solver module
------------------------
.. automodule:: andes.core.solver
:members:
:undoc-members:
:show-inheritance:
andes.core.common module
------------------------
.. automodule:: andes.core.common
:members:
:undoc-members:
:show-inheritance:
andes.core.var module
---------------------
.. automodule:: andes.core.var
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.core
:members:
:undoc-members:
:show-inheritance:

46
docs/source/moduledoc/andes.io.rst Normal file
View File

@@ -0,0 +1,46 @@
andes.io package
================
Submodules
----------
andes.io.matpower module
------------------------
.. automodule:: andes.io.matpower
:members:
:undoc-members:
:show-inheritance:
andes.io.psse module
--------------------
.. automodule:: andes.io.psse
:members:
:undoc-members:
:show-inheritance:
andes.io.txt module
-------------------
.. automodule:: andes.io.txt
:members:
:undoc-members:
:show-inheritance:
andes.io.xlsx module
--------------------
.. automodule:: andes.io.xlsx
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.io
:members:
:undoc-members:
:show-inheritance:

94
docs/source/moduledoc/andes.models.rst Normal file
View File

@@ -0,0 +1,94 @@
andes.models package
====================
Submodules
----------
andes.models.area module
------------------------
.. automodule:: andes.models.area
:members:
:undoc-members:
:show-inheritance:
andes.models.bus module
-----------------------
.. automodule:: andes.models.bus
:members:
:undoc-members:
:show-inheritance:
andes.models.governor module
----------------------------
.. automodule:: andes.models.governor
:members:
:undoc-members:
:show-inheritance:
andes.models.group module
-------------------------
.. automodule:: andes.models.group
:members:
:undoc-members:
:show-inheritance:
andes.models.line module
------------------------
.. automodule:: andes.models.line
:members:
:undoc-members:
:show-inheritance:
andes.models.pq module
----------------------
.. automodule:: andes.models.pq
:members:
:undoc-members:
:show-inheritance:
andes.models.pv module
----------------------
.. automodule:: andes.models.pv
:members:
:undoc-members:
:show-inheritance:
andes.models.shunt module
-------------------------
.. automodule:: andes.models.shunt
:members:
:undoc-members:
:show-inheritance:
andes.models.synchronous module
-------------------------------
.. automodule:: andes.models.synchronous
:members:
:undoc-members:
:show-inheritance:
andes.models.timer module
-------------------------
.. automodule:: andes.models.timer
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.models
:members:
:undoc-members:
:show-inheritance:

46
docs/source/moduledoc/andes.routines.rst Normal file
View File

@@ -0,0 +1,46 @@
andes.routines package
======================
Submodules
----------
andes.routines.base module
--------------------------
.. automodule:: andes.routines.base
:members:
:undoc-members:
:show-inheritance:
andes.routines.eig module
-------------------------
.. automodule:: andes.routines.eig
:members:
:undoc-members:
:show-inheritance:
andes.routines.pflow module
---------------------------
.. automodule:: andes.routines.pflow
:members:
:undoc-members:
:show-inheritance:
andes.routines.tds module
-------------------------
.. automodule:: andes.routines.tds
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.routines
:members:
:undoc-members:
:show-inheritance:

54
docs/source/moduledoc/andes.utils.rst Normal file
View File

@@ -0,0 +1,54 @@
andes.utils package
===================
Submodules
----------
andes.utils.cached module
-------------------------
.. automodule:: andes.utils.cached
:members:
:undoc-members:
:show-inheritance:
andes.utils.paths module
------------------------
.. automodule:: andes.utils.paths
:members:
:undoc-members:
:show-inheritance:
andes.utils.func module
-----------------------
.. automodule:: andes.utils.func
:members:
:undoc-members:
:show-inheritance:
andes.utils.misc module
-----------------------
.. automodule:: andes.utils.misc
:members:
:undoc-members:
:show-inheritance:
andes.utils.tab module
----------------------
.. automodule:: andes.utils.tab
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.utils
:members:
:undoc-members:
:show-inheritance:

38
docs/source/moduledoc/andes.variables.rst Normal file
View File

@@ -0,0 +1,38 @@
andes.variables package
=======================
Submodules
----------
andes.variables.dae module
--------------------------
.. automodule:: andes.variables.dae
:members:
:undoc-members:
:show-inheritance:
andes.variables.fileman module
------------------------------
.. automodule:: andes.variables.fileman
:members:
:undoc-members:
:show-inheritance:
andes.variables.report module
-----------------------------
.. automodule:: andes.variables.report
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: andes.variables
:members:
:undoc-members:
:show-inheritance:

20
docs/source/old/about.md Normal file
View File

@@ -0,0 +1,20 @@
# About
### Contributors
* Rui Yao, Argonne National Laboratory <<ryao@anl.gov>>
* Feng Qiu, Argonne National Laboratory <<fqiu@anl.gov>>
* Kai Sun, University of Tennessee, Knoxville <<kaisun@utk.edu>>
* Jianzhe Liu, Argonne National Laboratory <<jianzhe.liu@ieee.org>>
### Acknowledgement
This work is supported by the Laboratory Directed Research and Development (LDRD) program of Argonne National Laboratory, provided by the U.S. Department of Energy Office of Science under Contract No. DE-AC02-06CH11357, and the U.S. Department of Energy Office of Electricity, Advanced Grid Modeling program under Grant DE-OE0000875.
### Publications
* Rui Yao, Kai Sun, Feng Qiu, “Vectorized Efficient Computation of Padé Approximation for Semi-Analytical Simulation of Large-Scale Power Systems,” IEEE Transactions on Power Systems, 34 (5), 3957-3959, 2019.
* Rui Yao, Yang Liu, Kai Sun, Feng Qiu, Jianhui Wang,"Efficient and Robust Dynamic Simulation of Power Systems with Holomorphic Embedding", IEEE Transactions on Power Systems, 35 (2), 938 - 949, 2020.
* Rui Yao, Feng Qiu, "Novel AC Distribution Factor for Efficient Outage Analysis", IEEE Transactions on Power Systems, 35 (6), 4960-4963, 2020.
* Xin Xu, Rui Yao, Kai Sun, Feng Qiu, "A Semi-Analytical Solution Approach for Solving Constant-Coefficient First-Order Partial Differential Equations", IEEE Control Systems Letters, 6, 704-709, 2021.
* Rui Yao, Feng Qiu, Kai Sun, “Contingency Analysis Based on Partitioned and Parallel Holomorphic Embedding”, IEEE Transactions on Power Systems, in press.
### License
This software is under BSD license. Please refer to LICENSE.md for details.

439
docs/source/old/advanced_usage.md Normal file
View File

@@ -0,0 +1,439 @@
# Advanced Usage
### 1. Customize analysis with settings file/struct
PowerSAS.m lets you customize your simulation by providing a simulation settings interface to specify the events and scenarios to be analyzed. To use the customized simulation, call the `runPowerSAS` function as follows:
```Matlab
res=runPowerSAS('dyn',data,options,settings,snapshot)
```
Details are explained as follows:
#### 1.1 Settings file
The input argument `settings` can be a string specifying the settings file name, or a struct containing all the simulation settings.
When `settings` is a string, it should be a valid file name of an .m script file containing the settings. Some examples of the settings files can be found in the directory `/data`. The settings file should have the following variables:
* `eventList`: A gross list of events. ([more details](#variable-eventlist))
* `bsBus`: (for black start simulation only) Black start bus information. ([more details](#variable-bsbus))
* `bsSyn`: (for black start simulation only) Generator information on black start bus. ([more details](#variable-bssyn))
* `bsInd`: (for black start simulation only) Inductin motor on black start bus. ([more details](#variable-bsind))
* `Efstd`: Excitation potential of synchronous generators. ([more details](#variable-efstd))
* `evtLine`: List of line addition/outage events. ([more details](#variables-evtline-and-evtlinespec))
* `evtLineSpec`: Specifications of line addition/outage events. ([more details](#variables-evtline-and-evtlinespec))
* `evtZip`: List of static load addition/shedding events. ([more details](#variables-evtzip-evtzipspec-and-evtzipspec2))
* `evtZipSpec`: Specifications of static load addition/shedding events. ([more details](#variables-evtzip-evtzipspec-and-evtzipspec2))
* `evtZipSpec2`: Alternative specifications of static load addition/shedding events. ([more details](#variables-evtzip-evtzipspec-and-evtzipspec2))
* `evtInd`: List of induction motor addition/outage events. ([more details](#variables-evtind-and-evtindspec))
* `evtIndSpec`: Specifications of induction motor addition/outage events. ([more details](#variables-evtind-and-evtindspec))
* `evtSyn`: List of synchronous generator addition/outage events. ([more details](#variables-evtsyn-and-evtsynspec))
* `evtSynSpec`: Specifications of synchronous generator addition/outage events. ([more details](#variables-evtsyn-and-evtsynspec))
* `evtFault`: List of fault occurrence/clearing events. ([more details](#variables-evtfault-and-evtfaultspec))
* `evtFaultSpec`: Specifications of fault occurrence/clearning events. ([more details](#variables-evtfault-and-evtfaultspec))
* `evtDyn`: List of dynamic ramping events. ([more details](#variable-evtdyn))
* `evtDynPQ`: Specifications of PQ bus ramping. ([more details](#variable-evtdynpq))
* `evtDynPV`: Specifications of PV bus ramping. ([more details](#variable-evtdynpv))
* `evtDynInd`: Specifications of induction motor mechanical load ramping. ([more details](#variable-evtdynind))
* `evtDynZip`: Specifications of ZIP load ramping. ([more details](#variable-evtdynzip))
* `evtDynSh`: Specifications of shunt compensator ramping. ([more details](#variable-evtdynsh))
* `evtDynZipRamp`: Alternative specifications of ZIP load ramping. ([more details](#variable-evtdynramp))
* `evtDynTmech`: Specifications of generator mechanical torque ramping. ([more details](#variable-evtdyntmech))
* `evtDynPm`: Specifications of generator input active power ramping. ([more details](#variable-evtdynpm))
* `evtDynEf`: Specifications of generator excitation potential ramping. ([more details](#variable-evtdynef))
* `evtDynVref`: Specifications of exciter reference voltage ramping. ([more details](#variable-evtdynvref))
* `evtDynEq1`: Specifications of generator transient excitation potential ramping. ([more details](#variable-evtdyneq1))
#### 1.2 Settings struct
Alternatively, the `settings` can be a struct containing all the previous variables as its fields.
#### Example 1: Transient stability analysis (TSA) using settings file
In this example, we want to perform transient stability analysis on 2383-bus system. Here is the scenario of the TSA:
* The total simulation period is 10 seconds.
* At 0.5 s, apply faults on the starting terminals of lines 74 and 114, the fault resistance is 0.0 and the reactance is 0.02. At 0.75 s, clear the faults.
* At 1.5 s, apply fault on the starting terminal of line 1674, the fault resistance is 0.0 and the reactance is 0.1. At 1.95 s, clear the faults.
The settings file for this simulation is shown below. Other variables irrelevant to the fault events are omitted here for the sake of clarity.
```Matlab
eventList=[...
1 0.0000 0.0000 0 1 0.0 0.0000
1.1 0.5000 0.0000 6 1 0.0 0.0000
1.2 0.7500 0.0000 6 2 0.0 0.0000
1.3 1.5000 0.0000 6 3 0.0 0.0000
1.4 1.9500 0.0000 6 4 0.0 0.0000
3 10.00 0.0000 99 0 0.0 0.0000
];
% Fault event data
evtFault=[...
1 1 2
2 3 4
3 5 5
4 6 6
];
evtFaultSpec=[...
114, 0.00, 0, 0.02, 0;
74, 0.00, 0, 0.02, 0;
114, 0.00, 0, 0.02, 1;
74, 0.00, 0, 0.02, 1;
1674, 0.00, 0, 0.1, 0;
1674, 0.00, 0, 0.1, 1;
];
```
Assume the settings file is `settings_polilsh_tsa.m` and the system data file is `d_dcase2383wp_mod2_ind_zip_syn.m`. We can run the TSA as follows:
```Matlab
res_2383_st=runPowerSAS('pf','d_dcase2383wp_mod2_ind_zip_syn.m'); % Run steady-state
res_2383_tsa=runPowerSAS('dyn','d_dcase2383wp_mod2_ind_zip_syn.m',setOptions('hotStart',1),'settings_polilsh_tsa',res_2383_st.snapshot); % Hot start from existing steady-state
plotCurves(1,res_2383_tsa.t,res_2383_tsa.stateCurve,res_2383_tsa.SysDataBase,'v'); % plot the voltage magnitude curves
```
### 2. Extended-term simulation using hybrid QSS and dynamic engines
To accelerate computation — especially for extended-term simulation — PowerSAS.m provides an adaptive way to switch between QSS and dynamic engines in the course of a simulation. With this feature enabled, PowerSAS.m can switch to QSS simulation for better speed on detecting the fade-away of transients and switch back to dynamic simulation upon detecting transient events.
For more details on the technical approach, please refer to our paper:
* Hybrid QSS and Dynamic Extended-Term Simulation Based on Holomorphic Embedding, arXiv:2104.02877
Example 2 illustrates the use of PowerSAS.m to perform extended-term simulation.
#### Example 2: Extended-term simulation
We want to study the response of a 4-bus system under periodic disturbances. The entire simulated process is 500 seconds. Starting at 60 s and continuing until 270 s, the system undergoes events of adding/shedding loads every 30 s.
The key settings of the simulation are:
```Matlab
% settings_d_004_2a_agc.m
eventList=[...
1 0.0000 0.0000 0 1 0.0 0.0100
6 60.0000 0.0000 2 1 0.0 0.0100
7 90.0000 0.0000 2 2 0.0 0.0100
8 120.0000 0.0000 2 3 0.0 0.0100
9 150.0000 0.0000 2 4 0.0 0.0100
10 180.0000 0.0000 2 1 0.0 0.0100
11 210.0000 0.0000 2 2 0.0 0.0100
12 240.0000 0.0000 2 3 0.0 0.0100
13 270.0000 0.0000 2 4 0.0 0.0100
18 500.0000 0.0000 99 0 0.0 0.0100
];
% Static load event data
evtZip=[...
1 1 1 1
2 1 2 2
3 1 3 3
4 1 4 4
];
evtZipSpec2=[...
3 100.0000 100.0000 60.0000 0.0648 0.0648 0.0648 0.0359 0.0359 0.0359 0 1
2 100.0000 100.0000 60.0000 0.0648 0.0648 0.0648 0.0359 0.0359 0.0359 0 1
3 100.0000 100.0000 60.0000 -0.0648 -0.0648 -0.0648 -0.0359 -0.0359 -0.0359 0 1
2 100.0000 100.0000 60.0000 -0.0648 -0.0648 -0.0648 -0.0359 -0.0359 -0.0359 0 1
];
```
First we run the simulation in full-dynamic mode and record time:
```Matlab
% Full dynamic simulation
tagFullDynStart=tic;
res_004_fulldyn=runPowerSAS('dyn','d_004_2a_bs_agc.m',[]],'settings_d_004_2a_agc');
timeFullDyn=toc(tagFullDynStart);
```
Then we run the simulation in hybrid QSS & dynamic mode and record time:
```Matlab
% Hybrid simulation with dynamic-QSS switching
tagHybridStart=tic;
res_004=runPowerSAS('dyn','d_004_2a_bs_agc.m',setOptions('allowSteadyDynSwitch',1),'settings_d_004_2a_agc');
timeHybrid=toc(tagHybridStart);
```
Compare the results:
```Matlab
plotCurves(1,res_004_fulldyn.t,res_004_fulldyn.stateCurve,res_004_fulldyn.SysDataBase,'v');
plotCurves(2,res_004.t,res_004.stateCurve,res_004.SysDataBase,'v');
```
And compare the computation time:
```Matlab
disp(['Full dynamic simulation computation time:', num2str(timeFullDyn),' s.']);
disp(['Hybrid simulation computation time:', num2str(timeHybrid),' s.']);
```
The complete example can be found in `/example/ex_extended_term_dyn.m`. And the results can also be found in our paper:
* Hybrid QSS and Dynamic Extended-Term Simulation Based on Holomorphic Embedding, arXiv:2104.02877
### Appendix: Variables in settings
#### variable `eventList`
([back to top](#11-settings-file))
##### Table 1. Definition of `eventList`
Column | Content
-------| -------------
1 | Event index (can be an integer or a real number)
2 | Event start time
3 | Event end time (no effect for instant event)
4 | Type of event (see [Table 2](#table-2-event-types))
5 | Index of event under its type
6 | Simulation method (default 0.0) (see below [Simulation methods](#simulation-methods))
7 | Timestep (default 0.01)
##### Table 2. Event types
([back to top](#11-settings-file))
Value | Event type
-------| -------------
0 | Calculate steady-state at start
1 | Add line
2 | Add static load
3 | Add induction motor load
4 | Add synchronous generator
6 | Applying/clearing faults
7 | Cut line
8 | Cut static load
9 | Cut motor load
10| Cut synchronous generator
50| Dynamic process
99| End of simulation
##### Simulation methods
Simulation methods can be specified for each event on the 6th column of `eventList`. It is encoded as a number `x.yz`, where:
* `x` is the method for solving differential equation, where 0 - SAS, 1 - Modified Euler, 2 - R-K 4, 3 - Trapezoidal rule.
* `y` is the method for solving algebraic equation, where 0 - SAS, 1 - Newton-Raphson.
* `z` is whether to use variable time step scheme for numerical integration (`x` is 1, 2 or 3). 0 - Fixed step, 1 - Variable step.
Note that when `x=0`, `y` and `z` are not effective, it automatically uses SAS and variable time steps.
#### variable `bsBus`
([back to top](#11-settings-file))
Current version only support one black start bus and therefore only the first line will be recognized. Will expand in the future versions.
Column | Content
-------| -------------
1 | Bus index
2 | Active power of Z component load
3 | Active power of I component load
4 | Active power of P component load
5 | Reactive power of Z component load
6 | Reactive power of I component load
7 | Reactive power of P component load
#### variable `bsSyn`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Excitation potential
3 | Active power
4 | Participation factor for power balancing
#### variable `bsInd`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of induction motor
2 | Mechanical load torque
#### variable `Efstd`
([back to top](#11-settings-file))
When there are synchronous generators in the system model, `Efstd` is needed to compute steady state. The `Efstd` is a column vector specifying the excitation potential of every synchronous generator, or it can also be a scalar assigning the excitation potentials of all the generator as the same value.
#### variables `evtLine` and `evtLineSpec`
([back to top](#11-settings-file))
In `eventList`, when the 4th column (event type) equals 1 or 7 (add or cut line, respectively), the index of the line events in `evtLine` corresponds to the 5th column of `eventList`.
##### variable `evtLine`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of line events (from 5th column of `eventList`)
2 | Start index in `evtLineSpec`
3 | End index in `evtLineSpec`
##### variable `evtLineSpec`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of line
2 | Add/cut mark, 0 - add line, 1 - cut line
3 | Reserved
4 | Reserved
5 | Reserved
#### variables `evtZip`, `evtZipSpec` and `evtZipSpec2`
([back to top](#11-settings-file))
In `eventList`, when the 4th column (event type) equals 2 or 8 (add/cut static load), the index of the load events in `evtZip` corresponds to the 5th column of `eventList`.
##### variable `evtLine`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of load events (from 5th column of `eventList`)
2 | Choose `evtZipSpec` (0) or `evtZipSpec2` (1)
3 | Start index in `evtZipSpec` or `evtZipSpec2`
4 | End index in `evtZipSpec` or `evtZipSpec2`
##### variable `evtZipSpec`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of zip loads in system base state
2 | Add/cut mark, 0 - add load, 1 - cut load
##### variable `evtZipSpec2` (recommended)
([back to top](#11-settings-file))
`evtZipSpec2` has the same format as PSAT ZIP load format, which represents the change of ZIP load. Whether the event is specified as add/cut load does not make difference.
#### variables `evtInd` and `evtIndSpec`
([back to top](#11-settings-file))
In `eventList`, when the 4th column (event type) equals 3 or 9 (add or cut induction motors, respectively), the index of the induction motor events in `evtInd` corresponds to the 5th column of `eventList`.
##### variable `evtInd`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of induction motor events (from 5th column of `eventList`)
2 | Start index in `evtIndSpec`
3 | End index in `evtIndSpec`
##### variable `evtIndSpec`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of induction motor
2 | Event type, 0 - add motor, 1 - change state, 2 - cut motor
3 | Designated mechanical torque
4 | Designated slip
#### variables `evtSyn` and `evtSynSpec`
([back to top](#11-settings-file))
In `eventList`, when the 4th column (event type) equals 4 or 10 (add or cut synchronous generators, respectively), the index of the synchronous generator events in `evtSyn` corresponds to the 5th column of `eventList`.
##### variable `evtSyn`
Column | Content
-------| -------------
1 | Index of synchronous generator events (from 5th column of `eventList`)
2 | Start index in `evtSynSpec`
3 | End index in `evtSynSpec`
##### variable `evtSynSpec`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Event type, 0 - add generator, 1 - cut generator
3 | Designated rotor angle (only effective when adding generator, NaN means the rotor angle is the same with voltage angle).
4 | Designated mechanical power (only effective when adding generator).
5 | Designated excitation potential (only effective when adding generator).
#### variables `evtFault` and `evtFaultSpec`
([back to top](#11-settings-file))
In `eventList`, when the 4th column (event type) equals 6 (apply or clear faults, respectively), the index of the fault events in `evtFault` corresponds to the 5th column of `eventList`. In the current version, we only consider three-phase grounding faults.
##### variable `evtFault`
Column | Content
-------| -------------
1 | Index of fault events (from 5th column of `eventList`)
2 | Start index in `evtFaultSpec`
3 | End index in `evtFaultSpec`
##### variable `evtFaultSpec`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of fault line
2 | Position of fault, 0.0 stands for starting terminal and 1.0 stands for ending terminal.
3 | Resistance of fault.
4 | Reactance of fault.
5 | Event type: 0 - add fault; 1 - clear fault.
#### variable `evtDyn`
([back to top](#11-settings-file))
The `evtDyn` variable specifies the indexes of ramping events involving various types of components.
Column | Content
-------| -------------
1 | Index of event
2 | Start index in `evtDynPQ`
3 | End index in `evtDynPQ`
4 | Start index in `evtDynPV`
5 | End index in `evtDynPV`
6 | Start index in `evtDynInd`
7 | End index in `evtDynInd`
8 | Start index in `evtDynZip`
9 | End index in `evtDynZip`
10| Start index in `evtDynSh`
11| End index in `evtDynSh`
12| Start index in `evtDynZipRamp`
13| End index in `evtDynZipRamp`
14| Start index in `evtDynTmech`
15| End index in `evtDynTmech`
16| Start index in `evtDynPm`
17| End index in `evtDynPm`
18| Start index in `evtDynEf`
19| End index in `evtDynEf`
20| Start index in `evtDynVref`
21| End index in `evtDynVref`
22| Start index in `evtDynEq1`
23| End index in `evtDynEq1`
#### variable `evtDynPQ`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of bus
2 | Active power ramping rate
3 | Reactive power ramping rate
#### variable `evtDynPV`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of bus
2 | Active power ramping rate
#### variable `evtDynInd`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of induction motor
2 | Mechanical load torque ramping rate
#### variable `evtDynZip`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of bus
2 | ZIP load ramping rate
#### variable `evtDynSh`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of bus
2 | Shunt admittance ramping rate
#### variable `evtDynZipRamp`
([back to top](#11-settings-file))
`evtDynZipRamp` has the same format as PSAT ZIP load format, which represents the ramping direction of ZIP load.
#### variable `evtDynTmech`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Ramping rate of mechanical power reference value (TG required)
#### variable `evtDynEf`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Ramping rate of excitation potential
#### variable `evtDynVref`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Ramping rate of exciter reference voltage
#### variable `evtDynEq1`
([back to top](#11-settings-file))
Column | Content
-------| -------------
1 | Index of synchronous generator
2 | Ramping rate of transient excitation potential

141
docs/source/old/basic_usage.md Normal file
View File

@@ -0,0 +1,141 @@
# Using PowerSAS.m: The Basics
### 1 Initialization before use
To initialize PowerSAS.m, add the main directory of PowerSAS to Matlab or GNU Octave path, and execute command `initpowersas`. This will ensure all the functions of PowerSAS be added to the path and thus callable.
### 2 Call high-level API -- `runPowerSAS`
Most grid analysis functionalities can be invoked through the high-level function `runPowerSAS`. `runPowerSAS` is defined as follows:
```Matlab
function res=runPowerSAS(simType,data,options,varargin)
```
##### Input arguments
* `simType` is a string specifying the type of analysis, which can be one of the following values:
* `'pf'`: Conventional power flow or extended power flow (for finding steady state of dynamic model).
* `'cpf'`: Continuation power flow.
* `'ctg'`: Contingency analysis (line outages).
* `'n-1'`: N-1 line outage screening.
* `'tsa'`: Transient stability analysis.
* `'dyn'`: General dynamic simulation.
* `data` is the system data to be analyzed. It can be either a string specifying the data file name, or a `SysData` struct. For more information about data format and `SysData` struct, please refer to the "Data format and models" chapter.
* `options` specifies the options for analysis. If you do not provide `options` argument, or if you simply set the field to empty with `[]`, the corresponding routines will provide default options that will fit most cases. See Advanced Use chapter for more details.
* `varargin` are the additional input variables depending on the type of analysis. Section 3 Basic analysis funtionalifies will explain more details.
##### Output
Output `res` is a struct containing simulation result, system states, system data, etc.
* `res.flag`: Flag information returned by the analysis task.
* `res.msg`: More information as supplemental to the flag information.
* `res.caseName`: The name of the analyzed case.
* `res.timestamp`: A string showing the timestamp the analysis started, can be viewed as an unique identifier of the analysis task.
* `res.stateCurve`: A matrix storing the evolution of system states, where the number of rows equals the number of state variables, and the number of columns equals the number of time points.
* `res.t`: A vector storing time points corresponding to states in `res.stateCurve`.
* `res.simSettings`: A struct specifying the simulation settings, including simulation parametersand defined events.
* `res.eventList`: A matrix showing as the list of events in the system in the analysis task.
* `res.SysDataBase`: A struct of system data at base state.
* `res.snapshot`: The snapshot of the system states at the end of anlaysis, which can be used to initilize other analysis tasks.
To access the system states, we need to further access each kind of state variable in `res.stateCurve`. For example, the commands to extract the voltage from `res.stateCurve` are shown below:
```Matlab
[~,idxs]=getIndexDyn(res.SysDataBase); % Get the indexes of each kind of state variables
vCurve=res.StateCurve(idxs.vIdx,:); % idxs.vIdx is the row indexes of voltage variables
```
### 3 Basic analysis functionalities
#### 3.1 Power flow analysis
When `simType='pf'`, the `runPowerSAS` function runs power flow analysis. In addition to the conventional power flow model, `runPowerSAS` also integrates an extended power flow to solve the steady state of dynamic models. For example, it will calculate the rotor angles of synchronous generators and slips of induction motors in addition to the network equations.
To perform power flow analysis, call the `runPowerSAS` function as follows:
```Matlab
res=runPowerSAS('pf',data,options)
```
where the argument `data` can either be a string of file name or a `SysData` struct.
Below are some examples:
```Matlab
% Use file name string to specify data
res1=runPowerSAS('pf','d:/codes/d_003.m'); % Filename can use absolute path
res2=runPowerSAS('pf','d_003.m'); % If data file is already in the Matlab/Octave path,
% then can directly use file name
res3=runPowerSAS('pf','d_003'); % Filename can be without '.m'
res4=runPowerSAS('pf','d_003',setOptions('dataPath','d:/codes'); % Another way to specify data path
% Use SysData struct to specify data
SysData=readDataFile('d_003.m','d:/codes'); % Generate SysData struct from data file
res5=runPowerSAS('pf',SysData); % Run power flow using SysData struct
```
#### 3.2 Continuation Power Flow
Continuation power flow (CPF) analysis in PowerSAS.m features enhanced efficiency and convergence. To perform continuation power flow analysis, call `runPowerSAS` function as follows:
```Matlab
res=runPowerSAS('cpf',data,options,varargin)
```
where `options` (optional) specifies the options of CPF analysis, and `varargin` are the input arguments:
* `varargin{1}` (optional) is the ramping direction of load, which is an $\text{N}\times \text{12}$ matrix, the first column is the index of the bus, and the columns 5-10 are the ZIP load increase directions.
* `varargin{2}` (optional) is the ramping direction of generation power, which is an $\text{N}\times \text{2}$ matrix, the first column is the index of the bus, and the 2nd column is the generation increase directions.
* `varargin{3}` (optional) is the snapshot of the starting state, with which the computation of starting steady state is skipped.
Some examples can be found in `example/ex_cpf.m`.
#### 3.3 Contingency Analysis
Contingency analysis computes the system states immediately after removing a line/lines. To perform contingency analysis, call `runPowerSAS` as follows:
```Matlab
res=runPowerSAS('ctg',data,options,varargin)
```
where `options` (optional) specifies the options of contingency analysis. When not using customized options, set `options=[]`. And `varargin` are the input arguments:
* `varargin{1}` (mandatory) is a vector specifying the indexes of lines to be removed simultaneously.
* `varargin{2}` (optional) is the snapshot of the starting state. With this option, computing the starting steady state is skipped.
Some examples can be found in `example/ex_ctg.m`.
#### 3.4 N-1 screening
N-1 screening is essentially performing a series of contingency analysis, each removing a line from the base state. To perform N-1 screening, call `runPowerSAS` as follows:
```Matlab
res=runPowerSAS('n-1',data,options)
```
The return value `res` is a cell containing each contingency analysis results.
Some examples can be found in `example/ex_n_minus_1.m`.
#### 3.5 Transient Stability Analysis
Transient stability anslysis (TSA) assesses the system dynamic behavior and stability after given disturbance(s). 3-phase balanced fault(s) are the most common disturbances in the TSA. In PowerSAS, the TSA supports the analysis of the combinations of multiple faults. To perform transient Stability Analysis, call `runPowerSAS` in the following way:
```Matlab
res=runPowerSAS('tsa',data,options,varargin)
```
where `options` (optional) specifies the options of TSA. When not using customized options, set `options=[]`. And `varargin` are the input arguments:
* `varargin{1}` (mandatory) is a $\text{N}\times \text{6}$ matrix specifying the faults:
* The 1st column is the index of line where the fault happens.
* The 2nd column is the relative position of the fault, 0.0 stands for the starting terminal and 1.0 stands for the ending terminal. For example, 0.5 means the fault happens in the middle point of the line.
* The 3rd and 4th columns are the resistance and reactance of the fault.
* The 5th and 6th columns specify the fault occurrence and clearing times.
* `varargin{2}` (optional) is the snapshot of the starting state, with which the computation of starting steady state is skipped.
By default, the TSA is run for 10 seconds. To change the simulation length, specify in the `options` argument, e.g. `options=setOptions('simlen',30)`.
Example can be found in `example/ex_tsa.m`.
### 4. Plot dynamic analysis results
PowerSAS provides an integrated and formatted way of plotting the system behavior in the time domain. The function for plotting curves is `plotCurves`. The function is defined as follows:
```Matlab
function plotCurves(figId,t,stateCurve,SysDataBase,variable,...
subIdx,lw,dot,fontSize,width,height,sizeRatio)
```
The argument list is explained as follows:
* `figId`: A positive integer or `[]` specifying the index of figure.
* `t`: A vector of time instants. If got `res` from `runPowreSAS` function, then input this argument as `res.t`.
* `stateCurve`: A matrix of system states in time domain, the number of columns should equal to the length of `t`. If got `res` from `runPowreSAS` function, then input this argument as `res.stateCurve`.
* `SysDataBase`: A SysData struct specifying the base system. If got `res` from `runPowreSAS` function, then input this argument as `res.SysDataBase`.
* `variable`: A string of variable name to be plotted. Here is a nonexhaustive list:
* `'v'`: voltage magnitude (pu);
* `'a'`: voltage angle (rad);
* `'delta'`: rotor angle of synchronous generators;
* `'omega'`: deviation of synchronous generator rotor speed;
* `'s'`: induction motor slips;
* `'f'`: frequency;
* `subIdx`: Allows you to pick a portion of the variables to plot e.g., the voltage of some selected buses. Default value is `[]`, which means that all the selected type of variables are plotted.
* `lw`: Line width. Default value is 1.
* `dot`: Allows you to choose whether to show data points. 1 means curves mark data dots, and 0 means no data dots are shown on curves. The default value is 0.
* `fontSize`: Font size of labels. Default value is 12.
* `width`: Width of figure window in pixels.
* `height`: Height of figure window in pixels.
* `sizeRatio`: If `width` or `height` is not specified, the size of the figure is determined by the `sizeRatio` of the screen size. The default value of `sizeRatio` is 0.7.

13
docs/source/old/data_and_models.md Normal file
View File

@@ -0,0 +1,13 @@
# Data and Models
### 1. Supported data formats
Currently PowerSAS.m supports extended PSAT (Matlab) data format. Support for other formats and data format conversion features will be added in future versions.
### 2. Extension of PSAT (Matlab) format
#### 2.1 Automatic generation control (AGC) model
Here PowerSAS provides a simple AGC model. It is named as `Agc.con` in data files and it is a $\text{N}\times \text{4}$ matrix. Each column is defined as below:
Column | Content
-------| -------------
1 | Bus index
2 | Reciprocal of turbine governor gain on bus
3 | Effective damping ratio on bus
4 | Reciprocal of AGC control time constant

BIN
docs/source/old/img/accuracy_039_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 235 KiB

BIN
docs/source/old/img/accuracy_039_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 168 KiB

BIN
docs/source/old/img/comp_speed_458.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 175 KiB

BIN
docs/source/old/img/comp_time_039.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/source/old/img/contingency_458.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 199 KiB

BIN
docs/source/old/img/ssa_benchmarking.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 263 KiB

12
docs/source/old/index.md Normal file
View File

@@ -0,0 +1,12 @@
# PowerSAS.m
**PowerSAS.m** is a robust, efficient and scalable power grid analysis framework based on semi-analytical solutions (SAS) technology. The **PowerSAS.m** is the version for MATLAB/Octave users. It currently provides the following functionalities (more coming soon!):
* **Steady-state analysis**, including power flow (PF), continuation power flow (CPF), contingency analysis.
* **Dynamic security analysis**, including voltage stability analysis, transient stability analysis, and flexible user-defined simulation.
* **Hybrid extended-term simulation** provides adaptive QSS-dynamic hybrid simulation in extended term with high accuracy and efficiency.
### Key features
* **High numerical robustness.** Backed by the SAS approach, the PowerSAS tool provides much better convergence than the tools using traditional Newton-type algebraic equation solvers when solving algebraic equations (AE)/ordinary differential equations (ODE)/differential-algebraic equations(DAE).
* **Enhanced computational performance.** Due to the analytical nature, PowerSAS provides model-adaptive high-accuracy approximation, which brings significantly extended effective range and much larger steps for steady-state/dynamic analysis. PowerSAS has been used to solve large-scale system cases with 200,000+ buses.
* **Customizable and extensible.** PowerSAS supports flexible customization of grid analysis scenarios, including complex event sequences in extended simulation term.

22
docs/source/old/installation.md Normal file
View File

@@ -0,0 +1,22 @@
# Installation
### 1. System requirements
Matlab (7.1 or later) or GNU Octave (4.0.0 or later).
### 2. Installation
* Extract source code to a directory.
* Enter the directory in Matlab or GNU Octave.
* Execute command `setup`. You will see the following sub-directories:
* `/data`: Stores test system data, simulation settings data, etc.
* `/example`: Some examples of using PowerSAS.m.
* `/output`: Stores test result data.
* `/internal`: Internal functions of PowerSAS.m computation core.
* `/util`: Auxiliary functions including data I/O, plotting, data conversion, etc.
* `/logging`: Built-in logging system.
* `/doc`: Documentation.
### 3. Test
* Execute command `initpowersas` to initialize the environment, then execute `test_powersas` to run tests. You should expect all tests to pass.
### 4. Initialization
To initialize PowerSAS.m, add the main directory of PowerSAS.m to your Matlab or GNU Octave path and run the command `initpowersas`. This will ensure that all the functions of PowerSAS.m are added to the path and thus callable.

61
docs/source/old/sas_basics.md Normal file
View File

@@ -0,0 +1,61 @@
# SAS and PowerSAS.m: The Story
### 1. What are Semi-Analysical Solutions (SAS)?
Semi-analytical solutions (SAS) is a family of computational methods that uses certain analytical formulations (e.g., power series, fraction of power series, continued fractions) to approximate the solutions of mathematical problems. In terms of formulation, they are quite different from the commonly used numerical approaches e.g., Newton-Raphson method for solving algebraic equations, Runge-Kutta and Trapezoidal methods for solving differential equations. The parameters of SAS still need to be determined through some (easier and more robustness-guaranteed) numerical computation, and thus these methods are called semi-analytical.
### 2. What are the advantages of SAS?
In power system modeling and analysis, SAS has been proven to have the following features:
* **High numerical robustness.** Steady-state analysis usually requires solving nonlinear algebraic equations. Traditional tools usually use Newton-Raphson method or its variants, whose results can be highly dependent on the selection of starting point and they suffer from non-convergence problem. In contrast, SAS provides much better convergence thanks to the high-level analytical nature.
* **Enhanced computational performance.** In dynamic analysis, the traditional numerical integration approaches are essentially lower-order methods, which are confined to small time steps to avoid too-rapid error accumulation. These tiny time steps severely restrict the computation speed. In contrast, SAS provides high-order approximation, enabling much larger effective time steps and faster computation speed.
* **More accurate event-driven simulation.** For complex system simulation, it is common to simulate discrete events. Traditional numerical integration methods only provide solution values on discrete time steps and thus may incur substantial errors predicting events. In contrast, SAS provides an analytical form of solution as a continuous function, and thus can significantly reduce event prediction errors.
### 3. How is the performance of PowerSAS.m?
#### 3.1 Benchmarking with traditional methods on Matlab
PowerSAS.m shows advantages in both computational robustness and efficiency over the traditional approaches.
On **steady-state analysis**, we have done several benchmarking with traditional methods. For example, we test the steady-state contingency analysis on PowerSAS.m and Newton-Raphson (NR) method and its variants on Matlab. The test is performed on a reduced Eastern-Interconnection (EI) system and we tested on 30,000 contingency scenarios. The results suggest that the traditional methods have about 1% chance of failing to deliver correct results, while SAS has delivered all the correct results.
For more details, please refer to our recent paper:
* Rui Yao, Feng Qiu, Kai Sun, “Contingency Analysis Based on Partitioned and Parallel Holomorphic Embedding”, IEEE Transactions on Power Systems, in press.
On **dynamic analysis**, we have compared with serveral most commonly used traditional numerical approaches for solving ODE/DAEs, including modified Euler, Runge-Kutta, and trapezoidal methods. Tests of transient-stability analysis on IEEE 39-bus system model and large-scale mdodified Polish 2383-bus system model have verified that SAS has significant advantages over the traditional methods in both accuracy and efficiency.
**Accuracy comparison on IEEE 39-bus system (1) -- Comparison with fixed-time-step traditional methods**
![accuracy_039_1](https://user-images.githubusercontent.com/96191387/183999952-362734f7-d40c-4d27-aa79-eb48bdebcebf.png)
**Accuracy comparison on IEEE 39-bus system (2) -- Comparison with variable-time-step traditional method**
![accuracy_039_2](https://user-images.githubusercontent.com/96191387/184000210-90382d81-06bb-4cf6-a423-b8588579e0fd.png)
**Computation time comparison on IEEE 39-bus system**
![comp_time_039](https://user-images.githubusercontent.com/96191387/184000437-6aa9150e-d4b1-4297-b982-61e3e68bc2b8.png)
For more details, please refer to our recent paper:
* Rui Yao, Yang Liu, Kai Sun, Feng Qiu, Jianhui Wang,"Efficient and Robust Dynamic Simulation of Power Systems with Holomorphic Embedding", IEEE Transactions on Power Systems, 35 (2), 938 - 949, 2020.
#### 3.2 Benchmarking with PSS/E
##### 3.2.1 Static Security Region (SSR)
Static Security Region (SSR) is an important decision-support tool showing region of stable operating points. However, there are often challenges on convergence when computing SSRs, especially near the boundaries. So SSR can be used for benchmarking the numerical robustness of computational methods.
We test SSR on IEEE 39-bus system by varying active power of buses 3&4. The active power of buses 3&4 are sampled uniformly over the interval of [-4000, 4000] MW. The figure below shows the SSR derived by PSS/E and PowerSAS.m. It shows that PSS/E result have some irregular outliers (about 0.1% of the samples) outside of the SSR and actually are not correct solutions of power flow equations. In contrast, PowerSAS.m correctly identifies the SSR.
![ssa_benchmarking](https://user-images.githubusercontent.com/96191387/184000532-d838e7c4-7dc3-4fd6-98ad-486a596ef33d.png)
##### 3.2.2 N-k Contingency analysis
Contingency ananlysis also has convergence challenges due to large disturbances. Here we perform benchmarking between PSS/E (with and without non-divergence options) and PowerSAS.m on the N-25 contingency analysis on a reduced eastern-interconnection (EI) system with 458 buses. We increase the load & generation level by 15%, 20%, and 20.7%, respectively, as 3 different loading scenarios (loading margin is 20.791%). In each scenario, we randomly choose 5000 N-25 contingency samples.
![contingency_458](https://user-images.githubusercontent.com/96191387/184000600-6ac3101f-d8bc-49bb-b85d-4cea43ab3549.png)
The figure shows the percentage of correct results using different tools. It can be seen that PSS/E has some chance to deliver incorrect results, and the chance increases with loading level. In contrast, PowerSAS.m still returns results all correctly.
We also compared the computation speeds of PowerSAS.m and PSS/E. The figure below shows the average contingency analysis computation time of on the 458-bus system. The results show that SAS’s speed is comparable to and even faster than PSS/E’s.
![x](/img/comp_speed_458.png)

522
docs/source/release-notes.rst Normal file
View File

@@ -0,0 +1,522 @@
.. _ReleaseNotes:
=============
Release Notes
=============
The APIs before v3.0.0 are in beta and may change without prior notice.
v1.4 Notes
----------
v1.4.3 (2021-09-25)
```````````````````
This release features parallel processing that cuts the time for
``andes prepare`` by more than half.
- ``andes prepare`` supports multiprocessing and uses it by default.
- Added aliases ``andes st`` and ``andes prep`` for
``andes selftest`` and ``andes prepare``.
- ``andes.config_logger`` supports setting new ``stream_level`` and
``file_level``.
New exciter models are contributed by Jinning Wang.
- Added ``AC8B``, ``IEEET3`` and ``ESAC1A``.
Other changes include disallowing numba's ``nopython`` mode.
v1.4.2 (2021-09-12)
```````````````````
- Bug fixes
- Dropped support for ``cvxoptklu``.
v1.4.1 (2021-09-12)
```````````````````
- Bug fixes.
- Overhaul of the ``prepare`` and ``undill`` methods.
- ``andes prepare`` can be called for specific models through
``-m``, which takes one or many model names as arguments.
v1.4.0 (2021-09-08)
```````````````````
This release highlights the distributed energy resource protection model.
- Added ``DGPRCT1`` model to provide DG models with voltage-
and frequency-based protection following IEEE 1547-2018.
- ``REECA1E`` supports frequency droop on power.
- Throws TypeError if type mismatches when using ExtAlgeb and ExtState.
v1.3 Notes
----------
v1.3.12 (2021-08-22)
````````````````````
Plot enhancements:
- ``plot()`` takes an argument ``mark`` for masking y-axis data based on
the ``left`` and ``right`` range parameters.
- ``TDS.plt`` provides a ``panoview`` method for plotting an panoramic view
for selected variables and devices of a model.
Models:
- Added WIP EV models and protection models.
Test case:
- Added CURENT EI test system.
- Added a number of IEEE 14 bus test systems for specific models.
v1.3.11 (2021-07-27)
````````````````````
- Added ``REECA1E`` model with inertia emulation.
- Fixed an issue where the ``vtype`` of services was ignored.
- Changed default DPI for plotting to 100.
v1.3.10 (2021-06-08)
````````````````````
- Bug fixes for controllers when generators are off.
v1.3.9 (2021-06-02)
```````````````````
- Bug fixes in exciters when generators are offline.
- Added `safe_div` function for initialization equations.
v1.3.8 (2021-06-02)
```````````````````
- Added ``REGCVSG`` model for voltage-source controlled renewables.
- Turbine governors are now aware of the generator connection status.
v1.3.7 (2021-05-03)
```````````````````
- Allow manually specifying variables needing initialization
preceding a variable. Specify a list of variable names through
``BaseVar.deps``.
v1.3.6 (2021-04-23)
```````````````````
- Patched ESD1 model. Converted `distributed.py` into a package.
- Bug fixes.
v1.3.5 (2021-03-20)
```````````````````
- Fixed a bug in connectivity check when bus 0 is islanded.
- Updated notebook examples.
- Updated tutorials.
v1.3.4 (2021-03-13)
```````````````````
- Fixed a bug for the generated renewable energy code.
v1.3.2 (2021-03-08)
```````````````````
- Relaxed the version requirements for NumPy and SymPy.
v1.3.1 (2021-03-07)
```````````````````
- Writes all generated Python code to ``~/.andes/pycode`` by default.
- Uses generated Python code by default instead of `calls.pkl`.
- Works with NumPy 1.20; works on Apple Silicon (use `miniforge`) to
install native Python and NumPy for Apple Silicon.
- Generalized model initialization: automatically determines the
initialization sequence and solve equations iteratively when
necessary.
- In `System.config`, `save_pycode` and `use_pycode` are now
deprecated.
v1.3.0 (2021-02-20)
```````````````````
- Allow `State` variable set `check_init=False` to skip
initialization test. One use case is for integrators
with non-zero inputs (such as state-of-charge integration).
- Solves power flow for systems with multiple areas, each with
one Slack generator.
- Added `Jumper` for connecting two buses with zero impedance.
- `REGCA1` and synchronous generators can take power ratio
parameters `gammap` and `gammaq`.
- New models: `IEESGO` and `IEEET1`, `EXAC4`.
- Refactored exciters, turbine governors, and renewable models
into modules.
v1.2 Notes
----------
v1.2.9 (2021-01-16)
```````````````````
- Added system connectivity check for islanded buses.
- Depend on `openpyxl` for reading excel files since `xlrd` dropped
support for any format but `xlsx` since v2.0.0.
v1.2.7 (2020-12-08)
```````````````````
- Time-domain integration now evaluates anti-windup limiter before
algebraic residuals. It assures that algebraic residuals are
calculated with the new state values if pegged at limits.
- Fixed the conditions for Iq ramping in REGC;
removed ``Iqmax`` and ``Iqmin``.
- Added a new plot function ``plotn`` to allow multiple subplots in
one figure.
- ``TDS.config.g_scale`` is now now used as a factor for scaling
algebraic equations for better convergence. Setting it to 1.0
functions the same as before.
v1.2.6 (2020-12-01)
```````````````````
- Added `TGOV1N` model which sums `pref` and `paux` after
the 1/droop block.
- Added `ZIP` and `FLoad` for dynamic analysis. Need to be initialized
after power flow.
- Added `DAETimeSeries.get_data()` method.
- Added IEEE 14-bus test cases with solar PV (ieee14_solar.xlsx) and
Generic Type 3 wind (ieee14_wt3.xlsx).
v1.2.5 (2020-11-19)
```````````````````
- Added `Summary` model to allow arbitrary information for
a test case. Works in `xlsx` and `json` formats.
- PV reactive power limit works. Automatically determines
the number of PVs to convert if `npv2pq=0`.
- Limiter and AntiWindup limiter can use `sign_upper=-1` and
`sign_lower=-1` to negate the provided limits.
- Improved error messages for inconsistent data.
- `DAETimeSeries` functions refactored.
v1.2.4 (2020-11-13)
```````````````````
- Added switched shunt class `ShuntSw`.
- BaseParam takes `inconvert` and `oconvert` for converting parameter
elements from and to files.
v1.2.3 (2020-11-02)
```````````````````
- Support variable `sys_mva` (system base mva) in equation strings.
- Default support for KVXOPT through ``pip`` installation.
v1.2.2 (2020-11-01)
```````````````````
New Models:
- ``PVD1`` model, WECC distributed PV model.
Supports multiple PVD1 devices on the same bus.
- Added ``ACEc`` model, ACE calculation with continuous freq.
Changes and fixes:
- Renamed `TDS._itm_step` to `TDS.itm_step` as a public API.
- Allow variable `sys_f` (system frequency) in equation strings.
- Fixed ACE equation.
measurement.
- Support ``kvxopt`` as a drop-in replacement for ``cvxopt``
to bring KLU to Windows (and other platforms).
- Added ``kvxopt`` as a dependency for PyPI installation.
v1.2.1 (2020-10-11)
```````````````````
- Renamed `models.non_jit` to `models.file_classes`.
- Removed `models/jit.py` as models have to be loaded and instantiated
anyway before undill.
- Skip generating empty equation calls.
v1.2.0 (2020-10-10)
```````````````````
This version contains major refactor for speed improvement.
- Refactored Jacobian calls generation so that for each model, one call
is generated for each Jacobian type.
- Refactored Service equation generation so that the exact arguments are
passed.
Also contains an experimental Python code dump function.
- Controlled in ``System.config``, one can turn on ``save_pycode`` to dump
equation and Jacobian calls to ``~/.andes/pycode``. Requires one call to
``andes prepare``.
- The Python code dump can be reformatted with ``yapf`` through the config
option ``yapf_pycode``. Requires separate installation.
- The dumped Python code can be used for subsequent simulations through
the config option ``use_pycode``.
v1.1 Notes
----------
v1.1.5 (2020-10-08)
```````````````````
- Allow plotting to existing axes with the same plot API.
- Added TGOV1DB model (TGOV1 with an input dead-band).
- Added an experimental numba support.
- Patched `LazyImport` for a snappier command-line interface.
- ``andes selftest -q`` now skips code generation.
v1.1.4 (2020-09-22)
```````````````````
- Support `BackRef` for groups.
- Added CLI ``--pool`` to use ``multiprocess.Pool`` for multiple cases.
When combined with ``--shell``, ``--pool`` returns ``System`` Objects
in the list ``system``.
- Fixed bugs and improved manual.
v1.1.3 (2020-09-05)
```````````````````
- Improved documentation.
- Minor bug fixes.
v1.1.2 (2020-09-03)
```````````````````
- Patched time-domain for continuing simulation.
v1.1.1 (2020-09-02)
```````````````````
- Added back quasi-real-time speed control through `--qrt`
and `--kqrt KQRT`.
- Patched the time-domain routine for the final step.
v1.1.0 (2020-09-01)
```````````````````
- Defaulted `BaseVar.diag_eps` to `System.Config.diag_eps`.
- Added option `TDS.config.g_scale` to allow for scaling the
algebraic mismatch with step size.
- Added induction motor models `Motor3` and `Motor5` (PSAT models).
- Allow a PFlow-TDS model to skip TDS initialization by setting
`ModelFlags.tds_init` to False.
- Added Motor models `Motor3` and `Motor5`.
- Imported `get_case` and `list_cases` to the root package level.
- Added test cases (Kundur's system) with wind.
Added Generic Type 3 wind turbine component models:
- Drive-train models `WTDTA1` (dual-mass model) and `WTDS`
(single-mass model).
- Aerodynamic model `WTARA1`.
- Pitch controller model `WTPTA1`.
- Torque (a.k.a. Pref) model `WTTQA1`.
v1.0 Notes
----------
v1.0.8 (2020-07-29)
```````````````````
New features and models:
- Added renewable energy models `REECA1` and `REPCA1`.
- Added service `EventFlag` which automatically calls events
if its input changes.
- Added service `ExtendedEvent` which flags an extended event
for a given time.
- Added service `ApplyFunc` to apply a numeric function.
For the most cases where one would need `ApplyFunc`,
consider using `ConstService` first.
- Allow `selftest -q` for quick selftest by skipping codegen.
- Improved time stepping logic and convergence tests.
- Updated examples.
Default behavior changes include:
- ``andes prepare`` now takes three mutually exclusive arguments,
`full`, `quick` and `incremental`. The command-line now defaults
to the quick mode. ``andes.prepare()`` still uses the full mode.
- ``Model.s_update`` now evaluates the generated and the
user-provided calls in sequence for each service in order.
- Renamed model `REGCAU1` to `REGCA1`.
v1.0.7 (2020-07-18)
```````````````````
- Use in-place assignment when updating Jacobian values in Triplets.
- Patched a major but simple bug where the Jacobian refactorization
flag is set to the wrong place.
- New models: PMU, REGCAU1 (tests pending).
- New blocks: DeadBand1, PIFreeze, PITrackAW, PITrackAWFreeze (tests
pending), and LagFreeze (tests pending).
- `andes plot` supports dashed horizontal and vertical lines through
`hline1`, `hline2`, `vline1` and `vline2`.
- Discrete: renamed `DeadBand` to `DeadBandRT` (deadband with
return).
- Service: renamed `FlagNotNone` to `FlagValue` with an option
to flip the flags.
- Other tweaks.
v1.0.6 (2020-07-08)
```````````````````
- Patched step size adjustment algorithm.
- Added Area Control Error (ACE) model.
v1.0.5 (2020-07-02)
```````````````````
- Minor bug fixes for service initialization.
- Added a wrapper to call TDS.fg_update to
allow passing variables from caller.
- Added pre-event time to the switch_times.
v1.0.4 (2020-06-26)
```````````````````
- Implemented compressed NumPy format (npz) for time-domain
simulation output data file.
- Implemented optional attribute `vtype` for specifying data type
for Service.
- Patched COI speed initialization.
- Patched PSS/E parser for two-winding transformer winding and
impedance modes.
v1.0.3 (2020-06-02)
```````````````````
- Patches `PQ` model equations where the "or" logic "|" is ignored in
equation strings. To adjust PQ load in time domain simulation, refer
to the note in `pq.py`.
- Allow `Model.alter` to update service values.
v1.0.2 (2020-06-01)
```````````````````
- Patches the conda-forge script to use SymPy < 1.6. After SymPy version
1.5.1, comparison operations cannot be sympified. Pip installations are
not affected.
v1.0.1 (2020-05-27)
```````````````````
- Generate one lambda function for each of f and g, instead of generating
one for each single f/g equation. Requires to run `andes prepare` after
updating.
v1.0.0 (2020-05-25)
```````````````````
This release is going to be tagged as v0.9.5 and later tagged as v1.0.0.
- Added verification results using IEEE 14-bus, NPCC, and WECC systems
under folder `examples`.
- Patches GENROU and EXDC2 models.
- Updated test cases for WECC, NPCC IEEE 14-bus.
- Documentation improvements.
- Various tweaks.
Pre-v1.0.0
----------
v0.9.4 (2020-05-20)
```````````````````
- Added exciter models EXST1, ESST3A, ESDC2A, SEXS, and IEEEX1,
turbine governor model IEEEG1 (dual-machine support), and stabilizer
model ST2CUT.
- Added blocks HVGate and LVGate with a work-around for sympy.maximum/
minimum.
- Added services `PostInitService` (for storing initialized values), and
`VarService` (variable services that get updated) after limiters and before
equations).
- Added service `InitChecker` for checking initialization values against
typical values. Warnings will be issued when out of bound or equality/
inequality conditions are not met.
- Allow internal variables to be associated with a discrete component which
will be updated before initialization (through `BaseVar.discrete`).
- Allow turbine governors to specify an optional `Tn` (turbine rating). If
not provided, turbine rating will fall back to `Sn` (generator rating).
- Renamed `OptionalSelect` to `DataSelect`; Added `NumSelect`, the array-based
version of `DataSelect`.
- Allow to regenerate code for updated models through ``andes prepare -qi``.
- Various patches to allow zeroing out time constants in transfer functions.
v0.9.3 (2020-05-05)
```````````````````
This version contains bug fixes and performance tweaks.
- Fixed an `AntiWindup` issue that causes variables to stuck at limits.
- Allow ``TDS.run()`` to resume from a stopped simulation and run to the new
end time in ``TDS.config.tf``.
- Improved TDS data dump speed by not constructing DataFrame by default.
- Added tests for `kundur_full.xlsx` and `kundur_aw.xlsx` to ensure
results are the same as known values.
- Other bug fixes.
v0.9.1 (2020-05-02)
```````````````````
This version accelerates computations by about 35%.
- Models with flag ``collate=False``, which is the new default,
will slice DAE arrays for all internal vars to reduce copying back and forth.
- The change above greatly reduced computation time.
For ``kundur_ieeest.xlsx``, simulation time is down from 2.50 sec to 1.64 sec.
- The side-effects include a change in variable ordering in output lst file.
It also eliminated the feasibility of evaluating model equations in
parallel, which has not been implemented and does not seem promising in Python.
- Separated symbolic processor and documentation generator from Model into
``SymProcessor`` and ``Documenter`` classes.
- ``andes prepare`` now shows progress in the console.
- Store exit code in ``System.exit_code`` and returns to system when called
from CLI.
- Refactored the solver interface.
- Patched Config.check for routines.
- SciPy Newton-Krylov power flow solver is no longer supported.
- Patched a bug in v0.9.0 related to `dae.Tf`.
v0.8.8 (2020-04-28)
```````````````````
This update contains a quick but significant fix to boost the simulation speed by avoiding
calls to empty user-defined numerical calls.
- In `Model.flags` and `Block.flags`, added `f_num`, `g_num` and `j_num` to indicate
if user-defined numerical calls exist.
- In `Model.f_update`, `Model.g_update` and `Model.j_update`, check the above flags
to avoid unnecessary calls to empty numeric functions.
- For the `kundur_ieeest.xlsx` case, simulation time was reduced from 3.5s to 2.7s.
v0.8.7 (2020-04-28)
```````````````````
- Changed `RefParam` to a service type called `BackRef`.
- Added `DeviceFinder`, a service type to find device idx when not provided.
`DeviceFinder` will also automatically add devices if not found.
- Added `OptionalSelect`, a service type to select optional parameters if provided
and select fallback ones otherwise.
- Added discrete types `Derivative`, `Delay`, and `Average`,
- Implemented full IEEEST stabilizer.
- Implemented COI for generator speed and angle measurement.
v0.8.6 (2020-04-21)
```````````````````
This release contains important documentation fixes and two new blocks.
- Fixed documentations in `andes doc` to address a misplacement of symbols and equations.
- Converted all blocks to the division-free formulation (with `dae.zf` renamed to `dae.Tf`).
- Fixed equation errors in the block documentation.
- Implemented two new blocks: Lag2ndOrd and LeadLag2ndOrd.
- Added a prototype for IEEEST stabilizer with some fixes needed.
v0.8.5 (2020-04-17)
```````````````````
- Converted the differential equations to the form of ``T \dot{x} = f(x, y)``, where T is supplied to
``t_const`` of ``State/ExtState``.
- Added the support for Config fields in documentation (in ``andes doc`` and on readthedocs).
- Added Config consistency checking.
- Converted `Model.idx` from a list to `DataParam`.
- Renamed the API of routines (summary, init, run, report).
- Automatically generated indices now start at 1 (i.e., "GENCLS_1" is the first GENCLS device).
- Added test cases for WECC system. The model with classical generators is verified against TSAT.
- Minor features: `andes -v 1` for debug output with levels and line numbers.
v0.8.4 (2020-04-07)
```````````````````
- Added support for JSON case files. Convert existing case file to JSON with ``--convert json``.
- Added support for PSS/E dyr files, loadable with ``-addfile ADDFILE``.
- Added ``andes plot --xargs`` for searching variable name and plotting. See example 6.
- Various bug fixes: Fault power injection fix;
v0.8.3 (2020-03-25)
```````````````````
- Improved storage for Jacobian triplets (see ``andes.core.triplet.JacTriplet``).
- On-the-fly parameter alteration for power flow calculations (``Model.alter`` method).
- Exported frequently used functions to the root package
(``andes.config_logger``, ``andes.run``, ``andes.prepare`` and ``andes.load``).
- Return a list of System objects when multiprocessing in an interactive environment.
- Exported classes to `andes.core`.
- Various bug fixes and documentation improvements.
v0.8.0 (2020-02-12)
```````````````````
- First release of the hybrid symbolic-numeric framework in ANDES.
- A new framework is used to describe DAE models, generate equation documentation, and generate code for
numerical simulation.
- Models are written in the new framework. Supported models include GENCLS, GENROU, EXDC2, TGOV1, TG2
- PSS/E raw parser, MATPOWER parser, and ANDES xlsx parser.
- Newton-Raphson power flow, trapezoidal rule for numerical integration, and full eigenvalue analysis.
v0.6.9 (2020-02-12)
```````````````````
- Version 0.6.9 is the last version for the numeric-only modeling framework.
- This version will not be updated any more.
But, models, routines and functions will be ported to the new version.

59
docs/source/troubleshooting.rst Normal file
View File

@@ -0,0 +1,59 @@
.. _troubleshooting:
**************************
Troubleshooting
**************************
Import Errors
=============
ImportError: DLL load failed
----------------------------
Platform: Windows, error message:
ImportError: DLL load failed: The specified module could not be found.
This usually happens when andes is not installed in a Conda environment
but instead in a system-wide Python whose library path was not correctly
set in environment variables.
The easiest fix is to install andes in a Conda environment.
Runtime Errors
==============
EOFError: Ran out of input
--------------------------
The error message looks like ::
Traceback (most recent call last):
File "/home/user/miniconda3/envs/andes/bin/andes", line 11, in <module>
load_entry_point('andes', 'console_scripts', 'andes')()
File "/home/user/repos/andes/andes/cli.py", line 179, in main
return func(cli=True, **vars(args))
File "/home/user/repos/andes/andes/main.py", line 514, in run
system = run_case(cases[0], codegen=codegen, **kwargs)
File "/home/user/repos/andes/andes/main.py", line 304, in run_case
system = load(case, codegen=codegen, **kwargs)
File "/home/user/repos/andes/andes/main.py", line 284, in load
system.undill()
File "/home/user/repos/andes/andes/system.py", line 980, in undill
loaded_calls = self._load_pkl()
File "/home/user/repos/andes/andes/system.py", line 963, in _load_pkl
loaded_calls = dill.load(f)
File "/home/user/miniconda3/envs/andes/lib/python3.7/site-packages/dill/_dill.py", line 270, in load
return Unpickler(file, ignore=ignore, **kwds).load()
File "/home/user/miniconda3/envs/andes/lib/python3.7/site-packages/dill/_dill.py", line 473, in load
obj = StockUnpickler.load(self)
EOFError: Ran out of input
Resolution:
The error indicates the file for generated code is corrupt or inaccessible.
It can be fixed by running ``andes prepare`` from the command line.
If the issue persists, try removing ``~/.andes/calls.pkl`` and running
``andes prepare`` agian.

1058
docs/source/tutorial.rst Normal file
View File

File diff suppressed because it is too large Load Diff