Voltage sensor angle residual mod 2pi

docs/user_manual/components.md

@@ -627,10 +627,12 @@ A sensor only has output for state estimation. For other calculation types, sens
 $$
    \begin{eqnarray}
         & u_{\text{residual}} = u_{\text{measured}} - u_{\text{state}} \\
-        & \theta_{\text{residual}} = \theta_{\text{measured}} - \theta_{\text{state}}
+        & \theta_{\text{residual}} = \theta_{\text{measured}} - \theta_{\text{state}} \pmod{2 \pi}
    \end{eqnarray}
 $$
 
+The $\pmod{2\pi}$ is handled such that $-\pi \lt \theta_{\text{angle},\text{residual}} \leq \pi$.
+
 ### Generic Power Sensor
 
 * type name: `generic_power_sensor`

power_grid_model_c/power_grid_model/include/power_grid_model/component/voltage_sensor.hpp

@@ -151,7 +151,7 @@ template <symmetry_tag sym> class VoltageSensor : public GenericVoltageSensor {
         } else {
             value.u_residual = (real(u1_measured) - cabs(u)) * u_rated_;
         }
-        value.u_angle_residual = arg(u1_measured) - arg(u);
+        value.u_angle_residual = arg(ComplexValue<symmetric_t>{exp(1.0i * (arg(u1_measured) - arg(u)))});
         return value;
     }
 
@@ -160,7 +160,7 @@ template <symmetry_tag sym> class VoltageSensor : public GenericVoltageSensor {
         value.id = id();
         value.energized = 1;
         value.u_residual = (u_measured_ - cabs(u)) * u_rated_ / sqrt3;
-        value.u_angle_residual = u_angle_measured_ - arg(u);
+        value.u_angle_residual = arg(ComplexValue<asymmetric_t>{exp(1.0i * (u_angle_measured_ - arg(u)))});
         return value;
     }
 };

tests/cpp_unit_tests/test_voltage_sensor.cpp

@@ -363,6 +363,47 @@ TEST_CASE("Test voltage sensor") {
             CHECK(sym_voltage_sensor_asym_output.u_angle_residual[2] == doctest::Approx(-0.2));
         }
 
+        SUBCASE("Angle = ± pi ∓ 0.1") {
+            RealValue<symmetric_t> const u_measured{10.1e3};
+            RealValue<symmetric_t> const u_angle_measured{pi - 0.1};
+            double const u_sigma = 1.0;
+            double const u_rated = 10.0e3;
+
+            VoltageSensorInput<symmetric_t> voltage_sensor_input{};
+            voltage_sensor_input.id = 0;
+            voltage_sensor_input.measured_object = 1;
+            voltage_sensor_input.u_sigma = u_sigma;
+            voltage_sensor_input.u_measured = u_measured;
+            voltage_sensor_input.u_angle_measured = u_angle_measured;
+
+            VoltageSensor<symmetric_t> const voltage_sensor{voltage_sensor_input, u_rated};
+
+            ComplexValue<symmetric_t> const u_calc_sym{1.02 * exp(1i * (-pi + 0.1))};
+            VoltageSensorOutput<symmetric_t> sym_voltage_sensor_sym_output =
+                voltage_sensor.get_output<symmetric_t>(u_calc_sym);
+
+            ComplexValue<asymmetric_t> const u_calc_asym{1.02 * exp(1i * (-pi + 0.1)), 1.03 * exp(1i * (-pi + 0.2)),
+                                                         1.04 * exp(1i * (-pi + 0.3))};
+            VoltageSensorOutput<asymmetric_t> sym_voltage_sensor_asym_output =
+                voltage_sensor.get_output<asymmetric_t>(u_calc_asym);
+
+            // Check sym output
+            CHECK(sym_voltage_sensor_sym_output.id == 0);
+            CHECK(sym_voltage_sensor_sym_output.energized == 1);
+            CHECK(sym_voltage_sensor_sym_output.u_residual == doctest::Approx(-100.0));
+            CHECK(sym_voltage_sensor_sym_output.u_angle_residual == doctest::Approx(-0.2).epsilon(1e-12));
+
+            // Check asym output
+            CHECK(sym_voltage_sensor_asym_output.id == 0);
+            CHECK(sym_voltage_sensor_asym_output.energized == 1);
+            CHECK(sym_voltage_sensor_asym_output.u_residual[0] == doctest::Approx(-100.0 / sqrt3));
+            CHECK(sym_voltage_sensor_asym_output.u_residual[1] == doctest::Approx(-200.0 / sqrt3));
+            CHECK(sym_voltage_sensor_asym_output.u_residual[2] == doctest::Approx(-300.0 / sqrt3));
+            CHECK(sym_voltage_sensor_asym_output.u_angle_residual[0] == doctest::Approx(-0.2).epsilon(1e-12));
+            CHECK(sym_voltage_sensor_asym_output.u_angle_residual[1] == doctest::Approx(-0.3));
+            CHECK(sym_voltage_sensor_asym_output.u_angle_residual[2] == doctest::Approx(-0.4));
+        }
+
         SUBCASE("Angle = nan") {
             RealValue<symmetric_t> const u_measured{10.1e3};
             RealValue<symmetric_t> const u_angle_measured{nan};