Merge branch 'develop'

README.rst

@@ -80,7 +80,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-09-15 (Git commit: 09a0fb7)
+.. table:: ESA's testing coverage as of 2022-09-26 (Git commit: 9fe1d36)
     :widths: auto
     :align: left
 
@@ -89,7 +89,7 @@ testing coverage data for ESA, using `coverage
     +=================+===================+=================+=================+====================+
     | esa/__init__.py |                 2 |               0 |               2 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+
-    | esa/saw.py      |              1124 |               0 |            1124 |                100 |
+    | esa/saw.py      |              1140 |               0 |            1140 |                100 |
     +-----------------+-------------------+-----------------+-----------------+--------------------+
 
 License

VERSION

@@ -1 +1 @@
-1.2.9
+1.3.0

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: e0464f6a5f354efa64833053541a243d
+config: b7c62c6de69d4bab05d2a187be4395f4
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/snippets.rst.txt

@@ -38,10 +38,15 @@ Transient Stability Analysis
 
 .. include:: snippets/ts_mycontingency_200.rst
 
-Contingency Analysis
---------------------
+Fast Contingency Analysis
+-------------------------
+
+.. include:: snippets/fast_contingency_analysis_2000.rst
 
-.. include:: snippets/contingency_analysis_2000.rst
+Contingency Analysis using PW Built-in capability
+-------------------------------------------------
+
+.. include:: snippets/pw_contingency_analysis_2000.rst
 
 Create Simple Graph Model
 -------------------------
@@ -57,3 +62,4 @@ Plot Histogram of Line Flows with Matplotlib
 --------------------------------------------
 
 .. include:: snippets/line_loading_matplotlib_2000.rst
+

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.9',
+    VERSION: '1.3.0',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/html/esa.html

@@ -1481,19 +1481,34 @@
 
 <dl class="py method">
 <dt class="sig sig-object py" id="esa.saw.SAW.get_lodf_matrix">
-<span class="sig-name descname"><span class="pre">get_lodf_matrix</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">precision</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">int</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">3</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.get_lodf_matrix" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">get_lodf_matrix</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">precision</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">int</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method</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">'DC'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">post</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>, <em class="sig-param"><span class="n"><span class="pre">raw</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">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#esa.saw.SAW.get_lodf_matrix" title="Permalink to this definition">¶</a></dt>
 <dd><p>Obtain LODF matrix in numpy array or scipy sparse matrix.
 By default, it obtains the lodf matrix directly from PW. If size
 is larger than 1000, then precision will be applied to filter out
 small values and the result will be returned in scipy sparse matrix.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
-<dd class="field-odd"><p><strong>precision</strong> – number of decimal to keep.</p>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>precision</strong> – number of decimal to keep.</p></li>
+<li><p><strong>method</strong> – The linear method to be used for the LODF calculation. Default is DC.</p></li>
+</ul>
 </dd>
-<dt class="field-even">Returns</dt>
-<dd class="field-even"><p>LODF matrix</p>
+</dl>
+<p>Change to DCPS would take phase shifter into account. Note: AC is NOT an option for the
+LODF calculation.
+:param post: Set to True to calculate any line closure sensitivies relative to
+post-closure flow on the line being closed. This is known as the LCDF value.
+Set to False to calculate any line closure sensitivities based on calculating the flow on
+the line being closed from pre-closure voltages and angles. This is known as the MLCDF
+value.
+:param raw: Set to True if you want to get the raw LODF matrix (dataframe), which suppose to
+be exactly the same as the table shown in the PW GUI. Default is False.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>The LODF matrix and a boolean vector to indicate which lines would cause</p>
 </dd>
 </dl>
+<p>islanding.</p>
 </dd></dl>
 
 <dl class="py method">

docs/html/index.html

@@ -247,7 +247,8 @@ <h1>Easy SimAuto (ESA) Documentation<a class="headerlink" href="#easy-simauto-es
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#increase-loading-in-case">Increase Loading in Case</a></li>
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#add-lines-to-case">Add Lines to Case</a></li>
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#transient-stability-analysis">Transient Stability Analysis</a></li>
-<li class="toctree-l2"><a class="reference internal" href="snippets.html#contingency-analysis">Contingency Analysis</a></li>
+<li class="toctree-l2"><a class="reference internal" href="snippets.html#fast-contingency-analysis">Fast Contingency Analysis</a></li>
+<li class="toctree-l2"><a class="reference internal" href="snippets.html#contingency-analysis-using-pw-built-in-capability">Contingency Analysis using PW Built-in capability</a></li>
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#create-simple-graph-model">Create Simple Graph Model</a></li>
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#created-graph-model-with-edges-weighted-by-branch-impedance">Created Graph Model with Edges Weighted by Branch Impedance</a></li>
 <li class="toctree-l2"><a class="reference internal" href="snippets.html#plot-histogram-of-line-flows-with-matplotlib">Plot Histogram of Line Flows with Matplotlib</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-09-15 (Git commit: 09a0fb7)</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-26 (Git commit: 9fe1d36)</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>1124</p></td>
+<td><p>1140</p></td>
 <td><p>0</p></td>
-<td><p>1124</p></td>
+<td><p>1140</p></td>
 <td><p>100</p></td>
 </tr>
 </tbody>

docs/html/snippets.html

@@ -167,7 +167,9 @@
 
                   <li class="toctree-l2"><a href="#transient-stability-analysis" class="reference internal">Transient Stability Analysis</a></li>
 
-                  <li class="toctree-l2"><a href="#contingency-analysis" class="reference internal">Contingency Analysis</a></li>
+                  <li class="toctree-l2"><a href="#fast-contingency-analysis" class="reference internal">Fast Contingency Analysis</a></li>
+
+                  <li class="toctree-l2"><a href="#contingency-analysis-using-pw-built-in-capability" class="reference internal">Contingency Analysis using PW Built-in capability</a></li>
 
                   <li class="toctree-l2"><a href="#create-simple-graph-model" class="reference internal">Create Simple Graph Model</a></li>
 
@@ -663,8 +665,8 @@ <h2>Transient Stability Analysis<a class="headerlink" href="#transient-stability
 in the case and then load the case using ESA. GetParametersMultipleElement cannot be used
 here to retrieve the TS datapoints (which is a very rare situation).</p>
 </section>
-<section id="contingency-analysis">
-<h2>Contingency Analysis<a class="headerlink" href="#contingency-analysis" title="Permalink to this headline">¶</a></h2>
+<section id="fast-contingency-analysis">
+<h2>Fast Contingency Analysis<a class="headerlink" href="#fast-contingency-analysis" title="Permalink to this headline">¶</a></h2>
 <p>This example shows how to do fast contingency analysis (N-1 &amp; N-2) using
 ESA. The fast contingency analysis is a slightly improved implementation
 of <a class="reference external" href="https://ieeexplore.ieee.org/document/7390321">this paper</a>. It is generally
@@ -698,6 +700,38 @@ <h2>Contingency Analysis<a class="headerlink" href="#contingency-analysis" title
 <p>You could also validate the fast CA result with the built-in CA result by
 simply set the argument <cite>validate=True</cite> when calling <cite>run_contingency_analysis</cite> function.</p>
 </section>
+<section id="contingency-analysis-using-pw-built-in-capability">
+<h2>Contingency Analysis using PW Built-in capability<a class="headerlink" href="#contingency-analysis-using-pw-built-in-capability" title="Permalink to this headline">¶</a></h2>
+<p>This example shows how to perform the contingency analysis via PW’s built-in capability. We assume
+you already have the aux file that contains all the contingencies.</p>
+<p>The initialization procedure is the same as others.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">CASE_PATH</span> <span class="o">=</span> <span class="sa">r</span><span class="s2">&quot;C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">esa</span> <span class="kn">import</span> <span class="n">SAW</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">saw</span> <span class="o">=</span> <span class="n">SAW</span><span class="p">(</span><span class="n">CASE_PATH</span><span class="p">,</span> <span class="n">CreateIfNotFound</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">saw</span><span class="o">.</span><span class="n">pw_order</span> <span class="o">=</span> <span class="kc">True</span>
+</pre></div>
+</div>
+<p>Make sure your case already has a valid operating states. If not, run power flow first:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">saw</span><span class="o">.</span><span class="n">SolvePowerFlow</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>Then load the auxiliary file into Powerworld.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">filepath_aux</span> <span class="o">=</span> <span class="sa">r</span><span class="s2">&quot;C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_contingency_auxfile.aux&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">saw</span><span class="o">.</span><span class="n">ProcessAuxFile</span><span class="p">(</span><span class="n">filepath_aux</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Run the powerworld script command to solve all the contingencies that are not set to skip in the
+loaded auxiliary file.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cmd_solve</span> <span class="o">=</span> <span class="s1">&#39;CTGSolveAll(</span><span class="si">{}</span><span class="s1">,</span><span class="si">{}</span><span class="s1">)&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="s1">&#39;NO&#39;</span><span class="p">,</span><span class="s1">&#39;YES&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">saw</span><span class="o">.</span><span class="n">RunScriptCommand</span><span class="p">(</span><span class="n">cmd_solve</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Use ESA to obtain the CA result</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">saw</span><span class="o">.</span><span class="n">GetParametersMultipleElement</span><span class="p">(</span><span class="s1">&#39;Contingency&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;CTGLabel&#39;</span><span class="p">,</span> <span class="s1">&#39;CTGSolved&#39;</span><span class="p">,</span> <span class="s1">&#39;CTGProc&#39;</span><span class="p">,</span> <span class="s1">&#39;CTGCustMonViol&#39;</span><span class="p">,</span> <span class="s1">&#39;CTGViol&#39;</span><span class="p">])</span>
+</pre></div>
+</div>
+<p>The result is stored as a dataframe.</p>
+</section>
 <section id="create-simple-graph-model">
 <h2>Create Simple Graph Model<a class="headerlink" href="#create-simple-graph-model" title="Permalink to this headline">¶</a></h2>
 <p>This example shows how to easily transform a grid model into a graph

docs/html/welcome.html

@@ -544,6 +544,14 @@ <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-3-0">
+<h3>Version 1.3.0<a class="headerlink" href="#version-1-3-0" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><p>Improve the <cite>get_lodf_matrix</cite> function to support DCPS (DC with phase shifter) and MLCDF</p></li>
+<li><p>Add a new example for the built-in contingency analysis</p></li>
+<li><p>Fix typos and bugs</p></li>
+</ul>
+</section>
 <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">

docs/rst/coverage.rst

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

docs/rst/snippets.rst

@@ -38,10 +38,15 @@ Transient Stability Analysis
 
 .. include:: snippets/ts_mycontingency_200.rst
 
-Contingency Analysis
---------------------
+Fast Contingency Analysis
+-------------------------
+
+.. include:: snippets/fast_contingency_analysis_2000.rst
 
-.. include:: snippets/contingency_analysis_2000.rst
+Contingency Analysis using PW Built-in capability
+-------------------------------------------------
+
+.. include:: snippets/pw_contingency_analysis_2000.rst
 
 Create Simple Graph Model
 -------------------------
@@ -57,3 +62,4 @@ Plot Histogram of Line Flows with Matplotlib
 --------------------------------------------
 
 .. include:: snippets/line_loading_matplotlib_2000.rst
+

docs/rst/snippets/pw_contingency_analysis_2000.rst

@@ -0,0 +1,39 @@
+This example shows how to perform the contingency analysis via PW's built-in capability. We assume
+you already have the aux file that contains all the contingencies.
+
+The initialization procedure is the same as others.
+
+.. code:: python
+
+    >>> CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
+    >>> from esa import SAW
+    >>> saw = SAW(CASE_PATH, CreateIfNotFound=True)
+    >>> saw.pw_order = True
+
+Make sure your case already has a valid operating states. If not, run power flow first:
+
+.. code:: python
+
+    >>> saw.SolvePowerFlow()
+
+Then load the auxiliary file into Powerworld.
+
+.. code:: python
+
+    >>> filepath_aux = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_contingency_auxfile.aux"
+    >>> saw.ProcessAuxFile(filepath_aux)
+    
+Run the powerworld script command to solve all the contingencies that are not set to skip in the
+loaded auxiliary file.
+
+.. code:: python
+
+    >>> cmd_solve = 'CTGSolveAll({},{})'.format('NO','YES')
+    >>> saw.RunScriptCommand(cmd_solve)
+
+Use ESA to obtain the CA result
+
+.. code:: python
+
+    >>> result = saw.GetParametersMultipleElement('Contingency', ['CTGLabel', 'CTGSolved', 'CTGProc', 'CTGCustMonViol', 'CTGViol'])
+The result is stored as a dataframe.