Merge remote-tracking branch 'origin/main' into feature/full-clang-tidy

Author: Laurynas-Jagutis

docs/advanced_documentation/high-level-design.md

@@ -0,0 +1,131 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# High-level design
+
+The power-grid-model follows a typical dynamic/shared library approach, in which the user
+interface is separated from the core implementation using a strict system boundary. Depending
+on the use case and programming language used by the user to call the interface, the user can
+opt to interface with the C API in different ways.
+
+## Layers of abstraction
+
+For the sake of explanation, we consider the
+following layers of abstraction, in increasing order of ease-of-use and abstraction.
+
+* Raw system interface
+  * System symbols only
+  * Everything is handled by the user, including which symbols are supported
+* Exposition-only
+  * Exposes the supported symbols in a language supported by the user
+  * Memory management and error handling is the responsibility of the user
+* Simple wrapper
+  * Wraps the interface in a language supported by the user
+  * Handles memory management, basic error handling and type conversions
+  * Contains no additional features except maybe some basic utility tools
+* The feature-rich layer
+  * Extensive wrapper around the interface with easy functionality exposure and utility functions
+  * Extensive type checks
+
+## Existing library interfaces
+
+The following library interfaces are currently included in the power-grid-model.
+
+| Interface type | Status       | Layer              | Explanation                                                     | Supported by                                        |
+| -------------- | ------------ | ------------------ | --------------------------------------------------------------- | --------------------------------------------------- |
+| C API          | Stable       | Raw interface      | Shared object / DLL that contains the core implementation       | All programming languages with dynamic load support |
+| C headers      | Stable       | Exposition-only    | Exposition-only library using dynamic linking                   | C and C++                                           |
+| C++ headers    | Experimental | Wrapper            | Handles memory management and basic error handling              | C++                                                 |
+| Python library | Stable       | Feature-rich layer | Library with useful functions, conversions and extensive checks | Python                                              |
+
+Note that the Python library in turn also follows the pattern of a feature-rich library that uses a
+module-internal wrapper layer core module, that wraps the exposition-only core module, that exposes
+the raw interface.
+
+This can be visualized graphically as follows.
+
+```{mermaid}
+    :title: Full design
+
+flowchart TD
+    classDef user_node fill:#9f6,stroke:#333,stroke-width:2px
+    classDef public_interface fill:#69f,stroke:#333,stroke-width:2px
+    classDef experimental_interface fill:#99b,stroke:#333,stroke-width:2px
+    classDef private_interface fill:#999,stroke:#333,stroke-width:2px
+    classDef inclusion_method fill:#ddd,stroke:#fff,stroke-width:2px
+
+    subgraph User
+        any_language_user(["Any language user"]):::user_node
+        c_user(["C user"]):::user_node
+        cpp_user(["C++ user"]):::user_node
+        python_user(["Python user"]):::user_node
+    end
+
+    dynamic_loading{ }:::inclusion_method
+    c_includes{ }:::inclusion_method
+
+    subgraph Raw interface
+        power_grid_model_c_dll("power_grid_model_c<br>(shared library)"):::public_interface
+    end
+
+    subgraph Exposition
+        power_grid_model_c("power_grid_model_c<br>(C library)"):::public_interface
+        power_grid_core_python("power_grid_model._core<br>.power_grid_core.py<br>(exposition-only<br>Python module)"):::private_interface
+    end
+
+    subgraph Wrapper
+        power_grid_model_cpp("power_grid_model_cpp<br>(experimental,<br>C++ library)"):::experimental_interface
+        power_grid_model_core_python("power_grid_model._core<br>(Python wrapper library)"):::private_interface
+    end
+
+    subgraph Feature-rich library
+        power_grid_model_python("power_grid_model<br>(Python library)"):::public_interface
+    end
+
+    any_language_user --> dynamic_loading
+    c_includes --> dynamic_loading
+    dynamic_loading -->|dynamic loading| power_grid_model_c_dll
+    c_user --> c_includes
+    cpp_user --> c_includes
+    c_includes -->|links +<br>includes| power_grid_model_c -->|dynamic linking| power_grid_model_c_dll
+    cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
+    python_user -->|import| power_grid_model_python -->|internal import| power_grid_model_core_python -->|internal import| power_grid_core_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
+```
+
+## Creating a custom library or interface
+
+We seek to provide an optimal user experience, but with the sheer amount of programming languages and
+features, it would be impossible to provide a full feature-rich library for every single one. We,
+being a {{ "[community-driven]({}/GOVERNANCE.md)".format(pgm_project_contribution) }} project strongly in
+favor of modern software engineering practices, therefore encourage people to create their own
+libraries and interfaces to improve their own experience. There are several possible reasons a user
+may want to create their own library or interface, e.g.:
+
+* Support for a new programming language
+* Extending library support for a specific programming language
+* A custom wrapper that provides extra features or useful commands for specific custom requirements
+
+In all cases, it is recommended that the user determines their own desired
+[layer of abstraction](#layers-of-abstraction) and then creates internal wrappers for all
+lower-level ones, following the same pattern as the power-grid-model
+[uses internally](#existing-library-interfaces) for the custom interfaces.
+
+### Hosting a custom library or interface
+
+The Power Grid Model organization supports people creating and hosting custom libraries and
+interfaces. If you are doing so and are willing to notify us, please create an item on our
+[discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The Power Grid
+Model organization will review your item and we may decide to mention your custom library on our
+project website and documentation.
+
+### Contributing a custom library or interface
+
+When a custom library or interface becomes mature enough and the circumstances allow making it
+publicly available, please consider contributing it to the Power Grid Model organization. If you are
+considering contributing your custom library or interface, please read and follow our
+{{ "[contributing guidelines]({}/CONTRIBUTING.md)".format(pgm_project_contribution) }} and open an
+item on our [discussion board](https://github.com/orgs/PowerGridModel/discussions) on GitHub. The
+Power Grid Model organization will review your item and contact you accordingly.

docs/conf.py

@@ -25,9 +25,13 @@
     commit_version = git.Repo(search_parent_directories=True).head.object.hexsha
     link_head_gh_blob = link_head_gh + "blob/" + commit_version
     link_head_gh_tree = link_head_gh + "tree/" + commit_version
+    pgm_project_root = ""
+    pgm_project_contribution = pgm_project_root + "/contribution"
 else:
     link_head_gh_blob = ""
     link_head_gh_tree = ""
+    pgm_project_root = "https://github.com/PowerGridModel/.github/blob/main"
+    pgm_project_contribution = pgm_project_root
 
 
 # -- General configuration ---------------------------------------------------
@@ -78,6 +82,8 @@
 myst_substitutions = {
     "gh_link_head_blob": link_head_gh_blob,
     "gh_link_head_tree": link_head_gh_tree,
+    "pgm_project_root": pgm_project_root,
+    "pgm_project_contribution": pgm_project_contribution,
 }
 
 

docs/index.md

@@ -108,6 +108,7 @@ algorithms/lu-solver
 advanced_documentation/native-data-interface
 advanced_documentation/build-guide
 advanced_documentation/c-api
+advanced_documentation/high-level-design
 advanced_documentation/core-design
 advanced_documentation/python-wrapper-design
 ```

power_grid_model_c/power_grid_model/include/power_grid_model/all_components.hpp

@@ -31,16 +31,4 @@ using AllComponents =
     ComponentList<Node, Line, Link, GenericBranch, Transformer, ThreeWindingTransformer, Shunt, Source, SymGenerator,
                   AsymGenerator, SymLoad, AsymLoad, SymPowerSensor, AsymPowerSensor, SymVoltageSensor,
                   AsymVoltageSensor, SymCurrentSensor, AsymCurrentSensor, Fault, TransformerTapRegulator>;
-
-template <typename T>
-concept power_or_current_sensor_c =
-    std::derived_from<T, GenericPowerSensor> || std::derived_from<T, GenericCurrentSensor>;
-
-static_assert(power_or_current_sensor_c<SymPowerSensor>);
-static_assert(power_or_current_sensor_c<AsymPowerSensor>);
-static_assert(power_or_current_sensor_c<SymCurrentSensor>);
-static_assert(power_or_current_sensor_c<AsymCurrentSensor>);
-static_assert(!power_or_current_sensor_c<SymVoltageSensor>);
-static_assert(!power_or_current_sensor_c<AsymVoltageSensor>);
-
 } // namespace power_grid_model

power_grid_model_c/power_grid_model/include/power_grid_model/component/current_sensor.hpp

@@ -26,11 +26,12 @@ class GenericCurrentSensor : public Sensor {
     MeasuredTerminalType get_terminal_type() const { return terminal_type_; }
     AngleMeasurementType get_angle_measurement_type() const { return angle_measurement_type_; }
 
-    template <symmetry_tag sym> CurrentSensorOutput<sym> get_output(ComplexValue<sym> const& i) const {
+    template <symmetry_tag sym>
+    CurrentSensorOutput<sym> get_output(ComplexValue<sym> const& i, ComplexValue<sym> const& u) const {
         if constexpr (is_symmetric_v<sym>) {
-            return get_sym_output(i);
+            return get_sym_output(i, u);
         } else {
-            return get_asym_output(i);
+            return get_asym_output(i, u);
         }
     }
 
@@ -62,8 +63,10 @@ class GenericCurrentSensor : public Sensor {
     virtual CurrentSensorCalcParam<symmetric_t> sym_calc_param() const = 0;
     virtual CurrentSensorCalcParam<asymmetric_t> asym_calc_param() const = 0;
 
-    virtual CurrentSensorOutput<symmetric_t> get_sym_output(ComplexValue<symmetric_t> const& i) const = 0;
-    virtual CurrentSensorOutput<asymmetric_t> get_asym_output(ComplexValue<asymmetric_t> const& i) const = 0;
+    virtual CurrentSensorOutput<symmetric_t> get_sym_output(ComplexValue<symmetric_t> const& i,
+                                                            ComplexValue<symmetric_t> const& u) const = 0;
+    virtual CurrentSensorOutput<asymmetric_t> get_asym_output(ComplexValue<asymmetric_t> const& i,
+                                                              ComplexValue<asymmetric_t> const& u) const = 0;
 };
 
 template <symmetry_tag current_sensor_symmetry_> class CurrentSensor : public GenericCurrentSensor {
@@ -137,20 +140,43 @@ template <symmetry_tag current_sensor_symmetry_> class CurrentSensor : public Ge
         return CurrentSensorCalcParam<sym_calc>{.angle_measurement_type = angle_measurement_type(),
                                                 .measurement = DecomposedComplexRandVar<sym_calc>(i_polar)};
     }
-    CurrentSensorOutput<symmetric_t> get_sym_output(ComplexValue<symmetric_t> const& i) const final {
-        return get_generic_output<symmetric_t>(i);
+    CurrentSensorOutput<symmetric_t> get_sym_output(ComplexValue<symmetric_t> const& i,
+                                                    ComplexValue<symmetric_t> const& u) const final {
+        return get_generic_output<symmetric_t>(i, u);
     }
-    CurrentSensorOutput<asymmetric_t> get_asym_output(ComplexValue<asymmetric_t> const& i) const final {
-        return get_generic_output<asymmetric_t>(i);
+    CurrentSensorOutput<asymmetric_t> get_asym_output(ComplexValue<asymmetric_t> const& i,
+                                                      ComplexValue<asymmetric_t> const& u) const final {
+        return get_generic_output<asymmetric_t>(i, u);
     }
     template <symmetry_tag sym_calc>
-    CurrentSensorOutput<sym_calc> get_generic_output(ComplexValue<sym_calc> const& i) const {
+    CurrentSensorOutput<sym_calc> get_generic_output(ComplexValue<sym_calc> const& i,
+                                                     ComplexValue<sym_calc> const& u) const {
         CurrentSensorOutput<sym_calc> output{};
         output.id = id();
-        ComplexValue<sym_calc> const i_residual{process_mean_val<sym_calc>(i_measured_ - i) * base_current_};
         output.energized = 1; // current sensor is always energized
-        output.i_residual = cabs(i_residual);
-        output.i_angle_residual = arg(i_residual);
+        auto const i_calc_param = calc_param<sym_calc>();
+        auto const angle_measurement_type = i_calc_param.angle_measurement_type;
+        auto const i_measured_complex = i_calc_param.measurement.value();
+        ComplexValue<sym_calc> i_output = [&i, &u, &angle_measurement_type] {
+            switch (angle_measurement_type) {
+            case AngleMeasurementType::global_angle: {
+                return i;
+            }
+            case AngleMeasurementType::local_angle: {
+                // I_l = conj(I_g) * exp(i * u_angle)
+                // Tranform back the output angle to the local angle frame of reference
+                auto const u_angle = arg(u);
+                return ComplexValue<sym_calc>{conj(i) * (cos(u_angle) + 1i * sin(u_angle))};
+            }
+            default: {
+                throw MissingCaseForEnumError{"generic output angle measurement type", angle_measurement_type};
+            }
+            }
+        }();
+        output.i_residual = (cabs(i_measured_complex) - cabs(i_output)) * base_current_;
+        // arg(e^i * u_angle) = u_angle in (-pi, pi]
+        auto const unbounded_i_angle_residual = arg(i_measured_complex) - arg(i_output);
+        output.i_angle_residual = arg(ComplexValue<sym_calc>{exp(1.0i * unbounded_i_angle_residual)});
         return output;
     }
 };