Skip to content

Commit 693c4a2

Browse files
mgoversmgovers
authored
Merge branch 'main' into drop-manylinux-2-24
2 parents 1c95364 + 2e42a32 commit 693c4a2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+917
-568
lines changed

‎.vscode/extensions.json

-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
"ms-vscode.test-adapter-converter",
2222
"njpwerner.autodocstring",
2323
"jeff-hykin.better-cpp-syntax",
24-
"twxs.cmake",
2524
"matepek.vscode-catch2-test-adapter",
2625
"cschlosser.doxdocgen",
2726
"fredericbonnet.cmake-test-adapter",

‎docs/api_reference/python-api-reference.md

+11-3
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ SPDX-License-Identifier: MPL-2.0
66

77
# power_grid_model (Python API)
88

9-
This is the Python API reference for the `power-grid-model` library
9+
This is the Python API reference for the `power-grid-model` library.
10+
Due to the nature of how Python module works, we cannnot hide the implementation detail completely from the user.
11+
As a general rule, any Python modules/functions/classes which are not documented in this API documentation,
12+
are internal implementations.
13+
**The user should not use any of them. We do not guarantee the stability or even the existence of those modules.**
1014

1115
```{eval-rst}
1216
.. py:module:: power_grid_model
@@ -71,14 +75,18 @@ This includes all miscellaneous type hints not under dataset or categories.
7175
.. autofunction:: power_grid_model.validation.validate_input_data
7276
.. autofunction:: power_grid_model.validation.validate_batch_data
7377
.. autofunction:: power_grid_model.validation.assert_valid_input_data
74-
.. autofunction:: power_grid_model.validation.assert_valid_batch_data
78+
.. autofunction:: power_grid_model.validation.assert_valid_batch_data
79+
.. autofunction:: power_grid_model.validation.assert_valid_data_structure
7580
.. autofunction:: power_grid_model.validation.errors_to_string
81+
.. autoclass:: power_grid_model.validation.ValidationException
7682
```
7783

7884
### validation errors
7985

8086
```{eval-rst}
81-
.. autoclass:: power_grid_model.validation.errors.ValidationError
87+
.. automodule:: power_grid_model.validation.errors
88+
:undoc-members:
89+
:show-inheritance:
8290
```
8391

8492
## utils

‎docs/user_manual/calculations.md

+10-4
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@ Power flow calculations that take the behavior of these regulators into account
626626

627627
##### Control logic for power flow with automatic tap changing
628628

629-
The following control logic is used:
629+
We provide the control logic used for tap changing. For simplicity, we demonstrate the case where the regulator control side and the transformer tap side are at different sides.
630630

631631
- Regulated transformers are ranked according to how close they are to {hoverxreftooltip}`sources <user_manual/components:source>` in terms of the amount of regulated transformers inbetween.
632632
- Transformers are regulated in order according to their ranks.
@@ -652,6 +652,7 @@ The following control logic is used:
652652
- Exploit the neighbourhood of all transformers (see {hoverxreftooltip}`user_manual/calculations:Initialization and exploitation of regulated transformers`)
653653
- Re-run the iteration in the above if any of the tap positions changed by the exploitation.
654654

655+
In the case where the control side of the regulator and the tap side of the transformer are at the same side, the control logic of taps will be reverted (see `user_manual/calculations:Initialization and exploitation of regulated transformers`).
655656
The exploitation of the neighbourhood ensures that the actual optimum is not accidentally missed due to feedback mechanisms in the grid.
656657

657658
```{note}
@@ -667,7 +668,6 @@ This assumption is reflected in the requirements mentioned in {hoverxreftooltip}
667668
```
668669

