1. Ready to release the new version

README.rst

@@ -77,7 +77,7 @@ The ESA team works hard to ensure ESA is well tested, and we strive for
 testing coverage data for ESA, using `coverage
 <https://pypi.org/project/coverage/>`__.
 
-.. table:: ESA's testing coverage as of 2022-08-22 (Git commit: 4b28569)
+.. table:: ESA's testing coverage as of 2022-09-15 (Git commit: 09a0fb7)
     :widths: auto
     :align: left
 
@@ -86,7 +86,7 @@ testing coverage data for ESA, using `coverage
     +=================+===================+=================+=================+====================+
     | esa/__init__.py |                 2 |               0 |               2 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+
-    | esa/saw.py      |               920 |               0 |             920 |                100 |
+    | esa/saw.py      |              1124 |               0 |            1124 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+
 
 License

VERSION

@@ -1 +1 @@
-1.2.8
+1.2.9

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a53f9ecfe3e60fd7052d70b826a9f37e
+config: e0464f6a5f354efa64833053541a243d
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '1.2.8',
+    VERSION: '1.2.9',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/html/esa.html

@@ -1396,6 +1396,24 @@
 <dd><p>Clean up for the PowerWorld COM object</p>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="esa.saw.SAW.fast_n1_test">
+<span class="sig-name descname"><span class="pre">fast_n1_test</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.fast_n1_test" title="Permalink to this definition">¶</a></dt>
+<dd><p>A pure LODF-based fast N-1 contingency analysis implementation.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>A boolean value to indicate whether the system is N-1 secure.</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="esa.saw.SAW.fast_n2_islanding_detection">
+<span class="sig-name descname"><span class="pre">fast_n2_islanding_detection</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.fast_n2_islanding_detection" title="Permalink to this definition">¶</a></dt>
+<dd><p>Quickly identify the N-2 islanding CTGs using LODF</p>
+<p>returns: A tuple with the number of islanding CTGs and the islanding matrix</p>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="esa.saw.SAW.get_branch_admittance">
 <span class="sig-name descname"><span class="pre">get_branch_admittance</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.get_branch_admittance" title="Permalink to this definition">¶</a></dt>
@@ -1533,10 +1551,10 @@
 script CalculateShiftFactorsMultipleElement.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
-<dd class="field-odd"><p><strong>method</strong> – The linear method to be used for the calculation. The</p>
+<dd class="field-odd"><p><strong>method</strong> – The linear method to be used for the calculation. The options are AC,</p>
 </dd>
 </dl>
-<p>options are AC, DC or DCPS.
+<p>DC or DCPS.
 :returns: A dense float matrix in the numpy array format.</p>
 </dd></dl>
 
@@ -1695,6 +1713,54 @@
 </dl>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="esa.saw.SAW.run_ecological_analysis">
+<span class="sig-name descname"><span class="pre">run_ecological_analysis</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">'MW'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">split_generator</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">bool</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.run_ecological_analysis" title="Permalink to this definition">¶</a></dt>
+<dd><p>This method is leveraging applied ecological network analysis to quantify
+the varity of robustness of the power system.</p>
+<p>Reference:
+[1] H. Huang, Z. Mao, A. Layton and K. R. Davis, 
+“An Ecological Robustness Oriented Optimal Power Flow for Power Systems’ Survivability,”
+in IEEE Transactions on Power Systems, doi: 10.1109/TPWRS.2022.3168226.
+[2] Panyam, V., Huang, H., Davis, K., &amp; Layton, A. (2019).
+An ecosystem perspective for the design of sustainable power systems. Procedia Cirp, 80, 269-274.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>target</strong> – the real, reactive, and apparent power over the system. The default value</p>
+</dd>
+</dl>
+<p>is MW, which is the real power. Users can change to MVR, which is the reactive power; or
+MVA, which is the apparent power.
+:param split_generator: Choose to split or aggregate multiple generators associated with
+the same bus. If true, the method will consider the generators’ robustness for each
+generator.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Results</dt>
+<dd class="field-odd"><p>it is a list of ecological metrics, including the Ecological Robustness (Reco),</p>
+</dd>
+</dl>
+<p>the Ascendancy (ASC), the Development Capacity (DC), the Cycled Throughflow (tstc), the Finn Cycling Index (CI)
+and the Total System Overhead (TSO)</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="esa.saw.SAW.run_robustness_analysis">
+<span class="sig-name descname"><span class="pre">run_robustness_analysis</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.run_robustness_analysis" title="Permalink to this definition">¶</a></dt>
+<dd><p>Compute the metric RCF to quantify the robustness of
+power grids against cascading failures. The RCF metric takes the
+operational states, the branch’s capacities and the topological
+structure into account and gives an entropy-based value.
+The formula is given from the following paper:
+Koç, Yakup, Martijn Warnier, Robert E. Kooij, and Frances MT Brazier.
+“An entropy-based metric to quantify the robustness of power grids
+against cascading failures.” Safety science 59 (2013): 126-134.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>The RCF value.</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="esa.saw.SAW.set_simauto_property">
 <span class="sig-name descname"><span class="pre">set_simauto_property</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">property_name</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">property_value</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">Union</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.set_simauto_property" title="Permalink to this definition">¶</a></dt>

docs/html/genindex.html

@@ -295,10 +295,14 @@ <h2 id="E">E</h2>
 <h2 id="F">F</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="esa.html#esa.saw.SAW.FIELD_LIST_COLUMNS">FIELD_LIST_COLUMNS (esa.saw.SAW attribute)</a>
+      <li><a href="esa.html#esa.saw.SAW.fast_n1_test">fast_n1_test() (esa.saw.SAW method)</a>
+</li>
+      <li><a href="esa.html#esa.saw.SAW.fast_n2_islanding_detection">fast_n2_islanding_detection() (esa.saw.SAW method)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="esa.html#esa.saw.SAW.FIELD_LIST_COLUMNS">FIELD_LIST_COLUMNS (esa.saw.SAW attribute)</a>
+</li>
       <li><a href="esa.html#esa.saw.SAW.FIELD_LIST_COLUMNS_NEW">FIELD_LIST_COLUMNS_NEW (esa.saw.SAW attribute)</a>
 </li>
       <li><a href="esa.html#esa.saw.SAW.FIELD_LIST_COLUMNS_OLD">FIELD_LIST_COLUMNS_OLD (esa.saw.SAW attribute)</a>
@@ -447,10 +451,14 @@ <h2 id="R">R</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="esa.html#esa.saw.SAW.RequestBuildDate">RequestBuildDate (esa.saw.SAW property)</a>
+</li>
+      <li><a href="esa.html#esa.saw.SAW.run_contingency_analysis">run_contingency_analysis() (esa.saw.SAW method)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="esa.html#esa.saw.SAW.run_contingency_analysis">run_contingency_analysis() (esa.saw.SAW method)</a>
+      <li><a href="esa.html#esa.saw.SAW.run_ecological_analysis">run_ecological_analysis() (esa.saw.SAW method)</a>
+</li>
+      <li><a href="esa.html#esa.saw.SAW.run_robustness_analysis">run_robustness_analysis() (esa.saw.SAW method)</a>
 </li>
       <li><a href="esa.html#esa.saw.SAW.RunScriptCommand">RunScriptCommand() (esa.saw.SAW method)</a>
 </li>

docs/html/overview.html

@@ -316,7 +316,7 @@ <h2>Testing Coverage<a class="headerlink" href="#testing-coverage" title="Permal
 <p>The ESA team strives to write good tests with 100% coverage. The table
 below provides the latest test coverage data for ESA.</p>
 <table class="colwidths-auto docutils align-left" id="id3">
-<caption><span class="caption-text">ESA’s testing coverage as of 2022-08-22 (Git commit: 4b28569)</span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
+<caption><span class="caption-text">ESA’s testing coverage as of 2022-09-15 (Git commit: 09a0fb7)</span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
 <thead>
 <tr class="row-odd"><th class="head"><p>Name</p></th>
 <th class="head"><p>Num. Statements</p></th>
@@ -333,9 +333,9 @@ <h2>Testing Coverage<a class="headerlink" href="#testing-coverage" title="Permal
 <td><p>100</p></td>
 </tr>
 <tr class="row-odd"><td><p>esa/saw.py</p></td>
-<td><p>920</p></td>
+<td><p>1124</p></td>
 <td><p>0</p></td>
-<td><p>920</p></td>
+<td><p>1124</p></td>
 <td><p>100</p></td>
 </tr>
 </tbody>

docs/html/welcome.html

@@ -544,6 +544,16 @@ <h3>Credits and Thanks<a class="headerlink" href="#credits-and-thanks" title="Pe
 <p>Changes made with each ESA release are listed here. Please note that
 versions prior to 1.0.0 are not listed here, but are still available on
 <a class="reference external" href="https://pypi.org/project/esa/#history">PyPi</a>.</p>
+<section id="version-1-2-9">
+<h3>Version 1.2.9<a class="headerlink" href="#version-1-2-9" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><p>Fix the scipy sparse linalg import issue</p></li>
+<li><p>Add the function to quickly identify the N-2 islanding contingencies</p></li>
+<li><p>Add the functions for robustness and ecological analysis</p></li>
+<li><p>Preliminary support for Streamlit (getting close to thread-safe)</p></li>
+<li><p>Add the support for Python 3.10</p></li>
+</ul>
+</section>
 <section id="version-1-2-8">
 <h3>Version 1.2.8<a class="headerlink" href="#version-1-2-8" title="Permalink to this headline">¶</a></h3>
 <ul class="simple">

docs/rst/coverage.rst

@@ -1,4 +1,4 @@
-.. table:: ESA's testing coverage as of 2022-08-22 (Git commit: 4b28569)
+.. table:: ESA's testing coverage as of 2022-09-15 (Git commit: 09a0fb7)
     :widths: auto
     :align: left
 
@@ -7,5 +7,5 @@
     +=================+===================+=================+=================+====================+
     | esa/__init__.py |                 2 |               0 |               2 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+
-    | esa/saw.py      |               920 |               0 |             920 |                100 |
+    | esa/saw.py      |              1124 |               0 |            1124 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+

esa/__init__.py

@@ -16,4 +16,4 @@
 # Please keep the docstring above up to date with all the imports.
 from .saw import SAW, PowerWorldError, COMError, CommandNotRespectedError,\
     Error
-__version__ = "1.2.8"
+__version__ = "1.2.9"

esa/saw.py

@@ -948,8 +948,8 @@ def get_shift_factor_matrix(self, method: str = 'DC'):
         Calculate the injection shift factor matrix using the auxiliary
         script CalculateShiftFactorsMultipleElement.
 
-        :param method: The linear method to be used for the calculation. The
-        options are AC, DC or DCPS.
+        :param method: The linear method to be used for the calculation. The options are AC,
+        DC or DCPS.
         :returns: A dense float matrix in the numpy array format.
         """
         temp = self.pw_order
@@ -1318,12 +1318,12 @@ def run_ecological_analysis(self, target: str = 'MW', split_generator: bool = Tr
         [2] Panyam, V., Huang, H., Davis, K., & Layton, A. (2019).
         An ecosystem perspective for the design of sustainable power systems. Procedia Cirp, 80, 269-274.
 
-        :param target: the real, reactive, and apparent power over the system. 
-        The default value is MW, which is the real power
-        Users can change to MVR, which is the reactive power; or MVA, which is the apparent power
-        :param split_generator: Choose to split or aggregate multiple generators connected to one bus
-        True: split generators, which considers the generators' robustness to the whole system
-        False: aggregate generators, which doesn't consider generators' robustness 
+        :param target: the real, reactive, and apparent power over the system. The default value
+        is MW, which is the real power. Users can change to MVR, which is the reactive power; or
+        MVA, which is the apparent power.
+        :param split_generator: Choose to split or aggregate multiple generators associated with
+        the same bus. If true, the method will consider the generators' robustness for each
+        generator.
 
         :results: it is a list of ecological metrics, including the Ecological Robustness (Reco), 
         the Ascendancy (ASC), the Development Capacity (DC), the Cycled Throughflow (tstc), the Finn Cycling Index (CI)

tests/test_saw.py

@@ -1045,25 +1045,23 @@ class RunEcologicalAnalysisTestCase(unittest.TestCase):
 
     @classmethod
     def setUpClass(cls) -> None:
-        cls.saw = SAW(PATH_200, CreateIfNotFound=True)
-        cls.saw2 = SAW(PATH_2000, CreateIfNotFound=True)
+        cls.saw = SAW(PATH_2000, CreateIfNotFound=True)
 
     @classmethod
     def tearDownClass(cls) -> None:
         # noinspection PyUnresolvedReferences
         cls.saw.exit()
-        cls.saw2.exit()
 
     def test_run_ecological_analysis(self):
         """ Returns a list of values.
         """
         self.saw.SolvePowerFlow(SolMethod='RECTNEWT')
-        data1 = self.saw.run_ecological_analysis()
+        old = self.saw.run_ecological_analysis()
 
-        self.saw2.SolvePowerFlow(SolMethod='RECTNEWT')
-        data2 = self.saw2.run_ecological_analysis()
-        
-        self.assertLess(data2[0], data1[0])
+        self.saw.SolvePowerFlow(SolMethod='RECTNEWT')
+        new = self.saw.run_ecological_analysis(split_generator=False)
+
+        self.assertLess(new, old)
 
 
 class CTGAutoInsertTestCase(unittest.TestCase):