Merge branch 'main' into feature/voltage-sensor-residuals

Author: mgovers

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/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/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.

docs/user_manual/components.md

@@ -652,6 +652,11 @@ In the state estimation result, the power from this injection is distributed equ
 Because of this distribution, at least one appliance is required to be connected to the node where an injection sensor is placed for it to function.
 ```
 
+```{note}
+It is not possible to add both a [power sensor](#generic-current-sensor) and a [current sensor](#generic-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.
+```
+
 ##### Input
 
 | name                     | data type                                                                     | unit             | description                                                                                                                                                                                 |                                                           required                                                            |  update  |                     valid values                     |
@@ -743,6 +748,11 @@ The terminal is connecting the from/to end of a `branch` (except `link`) and a `
 Due to the high admittance of a `link` it is chosen that a current sensor cannot be coupled to a `link`, even though a link is a `branch`
 ```
 
+```{note}
+It is not possible to add both a [power sensor](#generic-current-sensor) and a [current sensor](#generic-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.
+```
+
 ##### Input
 
 | name                     | data type                                                                     | unit       | description                                                                                                                               | required |  update  |                     valid values                     |
@@ -828,11 +838,11 @@ As a result, the local angle current sensors have a different sign convention fr
 $$
    \begin{eqnarray}
         & i_{\text{residual}} = i_{\text{measured}} - i_{\text{state}} && \\
-        & i_{\text{angle},\text{residual}} = i_{\text{angle},\text{measured}} - i_{\text{angle},\text{state}} \pmod 2 \pi
+        & i_{\text{angle},\text{residual}} = i_{\text{angle},\text{measured}} - i_{\text{angle},\text{state}} \pmod{2 \pi}
    \end{eqnarray}
 $$
 
-The $\pmod 2\pi$ is handled such that $-\pi \lt i_{\text{angle},\text{residual}} \leq \pi$.
+The $\pmod{2\pi}$ is handled such that $-\pi \lt i_{\text{angle},\text{residual}} \leq \pi$.
 
 ## Fault