Prepare for v1.6.2 release

.azure-pipelines/azure-pipelines-linux.yml

@@ -21,8 +21,7 @@ jobs:
 
   - script: |
       python -m pip install --upgrade pip
-      pip install .
-      pip install -r requirements-dev.txt
+      pip install .[dev,interop]
     displayName: 'Install dependencies'
 
   - script: |

.azure-pipelines/azure-pipelines-macos.yml

@@ -21,8 +21,7 @@ jobs:
 
   - script: |
       python -m pip install --upgrade pip
-      pip install .
-      pip install -r requirements-dev.txt
+      pip install .[all]
     displayName: 'Install dependencies'
 
   - script: |

.azure-pipelines/azure-pipelines-win.yml

@@ -29,8 +29,7 @@ jobs:
       call activate andesEnv
       python -m pip install --upgrade pip
       pip install pytest pytest-azurepipelines
-      pip install .
-      pip install -r requirements-dev.txt
+      pip install .[dev,interop]
       pytest
     displayName: pytest
 

.github/workflows/pythonapp.yml

@@ -15,10 +15,10 @@ jobs:
         python-version: 3.8
     - name: Install dependencies
       run: |
+        # work around a pip issue with extras_require: https://github.com/pypa/pip/issues/8323
+        python -m pip install -U "pip @ git+https://github.com/pypa/pip.git"
         python -m pip install --upgrade pip
-        python -m pip install -r requirements.txt
-        python -m pip install -r requirements-dev.txt
-        python -m pip install .
+        python -m pip install .[all]
         python -m pip install nbmake==0.10 pytest-xdist line_profiler  # add'l packages for notebook tests.
     - name: Lint with flake8 for pull requests
       if: github.event_name == 'pull_request'

.gitignore

@@ -63,7 +63,7 @@ coverage.xml
 docs/source/modelref.rst
 docs/source/configref.rst
 docs/source/groupdoc
-docs/source/examples
+docs/source/_examples
 docs/build/
 docs/jupyter_execute/
 docs/source/_build/

.readthedocs.yml

@@ -11,11 +11,10 @@ python:
   version: 3.8
   install:
     - requirements: requirements.txt
-    - requirements: requirements-dev.txt
     - method: pip
       path: .
       extra_requirements:
-        - docs
+        - doc
     - method: setuptools
       path: .
   system_packages: true

CONTRIBUTING.rst

@@ -66,8 +66,7 @@ set up your fork for local development::
 
     $ mkvirtualenv andes
     $ cd andes/
-    $ python setup.py develop
-    $ pip install requirements-dev.txt
+    $ pip install -e .[dev]
 
 4. Create a branch for local development::
 

MANIFEST.in

@@ -3,7 +3,7 @@ include CONTRIBUTING.rst
 include LICENSE
 include README.md
 include requirements.txt
-include requirements-dev.txt
+include extra-requirements.txt
 
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

andes/__init__.py

@@ -9,6 +9,7 @@
 from andes import utils      # NOQA
 from andes import variables  # NOQA
 from andes import thirdparty  # NOQA
+from andes import interop    # NOQA
 
 from andes.main import config_logger, run, load, prepare  # NOQA
 from andes.system import System                    # NOQA
@@ -18,5 +19,5 @@
 __author__ = 'Hantao Cui'
 
 __all__ = ['main', 'plot', 'system', 'cli',
-           'utils', 'core', 'models', 'io', 'routines', 'variables', 'thirdparty',
+           'utils', 'core', 'models', 'io', 'routines', 'variables', 'thirdparty', 'interop',
            '__version__']

andes/cases/ieee14/README.md

@@ -1,9 +1,44 @@
-IEEE 14-Bus System
+# IEEE 14-Bus Systems
 
-Power flow data is created by J. Conto.
+The folder contains many variants of the IEEE 14-bus system that are created
+during model development. One cawn find cases containing the needed model and modify
+from them.
+## Power flow data
 
