change new read-the-docs template

3 years ago · b0d1c6fabb
parent 13018d08e7
commit b0d1c6fabb
62 changed files with 4650 additions and 227 deletions
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@ -1,7 +0,0 @@
-.. _api_reference:
-
-=============
-API reference
-=============
-
-
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@ -1,124 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.doctest',
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
-    'sphinx_panels',
-    'IPython.sphinxext.ipython_directive',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'matplotlib.sphinxext.plot_directive',
-    'numpydoc',
-    'sphinx_copybutton',
-    'myst_nb',
-]
-
-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'
-
-exclude_patterns = []
-
-# 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 = "en"
-
-# General information about the project.
-project = 'AMS'
-copyright = '2023, Jinning Wang'
-author = 'Jinning Wang'
-release = '0.4'
-
-# 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 -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = 'pydata_sphinx_theme'
-
-# 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 = {
-    "use_edit_page_button": True,
-}
-
-html_context = {
-    "github_url": "https://github.com",
-    "github_user": "jinningwang",
-    "github_repo": "ams",
-    "github_version": "master",
-    "doc_path": "docs/source",
-}
-
-# 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']
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'ams'
-
-# -- 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("genroutineref.py").read())
-
-# sphinx-panels shouldn't add bootstrap css since the pydata-sphinx-theme
-# already loads it
-panels_add_bootstrap_css = False
--- a/doc/source/examples/index.rst
+++ b/doc/source/examples/index.rst
@ -1,4 +0,0 @@
-.. _scripting_examples:
-
-Examples
-========
--- a/doc/source/genroutineref.py
+++ b/doc/source/genroutineref.py
@ -1,3 +0,0 @@
-"""
-This file is used to generate reStructuredText tables for Routine references.
-"""
--- a/doc/source/getting_started/index.rst
+++ b/doc/source/getting_started/index.rst
@ -1,21 +0,0 @@
-
-.. raw:: html
-
-   <embed>
-   <h1 style="letter-spacing: 0.4em; font-size: 2.5em !important;
-   margin-bottom: 0; padding-bottom: 0"> AMS </h1>
-
-   <p style="color: #00746F; font-variant: small-caps; font-weight: bold;
-   margin-bottom: 2em">
-   Python Library for Power System Dispatch Modeling and Dispatch-Dynamic Co-Simulation</p>
-   </embed>
-
-.. _getting-started:
-
-===============
-Getting started
-===============
-
-.. toctree::
-    :maxdepth: 3
-    :hidden:
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@ -1,33 +0,0 @@
-.. AMS documentation master file, created by
-   sphinx-quickstart on Thu Jan 26 15:32:32 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-==================
-AMS documentation
-==================
-**Useful Links**: `Source Repository`_ | `Report Issues`_ | `Q&A`_ 
-
-.. _`Source Repository`: https://github.com/jinningwang/ams
-.. _`Report Issues`: https://github.com/jinningwang/ams/issues
-.. _`Q&A`: https://github.com/jinningwang/ams/discussions
-.. _`LTB Repository`: https://github.com/CURENT/ltb2
-
-AMS is still under DEVELOPMENT, stay tuned!
-
-AMS is an open-source packages for dispatch modeling and co-simulation with dynanic.
-
-AMS is the dispatch simulation engine for the CURENT Largescale Testbed (LTB).
-More information about CURENT LTB can be found at the `LTB Repository`_.
-
-
-.. toctree::
-   :maxdepth: 3
-   :caption: AMS Manual
-   :hidden:
-
-   getting_started/index
-   examples/index
-   modeling/index
-   release-notes
-   api
--- a/doc/source/modeling/index.rst
+++ b/doc/source/modeling/index.rst
@ -1,7 +0,0 @@
-.. _development:
-
-===========
-Development
-===========
-
-Modeling guide for AMS.
--- a/doc/source/release-notes.rst
+++ b/doc/source/release-notes.rst
@ -1,21 +0,0 @@
-.. _ReleaseNotes:
-
-=============
-Release notes
-=============
-
-The APIs before v3.0.0 are in beta and may change without prior notice.
-
-Pre-v1.0.0
-==========
-
-v0.5 (2023-02-17)
-------------------
-
- Base System setup
- Development preparation
-
-v0.4 (2023-01)
-------------------
-
-This release outlines the package.
--- a/docs/Makefile
+++ b/docs/Makefile
@ -1,10 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #

-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+# 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

--- a/docs/make.bat
+++ b/docs/make.bat
@ -9,6 +9,7 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=source
 set BUILDDIR=build
+set SPHINXPROJ=PackagingScientificPython

 if "%1" == "" goto help

@ -21,15 +22,15 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
+	echo.http://sphinx-doc.org/
 	exit /b 1
 )

-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
 goto end

 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%

 :end
 popd
