Merge pull request #1164 from PowerGridModel/feature/meshed-observability-documentation

Documentation: meshed observability check and the handling of the voltage phasor sensor

Author: Jerry-Jinfeng-Guo

docs/user_manual/calculations.md

@@ -159,8 +159,16 @@ Either of them counts as one.
 The condition check above only checks the necessary condition for observability.
 When the measurements are not independent enough, the system may still be unobservable even if the necessary condition
 is met.
-It is rather complicated to do a full sufficient and necessary observability check in generic cases.
-However, `power-grid-model` performs the sufficient condition check when the underlying grid is radial.
+The `power-grid-model` performs the sufficient condition check on radial networks.
+The `power-grid-model` performs the sufficient condition check on meshed networks without voltage phasor sensor.
+
+The sufficient check is done by the topological approach of finding a full spanning tree with the available sensors
+ at components in the network.
+That is to say, if there exists a tree that visits all nodes in the network, the network is observable.
+
+```{warning}
+The handling of voltage phasor sensor in the context of observability check is still work in progress.
+```
 
 In this case, the validation of the independent measurements is rather straightforward.
 If the system is not observable, the calculation will raise a `NotObservableError` instead of `SparseMatrixError`.

docs/user_manual/components.md

@@ -106,7 +106,7 @@ In this case, the attribute `from_status` and `to_status` is always 1.
 | `q_to`    | `RealValueOutput` | volt-ampere-reactive (var) | reactive power flowing into the branch at to-side        |
 | `i_to`    | `RealValueOutput` | ampere (A)                 | magnitude of current at to-side                          |
 | `s_to`    | `RealValueOutput` | volt-ampere (VA)           | apparent power flowing at to-side                        |
-| `loading` | `double`          | -                          | relative loading of the line, `1.0` meaning 100% loaded. |
+| `loading` | `double`          | -                          | relative loading of the branch, `1.0` meaning 100% loaded. |
 
 #### Short circuit output
 

power_grid_model_c/power_grid_model/include/power_grid_model/math_solver/observability.hpp

@@ -558,12 +558,9 @@ inline ObservabilityResult observability_check(MeasuredValues<sym> const& measur
     // check the sufficient condition for observability
     // the check is currently only implemented for radial grids
     if (topo.is_radial) {
-        // Temporary path, ideally this is only called when
-        // n_voltage_phasor_sensors > 0, regardless of network type
         is_sufficient_condition_met = detail::sufficient_condition_radial_with_voltage_phasor(
             y_bus_structure, observability_sensors, n_voltage_phasor_sensors);
     } else {
-        // Temporary path, to be refined later
         is_sufficient_condition_met =
             detail::sufficient_condition_meshed_without_voltage_phasor(bus_neighbourhood_info);
     }