Step-up transformer tap changer support: linear search control logic

.clang-tidy

@@ -55,6 +55,7 @@ readability-*,
 -readability-function-cognitive-complexity,
 -readability-identifier-length,
 -readability-magic-numbers,
+-bugprone-unchecked-optional-access,
 '
 
 WarningsAsErrors: '*'

.github/workflows/citations.yml

@@ -35,4 +35,4 @@ jobs:
       run: |
         sudo apt-get update && sudo apt-get install -y r-base
     - name: Validate CITATION.cff
-      uses: dieghernan/cff-validator@v3
+      uses: dieghernan/cff-validator@v4

.github/workflows/main.yml

@@ -188,7 +188,7 @@ jobs:
             os: ubuntu-24.04
             cibw_build: "*_x86_64"
           - platform: linux-aarch64
-            os: ubuntu-24.04
+            os: ubuntu-24.04-arm
             cibw_build: "*_aarch64"
           - platform: macos
             os: macos-14
@@ -208,10 +208,6 @@ jobs:
           name: version
           path: .
 
-      - name: Set up QEMU
-        if: matrix.os == 'ubuntu-24.04'
-        uses: docker/setup-qemu-action@v3
-
       - name: Set up XCode
         if: matrix.os == 'macos-14'
         uses: maxim-lobanov/setup-xcode@v1

.readthedocs.yaml

@@ -12,6 +12,8 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.11"
+  apt_packages:
+    - graphviz
   jobs:
     post_install:
       # Build package with doc requirements from pyproject.optional-dependencies
@@ -21,6 +23,11 @@ build:
       - find power_grid_model_c/power_grid_model_c/include -name *.h -exec sed -i -r "s/PGM_API //g" {} \;
       # build doxygen for C header
       - cd docs/doxygen && doxygen && cd ../..
+      # build class and package diagrams
+      - pyreverse --no-standalone -o dot src/power_grid_model
+      - ccomps -x classes.dot | dot -Grankdir=LR -Nfontsize=13 -Efontsize=13 | gvpack -m100 -array_l1 | neato -n2 -Tsvg -o docs/_static/classes.svg
+      - dot packages.dot -Grankdir=TD -Nfontsize=13 -Efontsize=13 -Tsvg -o docs/_static/packages.svg
+      - rm packages.dot classes.dot
       # download support
       - wget -P docs/release_and_support https://github.com/PowerGridModel/.github/raw/main/RELEASE.md
       - wget -P docs/release_and_support https://github.com/PowerGridModel/.github/raw/main/SUPPORT.md

CMakeLists.txt

@@ -29,8 +29,13 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 
 include(GNUInstallDirs)
 
-find_package(Eigen3 CONFIG REQUIRED)
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.30.0") 
+#  libboost-headers packaged by conda does not come with BoostConfig.cmake
+cmake_policy(SET CMP0167 OLD)  
+endif()
+
 find_package(Boost REQUIRED)
+find_package(Eigen3 CONFIG REQUIRED)
 find_package(nlohmann_json CONFIG REQUIRED)
 find_package(msgpack-cxx REQUIRED)
 

CMakePresets.json

