shortcircuit documentation and tests

doc/elements/impedance.rst

@@ -23,7 +23,8 @@ Input Parameters
 
 \*necessary for executing a power flow calculation.
 
-
+.. _impedance_model:
+
 Electric Model
 =================
 

doc/shortcircuit.rst

@@ -1,55 +1,13 @@
 ############################
-Short-Circuit *beta!*
+Short-Circuit 
 ############################
 
 The shortcircuit module is used to calculate short-circuits according to DIN/IEC EN 60909.
 
-.. warning:: The pandapower short circuit module is in beta stadium, so please proceed with caution. If you have any question about the shortcircuit module or want to contribute to its development please contact [email protected]
-
-
-The shortcircuit calculation works with the following elements:
-
-    - bus
-    - load (neglected)
-    - shunt (neglected)
-    - sgen
-    - gen
-    - ext_grid
-    - line
-    - trafo
-    - trafo3w
-    - switch
-
-Correction factors for generator and branch elements are implemented as defined in the IEC 60909 standard. The results for all elements are tested against commercial software to ensure that correction factors are correctly applied.
-
-The following currents can be calculated:
-
-   - Ikss
-   - Ith (does not yet work for generator)
-   - ip (does not yet work for generators)
-
-The to-do list for future implementations is:
-
-    - Implement block transformers correction factor (generators and transformers are now always considered seperately)
-    - output branch results
-    - ip and ith for generators
-    - implement ib and ik
-    - implement unsymmetric short-circuit currents (one-phase, two-phase, two-phase-to-earth)
-
-.. autofunction:: pandapower.shortcircuit.runsc
-
-
-
-.. code:: python
-
-    import pandapower.shortcircuit as sc
-    import pandapower.networks as nw
-
-    net = nw.mv_oberrhein()
-    net.ext_grid["s_sc_min_mva"] = 100
-    net.ext_grid["rx_min"] = 0.1
-
-    net.line["endtemp_degree"] = 20
-    sc.runsc(net, case="min")
-    print(net.res_bus_sc)
-
+.. toctree:: 
+    :maxdepth: 1
+
+    shortcircuit/run
+    shortcircuit/currents
+    shortcircuit/elements
+    shortcircuit/correction

doc/shortcircuit/branch_elements.rst

