Merge pull request #1367 from PowerGridModel/feature/document-float-grid

Docs: unsupported floating grids in asymmetric calculations

Author: TonyXiang8787

docs/algorithms/pf-algorithms.md

@@ -35,6 +35,10 @@ The following bus types can be present in the system:
 - Voltage controlled bus: a bus with known $P$ and $U$.
   Note: this bus is not supported by power-grid-model yet.
 
+```{note}
+Asymmetric power flow calculations require the network to have a reference to ground. For details and internal solution of asymmetric floating grids calculations in power-grid-model, please refer to [Floating grid handling](../user_manual/calculations.md#floating-grid-handling). 
+```
+
 ## Newton-Raphson power flow
 
 Algorithm call: {py:class}`CalculationMethod.newton_raphson <power_grid_model.enum.CalculationMethod.newton_raphson>`

docs/algorithms/sc-algorithms.md

@@ -21,6 +21,11 @@ $$
 This gives the initial symmetrical short circuit current ($I_k^{\prime\prime}$) for a fault.
 This quantity is then used to derive almost all further calculations of short circuit studies applications.
 
+```{note}
+Short-circuit calculations are currently implemented in the phase (abc) domain and therefore require a grounded network, similar to asymmetric power flow calculations.
+Note that this limitation does not exist in the sequence (0-1-2) domain but is present in the phase domain calculation.
+```
+
 ## IEC 60909 short circuit calculation
 
 Algorithm call: {py:class}`CalculationMethod.iec60909 <power_grid_model.enum.CalculationMethod.iec60909>`

docs/user_manual/calculations.md

@@ -192,6 +192,10 @@ Output:
 - Node voltage magnitude and angle
 - Current flowing through branches and fault.
 
+```{note}
+Short-circuit calculations are currently implemented in the phase (abc) domain and therefore require a grounded configurations in certain cases, similar to asymmetric power flow calculations.
+For details on how floating grids are treated in power-grid-model, please refer to[Floating grid handling](calulations.md#floating-grid-handling).
+
 #### Common calculations
 
 Power flowing through a branch is calculated by voltage and current for any type of calculations in the following way:
@@ -235,12 +239,41 @@ The option affects which attributes are required and how results are exposed.
   For asymmetric calculations voltages are given as line-to-neutral and output contains arrays with values per phase
   for all output variables.
 
+```{note}
+In power-grid model, asymmetric calculations with certain configurations require the network to have a reference to ground. For details on how floating grids are treated in power-grid-model, please refer to [Floating grid handling](calulations.md#floating-grid-handling).
+```
+
 ```{note}
 For short-circuit calculations, a three-phase `fault_type` is calculated with a symmetric calculation, while any other
 `fault_type` (e.g. single- or two-phase faults) automatically triggers the asymmetric calculation.
 Outputs for short circuit calculations always give asymmetric output, independent of the fault type present.
 ```
 
+#### Floating grid handling
+
+In power-grid-model, two different concepts should be distinguished:
+
+- Physical grounding of the network
+  Whether the electrical system has an explicit path to ground
+  (e.g. via transformer winding connection, shunts, or grounding elements).
+- Numerical solvability in PGM
+  Whether the formulation provides enough reference to compute a unique solution,
+  even if the physical system is not explicitly grounded.
+
+A floating grid issue only arises in specific configurations where:
+
+- A transformer is present, and
+- All involved windings are ungrounded (no star-point grounding, no delta grounding reference, etc.), and
+- No other grounding path (shunt, source grounding, etc.) exists in the network.
+
+In this case, the system may lack a reference for calculating line to ground voltages,
+leading to an ill-posed or singular system.
+
+Currently in power-grid-model, a shunt with small admittance is added only in transformer-related configurations
+where a grounding reference is missing. This shunt is connected to one side of the transformer.
+This is intended to ensure numerical solvability in cases
+where the transformer topology introduces an ungrounded subsystem.
+
 ### Power flow algorithms
 
 Two types of power flow algorithms are implemented in power-grid-model; iterative algorithms (Newton-Raphson / Iterative

docs/user_manual/components.md

@@ -720,6 +720,10 @@ It behaves similar to a load/generator with type `const_impedance`.
 | `g0` | `double`  | siemens (S) | zero-sequence shunt conductance     | ✨ only for asymmetric calculation | ✔ |
 | `b0` | `double`  | siemens (S) | zero-sequence shunt susceptance     | ✨ only for asymmetric calculation | ✔ |
 
+```{note}
+In power-grid-model, shunts may also be used to introduce a ground reference in an otherwise floating grid. 
+```
+
 ```{note}
 In case of short circuit calculations, the zero-sequence parameters are required only if any of the faults in any of the
 scenarios within a batch are not three-phase faults (i.e. `fault_type` is not `FaultType.three_phase`).

src/power_grid_model/_core/enum.py

@@ -146,10 +146,29 @@ class WindingType(IntEnum):
     """Transformer Winding Types"""
 
     wye = 0
+    """
+    Star connection without an explicit neutral reference.
+    This winding does **not** provide a connection to neutral/ground.
+    """
     wye_n = 1
+    """
+    Star connection with an explicit neutral reference.
+    This winding provides a connection to neutral/ground.
+    """
     delta = 2
+    """Delta connection.
+    This winding does **not** provide a connection to neutral/ground.
+    """
     zigzag = 3
+    """
+    Zigzag/Interconnected connection.
+    This winding does **not** provide a connection to neutral/ground
+    """
     zigzag_n = 4
+    """
+    Zigzag/Interconnected connection with neutral.
+    This winding provides a reference to neutral/ground.
+    """
 
 
 class BranchSide(IntEnum):