-Data is available at <https://drive.google.com/drive/folders/0B7uS9L2Woq_7YzYzcGhXT2VQYXc>
+Power flow data is created by J. Conto obtained from the [Google drive
+link](https://drive.google.com/drive/folders/0B7uS9L2Woq_7YzYzcGhXT2VQYXc).
 
-Dynamic data is created by H. Cui for ANDES.
+The base power flow file is ``ieee14.raw``. Almost all other cases in this
+folder are created by adding models to it.
 
-`ieee14.dyr` contains more models than `ieee14_gentrip.xlsx` and `ieee14_linetrip.xlsx`.
+## Dynamic data
+
+The base dynamic data is created by H. Cui for ANDES, given in ``ieee14.dyr``.
+
+## Special cases
+
+### Contingency cases:
+
+- `ieee14_gentrip.xlsx` contains data for a generator trip using `Toggler`
+- `ieee14_linetrip.xlsx` contains data for a line trip
+- `ieee14_fault.xlsx` contains data for a three-phase-to-ground fault using `Fault`
+
+### Renewable energy models
+
+- `ieee14_wt3.xlsx` contains one generic Type-3 wind turbine
+- `ieee14_wt3n.xlsx` has (almost) all generators represented by Type-3 wind turbines
+- `ieee14_solar.xlsx` contains a generic solar PV device, which can also be used
+  to model a Type-4 wind turbine
+- `ieee14_pvd1.xlsx` contains WECC distributed PV
+- `ieee14_dgprct1.xlsx` contains the WECC distributed PV model with IEEE
+  1547.2018-based voltage and frequency protection
+
+### Playback and Timeseries
+- `ieee14_plbvfu1.xlsx` contains data for setting up a playback V-f generator
+- `ieee14_timeseries.xlsx` contains data for using time series from `pqts.xlsx`
+  for a PQ load. Note that one needs to convert PQ to constant power load for
+  simulation.
+
+### Other
+- `ieee14_jumper.xlsx` contains data for a jumper device that connects two buses
+  without impedance.

andes/cases/smib/README.md

@@ -0,0 +1,15 @@
+# Single Machine Infinite Bus (SMIB) System
+
+## Overview
+
+`SMIB.xlsx` is originally prepared by Xiaoge Huang using data in [[1]](#1).
+
+Parameters are modified by Hantao Cui to obtain the same per-unit results as in
+the textbook in the base of 100 MVA. Essentially, the power bases, `Sn`, of all
+devices are converted to 100 MVA. All elements are in the same voltage level.
+
+## References
+
+<a id="1">[1]</a> P. W. Sauer, M. A. Pai, and J. H. Chow, Power system dynamics
+and stability: with synchrophasor measurement and power system toolbox, Second
+edition. Hoboken, NJ, USA: IEEE Press, Wiley, 2017.

andes/cli.py

@@ -25,8 +25,14 @@
 
 def create_parser():
     """
-    The main level of command-line interface.
+    Create a parser for the command-line interface.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Parser with all ANDES options
     """
+
     parser = argparse.ArgumentParser()
 
     parser.add_argument(
@@ -192,7 +198,7 @@ def preamble():
 
 def main():
     """
-    Main command-line interface
+    Entry point of the ANDES command-line interface.
     """
 
     parser = create_parser()

andes/core/documenter.py

@@ -2,6 +2,7 @@
 Documenter class for ANDES models.
 """
 
+import inspect
 from collections import OrderedDict
 
 from andes.utils.tab import make_doc_table, math_wrap
@@ -71,8 +72,10 @@ def _param_doc(self, max_width=78, export='plain'):
         if export == 'rest':
             symbols = [item.tex_name for item in self.params.values()]
             symbols = math_wrap(symbols, export=export)
+            title = 'Parameters\n----------'
         else:
             symbols = [item.name for item in self.params.values()]
+            title = 'Parameters'
 
         plain_dict = OrderedDict([('Name', names),
                                   ('Description', info),
@@ -88,7 +91,7 @@ def _param_doc(self, max_width=78, export='plain'):
                                  ('Properties', properties)])
 
         # convert to rows and export as table
-        return make_doc_table(title='Parameters',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -118,10 +121,13 @@ def _var_doc(self, max_width=78, export='plain'):
                     plist.append(item)
             properties.append(','.join(plist))
 
+        title = 'Variables'
+
         # replace with latex math expressions if export is ``rest``
         if export == 'rest':
             call_store = self.system.calls[self.class_name]
             symbols = math_wrap(call_store.x_latex + call_store.y_latex, export=export)
+            title = 'Variables\n---------'
 
         plain_dict = OrderedDict([('Name', names),
                                   ('Type', ty),
@@ -136,7 +142,7 @@ def _var_doc(self, max_width=78, export='plain'):
                                  ('Unit', units_rest),
                                  ('Properties', properties)])
 
-        return make_doc_table(title='Variables (States + Algebraics)',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -146,6 +152,7 @@ def _init_doc(self, max_width=78, export='plain'):
         """
         Variable initialization docs.
         """
+
         if len(self.cache.all_vars) == 0:
             return ''
 
@@ -157,11 +164,14 @@ def _init_doc(self, max_width=78, export='plain'):
             ty.append(p.class_name)
             ivs.append(p.v_str if p.v_str else '')
 
+        title = 'Initialization Equations'
+
         # replace with latex math expressions if export is ``rest``
         if export == 'rest':
             call_store = self.system.calls[self.class_name]
             symbols = math_wrap(call_store.x_latex + call_store.y_latex, export=export)
             ivs_rest = math_wrap(call_store.init_latex.values(), export=export)
+            title = 'Initialization Equations\n------------------------'
 
         plain_dict = OrderedDict([('Name', names),
                                   ('Type', ty),
@@ -174,7 +184,7 @@ def _init_doc(self, max_width=78, export='plain'):
                                  ('Initial Value', ivs_rest),
                                  ])
 
-        return make_doc_table(title='Variable Initialization Equations',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -221,7 +231,7 @@ def _eq_doc(self, max_width=78, export='plain', e_code=None):
                                       ('Type', class_names),
                                       (f'RHS of Equation "{e2form[e_name]}"', eqs),
                                       ])
-
+            title = f'{e2full[e_name]} Equations'
             if export == 'rest':
                 call_store = self.system.calls[self.class_name]
                 e2var_sym = {'f': call_store.x_latex,
@@ -231,6 +241,7 @@ def _eq_doc(self, max_width=78, export='plain', e_code=None):
 
                 symbols = math_wrap(e2var_sym[e_name], export=export)
                 eqs_rest = math_wrap(e2eq_sym[e_name], export=export)
+                title = f'{e2full[e_name]} Equations\n-----------------------------'
 
             rest_dict = OrderedDict([('Name', names),
                                      ('Symbol', symbols),
@@ -242,7 +253,7 @@ def _eq_doc(self, max_width=78, export='plain', e_code=None):
                 plain_dict['T (LHS)'] = lhs_names
                 rest_dict['T (LHS)'] = math_wrap(lhs_tex_names, export=export)
 
-            out += make_doc_table(title=f'{e2full[e_name]} Equations',
+            out += make_doc_table(title=title,
                                   max_width=max_width,
                                   export=export,
                                   plain_dict=plain_dict,
@@ -263,10 +274,12 @@ def _service_doc(self, max_width=78, export='plain'):
             symbols.append(p.tex_name if p.tex_name is not None else '')
             eqs.append(p.v_str if p.v_str else '')
 
+        title = 'Services'
         if export == 'rest':
             call_store = self.system.calls[self.class_name]
             symbols = math_wrap(symbols, export=export)
             eqs_rest = math_wrap(call_store.s_latex, export=export)
+            title = 'Services\n----------'
 
         plain_dict = OrderedDict([('Name', names),
                                   ('Equation', eqs),
@@ -277,7 +290,7 @@ def _service_doc(self, max_width=78, export='plain'):
                                  ('Equation', eqs_rest),
                                  ('Type', class_names)])
 
-        return make_doc_table(title='Services',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -295,8 +308,11 @@ def _discrete_doc(self, max_width=78, export='plain'):
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
 
+        title = 'Discretes'
         if export == 'rest':
             symbols = math_wrap([item.tex_name for item in self.discrete.values()], export=export)
+            title = 'Discretes\n-----------'
+
         plain_dict = OrderedDict([('Name', names),
                                   ('Type', class_names),
                                   ('Info', info)])
@@ -306,7 +322,7 @@ def _discrete_doc(self, max_width=78, export='plain'):
                                  ('Type', class_names),
                                  ('Info', info)])
 
-        return make_doc_table(title='Discrete',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -327,8 +343,10 @@ def _block_doc(self, max_width=78, export='plain'):
             class_names.append(p.class_name)
             info.append(p.info if p.info else '')
 
+        title = 'Blocks'
         if export == 'rest':
             symbols = math_wrap([item.tex_name for item in self.blocks.values()], export=export)
+            title = 'Blocks\n-------'
 
         plain_dict = OrderedDict([('Name', names),
                                   ('Type', class_names),
@@ -339,7 +357,7 @@ def _block_doc(self, max_width=78, export='plain'):
                                  ('Type', class_names),
                                  ('Info', info)])
 
-        return make_doc_table(title='Blocks',
+        return make_doc_table(title=title,
                               max_width=max_width,
                               export=export,
                               plain_dict=plain_dict,
@@ -371,14 +389,12 @@ def get(self, max_width=78, export='plain'):
 
         if export == 'rest':
             out += model_header + f'{self.class_name}\n' + model_header
-            out += f'\nGroup {self.parent.group}_\n\n'
         else:
             out += model_header + f'Model <{self.class_name}> in Group <{self.parent.group}>\n' + model_header
 
-        if self.__doc__ is not None:
-            if self.parent.__doc__ is not None:
-                out += self.parent.__doc__
-            out += '\n'  # this fixes the indentation for the next line
+        if self.parent.__doc__ is not None:
+            out += inspect.cleandoc(self.parent.__doc__)
+        out += '\n\n'  # this fixes the indentation for the next line
 
         # add tables
         out += self._param_doc(max_width=max_width, export=export)

andes/core/model.py

@@ -703,6 +703,9 @@ def __init__(self, system=None, config=None):
         self.ii_args = OrderedDict()
         self.ij_args = OrderedDict()
 
+        self.coeffs = dict()  # pu conversion coefficient storage
+        self.bases = dict()   # base storage, such as Vn, Vb, Zn, Zb
+
     def _register_attribute(self, key, value):
         """
         Register a pair of attributes to the model instance.