Merge pull request #420 from CURENT/develop

Prepare for new minor release

andes/interop/pandapower.py

@@ -471,7 +471,14 @@ def to_pandapower(ssa, ctrl=[], verify=True, tol=1e-6):
     Notes
     -----
     Handling of the following parameters:
-
+      - This interface tracks static power flow model in ANDES: `Bus`, `Line`, `PQ`, `Shunt`, `PV`, and `Slack`.
+        However, it does not track the dynamic models in ANDES, including but not limited to
+        `TurbineGov`, `SynGen`, and `Exciter`.
+      - The interface converts the ``Slack`` in ANDES to ``gen`` in pandapower rather than ``ext_gen``.
+      - MUST NOT verify power flow after initializing TDS in ANDES. ANDES does not allow running ``PFlow``
+        for systems with initialized TDS as it will break variable addressing.
+      - If you want to track dynamic model outputs in ANDES and feedback into pandapower,
+        you might need to manually transfer the results from ANDES to pandapower.
       - Generator cost is not included in the conversion. Use ``add_gencost()``
         to add cost data.
       - By default, all generators in ``ssp`` are controllable unless user-defined controllability
@@ -514,8 +521,26 @@ def to_pandapower(ssa, ctrl=[], verify=True, tol=1e-6):
 
 def _verify_pf(ssa, ssp, tol=1e-6):
     """
-    Verify power flow results.
+    Verify power flow results between ANDES and pandapower.
+
+    Parameters
+    ----------
+    tol : float
+        The tolerance of error.
+
+    Returns
+    -------
+    True
+        If the difference between the two results is within the tolerance
+    False
+        If the difference is larger than the tolerance, OR time-domain
+        simulation has been run in the ANDES system. ANDES is not able to run
+        power flow after initializing time-domain simulation.
     """
+
+    if ssa.TDS.initialized:
+        return False
+
     ssa.PFlow.run()
     pp.runpp(ssp)
 

andes/models/group.py

@@ -491,13 +491,24 @@ class StaticGen(GroupBase):
     """
     Static generator group.
 
-    Static generators will be replaced by dynamic generators, either synchronous
-    generators or inverter-based resources upon the initialization for dynamics.
-    It is implemented by setting the connectivity status ``u`` of the replaced
-    StaticGen to 0.
+    Static generators include PV and Slack, which are used to impose algebraic
+    equations. Static generators are used primarily for power flow.
 
-    See the notes in :ref:`SynGen` for replacing one StaticGen with multiple
-    dynamic ones.
+    Static generators do not have the modeling details for stability
+    simulation. Although some of them can stay for time-domain simulation, most
+    of them should be substituted by dynamic generators, including synchronous
+    generators and inverter-based resources upon TDS initialization.
+
+    The substitution is done by setting the ``gen`` field of a dynamic generator
+    to refer to the static generator. To replace one StaticGen by multiple
+    dynamic generators, see the notes in :ref:`SynGen`. Generators connected to
+    the same bus need to have their `gammap` and `gammaq`, respectively, summed
+    up to be exactly 1.0.
+
+    TDS initialization will ensure that the dynamic generators impose the same
+    amount of power as the static generator. At the end of initialization,
+    `StaticGen`'s that have been substituted will have their connectivity status
+    ``u`` changed to ``0``.
     """
 
     def __init__(self):
@@ -607,6 +618,11 @@ class RenGen(GroupBase):
 
     See :ref:`SynGen` for the notes on replacing StaticGen and setting the power
     ratio parameters.
+
+    Attention is needed for the power base ``Sn``. When replacing a synchronous
+    generator, the renewable generator should have the same or larger ``Sn``.
+    Improper ``Sn`` will cause the initial values to exceed typical per-unit
+    ranges and cause the initialization to fail.
     """
 
     def __init__(self):