669670
```{note}
670-
The control logic assumes that the (compensated) control voltage decreases when the tap position increases.
671671
If the line drop compensation impedance is high, and the control side has generator-like behavior, then this assumption does not hold, and the calculation may diverge.
672672
Hence, this assumption is reflected in the requirements mentioned in {hoverxreftooltip}`user_manual/components:Line drop compensation`.
673673
```
@@ -679,10 +679,16 @@ Internally, to achieve an optimal regulated tap position, the control algorithm
679679
| strategy | initial tap position | exploitation direction | search method | description |
680680
| ----------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------- | ------------- | ------------------------------------------------------------------------------------- |
681681
| {py:class}`TapChangingStrategy.any_valid_tap <power_grid_model.enum.TapChangingStrategy.any_valid_tap>` | current tap position | no exploitation | linear search | Find any tap position that gives a control side voltage within the `u_band` |
682-
| {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` | `tap_max` | step up | binary search | Find the tap position that gives the lowest control side voltage within the `u_band` |
683-
| {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` | `tap_min` | step down | binary search | Find the tap position that gives the highest control side voltage within the `u_band` |
682+
| {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` | voltage min tap | voltage down | binary search | Find the tap position that gives the lowest control side voltage within the `u_band` |
683+
| {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` | voltage min tap | voltage up | binary search | Find the tap position that gives the highest control side voltage within the `u_band` |
684684
| {py:class}`TapChangingStrategy.fast_any_tap <power_grid_model.enum.TapChangingStrategy.fast_any_tap>` | current tap position | no exploitation | binary search | Find any tap position that gives a control side voltage within the `u_band` |
685685

686+
| transformer configuration | voltage min tap | voltage min tap | voltage down | voltage up |
687+
| ---------------------------------------------- | --------------- | --------------- | ------------ | ---------- |
688+
| regulator control side != transformer tap side | `tap_max` | `tap_min` | step up | step down |
689+
| regulator control side == transformer tap side | `tap_min` | `tap_max` | step down | step up |
690+
691+
686692
##### Search methods used for tap changing optimization
687693

688694
Given the discrete nature of the finite tap ranges, we use the following search methods to find the next tap position along the exploitation direction.

‎docs/user_manual/components.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -804,19 +804,19 @@ The actual grid state is not changed after calculations are done.
804804

805805
#### Input
806806

807-
| name | data type | unit | description | required | update | valid values |
808-
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- | :--------------------------: | :------: | :---------------: |
809-
| `control_side` | {py:class}`BranchSide <power_grid_model.enum.BranchSide>` if the regulated object is a {hoverxreftooltip}`user_manual/components:transformer` and {py:class}`Branch3Side <power_grid_model.enum.Branch3Side>` if it the regulated object is a {hoverxreftooltip}`user_manual/components:Three-Winding Transformer` | - | the controlled side of the transformer | &#10024; only for power flow | &#10060; | |
810-
| `u_set` | `double` | volt (V) | the voltage setpoint (at the center of the band) | &#10024; only for power flow | &#10004; | `>= 0` |
811-
| `u_band` | `double` | volt (V) | the width of the voltage band ($=2*\left(\Delta U\right)_{\text{acceptable}}$) | &#10024; only for power flow | &#10004; | `> 0` (see below) |
812-
| `line_drop_compensation_r` | `double` | ohm (Ω) | compensation for voltage drop due to resistance during transport (see [below](#line-drop-compensation)) | &#10060; default `0.0` | &#10004; | `>= 0` |
813-
| `line_drop_compensation_x` | `double` | ohm (Ω) | compensation for voltage drop due to reactance during transport (see [below](#line-drop-compensation)) | &#10060; default `0.0` | &#10004; | `>= 0` |
807+
| name | data type | unit | description | required | update | valid values |
808+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- | :--------------------------: | :------: | :--------------------------------------------------------------: |
809+
| `control_side` | {py:class}`BranchSide <power_grid_model.enum.BranchSide>` if the regulated object is a {hoverxreftooltip}`user_manual/components:transformer` and {py:class}`Branch3Side <power_grid_model.enum.Branch3Side>` if it the regulated object is a {hoverxreftooltip}`user_manual/components:Three-Winding Transformer` | - | the controlled side of the transformer | &#10024; only for power flow | &#10060; | `control_side` should be the relatively further side to a source |
810+
| `u_set` | `double` | volt (V) | the voltage setpoint (at the center of the band) | &#10024; only for power flow | &#10004; | `>= 0` |
811+
| `u_band` | `double` | volt (V) | the width of the voltage band ($=2*\left(\Delta U\right)_{\text{acceptable}}$) | &#10024; only for power flow | &#10004; | `> 0` (see below) |
812+
| `line_drop_compensation_r` | `double` | ohm (Ω) | compensation for voltage drop due to resistance during transport (see [below](#line-drop-compensation)) | &#10060; default `0.0` | &#10004; | `>= 0` |
813+
| `line_drop_compensation_x` | `double` | ohm (Ω) | compensation for voltage drop due to reactance during transport (see [below](#line-drop-compensation)) | &#10060; default `0.0` | &#10004; | `>= 0` |
814814

815815
The following additional requirements exist on the input parameters.
816816

817-
- The automatic tap changer algorithm currently only supports tap changers connected at HV side of the transformer. Hence, the rated voltage of the node at the `tap_side` must be greater than or equal to the rated voltage of the node at the other side of transformer.
818817
- Depending on the resultant voltage being transformed, the voltage band must be sufficiently large: At zero line drop compensation if the expected resultant voltages are in the proximity of the rated transformer voltages, it is recommended to have the $u_{band} >= \frac{u_2}{1+ u_1 / \text{tap}_{\text{size}}}$
819818
- The line drop compensation is small, in the sense that its product with the typical current through the transformer is much smaller (in absolute value) than the smallest change in voltage due to a change in tap position.
819+
- The `control_side` of a transformer regulator should be on the relatively further side to a source in the connected grid.
820820

821821
These requirements make sure no edge cases with undefined behavior are encountered. Typical real-world power grids already satisfy these requirements and they should therefore not cause any problems.
822822

‎power_grid_model_c/power_grid_model/include/power_grid_model/auxiliary/dataset.hpp

+20
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,11 @@ struct ComponentInfo {
4040
// for non-uniform component, this is -1, we use indptr to describe the elements per scenario
4141
Idx elements_per_scenario{};
4242
Idx total_elements{};
43+
// whether there is a subset of meaningful attributes that was deduced from the dataset
44+
bool has_attribute_indications{false};
45+
// this is not redundant as we use them for aggregate intialization
46+
// NOLINTNEXTLINE(readability-redundant-member-init)
47+
std::vector<MetaAttribute const*> attribute_indications{};
4348
};
4449

4550
struct DatasetInfo {
@@ -336,6 +341,21 @@ template <dataset_type_tag dataset_type_> class Dataset {
336341
add_component_info_impl(component, elements_per_scenario, total_elements);
337342
}
338343

344+
void enable_attribute_indications(std::string_view component)
345+
requires is_indptr_mutable_v<dataset_type>
346+
{
347+
Idx const idx = find_component(component, true);
348+
dataset_info_.component_info[idx].has_attribute_indications = true;
349+
}
350+
351+
void set_attribute_indications(std::string_view component, std::span<MetaAttribute const*> attribute_indications)
352+
requires is_indptr_mutable_v<dataset_type>
353+
{
354+
Idx const idx = find_component(component, true);
355+
dataset_info_.component_info[idx].attribute_indications = {attribute_indications.begin(),
356+
attribute_indications.end()};
357+
}
358+
339359
void add_buffer(std::string_view component, std::integral auto elements_per_scenario_,
340360
std::integral auto total_elements_, Indptr* indptr, Data* data)
341361
requires(!is_indptr_mutable_v<dataset_type>)

0 commit comments

Comments
 (0)