--- a/docs/requirements-rtd.txt
+++ b/docs/requirements-rtd.txt
@ -0,0 +1,17 @@
+cvxopt
+numpy
+scipy
+sympy
+pandas
+matplotlib
+openpyxl
+xlsxwriter
+dill
+pathos
+tqdm
+pyyaml
+coloredlogs
+ipython
+numpydoc
+sphinx-copybutton
+sphinx_rtd_theme
--- a/docs/source/_static/.placeholder
+++ b/docs/source/_static/.placeholder
--- a/docs/source/andes.rst
+++ b/docs/source/andes.rst
@ -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:
--- a/docs/source/cases.rst
+++ b/docs/source/cases.rst
@ -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"``.
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@ -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())
--- a/docs/source/copyright.rst
+++ b/docs/source/copyright.rst
@ -0,0 +1,23 @@
+.. role:: raw-html(raw)
+    :format: html
+
+*******
+License
+*******
+
+GNU Public License v3
+*********************
+| Copyright :raw-html:`&copy;` 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.
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@ -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.
--- a/docs/source/images/curent.ico
+++ b/docs/source/images/curent.ico
--- a/docs/source/images/diagrams/ieeest.png
+++ b/docs/source/images/diagrams/ieeest.png
--- a/docs/source/images/example-kundur/efd.png
+++ b/docs/source/images/example-kundur/efd.png
--- a/docs/source/images/example-kundur/omega.png
+++ b/docs/source/images/example-kundur/omega.png
--- a/docs/source/images/example-npcc/omega.png
+++ b/docs/source/images/example-npcc/omega.png
--- a/docs/source/images/example-tgov1/tgov1.png
+++ b/docs/source/images/example-tgov1/tgov1.png
--- a/docs/source/images/example-tgov1/tgov1_class.png
+++ b/docs/source/images/example-tgov1/tgov1_class.png
--- a/docs/source/images/example-tgov1/tgov1_eqns.png
+++ b/docs/source/images/example-tgov1/tgov1_eqns.png
--- a/docs/source/images/example-wecc/omega.png
+++ b/docs/source/images/example-wecc/omega.png
--- a/docs/source/images/misc/doc-screenshot.png
+++ b/docs/source/images/misc/doc-screenshot.png
--- a/docs/source/images/misc/ieeeg1-screenshot.png
+++ b/docs/source/images/misc/ieeeg1-screenshot.png
--- a/docs/source/images/sponsors/curent.jpg
+++ b/docs/source/images/sponsors/curent.jpg
--- a/docs/source/images/sponsors/doe.png
+++ b/docs/source/images/sponsors/doe.png
--- a/docs/source/images/sponsors/inl.jpg
+++ b/docs/source/images/sponsors/inl.jpg
--- a/docs/source/images/sponsors/llnl.jpg
+++ b/docs/source/images/sponsors/llnl.jpg
--- a/docs/source/images/sponsors/nsf.jpg
+++ b/docs/source/images/sponsors/nsf.jpg
--- a/docs/source/images/tutorial/xlsx-bus.png
+++ b/docs/source/images/tutorial/xlsx-bus.png
--- a/docs/source/images/tutorial/xlsx-pq.png
+++ b/docs/source/images/tutorial/xlsx-pq.png
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@ -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`
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@ -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
--- a/docs/source/misc.rst
+++ b/docs/source/misc.rst
@ -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.
--- a/docs/source/modeling.rst
+++ b/docs/source/modeling.rst
--- a/docs/source/modelref.py
+++ b/docs/source/modelref.py
@ -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)
--- a/docs/source/moduledoc/andes.core.rst
+++ b/docs/source/moduledoc/andes.core.rst
@ -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:
--- a/docs/source/moduledoc/andes.io.rst
+++ b/docs/source/moduledoc/andes.io.rst
@ -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:
--- a/docs/source/moduledoc/andes.models.rst
+++ b/docs/source/moduledoc/andes.models.rst
@ -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:
--- a/docs/source/moduledoc/andes.routines.rst
+++ b/docs/source/moduledoc/andes.routines.rst
@ -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:
--- a/docs/source/moduledoc/andes.utils.rst
+++ b/docs/source/moduledoc/andes.utils.rst
@ -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:
--- a/docs/source/moduledoc/andes.variables.rst
+++ b/docs/source/moduledoc/andes.variables.rst
@ -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:
--- a/docs/source/old/about.md
+++ b/docs/source/old/about.md
--- a/docs/source/old/advanced_usage.md
+++ b/docs/source/old/advanced_usage.md
--- a/docs/source/old/basic_usage.md
+++ b/docs/source/old/basic_usage.md
--- a/docs/source/old/data_and_models.md
+++ b/docs/source/old/data_and_models.md
--- a/docs/source/old/img/accuracy_039_1.png
+++ b/docs/source/old/img/accuracy_039_1.png
--- a/docs/source/old/img/accuracy_039_2.png
+++ b/docs/source/old/img/accuracy_039_2.png
--- a/docs/source/old/img/comp_speed_458.png
+++ b/docs/source/old/img/comp_speed_458.png
--- a/docs/source/old/img/comp_time_039.png
+++ b/docs/source/old/img/comp_time_039.png
--- a/docs/source/old/img/contingency_458.png
+++ b/docs/source/old/img/contingency_458.png
--- a/docs/source/old/img/ssa_benchmarking.png
+++ b/docs/source/old/img/ssa_benchmarking.png
--- a/docs/source/old/index.md
+++ b/docs/source/old/index.md
--- a/docs/source/old/installation.md
+++ b/docs/source/old/installation.md
--- a/docs/source/old/sas_basics.md
+++ b/docs/source/old/sas_basics.md
--- a/docs/source/release-notes.rst
+++ b/docs/source/release-notes.rst
@ -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.
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@ -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.
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst