Merge branch 'main' into feature/Cleanup-import-statements2

Author: emabre

code_generation/data/attribute_classes/input.json

@@ -127,6 +127,51 @@
                 }
             ]
         },
+        {
+            "name": "AsymLineInput",
+            "base": "BranchInput",
+            "attributes": [
+                {
+                    "data_type": "double",
+                    "names": [
+                        "r_aa",
+                        "r_ba",
+                        "r_bb",
+                        "r_ca",
+                        "r_cb",
+                        "r_cc",
+                        "r_na",
+                        "r_nb",
+                        "r_nc",
+                        "r_nn",
+                        "x_aa",
+                        "x_ba",
+                        "x_bb",
+                        "x_ca",
+                        "x_cb",
+                        "x_cc",
+                        "x_na",
+                        "x_nb",
+                        "x_nc",
+                        "x_nn",
+                        "c_aa",
+                        "c_ba",
+                        "c_bb",
+                        "c_ca",
+                        "c_cb",
+                        "c_cc",
+                        "c0",
+                        "c1"
+                    ],
+                    "description": "Lower triangle matrix values for R, X and C matrices"
+                },
+                {
+                    "data_type": "double",
+                    "names": "i_n",
+                    "description": "rated current"
+                }
+            ]
+        },
         {
             "name": "GenericBranchInput",
             "base": "BranchInput",

code_generation/data/dataset_class_maps/dataset_definitions.json

@@ -12,6 +12,10 @@
                     "names": ["line"],
                     "class_name": "LineInput"
                 },
+                {
+                    "names": ["asym_line"],
+                    "class_name": "AsymLineInput"
+                },
                 {
                     "names": ["link"],
                     "class_name": "LinkInput"
@@ -71,7 +75,7 @@
                     "class_name": "NodeOutput"
                 },
                 {
-                    "names": ["line", "link", "transformer", "generic_branch"],
+                    "names": ["line", "link", "transformer", "generic_branch", "asym_line"],
                     "class_name": "BranchOutput"
                 },
                 {
@@ -116,6 +120,10 @@
                     "names": ["line"],
                     "class_name": "BranchUpdate"
                 },
+                {
+                    "names": ["asym_line"],
+                    "class_name": "BranchUpdate"
+                },
                 {
                     "names": ["link"],
                     "class_name": "BranchUpdate"
@@ -171,7 +179,7 @@
                     "class_name": "NodeShortCircuitOutput"
                 },
                 {
-                    "names": ["line", "link", "transformer"],
+                    "names": ["line", "link", "transformer", "asym_line"],
                     "class_name": "BranchShortCircuitOutput"
                 },
                 {

docs/advanced_documentation/build-guide.md

@@ -477,11 +477,16 @@ The `pip install .` part of the command installs the complete package from scrat
 
 The C API documentation is generated using [Doxygen](https://www.doxygen.nl). If you do not have Doxygen installed, it can also be temporarily bypassed by commenting out the `breathe` settings in  `docs/conf.py`.
 
-The documentation can be built with the following commands, resulting in html files of the webpages which can be found in `docs/_build/html` directory.
+The documentation can be built with the following commands, resulting in HTML files of the webpages which can be found in `docs/_build/html` directory.
 
 ```shell
 cd docs/doxygen
 doxygen
 cd ..
 sphinx-build -b html . _build/html
 ```
+
+```{note}
+The user documentation generated by [Sphinx](https://github.com/sphinx-doc/sphinx) only contains the C API documentation.
+Doxygen, however, also builds the documentation for the Power Grid Model core implementation, which can be accessed after building the documentation locally via `docs/_build/html/index.html`.
+```

docs/advanced_documentation/core-design.md

@@ -48,3 +48,8 @@ graph TD
 
     ComponentsOutput -->|Output| Output(Output data)
 ```
+
+## Detailed Power Grid Model core design
+
+The sheer size and complexity of the Power Grid Model core implementation makes it hard to generate an up-to-date and comprehensive graph of its design.
+For a full overview of the core, it is recommended to build and access the Power Grid Model core documentation by following the steps in the [build guide](./build-guide.md#documentation).

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/doxygen/Doxyfile

@@ -495,25 +495,25 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PRIV_VIRTUAL   = YES
 
 # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
 # scope will be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PACKAGE        = NO
+EXTRACT_PACKAGE        = YES
 
 # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -529,7 +529,7 @@ EXTRACT_LOCAL_CLASSES  = YES
 # included.
 # The default value is: NO.
 
-EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_LOCAL_METHODS  = YES
 
 # If this flag is set to YES, the members of anonymous namespaces will be
 # extracted and appear in the documentation as a namespace called
@@ -538,7 +538,7 @@ EXTRACT_LOCAL_METHODS  = NO
 # are hidden.
 # The default value is: NO.
 
-EXTRACT_ANON_NSPACES   = NO
+EXTRACT_ANON_NSPACES   = YES
 
 # If this flag is set to YES, the name of an unnamed parameter in a declaration
 # will be determined by the corresponding definition. By default unnamed
@@ -868,7 +868,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../power_grid_model_c/power_grid_model_c/include
+INPUT                  = "../../power_grid_model_c/" "../../src/" "../../tests/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -897,7 +897,7 @@ INPUT_ENCODING         = UTF-8
 # *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl,
 # *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.h
+FILE_PATTERNS          =
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -2314,7 +2314,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: YES.
 
-HAVE_DOT               = NO
+HAVE_DOT               = YES
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of

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
 ```

docs/user_manual/calculations.md

@@ -96,6 +96,11 @@ also of importance, i.e., the measurements should be topologically independent.
 Global angle current measurements require at least one voltage angle measurement to make sense. See also the [current sensor component documentation](./components.md#global-angle-current-sensors).
 ```
 
+```{note}
+It is not possible to add both a [power sensor](./components.md#generic-current-sensor) and a [current sensor](#./components.mdgeneric-current-sensor) to the same terminal of the same component.
+It is, however, allowed to have both a power sensor and a current sensor on the same branch if they are on different terminals.
+```
+
 ```{warning}
 The [iterative linear](#iterative-linear-state-estimation) and [Newton-Raphson](#newton-raphson-state-estimation) state estimation algorithms will assume angles to be zero by default (see the details about voltage sensors).
 In observable systems this helps better outputting correct results. On the other hand with unobservable systems, exceptions raised from calculations due to faulty results will be prevented.
@@ -462,6 +467,11 @@ $$
 
 Where $S_k$ and $\sigma_{P,k}$ and $\sigma_{Q,k}$ are the measured value and the standard deviation of the individual appliances.
 
+```{note}
+It is not possible to add both a [power sensor](./components.md#generic-current-sensor) and a [current sensor](#./components.mdgeneric-current-sensor) to the same terminal of the same component.
+It is, however, allowed to have both a power sensor and a current sensor on the same branch if they are on different terminals.
+```
+
 #### State estimate sensor transformations
 
 Sometimes, measurements need to be transformed between coordinate spaces. For example, current measurements are in polar coordinates (magnitude and angle), but it is beneficial to transform them to separate real and imaginary components per phase, with each their own variances.