@@ -0,0 +1,70 @@
+Branch Elements
+=================
+
+
+Line
+-----------------------
+
+.. math::
+   :nowrap:
+
+   \begin{align*}
+    \underline{R} &= r\_ohm\_per\_km \cdot \frac{length\_km}{parallel} \cdot c_{R, line}\\
+    \underline{X} &= x\_ohm\_per\_km \cdot \frac{length\_km}{parallel} 
+   \end{align*}
+   
+where the correction factor  :math:`c_{R, line}` is defined as:
+
+.. math::
+
+  c_{R, line}=\left\{
+  \begin{array}{@{}ll@{}}
+            1 & \text{ for maximum short-circuit calculations} \\
+            1 + 0.04 K^{-1} (endtemp\_degree - 20°C) & \text{ for minimum short-circuit calculations} 
+  \end{array}\right.
+
+The end temperature in degree after a fault has to be defined with the parameter endtemp\_degre in the line table.
+
+The shunt capacitance is neglected for short-circuit calculations, so :math:`c_nf_per_km` does not have any influence on the short-circuit current.
+
+Two-Winding Transformer
+-------------------------
+
+The short-circuit impedance is calculated as:
+
+.. math::
+   :nowrap:
+
+   \begin{align*}
+   z_k &= \frac{vsc\_percent}{100} \cdot \frac{1000}{sn\_kva} \cdot c_{trafo} \\
+   r_k &= \frac{vscr\_percent}{100} \cdot \frac{1000}{sn\_kva} \cdot c_{trafo} \\
+   x_k &= \sqrt{z^2 - r^2} \\
+   \end{align*}    
+
+where the correction factor :math:`c_{trafo}` is defined in the standard as:
+
+.. math::
+
+    c_{trafo} = 0.95 \frac{c_{max}}{1 + 0.6 x_T}
+
+where :math:`c_{max}` is the :ref:`voltage correction factor <c>` on the low voltage side of the transformer and :math:`x_T` is the transformer impedance relative to the
+rated values of the transformer.
+
+The ratio of the transformer is considered to be the nominal ratio, the tap changer positions are not considered according to the standard. The shunt 
+admittance is neglected for short-circuit calculations, so :math:`pfe_kw` and :math:`i0_percent`doe not have any influence on the short-circuit current.
+
+
+Three-Winding Transformer
+--------------------------
+
+
+Impedance
+--------------------------
+The impedance element is a generic element that can be used 
+
+.. |variable| replace:: 1
+
+|variable|
+
+
+

doc/shortcircuit/bus_elements.rst

@@ -0,0 +1,42 @@
+Bus Elements
+================
+
+External Grid
+-----------------
+
+When calculating maximum short-circuit currents, the impedance of an external grid connection is given as:
+
+.. math::
+
+  z_{eg} =& \frac{c_{max}}{s\_sc\_max\_mva} \\[1em]
+  x_{sg} =& \frac{z_{sg}}{\sqrt{1 - (rx\_max)^2}} \\[1em]
+  r_{sg} =& rx\_max \cdot x_{sg} 
+  
+where :math:`rx\_max` and :math:`s\_sc\_max\_mva` are parameters in the ext_grid table and :math:`c_{max}` is the :ref:`voltage correction factor <c>` of the
+external grid bus.
+
+In case of minimal short-circuit currents, the impedance is calculated accordingly:
+
+.. math::
+
+  z_{eg} =& \frac{c_{min}}{s\_sc\_min\_mva} \\[1em]
+  x_{sg} =& \frac{z_{sg}}{\sqrt{1 - (rx\_min)^2}} \\[1em]
+  r_{sg} =& rx\_min \cdot x_{sg} 
+
+Static Generator
+-----------------------
+Not all inverter based elements contribute to the short-circuit current. That is why it can be chosen in the runsc function if static generators
+are to be considered or not. If they are considered, the short-circuit impedance is defined according to the standard as:
+
+.. math::
+
+    Z_{sg} = \frac{1}{3} \cdot \frac{vn\_kv^2 \cdot 1000}{sn\_kva} \\
+    X_{sg} = \frac{Z_{sg}}{\sqrt{1 - 0.1^2}} \\
+    R_{sg} = 0.1 \cdot X_{sg}
+
+Synchronous Generator
+-----------------------
+
+Loads and Shunts
+-----------------
+The contribution of loads and shunts are negligible according to the standard and therefore neglected in the short-circuit calculation.

doc/shortcircuit/correction.rst

@@ -0,0 +1,97 @@
+===================
+Correction Factors
+===================
+
+.. _c:
+
+Voltage Corection Factor c
+====================================
+
+The voltage correction factors :math:`c_{min}` for minimum and :math:`c_{max}` for maximum short-circuit currents are applied in calculating
+short-circuit impedances for some elements (transformer, ext_grid) as well as for the equivalent voltage source for the calculation of the
+initials short-circuit current :math:`I''_k`. 
+
+It is defined for each bus depending on the voltage level.
+In the low voltage level, there is an additional distinction between networks with a tolerance of 6% vs. a tolerance of 10% for :math:`c_{max}`:
+
+.. |cmin| replace:: :math:`c_{min}`
+.. |cmax| replace:: :math:`c_{max}`
+
++--------------+---------------+--------+--------+
+|Voltage Level                 | |cmin| | |cmax| |
++==============+===============+========+========+
+|              | Tolerance 6%  |        | 1.05   |
+|< 1 kV        +---------------+  0.95  +--------+
+|              | Tolerance 10% |        | 1.10   |
++--------------+---------------+--------+--------+
+|> 1 kV                        |  1.00  | 1.10   |
++--------------+---------------+--------+--------+
+
+.. _kappa:
+
+Peak Factor :math:`\kappa`
+============================
+
+The factor :math:`\kappa` is used for calculation of the peak short-circuit current :math:`i_p`, thermal equivalent short-circuit 
+current :math:`I_{th}` and unsymmetrical short-circuit currents.
+
+In radial networks, :math:`\kappa` is given as:
+
+.. math::
+
+    \kappa = 1.02 + 0.98 e^{-\frac{3}{R/X}}
+    
+where :math:`R/X` is the R/X ratio of the equivalent short-circuit impedance :math:`Z_k` at the fault location.
+
+In meshed networks, the standard defines three possibilities for the definition of  :math:`\kappa`:
+
+a ) Uniform Ratio R/X 
+
+b) Ratio R/X at short-circuit location
+
+c) Equivalent frequency 
+
+pandapower implements version b), in which the factor :math:`\kappa` is given as:
+
+.. math::
+
+    \kappa = [1.02 + 0.98 e^{-\frac{3}{R/X}}] \cdot 1.15
+
+   
+while being limited with :math:`\kappa_{min} < \kappa < \kappa_{max}` depending on the voltage level:
+
+.. |kmin| replace:: :math:`\kappa_{min}`
+.. |kmax| replace:: :math:`\kappa_{max}`
+
++-------------+--------+--------+
+|Voltage Level| |kmin| | |kmax| |
++=============+========+========+
+| < 1 kV      |        | 1.8    |
++-------------+  1.0   +--------+
+| > 1 kV      |        | 2.0    |
++-------------+--------+--------+
+
+
+.. _mn:
+
+Thermal Factors m and n
+========================
+The factors m and n are necessary for the calculation of the thermal equivalent short-circuit current :math:`I_{th}`.
+
+pandapower currently only implements short-circuit currents far from synchronous generators, where:
+
+.. math::
+
+    n = 1
+
+and m is given as:
+
+.. math::
+
+    m = \frac{1}{2 \cdot f \cdot T_k \cdot ln(\kappa - 1)} [e^{4 \cdot f \cdot T_k \cdot ln(\kappa - 1)} - 1]
+    
+where :math:`\kappa` is defined as above and :math:`T_k` is the duration of the short-circuit current that can be defined as a parameter when
+running the short-circuit calculation. 
+
+
+

