Implementation of feature 720 asym_line

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/user_manual/components.md

@@ -276,6 +276,132 @@ $$
    \end{eqnarray}
 $$
 
+### Asym Line
+
+* type name: `asym_line`
+
+`asym_line` is a {hoverxreftooltip}`user_manual/components:branch` with specified resistance and reactance per phase. A cable can be modelled as `line` or `asym_line`. An `asym_line` can only connect two nodes with the same rated voltage. If `i_n` is not provided, `loading` of line will be a `nan` value. The `asym_line` denotes a 3 or 4 phase line with phases `a`, `b`, `c` and optionally `n` for neutral.
+
+#### Input
+
+The provided values will be converted to a matrix representing the line's properties per phase in the following form:
+$$
+   \begin{bmatrix}
+      \text{aa} & \text{ba} & \text{ca} & \text{na}\\
+      \text{ba} & \text{bb} & \text{cb} & \text{nb}\\
+      \text{ca} & \text{cb} & \text{cc} & \text{nc}\\
+      \text{na} & \text{nb} & \text{nc} & \text{nn}
+   \end{bmatrix}
+$$
+
+This representation holds for all values `r_aa` - `r_nn`, `x_aa` - `x_nn` and `c_aa` - `c_cc`. If the neutral values are not provided, the last row and column from the above matrix are omitted.
+
+| name   | data type | unit       | description                       | required                     |  update  |            valid values            |
+| ------ | --------- | ---------- | --------------------------------- | ---------------------------- | :------: | :--------------------------------: |
+| `r_aa` | `double`  | ohm (Ω)    | Series serial resistance aa       | ✔                     | ❌ |               `> 0`                |
+| `r_ba` | `double`  | ohm (Ω)    | Series serial resistance ba       | ✔                     | ❌ |               `> 0`                |
+| `r_bb` | `double`  | ohm (Ω)    | Series serial resistance bb       | ✔                     | ❌ |               `> 0`                |
+| `r_ca` | `double`  | ohm (Ω)    | Series serial resistance ca       | ✔                     | ❌ |               `> 0`                |
+| `r_cb` | `double`  | ohm (Ω)    | Series serial resistance cb       | ✔                     | ❌ |               `> 0`                |
+| `r_cc` | `double`  | ohm (Ω)    | Series serial resistance cc       | ✔                     | ❌ |               `> 0`                |
+| `r_na` | `double`  | ohm (Ω)    | Series serial resistance na       | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `r_nb` | `double`  | ohm (Ω)    | Series serial resistance nb       | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `r_nc` | `double`  | ohm (Ω)    | Series serial resistance nc       | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `r_nn` | `double`  | ohm (Ω)    | Series serial resistance nn       | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `x_aa` | `double`  | ohm (Ω)    | Series serial reactance aa        | ✔                     | ❌ |               `> 0`                |
+| `x_ba` | `double`  | ohm (Ω)    | Series serial reactance ba        | ✔                     | ❌ |               `> 0`                |
+| `x_bb` | `double`  | ohm (Ω)    | Series serial reactance bb        | ✔                     | ❌ |               `> 0`                |
+| `x_ca` | `double`  | ohm (Ω)    | Series serial reactance ca        | ✔                     | ❌ |               `> 0`                |
+| `x_cb` | `double`  | ohm (Ω)    | Series serial reactance cb        | ✔                     | ❌ |               `> 0`                |
+| `x_cc` | `double`  | ohm (Ω)    | Series serial reactance cc        | ✔                     | ❌ |               `> 0`                |
+| `x_na` | `double`  | ohm (Ω)    | Series serial reactance na        | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `x_nb` | `double`  | ohm (Ω)    | Series serial reactance nb        | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `x_nc` | `double`  | ohm (Ω)    | Series serial reactance nc        | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `x_nn` | `double`  | ohm (Ω)    | Series serial reactance nn        | ✨ for a neutral phase | ❌ |               `> 0`                |
+| `c_aa` | `double`  | farad (F)  | Shunt nodal capacitance matrix aa | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c_ba` | `double`  | farad (F)  | Shunt nodal capacitance matrix ba | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c_bb` | `double`  | farad (F)  | Shunt nodal capacitance matrix bb | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c_ca` | `double`  | farad (F)  | Shunt nodal capacitance matrix ca | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c_cb` | `double`  | farad (F)  | Shunt nodal capacitance matrix cb | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c_cc` | `double`  | farad (F)  | Shunt nodal capacitance matrix cc | ✨ for a full c matrix | ❌ |               `> 0`                |
+| `c0`   | `double`  | farad (F)  | zero-sequence shunt capacitance   | ✨ without a c matrix  | ❌ |               `> 0`                |
+| `c1`   | `double`  | farad (F)  | Series shunt capacitance          | ✨ without a c matrix  | ❌ |               `> 0`                |
+
+For the r and x matrices providing values for the neutral phase is optional. To clarify which input values are required, please consult the tables below:
+
+| r_aa - r_cc   | r_na     | r_nb     | r_nc     | r_nn     | result   | Validation Error          |
+| ------------- | -------- | -------- | -------- | -------- | -------- | ------------------------- |
+| ✔      | ✔ | ✔ | ✔ | ✔ | ✔ |                           |
+| ✔      | ✔ | ✔ | ✔ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ✔ | ✔ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ✔ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ❌ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ❌ | ❌ | ❌ | ❌ | ✔ |                           |
+| ❌      | ❌ | ❌ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+
+| x_aa - x_cc   | x_na     | x_nb     | x_nc     | x_nn     | result   | Validation Error          |
+| ------------- | -------- | -------- | -------- | -------- | -------- | ------------------------- |
+| ✔      | ✔ | ✔ | ✔ | ✔ | ✔ |                           |
+| ✔      | ✔ | ✔ | ✔ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ✔ | ✔ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ✔ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ✔ | ❌ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+| ✔      | ❌ | ❌ | ❌ | ❌ | ✔ |                           |
+| ❌      | ❌ | ❌ | ❌ | ❌ | ❌ | MultiFieldValidationError |
+
+For the c-matrix values there are two options. Either provide all the required c-matrix values i.e. `c_aa` - `c_cc` or provide `c0`, `c1`. Whenver both sets are supplied the powerflow calculations will use `c0`, `c1`.
+The table below provides guidance in providing valid input.
+
+| c_aa - c_cc | c0       | c1       | result   | Validation Error          |
+| ----------- | -------- | -------- | -------- | ------------------------- |
+| ✔    | ✔ | ✔ | ✔ |                           |
+| ✔    | ✔ | ❌ | ✔ |                           |
+| ✔    | ❌ | ❌ | ✔ |                           |
+| ❌    | ✔ | ❌ | ❌ | MultiFieldValidationError |
+| ❌    | ✔ | ✔ | ✔ |                           |
+
+#### Electric Model
+
+The cable properties are described using matrices where the $Z_{\text{series}}$ matrix is computed as:
+
+$$
+   Z_{\text{series}} = R + j * X
+$$
+
+Where $R$ and $X$ denote the resistance and reactance matrices build from the input respectively.
+
+Whenever the neutral phase is provided in the $Z_{\text{series}}$, the $Z_{\text{series}}$ matrix will first be reduced to a 3 phase matrix $Z_{\text{reduced}}$ with a kron reduction as follows:
+
+$$
+   Z_{\text{aa}} = \begin{bmatrix}
+                     Z_{\text{0,0}} & Z_{\text{1,0}} & Z_{\text{2,0}}\\
+                     Z_{\text{1,0}} & Z_{\text{2,2}} & Z_{\text{2,1}}\\
+                     Z_{\text{2,0}} & Z_{\text{2,1}} & Z_{\text{2,2}}
+                   \end{bmatrix}
+$$
+$$
+   Z_{\text{ab}} = \begin{bmatrix}
+                     Z_{\text{0,3}} \\
+                     Z_{\text{1,3}} \\
+                     Z_{\text{2,3}}
+                   \end{bmatrix}
+$$
+$$
+   Z_{\text{ba}} = \begin{bmatrix}
+                     Z_{\text{3,0}} \\
+                     Z_{\text{3,1}} \\
+                     Z_{\text{3,2}}
+                   \end{bmatrix}
+$$
+$$
+   Z_{\text{bb}}^{-1} = \frac{1}{Z_{\text{3,3}}}
+$$
+$$
+   Z_{\text{reduced}} = Z_{\text{aa}} - Z_{\text{ba}} \otimes Z_{\text{ab}} \cdot Z_{\text{bb}}^{-1}
+$$
+
+Where $Z_{\text{i,j}}$ denotes the row and column of the $Z_{\text{series}}$ matrix.
+
 ## Branch3
 
 * type name: `branch3`

power_grid_model_c/power_grid_model/include/power_grid_model/all_components.hpp

@@ -9,6 +9,7 @@
 #include "common/component_list.hpp"
 // component include
 #include "component/appliance.hpp"
+#include "component/asym_line.hpp"
 #include "component/current_sensor.hpp"
 #include "component/fault.hpp"
 #include "component/generic_branch.hpp"
@@ -28,8 +29,8 @@
 namespace power_grid_model {
 
 using AllComponents =
-    ComponentList<Node, Line, Link, GenericBranch, Transformer, ThreeWindingTransformer, Shunt, Source, SymGenerator,
-                  AsymGenerator, SymLoad, AsymLoad, SymPowerSensor, AsymPowerSensor, SymVoltageSensor,
+    ComponentList<Node, Line, AsymLine, Link, GenericBranch, Transformer, ThreeWindingTransformer, Shunt, Source,
+                  SymGenerator, AsymGenerator, SymLoad, AsymLoad, SymPowerSensor, AsymPowerSensor, SymVoltageSensor,
                   AsymVoltageSensor, SymCurrentSensor, AsymCurrentSensor, Fault, TransformerTapRegulator>;
 
 template <typename T>

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

@@ -98,6 +98,51 @@ struct LineInput {
     operator BranchInput const&() const { return reinterpret_cast<BranchInput const&>(*this); }
 };
 
+struct AsymLineInput {
+    ID id{na_IntID};  // ID of the object
+    ID from_node{na_IntID};  // node IDs to which this branch is connected at both sides
+    ID to_node{na_IntID};  // node IDs to which this branch is connected at both sides
+    IntS from_status{na_IntS};  // whether the branch is connected at each side
+    IntS to_status{na_IntS};  // whether the branch is connected at each side
+    double r_aa{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_ba{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_bb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_ca{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_cb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_cc{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_na{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_nb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_nc{nan};  // Lower triangle matrix values for R, X and C matrices
+    double r_nn{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_aa{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_ba{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_bb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_ca{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_cb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_cc{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_na{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_nb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_nc{nan};  // Lower triangle matrix values for R, X and C matrices
+    double x_nn{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_aa{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_ba{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_bb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_ca{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_cb{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c_cc{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c0{nan};  // Lower triangle matrix values for R, X and C matrices
+    double c1{nan};  // Lower triangle matrix values for R, X and C matrices
+    double i_n{nan};  // rated current
+
+    // implicit conversions to BaseInput
+    operator BaseInput&() { return reinterpret_cast<BaseInput&>(*this); }
+    operator BaseInput const&() const { return reinterpret_cast<BaseInput const&>(*this); }
+
+    // implicit conversions to BranchInput
+    operator BranchInput&() { return reinterpret_cast<BranchInput&>(*this); }
+    operator BranchInput const&() const { return reinterpret_cast<BranchInput const&>(*this); }
+};
+
 struct GenericBranchInput {
     ID id{na_IntID};  // ID of the object
     ID from_node{na_IntID};  // node IDs to which this branch is connected at both sides