@@ -254,7 +254,10 @@
     },
     {
       "name": "ci-clang-release",
-      "inherits": "clang-release"
+      "inherits": "clang-release",
+      "cacheVariables": {
+        "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "TRUE"
+      }
     },
     {
       "name": "ci-gcc-debug",
@@ -270,7 +273,13 @@
       "name": "ci-gcc-release",
       "inherits": [
         "gcc-release"
-      ]
+      ],
+      "cacheVariables": {
+        "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "TRUE"
+      },
+      "environment": {
+        "ASAN_OPTIONS": "detect_odr_violation=0"
+      }
     },
     {
       "name": "ci-sonar",

README.md

@@ -41,6 +41,7 @@ Currently, it supports the following calculations:
 
 See the [power-grid-model documentation](https://power-grid-model.readthedocs.io/en/stable/) for more information.
 For various conversions to the power-grid-model, refer to the [power-grid-model-io](https://github.com/PowerGridModel/power-grid-model-io) repository.
+For an extended python interface to the the power-grid-model, refer to the [power-grid-model-ds](https://github.com/PowerGridModel/power-grid-model-ds) repository.
 
 ```{note}
 Want to be updated on the latest news and releases? Subscribe to the Power Grid Model mailing list by sending an (empty) email to: powergridmodel+subscribe@lists.lfenergy.org

code_generation/data/attribute_classes/input.json

@@ -494,6 +494,45 @@
                     "description": "line drop compensation reactance"
                 }
             ]
+        },
+        {
+            "name": "GenericCurrentSensorInput",
+            "base": "SensorInput",
+            "attributes": [
+                {
+                    "data_type": "MeasuredTerminalType",
+                    "names": "measured_terminal_type",
+                    "description": "type of measured terminal"
+                },
+                {
+                    "data_type": "AngleMeasurementType",
+                    "names": "angle_measurement_type",
+                    "description": "type of angle measurement"
+                },
+                {
+                    "data_type": "double",
+                    "names": [
+                        "i_sigma", 
+                        "i_angle_sigma"
+                    ],
+                    "description": "sigma of error margin of current (angle) measurement"
+                }
+            ]
+        },
+        {
+            "name": "CurrentSensorInput",
+            "base": "GenericCurrentSensorInput",
+            "is_template": true,
+            "attributes": [
+                {
+                    "data_type": "RealValue<sym>",
+                    "names": [
+                        "i_measured",
+                        "i_angle_measured"
+                    ],
+                    "description": "measured current and current angle"
+                }
+            ]
         }
     ]
 }

code_generation/data/attribute_classes/output.json

@@ -293,6 +293,21 @@
             "base": "BaseOutput",
             "is_template": false,
             "attributes": []
+        },
+        {
+            "name": "CurrentSensorOutput",
+            "base": "BaseOutput",
+            "is_template": true,
+            "attributes": [
+                {
+                    "data_type": "RealValue<sym>",
+                    "names": [
+                        "i_residual",
+                        "i_angle_residual"
+                    ],
+                    "description": "deviation between the measured value and calculated value"
+                }
+            ]
         }
     ]
 }

code_generation/data/attribute_classes/update.json

@@ -243,6 +243,29 @@
                     "description": "line drop compensation reactance"
                 }
             ]
+        },
+        {
+            "name": "CurrentSensorUpdate",
+            "base": "BaseUpdate",
+            "is_template": true,
+            "attributes": [
+                {
+                    "data_type": "double",
+                    "names": [
+                        "i_sigma", 
+                        "i_angle_sigma"
+                    ],
+                    "description": "sigma of error margin of current (angle) measurement"
+                },
+                {
+                    "data_type": "RealValue<sym>",
+                    "names": [
+                        "i_measured",
+                        "i_angle_measured"
+                    ],
+                    "description": "measured current and current angle"
+                }
+            ]
         }
     ]
 }

docs/advanced_documentation/python-wrapper-design.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# Design of the Python Wrapper Package
+
+The structure of the `power_grid_model` Python package is shown here below by means of the corresponding class and package diagrams.
+
+## Class Graph Diagram
+
+This is the class diagram of the `power_grid_model` package.
+
+```{note}
+Only classes that have connections to other classes are shown in this diagram.
+```
+
+```{raw} html
+<div style="overflow-x: auto; white-space: nowrap;">
+  <img src="../_static/classes.svg" style="max-width: none;" alt="Classe diagram">
+</div>.
+```
+
+## Package Graph Diagram
+
+This is the package diagram of the `power_grid_model` package.
+
+```{note}
+Only modules that import (or are impored by) other modules are shown in this diagram.
+```
+
+```{raw} html
+<div style="overflow-x: auto; white-space: nowrap;">
+  <img src="../_static/packages.svg" style="max-width: none;" alt="Package diagram">
+</div>.
+```

docs/index.md

@@ -22,6 +22,7 @@ Currently, it supports both symmetric and asymmetric calculations for the follow
 * Short Circuit
 
 For conversions from various data format to the power-grid-model, refer to the [power-grid-model-io](https://github.com/PowerGridModel/power-grid-model-io) repository.
+For an extended python interface to the the power-grid-model, refer to the [power-grid-model-ds](https://github.com/PowerGridModel/power-grid-model-ds) repository.
 
 ```{note}
 Do you wish to be updated on the latest news and releases? Subscribe to the Power Grid Model mailing list by sending an (empty) email to: powergridmodel+subscribe@lists.lfenergy.org
@@ -100,6 +101,7 @@ advanced_documentation/native-data-interface
 advanced_documentation/build-guide
 advanced_documentation/c-api
 advanced_documentation/core-design
+advanced_documentation/python-wrapper-design
 ```
 ```{toctree}
 :caption: "Contribution"

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/input.hpp

@@ -444,6 +444,52 @@ struct TransformerTapRegulatorInput {
     operator RegulatorInput const&() const { return reinterpret_cast<RegulatorInput const&>(*this); }
 };
 
+struct GenericCurrentSensorInput {
+    ID id{na_IntID};  // ID of the object
+    ID measured_object{na_IntID};  // ID of the measured object
+    MeasuredTerminalType measured_terminal_type{static_cast<MeasuredTerminalType>(na_IntS)};  // type of measured terminal
+    AngleMeasurementType angle_measurement_type{static_cast<AngleMeasurementType>(na_IntS)};  // type of angle measurement
+    double i_sigma{nan};  // sigma of error margin of current (angle) measurement
+    double i_angle_sigma{nan};  // sigma of error margin of current (angle) measurement
+
+    // implicit conversions to BaseInput
+    operator BaseInput&() { return reinterpret_cast<BaseInput&>(*this); }
+    operator BaseInput const&() const { return reinterpret_cast<BaseInput const&>(*this); }
+
+    // implicit conversions to SensorInput
+    operator SensorInput&() { return reinterpret_cast<SensorInput&>(*this); }
+    operator SensorInput const&() const { return reinterpret_cast<SensorInput const&>(*this); }
+};
+
+template <symmetry_tag sym_type>
+struct CurrentSensorInput {
+    using sym = sym_type;
+
+    ID id{na_IntID};  // ID of the object
+    ID measured_object{na_IntID};  // ID of the measured object
+    MeasuredTerminalType measured_terminal_type{static_cast<MeasuredTerminalType>(na_IntS)};  // type of measured terminal
+    AngleMeasurementType angle_measurement_type{static_cast<AngleMeasurementType>(na_IntS)};  // type of angle measurement
+    double i_sigma{nan};  // sigma of error margin of current (angle) measurement
+    double i_angle_sigma{nan};  // sigma of error margin of current (angle) measurement
+    RealValue<sym> i_measured{nan};  // measured current and current angle
+    RealValue<sym> i_angle_measured{nan};  // measured current and current angle
+
+    // implicit conversions to BaseInput
+    operator BaseInput&() { return reinterpret_cast<BaseInput&>(*this); }
+    operator BaseInput const&() const { return reinterpret_cast<BaseInput const&>(*this); }
+
+    // implicit conversions to SensorInput
+    operator SensorInput&() { return reinterpret_cast<SensorInput&>(*this); }
+    operator SensorInput const&() const { return reinterpret_cast<SensorInput const&>(*this); }
+
+    // implicit conversions to GenericCurrentSensorInput
+    operator GenericCurrentSensorInput&() { return reinterpret_cast<GenericCurrentSensorInput&>(*this); }
+    operator GenericCurrentSensorInput const&() const { return reinterpret_cast<GenericCurrentSensorInput const&>(*this); }
+};
+
+using SymCurrentSensorInput = CurrentSensorInput<symmetric_t>;
+using AsymCurrentSensorInput = CurrentSensorInput<asymmetric_t>;
+
 
 
 } // namespace power_grid_model

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/input.hpp

@@ -396,6 +396,38 @@ struct get_attributes_list<TransformerTapRegulatorInput> {
     };
 };
 
+template<>
+struct get_attributes_list<GenericCurrentSensorInput> {
+    static constexpr std::array<MetaAttribute, 6> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::id>(offsetof(GenericCurrentSensorInput, id), "id"),
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::measured_object>(offsetof(GenericCurrentSensorInput, measured_object), "measured_object"),
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::measured_terminal_type>(offsetof(GenericCurrentSensorInput, measured_terminal_type), "measured_terminal_type"),
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::angle_measurement_type>(offsetof(GenericCurrentSensorInput, angle_measurement_type), "angle_measurement_type"),
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::i_sigma>(offsetof(GenericCurrentSensorInput, i_sigma), "i_sigma"),
+            meta_data_gen::get_meta_attribute<&GenericCurrentSensorInput::i_angle_sigma>(offsetof(GenericCurrentSensorInput, i_angle_sigma), "i_angle_sigma"),
+    };
+};
+
+template <symmetry_tag sym_type>
+struct get_attributes_list<CurrentSensorInput<sym_type>> {
+    using sym = sym_type;
+
+    static constexpr std::array<MetaAttribute, 8> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::id>(offsetof(CurrentSensorInput<sym>, id), "id"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::measured_object>(offsetof(CurrentSensorInput<sym>, measured_object), "measured_object"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::measured_terminal_type>(offsetof(CurrentSensorInput<sym>, measured_terminal_type), "measured_terminal_type"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::angle_measurement_type>(offsetof(CurrentSensorInput<sym>, angle_measurement_type), "angle_measurement_type"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::i_sigma>(offsetof(CurrentSensorInput<sym>, i_sigma), "i_sigma"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::i_angle_sigma>(offsetof(CurrentSensorInput<sym>, i_angle_sigma), "i_angle_sigma"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::i_measured>(offsetof(CurrentSensorInput<sym>, i_measured), "i_measured"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorInput<sym>::i_angle_measured>(offsetof(CurrentSensorInput<sym>, i_angle_measured), "i_angle_measured"),
+    };
+};
+
 
 
 

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/output.hpp

@@ -247,6 +247,20 @@ struct get_attributes_list<RegulatorShortCircuitOutput> {
     };
 };
 
+template <symmetry_tag sym_type>
+struct get_attributes_list<CurrentSensorOutput<sym_type>> {
+    using sym = sym_type;
+
+    static constexpr std::array<MetaAttribute, 4> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&CurrentSensorOutput<sym>::id>(offsetof(CurrentSensorOutput<sym>, id), "id"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorOutput<sym>::energized>(offsetof(CurrentSensorOutput<sym>, energized), "energized"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorOutput<sym>::i_residual>(offsetof(CurrentSensorOutput<sym>, i_residual), "i_residual"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorOutput<sym>::i_angle_residual>(offsetof(CurrentSensorOutput<sym>, i_angle_residual), "i_angle_residual"),
+    };
+};
+
 
 
 

power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/meta_gen/update.hpp

@@ -197,6 +197,21 @@ struct get_attributes_list<TransformerTapRegulatorUpdate> {
     };
 };
 
+template <symmetry_tag sym_type>
+struct get_attributes_list<CurrentSensorUpdate<sym_type>> {
+    using sym = sym_type;
+
+    static constexpr std::array<MetaAttribute, 5> value{
+            // all attributes including base class
+
+            meta_data_gen::get_meta_attribute<&CurrentSensorUpdate<sym>::id>(offsetof(CurrentSensorUpdate<sym>, id), "id"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorUpdate<sym>::i_sigma>(offsetof(CurrentSensorUpdate<sym>, i_sigma), "i_sigma"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorUpdate<sym>::i_angle_sigma>(offsetof(CurrentSensorUpdate<sym>, i_angle_sigma), "i_angle_sigma"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorUpdate<sym>::i_measured>(offsetof(CurrentSensorUpdate<sym>, i_measured), "i_measured"),
+            meta_data_gen::get_meta_attribute<&CurrentSensorUpdate<sym>::i_angle_measured>(offsetof(CurrentSensorUpdate<sym>, i_angle_measured), "i_angle_measured"),
+    };
+};
+