doc/shortcircuit/currents.rst

@@ -0,0 +1,49 @@
+=======================
+Short-Circuit Currents
+=======================
+
+The short-circuit currents are calculated with the equivalent voltage source at the fault location.  
+For an explanation of the theory behind short-circuit calculations according to IEC 60909
+please refer to the norm or secondary literature:
+
+.. seealso::
+
+    `IEC 60909-0:2016 <https://webstore.iec.ch/publication/24100>`_ Short-circuit currents in three-phase a.c. systems
+
+    `According to the IEC 60909 <http://www.openelectrical.org/wiki/index.php?title=According_to_the_IEC_60909>`_ on openelectrical
+
+
+Initial Short-Circuit Current
+==========================================
+The initial short-circuit current is calculated as:
+
+.. math::
+   
+   I''_{k} = \frac{c \cdot V_N}{\sqrt{3} \cdot Z_k}
+
+where c is the :ref:`voltage correction factor <c>` and :math:`Z_k` is the short-circuit impedance at the fault bus. 
+The short-circuit impedance at the fault location is defined by the impedances of the :ref:` <network elements>` plus the defined fault impedance.
+:math:`Z_k` is calculated from the impedance matrix, which is the inverse of the nodal point admittance matrix. 
+
+
+Peak Short-Circuit Current
+==========================================
+
+The peak short-circuit current is calculated as:
+
+.. math::
+
+    i_p = \kappa \cdot \sqrt{2} \cdot I''_k
+
+where the factor :math:`\kappa` depends on the short-circuit impedance as defined :ref:`here <kappa>`.
+
+Thermal Short-Circuit Current
+==========================================
+
+The equivalent 
+
+.. math::
+
+    I_{th} = I''_k \cdot \sqrt{m + n}
+
+where the factors m and n are defined :ref:`here <mn>`.

doc/shortcircuit/elements.rst

@@ -0,0 +1,13 @@
+.. _sc_elements:
+==================
+Network Elements
+==================
+
+Correction factors for generator and branch elements are implemented as defined in the IEC 60909 standard. The results for all elements are tested against commercial software to ensure that correction factors are correctly applied.
+
+
+.. toctree:: 
+    :maxdepth: 1
+
+    bus_elements
+    branch_elements

doc/shortcircuit/run.rst

@@ -0,0 +1,20 @@
+====================================
+Running a Short-Circuit Calculation
+====================================
+
+.. autofunction:: pandapower.shortcircuit.runsc
+
+
+.. code:: python
+
+    import pandapower.shortcircuit as sc
+    import pandapower.networks as nw
+
+    net = nw.mv_oberrhein()
+    net.ext_grid["s_sc_min_mva"] = 100
+    net.ext_grid["rx_min"] = 0.1
+
+    net.line["endtemp_degree"] = 20
+    sc.runsc(net, case="min")
+    print(net.res_bus_sc)
+