pf-tool 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pf_tool-0.2.0/LICENSE.txt +29 -0
- pf_tool-0.2.0/PKG-INFO +304 -0
- pf_tool-0.2.0/README.md +291 -0
- pf_tool-0.2.0/exporter.py +886 -0
- pf_tool-0.2.0/models/__init__.py +7 -0
- pf_tool-0.2.0/models/branch.py +29 -0
- pf_tool-0.2.0/models/bus.py +39 -0
- pf_tool-0.2.0/models/case.py +67 -0
- pf_tool-0.2.0/models/csc.py +69 -0
- pf_tool-0.2.0/models/generator.py +24 -0
- pf_tool-0.2.0/models/hvdc_lcc.py +373 -0
- pf_tool-0.2.0/models/network_reduction.py +333 -0
- pf_tool-0.2.0/models/shunt.py +135 -0
- pf_tool-0.2.0/models/svc.py +108 -0
- pf_tool-0.2.0/models/transformer.py +360 -0
- pf_tool-0.2.0/newton_raphson.py +774 -0
- pf_tool-0.2.0/optimization.py +772 -0
- pf_tool-0.2.0/pf_tool.egg-info/PKG-INFO +304 -0
- pf_tool-0.2.0/pf_tool.egg-info/SOURCES.txt +29 -0
- pf_tool-0.2.0/pf_tool.egg-info/dependency_links.txt +1 -0
- pf_tool-0.2.0/pf_tool.egg-info/requires.txt +4 -0
- pf_tool-0.2.0/pf_tool.egg-info/top_level.txt +5 -0
- pf_tool-0.2.0/pyproject.toml +42 -0
- pf_tool-0.2.0/setup.cfg +4 -0
- pf_tool-0.2.0/tests/test_exporter.py +55 -0
- pf_tool-0.2.0/tests/test_newton_raphson.py +516 -0
- pf_tool-0.2.0/tests/test_optimization.py +168 -0
- pf_tool-0.2.0/utils/__init__.py +1 -0
- pf_tool-0.2.0/utils/dat_parser.py +57 -0
- pf_tool-0.2.0/utils/network.py +105 -0
- pf_tool-0.2.0/utils/utils.py +211 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, Marck Llerena Velásquez
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
pf_tool-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pf-tool
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: AC/DC power flow for the Brazilian Interconnected Power System (BIPS): Newton-Raphson and optimization (Pyomo/Ipopt) solvers for ANAREDE .dat cases.
|
|
5
|
+
Requires-Python: >=3.12
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
License-File: LICENSE.txt
|
|
8
|
+
Requires-Dist: numpy>=1.24
|
|
9
|
+
Requires-Dist: openpyxl>=3.1
|
|
10
|
+
Requires-Dist: pyomo>=6.8
|
|
11
|
+
Requires-Dist: scipy>=1.10
|
|
12
|
+
Dynamic: license-file
|
|
13
|
+
|
|
14
|
+
# pf-tool
|
|
15
|
+
|
|
16
|
+
AC/DC power-flow solver for the Brazilian Interconnected Power System (BIPS): ANAREDE `.dat` data model, Newton-Raphson and optimization methods.
|
|
17
|
+
|
|
18
|
+
[](docs/) [](pyproject.toml) [](https://github.com/astral-sh/ruff) [](LICENSE.txt)
|
|
19
|
+
|
|
20
|
+
**pf-tool** is an AC/DC power-flow package for the Brazilian Interconnected
|
|
21
|
+
Power System (BIPS). It solves the ANAREDE-style `.dat` cases in `tests/data/`, which
|
|
22
|
+
are BIPS snapshots of about 12,600 buses each, with two AC power-flow methods:
|
|
23
|
+
|
|
24
|
+
- [`newton_raphson.py`](newton_raphson.py): `NewtonRaphsonPowerFlow`, a sparse
|
|
25
|
+
polar Newton-Raphson solver.
|
|
26
|
+
- [`optimization.py`](optimization.py): `OptimizationPowerFlow`, an
|
|
27
|
+
optimization-based AC power flow (Pyomo NLP solved with Ipopt), following the
|
|
28
|
+
formulation of the o-grid optimization ACPF paper.
|
|
29
|
+
|
|
30
|
+
Component models live in [`models/`](models/), and the `.dat` parser and case
|
|
31
|
+
assembly live in [`utils/`](utils/).
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from newton_raphson import NewtonRaphsonPowerFlow
|
|
35
|
+
from optimization import OptimizationPowerFlow
|
|
36
|
+
|
|
37
|
+
newton = NewtonRaphsonPowerFlow("tests/data/CASO01-FLOW.dat").solve()
|
|
38
|
+
nlp = OptimizationPowerFlow("tests/data/CASO01-FLOW.dat", warm_start=True).solve()
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The optimization solver requires `pyomo` (see `requirements.txt`) and an Ipopt
|
|
42
|
+
executable on `PATH`.
|
|
43
|
+
|
|
44
|
+
### Documentation
|
|
45
|
+
|
|
46
|
+
Comprehensive [documentation](docs/) built with [Astro Starlight](https://starlight.astro.build/) documents:
|
|
47
|
+
|
|
48
|
+
- every data block and column;
|
|
49
|
+
- how each power-system component is modeled;
|
|
50
|
+
- the full Newton-Raphson algorithm;
|
|
51
|
+
- the full optimization formulation: sets, parameters, variables, expressions,
|
|
52
|
+
constraints, and objective.
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
cd docs
|
|
56
|
+
npm install
|
|
57
|
+
npm run build # static site in docs/dist
|
|
58
|
+
npm run dev # local preview at http://localhost:4321
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Example scripts
|
|
62
|
+
|
|
63
|
+
[`examples/`](examples/) contains one minimal script per solver class. Each
|
|
64
|
+
script sets `data_file`, solves the case, prints the result, and exports the
|
|
65
|
+
solution with `ExportSolution` to `examples/results/`. To run another case,
|
|
66
|
+
change `data_file`.
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
python examples/run_nr_powerflow.py
|
|
70
|
+
python examples/run_opt_powerflow.py
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Exporting results
|
|
74
|
+
|
|
75
|
+
`ExportSolution` (in [`exporter.py`](exporter.py)) writes every solved
|
|
76
|
+
component to an Excel workbook. It uses one sheet per component: Summary,
|
|
77
|
+
Buses, Generators, Loads, Lines, Transformers, LTC, PST, HVDC, SVC, CSC, and
|
|
78
|
+
Shunts.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
from exporter import ExportSolution
|
|
82
|
+
|
|
83
|
+
solver = NewtonRaphsonPowerFlow("tests/data/CASO01-FLOW.dat")
|
|
84
|
+
solver.solve()
|
|
85
|
+
ExportSolution(solver, output_path="results/CASO01-FLOW-nr.xlsx")
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Flows on branches collapsed by the zero-impedance reduction, such as switches
|
|
89
|
+
and bypassed CSCs, are recovered from Kirchhoff's current law in each reduced
|
|
90
|
+
node. In the exported solution, every bus balances to within 3e-5 MVA.
|
|
91
|
+
|
|
92
|
+
## Convergence summary
|
|
93
|
+
|
|
94
|
+
All 11 cases converge with every method.
|
|
95
|
+
|
|
96
|
+
| Method | Cases converged | Mean time per case (s) | Total time (s) |
|
|
97
|
+
| ------------------------------- | --------------: | ---------------------: | -------------: |
|
|
98
|
+
| Newton-Raphson | 11 / 11 | 2.8 | 31.0 |
|
|
99
|
+
| Optimization, Newton warm start | 11 / 11 | 10.2 | 112.5 |
|
|
100
|
+
| Optimization, cold start | 11 / 11 | 37.6 | 413.6 |
|
|
101
|
+
|
|
102
|
+
Measurement details:
|
|
103
|
+
|
|
104
|
+
- Tolerance is `TEPA / BASE = 1e-4 pu` from each case's `DCTE` block.
|
|
105
|
+
- Newton's iteration limit is `ACIT`.
|
|
106
|
+
- Elapsed time includes parsing, case construction, network reduction, and all
|
|
107
|
+
control passes.
|
|
108
|
+
- Runs used Windows, Python 3.12, Pyomo 6.10.1, and Ipopt 3.12.13.
|
|
109
|
+
- `Median / p99 dV` is the median and 99th-percentile absolute difference from
|
|
110
|
+
the bus voltages stored in each `.dat` file, which are the ANAREDE solution.
|
|
111
|
+
|
|
112
|
+
The lowest voltages, about 0.74–0.83 pu, occur at low-voltage SVC terminal
|
|
113
|
+
buses. ANAREDE's stored voltages are similarly low there; for example, bus
|
|
114
|
+
7035 is stored at 0.734 pu.
|
|
115
|
+
|
|
116
|
+
### Newton-Raphson
|
|
117
|
+
|
|
118
|
+
| Case | Buses | Converged | Iterations | Final max mismatch (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
119
|
+
| --------------- | ----: | --------: | ---------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
120
|
+
| CASO01-FLOW.dat | 12579 | Yes | 19 | 9.7e-07 | 2.7 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
121
|
+
| CASO02-FLOW.dat | 12579 | Yes | 15 | 6.0e-06 | 2.8 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
122
|
+
| CASO03-FLOW.dat | 12579 | Yes | 18 | 9.4e-07 | 3.2 | 0.755–1.165 | 0.0008 / 0.0077 |
|
|
123
|
+
| CASO04-FLOW.dat | 12572 | Yes | 11 | 2.6e-07 | 2.5 | 0.751–1.143 | 0.0005 / 0.0098 |
|
|
124
|
+
| CASO05-FLOW.dat | 12578 | Yes | 12 | 5.9e-06 | 2.7 | 0.760–1.120 | 0.0012 / 0.0100 |
|
|
125
|
+
| CASO06-FLOW.dat | 12613 | Yes | 12 | 2.0e-06 | 2.7 | 0.752–1.182 | 0.0009 / 0.0100 |
|
|
126
|
+
| CASO07-FLOW.dat | 12613 | Yes | 12 | 2.0e-06 | 2.7 | 0.742–1.166 | 0.0010 / 0.0093 |
|
|
127
|
+
| CASO08-FLOW.dat | 12613 | Yes | 19 | 3.2e-06 | 2.9 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
128
|
+
| CASO09-FLOW.dat | 12607 | Yes | 16 | 2.7e-07 | 2.7 | 0.764–1.131 | 0.0007 / 0.0101 |
|
|
129
|
+
| CASO10-FLOW.dat | 12611 | Yes | 17 | 2.0e-06 | 2.8 | 0.745–1.267 | 0.0010 / 0.0096 |
|
|
130
|
+
| CASO11-FLOW.dat | 12613 | Yes | 16 | 2.0e-06 | 3.1 | 0.827–1.121 | 0.0007 / 0.0098 |
|
|
131
|
+
|
|
132
|
+
Iterations are totals across all outer control passes.
|
|
133
|
+
|
|
134
|
+
### Optimization AC power flow (Newton warm start)
|
|
135
|
+
|
|
136
|
+
| Case | Converged | NLP solves | Ipopt iterations | Final max residual (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
137
|
+
| --------------- | --------: | ---------: | ---------------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
138
|
+
| CASO01-FLOW.dat | Yes | 1 | 7 (+19 Newton) | 4.5e-12 | 9.5 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
139
|
+
| CASO02-FLOW.dat | Yes | 1 | 8 (+15 Newton) | 3.4e-12 | 10.2 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
140
|
+
| CASO03-FLOW.dat | Yes | 1 | 7 (+18 Newton) | 9.6e-11 | 11.0 | 0.755–1.165 | 0.0008 / 0.0077 |
|
|
141
|
+
| CASO04-FLOW.dat | Yes | 1 | 7 (+11 Newton) | 4.5e-12 | 9.9 | 0.751–1.143 | 0.0005 / 0.0098 |
|
|
142
|
+
| CASO05-FLOW.dat | Yes | 1 | 8 (+12 Newton) | 5.5e-12 | 10.5 | 0.760–1.120 | 0.0012 / 0.0100 |
|
|
143
|
+
| CASO06-FLOW.dat | Yes | 1 | 7 (+12 Newton) | 1.2e-11 | 9.8 | 0.752–1.182 | 0.0009 / 0.0100 |
|
|
144
|
+
| CASO07-FLOW.dat | Yes | 1 | 7 (+12 Newton) | 1.3e-11 | 9.8 | 0.742–1.166 | 0.0010 / 0.0093 |
|
|
145
|
+
| CASO08-FLOW.dat | Yes | 1 | 8 (+19 Newton) | 3.3e-12 | 10.6 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
146
|
+
| CASO09-FLOW.dat | Yes | 1 | 8 (+16 Newton) | 1.9e-12 | 10.3 | 0.764–1.131 | 0.0007 / 0.0101 |
|
|
147
|
+
| CASO10-FLOW.dat | Yes | 1 | 7 (+17 Newton) | 3.2e-12 | 10.2 | 0.745–1.267 | 0.0010 / 0.0096 |
|
|
148
|
+
| CASO11-FLOW.dat | Yes | 1 | 7 (+16 Newton) | 4.3e-12 | 10.7 | 0.827–1.121 | 0.0007 / 0.0098 |
|
|
149
|
+
|
|
150
|
+
### Optimization AC power flow (cold start)
|
|
151
|
+
|
|
152
|
+
`warm_start=False` starts the NLP from the stored voltages. Before the first
|
|
153
|
+
solve, it reconciles transformer settings with those voltages; see
|
|
154
|
+
"Transformers" below.
|
|
155
|
+
|
|
156
|
+
| Case | Converged | NLP solves | Ipopt iterations | Final max residual (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
157
|
+
| --------------- | --------: | ---------: | ---------------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
158
|
+
| CASO01-FLOW.dat | Yes | 6 | 49 | 7.6e-12 | 43.9 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
159
|
+
| CASO02-FLOW.dat | Yes | 6 | 47 | 4.0e-12 | 42.5 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
160
|
+
| CASO03-FLOW.dat | Yes | 6 | 48 | 5.1e-11 | 42.9 | 0.755–1.165 | 0.0008 / 0.0078 |
|
|
161
|
+
| CASO04-FLOW.dat | Yes | 5 | 40 | 5.2e-12 | 35.4 | 0.751–1.143 | 0.0005 / 0.0112 |
|
|
162
|
+
| CASO05-FLOW.dat | Yes | 5 | 42 | 3.9e-12 | 35.9 | 0.760–1.120 | 0.0012 / 0.0161 |
|
|
163
|
+
| CASO06-FLOW.dat | Yes | 5 | 44 | 7.8e-12 | 35.6 | 0.752–1.182 | 0.0009 / 0.0110 |
|
|
164
|
+
| CASO07-FLOW.dat | Yes | 5 | 40 | 8.3e-12 | 35.3 | 0.742–1.164 | 0.0010 / 0.0102 |
|
|
165
|
+
| CASO08-FLOW.dat | Yes | 5 | 44 | 1.0e-11 | 36.0 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
166
|
+
| CASO09-FLOW.dat | Yes | 5 | 42 | 6.1e-11 | 35.5 | 0.764–1.133 | 0.0007 / 0.0116 |
|
|
167
|
+
| CASO10-FLOW.dat | Yes | 5 | 39 | 1.3e-11 | 35.2 | 0.745–1.267 | 0.0009 / 0.0109 |
|
|
168
|
+
| CASO11-FLOW.dat | Yes | 5 | 40 | 4.0e-12 | 35.5 | 0.827–1.204 | 0.0008 / 0.0109 |
|
|
169
|
+
|
|
170
|
+
The cold-start NLP does not include LTC voltage regulation. Its solutions are
|
|
171
|
+
therefore slightly farther from ANAREDE than the Newton and warm-start results,
|
|
172
|
+
with a larger p99 voltage difference.
|
|
173
|
+
|
|
174
|
+
## What made the cases converge
|
|
175
|
+
|
|
176
|
+
The earlier non-convergence came mainly from network-data errors, not from
|
|
177
|
+
solver tuning. With the corrected model, both methods reach the ANAREDE
|
|
178
|
+
operating point.
|
|
179
|
+
|
|
180
|
+
1. **`DCSC` series compensators are standalone circuits.** All 126 `DCSC`
|
|
181
|
+
records describe their own `I–J` circuit, and none duplicates a `DLIN` line.
|
|
182
|
+
The previous builder dropped them, removing series-compensated corridors such
|
|
183
|
+
as Itaipu 765 kV and the Mato Grosso 500 kV lines. Active compensators now
|
|
184
|
+
use reactance `Xv` (%), and bypassed ones (`Byp = "L"`) are shorts that the
|
|
185
|
+
network reduction contracts.
|
|
186
|
+
2. **Line shunts are placed at terminal `Extr`.** They are included only when
|
|
187
|
+
their circuit is in service. Previously every `DBSH` record was assigned to
|
|
188
|
+
bus `I`.
|
|
189
|
+
3. **Zero-range generators are fixed-Q buses.** PV buses with
|
|
190
|
+
`Qgn = Qgm = 0` are blank ANAREDE limits written as zero, and their stored
|
|
191
|
+
`Qg` is 0. They are modeled as PQ buses at that output.
|
|
192
|
+
4. **`DGER Pgn` is minimum generation.** It is no longer added to the
|
|
193
|
+
scheduled generation in `DBAR`.
|
|
194
|
+
5. **`VLIM` applies only to ANAREDE type-3 buses.** These are PQ buses with
|
|
195
|
+
voltage limits. Converting every out-of-range PQ bus to PV conflicted with
|
|
196
|
+
generator Q limits.
|
|
197
|
+
6. **Transformer settings are reconciled with stored voltages.** Saved cases
|
|
198
|
+
contain solved voltages, but some LTCs keep pre-solution taps. For example,
|
|
199
|
+
the Sapeaçu 230/500 kV units around bus 6368 would otherwise create a
|
|
200
|
+
357 pu initial mismatch across a 0.05 % reactance. Each tap or phase-shift
|
|
201
|
+
group receives a one-variable least-squares correction against the P/Q
|
|
202
|
+
mismatch at its terminals. The solver applies it only when it removes most
|
|
203
|
+
of a significant mismatch.
|
|
204
|
+
|
|
205
|
+
## Newton-Raphson details
|
|
206
|
+
|
|
207
|
+
- **Low-impedance contraction:** Branches with `|z| <= 2e-4 pu` are contracted
|
|
208
|
+
with exact complex tap scaling.
|
|
209
|
+
- **Islands:** Every island without a reference bus receives one.
|
|
210
|
+
- **State variables:** The Newton state includes:
|
|
211
|
+
- bus angles and PQ voltage magnitudes;
|
|
212
|
+
- SVC outputs;
|
|
213
|
+
- LTC tap shifts (`DOPC CTAP`);
|
|
214
|
+
- phase-shifter angles (`DOPC CPHS`, `DCTR` records).
|
|
215
|
+
- **LTCs:** An LTC group regulates its controlled bus only after that voltage
|
|
216
|
+
leaves `Vsp ± TLTC` (`DCTE TLTC`). It then regulates to the band edge.
|
|
217
|
+
Groups that keep pushing against `Tmn/Tmx` are fixed at that limit.
|
|
218
|
+
Groups whose Newton step is non-physical (`|Δtap| > 0.2`) are fixed because
|
|
219
|
+
they lack an independent effect on their target, such as two LTCs regulating
|
|
220
|
+
electrically identical buses.
|
|
221
|
+
- **Phase shifters:** A phase shifter holds the active power leaving the
|
|
222
|
+
`Ext` terminal at `Vsp` MW, within `Fmin/Fmax`.
|
|
223
|
+
- **Step control:** Large control moves shorten the whole Newton step, which
|
|
224
|
+
keeps the search direction intact. The line search accepts a step that reduces
|
|
225
|
+
either the max-norm or the 2-norm of the mismatch.
|
|
226
|
+
- **Outer control passes:** These handle generator Q limits (`QLIM`), type-3
|
|
227
|
+
voltage limits (`VLIM`), LTC activation, LCC set-points, and switched shunts
|
|
228
|
+
(`STEP`).
|
|
229
|
+
- **Switched shunts:** These switch one bank unit per pass. A shunt that would
|
|
230
|
+
reverse direction is frozen to prevent hunting.
|
|
231
|
+
|
|
232
|
+
## Optimization AC power flow details
|
|
233
|
+
|
|
234
|
+
The NLP follows the o-grid paper's formulation:
|
|
235
|
+
|
|
236
|
+
- **Residuals:** Signed P/Q residual variables are bounded per bus and in
|
|
237
|
+
aggregate by the tolerance.
|
|
238
|
+
- **Objective:** It minimizes tolerance-normalized squared residuals and
|
|
239
|
+
includes a small regularization toward the initial state.
|
|
240
|
+
- **Fixed schedule:** Scheduled active generation remains fixed.
|
|
241
|
+
- **Voltage bounds:** Voltage magnitudes have only broad numerical bounds,
|
|
242
|
+
`[0.4, 2.0]` pu. Operating limits are separate from convergence.
|
|
243
|
+
- **Convergence check:** A run converges only when Ipopt terminates
|
|
244
|
+
acceptably and every P/Q mismatch and SVC control error recomputed from
|
|
245
|
+
`Ybus` and the solved voltages is within tolerance. Aggregate P and Q
|
|
246
|
+
mismatches must also be within tolerance. Ipopt's constraint tolerance is set
|
|
247
|
+
to `1e-9`.
|
|
248
|
+
- **SVC regions:** SVCs are modeled by operating region. A regulating SVC
|
|
249
|
+
follows its `P` or `I` droop law. A saturated SVC injects `Qlim·Vterminal²`.
|
|
250
|
+
After each NLP solve, region changes, generator Q limits, switched shunts,
|
|
251
|
+
and LCC set-points are updated, and the NLP is solved again. A saturated SVC
|
|
252
|
+
returns to regulation before it can switch to the opposite limit.
|
|
253
|
+
- **Warm start:** The default `warm_start=True` uses the Newton solution and
|
|
254
|
+
control state as the initial point, as recommended by the paper.
|
|
255
|
+
|
|
256
|
+
## SVC control modes
|
|
257
|
+
|
|
258
|
+
The `.dat` `DCER` records use `P` for reactive-power control and `I` for
|
|
259
|
+
current control:
|
|
260
|
+
|
|
261
|
+
- `P`: `Vcontrolled - Vreference + slope * Q = 0`
|
|
262
|
+
- `I`: `Vcontrolled - Vreference + slope * Q / Vdevice = 0`
|
|
263
|
+
|
|
264
|
+
`Vreference` is the `DBAR` voltage of the controlled bus. Capability limits
|
|
265
|
+
scale with the square of the SVC terminal voltage. Both solvers handle
|
|
266
|
+
saturation by switching SVC operating regions.
|
|
267
|
+
|
|
268
|
+
## Tests
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
python -m unittest discover -s tests
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The test suite covers parser behavior, SVC `P/I` modes and saturation, and LCC
|
|
275
|
+
commutation overlap. It also covers `DCSC` series and bypass branches,
|
|
276
|
+
line-shunt placement, the LTC dead band, phase-shifter flow control, shunt
|
|
277
|
+
anti-hunting, and SVC region switching in the NLP.
|
|
278
|
+
|
|
279
|
+
## Formatting and linting
|
|
280
|
+
|
|
281
|
+
[prek](https://github.com/j178/prek) runs the hooks in
|
|
282
|
+
`.pre-commit-config.yaml`:
|
|
283
|
+
|
|
284
|
+
- **Builtin file checks:** trailing whitespace, end-of-file, LF line endings,
|
|
285
|
+
TOML/YAML/JSON validity, JSON formatting, merge conflicts, private keys, and
|
|
286
|
+
large files.
|
|
287
|
+
- **Python:** `ruff check --fix` and `ruff format`, configured in
|
|
288
|
+
`pyproject.toml`.
|
|
289
|
+
- **TOML:** `taplo` format and lint.
|
|
290
|
+
- **Docs and configs:** `prettier` for Markdown, MDX, CSS, JS/TS, and YAML.
|
|
291
|
+
- **Spelling:** `typos`.
|
|
292
|
+
|
|
293
|
+
The `data/` cases are excluded, so they are never rewritten.
|
|
294
|
+
|
|
295
|
+
`prek run --all-files` only checks files that git already tracks. To run every
|
|
296
|
+
hook on all non-ignored files, tracked or not, use:
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
./scripts/prek-all.ps1
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
The script runs `prek run --files` on every file from
|
|
303
|
+
`git ls-files --cached --others --exclude-standard`. Extra arguments are passed
|
|
304
|
+
to prek; for example, `./scripts/prek-all.ps1 ruff-format` runs only that hook.
|
pf_tool-0.2.0/README.md
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# pf-tool
|
|
2
|
+
|
|
3
|
+
AC/DC power-flow solver for the Brazilian Interconnected Power System (BIPS): ANAREDE `.dat` data model, Newton-Raphson and optimization methods.
|
|
4
|
+
|
|
5
|
+
[](docs/) [](pyproject.toml) [](https://github.com/astral-sh/ruff) [](LICENSE.txt)
|
|
6
|
+
|
|
7
|
+
**pf-tool** is an AC/DC power-flow package for the Brazilian Interconnected
|
|
8
|
+
Power System (BIPS). It solves the ANAREDE-style `.dat` cases in `tests/data/`, which
|
|
9
|
+
are BIPS snapshots of about 12,600 buses each, with two AC power-flow methods:
|
|
10
|
+
|
|
11
|
+
- [`newton_raphson.py`](newton_raphson.py): `NewtonRaphsonPowerFlow`, a sparse
|
|
12
|
+
polar Newton-Raphson solver.
|
|
13
|
+
- [`optimization.py`](optimization.py): `OptimizationPowerFlow`, an
|
|
14
|
+
optimization-based AC power flow (Pyomo NLP solved with Ipopt), following the
|
|
15
|
+
formulation of the o-grid optimization ACPF paper.
|
|
16
|
+
|
|
17
|
+
Component models live in [`models/`](models/), and the `.dat` parser and case
|
|
18
|
+
assembly live in [`utils/`](utils/).
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
from newton_raphson import NewtonRaphsonPowerFlow
|
|
22
|
+
from optimization import OptimizationPowerFlow
|
|
23
|
+
|
|
24
|
+
newton = NewtonRaphsonPowerFlow("tests/data/CASO01-FLOW.dat").solve()
|
|
25
|
+
nlp = OptimizationPowerFlow("tests/data/CASO01-FLOW.dat", warm_start=True).solve()
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The optimization solver requires `pyomo` (see `requirements.txt`) and an Ipopt
|
|
29
|
+
executable on `PATH`.
|
|
30
|
+
|
|
31
|
+
### Documentation
|
|
32
|
+
|
|
33
|
+
Comprehensive [documentation](docs/) built with [Astro Starlight](https://starlight.astro.build/) documents:
|
|
34
|
+
|
|
35
|
+
- every data block and column;
|
|
36
|
+
- how each power-system component is modeled;
|
|
37
|
+
- the full Newton-Raphson algorithm;
|
|
38
|
+
- the full optimization formulation: sets, parameters, variables, expressions,
|
|
39
|
+
constraints, and objective.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
cd docs
|
|
43
|
+
npm install
|
|
44
|
+
npm run build # static site in docs/dist
|
|
45
|
+
npm run dev # local preview at http://localhost:4321
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Example scripts
|
|
49
|
+
|
|
50
|
+
[`examples/`](examples/) contains one minimal script per solver class. Each
|
|
51
|
+
script sets `data_file`, solves the case, prints the result, and exports the
|
|
52
|
+
solution with `ExportSolution` to `examples/results/`. To run another case,
|
|
53
|
+
change `data_file`.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
python examples/run_nr_powerflow.py
|
|
57
|
+
python examples/run_opt_powerflow.py
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Exporting results
|
|
61
|
+
|
|
62
|
+
`ExportSolution` (in [`exporter.py`](exporter.py)) writes every solved
|
|
63
|
+
component to an Excel workbook. It uses one sheet per component: Summary,
|
|
64
|
+
Buses, Generators, Loads, Lines, Transformers, LTC, PST, HVDC, SVC, CSC, and
|
|
65
|
+
Shunts.
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
from exporter import ExportSolution
|
|
69
|
+
|
|
70
|
+
solver = NewtonRaphsonPowerFlow("tests/data/CASO01-FLOW.dat")
|
|
71
|
+
solver.solve()
|
|
72
|
+
ExportSolution(solver, output_path="results/CASO01-FLOW-nr.xlsx")
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Flows on branches collapsed by the zero-impedance reduction, such as switches
|
|
76
|
+
and bypassed CSCs, are recovered from Kirchhoff's current law in each reduced
|
|
77
|
+
node. In the exported solution, every bus balances to within 3e-5 MVA.
|
|
78
|
+
|
|
79
|
+
## Convergence summary
|
|
80
|
+
|
|
81
|
+
All 11 cases converge with every method.
|
|
82
|
+
|
|
83
|
+
| Method | Cases converged | Mean time per case (s) | Total time (s) |
|
|
84
|
+
| ------------------------------- | --------------: | ---------------------: | -------------: |
|
|
85
|
+
| Newton-Raphson | 11 / 11 | 2.8 | 31.0 |
|
|
86
|
+
| Optimization, Newton warm start | 11 / 11 | 10.2 | 112.5 |
|
|
87
|
+
| Optimization, cold start | 11 / 11 | 37.6 | 413.6 |
|
|
88
|
+
|
|
89
|
+
Measurement details:
|
|
90
|
+
|
|
91
|
+
- Tolerance is `TEPA / BASE = 1e-4 pu` from each case's `DCTE` block.
|
|
92
|
+
- Newton's iteration limit is `ACIT`.
|
|
93
|
+
- Elapsed time includes parsing, case construction, network reduction, and all
|
|
94
|
+
control passes.
|
|
95
|
+
- Runs used Windows, Python 3.12, Pyomo 6.10.1, and Ipopt 3.12.13.
|
|
96
|
+
- `Median / p99 dV` is the median and 99th-percentile absolute difference from
|
|
97
|
+
the bus voltages stored in each `.dat` file, which are the ANAREDE solution.
|
|
98
|
+
|
|
99
|
+
The lowest voltages, about 0.74–0.83 pu, occur at low-voltage SVC terminal
|
|
100
|
+
buses. ANAREDE's stored voltages are similarly low there; for example, bus
|
|
101
|
+
7035 is stored at 0.734 pu.
|
|
102
|
+
|
|
103
|
+
### Newton-Raphson
|
|
104
|
+
|
|
105
|
+
| Case | Buses | Converged | Iterations | Final max mismatch (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
106
|
+
| --------------- | ----: | --------: | ---------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
107
|
+
| CASO01-FLOW.dat | 12579 | Yes | 19 | 9.7e-07 | 2.7 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
108
|
+
| CASO02-FLOW.dat | 12579 | Yes | 15 | 6.0e-06 | 2.8 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
109
|
+
| CASO03-FLOW.dat | 12579 | Yes | 18 | 9.4e-07 | 3.2 | 0.755–1.165 | 0.0008 / 0.0077 |
|
|
110
|
+
| CASO04-FLOW.dat | 12572 | Yes | 11 | 2.6e-07 | 2.5 | 0.751–1.143 | 0.0005 / 0.0098 |
|
|
111
|
+
| CASO05-FLOW.dat | 12578 | Yes | 12 | 5.9e-06 | 2.7 | 0.760–1.120 | 0.0012 / 0.0100 |
|
|
112
|
+
| CASO06-FLOW.dat | 12613 | Yes | 12 | 2.0e-06 | 2.7 | 0.752–1.182 | 0.0009 / 0.0100 |
|
|
113
|
+
| CASO07-FLOW.dat | 12613 | Yes | 12 | 2.0e-06 | 2.7 | 0.742–1.166 | 0.0010 / 0.0093 |
|
|
114
|
+
| CASO08-FLOW.dat | 12613 | Yes | 19 | 3.2e-06 | 2.9 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
115
|
+
| CASO09-FLOW.dat | 12607 | Yes | 16 | 2.7e-07 | 2.7 | 0.764–1.131 | 0.0007 / 0.0101 |
|
|
116
|
+
| CASO10-FLOW.dat | 12611 | Yes | 17 | 2.0e-06 | 2.8 | 0.745–1.267 | 0.0010 / 0.0096 |
|
|
117
|
+
| CASO11-FLOW.dat | 12613 | Yes | 16 | 2.0e-06 | 3.1 | 0.827–1.121 | 0.0007 / 0.0098 |
|
|
118
|
+
|
|
119
|
+
Iterations are totals across all outer control passes.
|
|
120
|
+
|
|
121
|
+
### Optimization AC power flow (Newton warm start)
|
|
122
|
+
|
|
123
|
+
| Case | Converged | NLP solves | Ipopt iterations | Final max residual (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
124
|
+
| --------------- | --------: | ---------: | ---------------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
125
|
+
| CASO01-FLOW.dat | Yes | 1 | 7 (+19 Newton) | 4.5e-12 | 9.5 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
126
|
+
| CASO02-FLOW.dat | Yes | 1 | 8 (+15 Newton) | 3.4e-12 | 10.2 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
127
|
+
| CASO03-FLOW.dat | Yes | 1 | 7 (+18 Newton) | 9.6e-11 | 11.0 | 0.755–1.165 | 0.0008 / 0.0077 |
|
|
128
|
+
| CASO04-FLOW.dat | Yes | 1 | 7 (+11 Newton) | 4.5e-12 | 9.9 | 0.751–1.143 | 0.0005 / 0.0098 |
|
|
129
|
+
| CASO05-FLOW.dat | Yes | 1 | 8 (+12 Newton) | 5.5e-12 | 10.5 | 0.760–1.120 | 0.0012 / 0.0100 |
|
|
130
|
+
| CASO06-FLOW.dat | Yes | 1 | 7 (+12 Newton) | 1.2e-11 | 9.8 | 0.752–1.182 | 0.0009 / 0.0100 |
|
|
131
|
+
| CASO07-FLOW.dat | Yes | 1 | 7 (+12 Newton) | 1.3e-11 | 9.8 | 0.742–1.166 | 0.0010 / 0.0093 |
|
|
132
|
+
| CASO08-FLOW.dat | Yes | 1 | 8 (+19 Newton) | 3.3e-12 | 10.6 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
133
|
+
| CASO09-FLOW.dat | Yes | 1 | 8 (+16 Newton) | 1.9e-12 | 10.3 | 0.764–1.131 | 0.0007 / 0.0101 |
|
|
134
|
+
| CASO10-FLOW.dat | Yes | 1 | 7 (+17 Newton) | 3.2e-12 | 10.2 | 0.745–1.267 | 0.0010 / 0.0096 |
|
|
135
|
+
| CASO11-FLOW.dat | Yes | 1 | 7 (+16 Newton) | 4.3e-12 | 10.7 | 0.827–1.121 | 0.0007 / 0.0098 |
|
|
136
|
+
|
|
137
|
+
### Optimization AC power flow (cold start)
|
|
138
|
+
|
|
139
|
+
`warm_start=False` starts the NLP from the stored voltages. Before the first
|
|
140
|
+
solve, it reconciles transformer settings with those voltages; see
|
|
141
|
+
"Transformers" below.
|
|
142
|
+
|
|
143
|
+
| Case | Converged | NLP solves | Ipopt iterations | Final max residual (pu) | Elapsed (s) | Voltage range (pu) | Median / p99 dV (pu) |
|
|
144
|
+
| --------------- | --------: | ---------: | ---------------: | ----------------------: | ----------: | -----------------: | -------------------: |
|
|
145
|
+
| CASO01-FLOW.dat | Yes | 6 | 49 | 7.6e-12 | 43.9 | 0.777–1.175 | 0.0008 / 0.0083 |
|
|
146
|
+
| CASO02-FLOW.dat | Yes | 6 | 47 | 4.0e-12 | 42.5 | 0.785–1.198 | 0.0008 / 0.0050 |
|
|
147
|
+
| CASO03-FLOW.dat | Yes | 6 | 48 | 5.1e-11 | 42.9 | 0.755–1.165 | 0.0008 / 0.0078 |
|
|
148
|
+
| CASO04-FLOW.dat | Yes | 5 | 40 | 5.2e-12 | 35.4 | 0.751–1.143 | 0.0005 / 0.0112 |
|
|
149
|
+
| CASO05-FLOW.dat | Yes | 5 | 42 | 3.9e-12 | 35.9 | 0.760–1.120 | 0.0012 / 0.0161 |
|
|
150
|
+
| CASO06-FLOW.dat | Yes | 5 | 44 | 7.8e-12 | 35.6 | 0.752–1.182 | 0.0009 / 0.0110 |
|
|
151
|
+
| CASO07-FLOW.dat | Yes | 5 | 40 | 8.3e-12 | 35.3 | 0.742–1.164 | 0.0010 / 0.0102 |
|
|
152
|
+
| CASO08-FLOW.dat | Yes | 5 | 44 | 1.0e-11 | 36.0 | 0.746–1.165 | 0.0016 / 0.0090 |
|
|
153
|
+
| CASO09-FLOW.dat | Yes | 5 | 42 | 6.1e-11 | 35.5 | 0.764–1.133 | 0.0007 / 0.0116 |
|
|
154
|
+
| CASO10-FLOW.dat | Yes | 5 | 39 | 1.3e-11 | 35.2 | 0.745–1.267 | 0.0009 / 0.0109 |
|
|
155
|
+
| CASO11-FLOW.dat | Yes | 5 | 40 | 4.0e-12 | 35.5 | 0.827–1.204 | 0.0008 / 0.0109 |
|
|
156
|
+
|
|
157
|
+
The cold-start NLP does not include LTC voltage regulation. Its solutions are
|
|
158
|
+
therefore slightly farther from ANAREDE than the Newton and warm-start results,
|
|
159
|
+
with a larger p99 voltage difference.
|
|
160
|
+
|
|
161
|
+
## What made the cases converge
|
|
162
|
+
|
|
163
|
+
The earlier non-convergence came mainly from network-data errors, not from
|
|
164
|
+
solver tuning. With the corrected model, both methods reach the ANAREDE
|
|
165
|
+
operating point.
|
|
166
|
+
|
|
167
|
+
1. **`DCSC` series compensators are standalone circuits.** All 126 `DCSC`
|
|
168
|
+
records describe their own `I–J` circuit, and none duplicates a `DLIN` line.
|
|
169
|
+
The previous builder dropped them, removing series-compensated corridors such
|
|
170
|
+
as Itaipu 765 kV and the Mato Grosso 500 kV lines. Active compensators now
|
|
171
|
+
use reactance `Xv` (%), and bypassed ones (`Byp = "L"`) are shorts that the
|
|
172
|
+
network reduction contracts.
|
|
173
|
+
2. **Line shunts are placed at terminal `Extr`.** They are included only when
|
|
174
|
+
their circuit is in service. Previously every `DBSH` record was assigned to
|
|
175
|
+
bus `I`.
|
|
176
|
+
3. **Zero-range generators are fixed-Q buses.** PV buses with
|
|
177
|
+
`Qgn = Qgm = 0` are blank ANAREDE limits written as zero, and their stored
|
|
178
|
+
`Qg` is 0. They are modeled as PQ buses at that output.
|
|
179
|
+
4. **`DGER Pgn` is minimum generation.** It is no longer added to the
|
|
180
|
+
scheduled generation in `DBAR`.
|
|
181
|
+
5. **`VLIM` applies only to ANAREDE type-3 buses.** These are PQ buses with
|
|
182
|
+
voltage limits. Converting every out-of-range PQ bus to PV conflicted with
|
|
183
|
+
generator Q limits.
|
|
184
|
+
6. **Transformer settings are reconciled with stored voltages.** Saved cases
|
|
185
|
+
contain solved voltages, but some LTCs keep pre-solution taps. For example,
|
|
186
|
+
the Sapeaçu 230/500 kV units around bus 6368 would otherwise create a
|
|
187
|
+
357 pu initial mismatch across a 0.05 % reactance. Each tap or phase-shift
|
|
188
|
+
group receives a one-variable least-squares correction against the P/Q
|
|
189
|
+
mismatch at its terminals. The solver applies it only when it removes most
|
|
190
|
+
of a significant mismatch.
|
|
191
|
+
|
|
192
|
+
## Newton-Raphson details
|
|
193
|
+
|
|
194
|
+
- **Low-impedance contraction:** Branches with `|z| <= 2e-4 pu` are contracted
|
|
195
|
+
with exact complex tap scaling.
|
|
196
|
+
- **Islands:** Every island without a reference bus receives one.
|
|
197
|
+
- **State variables:** The Newton state includes:
|
|
198
|
+
- bus angles and PQ voltage magnitudes;
|
|
199
|
+
- SVC outputs;
|
|
200
|
+
- LTC tap shifts (`DOPC CTAP`);
|
|
201
|
+
- phase-shifter angles (`DOPC CPHS`, `DCTR` records).
|
|
202
|
+
- **LTCs:** An LTC group regulates its controlled bus only after that voltage
|
|
203
|
+
leaves `Vsp ± TLTC` (`DCTE TLTC`). It then regulates to the band edge.
|
|
204
|
+
Groups that keep pushing against `Tmn/Tmx` are fixed at that limit.
|
|
205
|
+
Groups whose Newton step is non-physical (`|Δtap| > 0.2`) are fixed because
|
|
206
|
+
they lack an independent effect on their target, such as two LTCs regulating
|
|
207
|
+
electrically identical buses.
|
|
208
|
+
- **Phase shifters:** A phase shifter holds the active power leaving the
|
|
209
|
+
`Ext` terminal at `Vsp` MW, within `Fmin/Fmax`.
|
|
210
|
+
- **Step control:** Large control moves shorten the whole Newton step, which
|
|
211
|
+
keeps the search direction intact. The line search accepts a step that reduces
|
|
212
|
+
either the max-norm or the 2-norm of the mismatch.
|
|
213
|
+
- **Outer control passes:** These handle generator Q limits (`QLIM`), type-3
|
|
214
|
+
voltage limits (`VLIM`), LTC activation, LCC set-points, and switched shunts
|
|
215
|
+
(`STEP`).
|
|
216
|
+
- **Switched shunts:** These switch one bank unit per pass. A shunt that would
|
|
217
|
+
reverse direction is frozen to prevent hunting.
|
|
218
|
+
|
|
219
|
+
## Optimization AC power flow details
|
|
220
|
+
|
|
221
|
+
The NLP follows the o-grid paper's formulation:
|
|
222
|
+
|
|
223
|
+
- **Residuals:** Signed P/Q residual variables are bounded per bus and in
|
|
224
|
+
aggregate by the tolerance.
|
|
225
|
+
- **Objective:** It minimizes tolerance-normalized squared residuals and
|
|
226
|
+
includes a small regularization toward the initial state.
|
|
227
|
+
- **Fixed schedule:** Scheduled active generation remains fixed.
|
|
228
|
+
- **Voltage bounds:** Voltage magnitudes have only broad numerical bounds,
|
|
229
|
+
`[0.4, 2.0]` pu. Operating limits are separate from convergence.
|
|
230
|
+
- **Convergence check:** A run converges only when Ipopt terminates
|
|
231
|
+
acceptably and every P/Q mismatch and SVC control error recomputed from
|
|
232
|
+
`Ybus` and the solved voltages is within tolerance. Aggregate P and Q
|
|
233
|
+
mismatches must also be within tolerance. Ipopt's constraint tolerance is set
|
|
234
|
+
to `1e-9`.
|
|
235
|
+
- **SVC regions:** SVCs are modeled by operating region. A regulating SVC
|
|
236
|
+
follows its `P` or `I` droop law. A saturated SVC injects `Qlim·Vterminal²`.
|
|
237
|
+
After each NLP solve, region changes, generator Q limits, switched shunts,
|
|
238
|
+
and LCC set-points are updated, and the NLP is solved again. A saturated SVC
|
|
239
|
+
returns to regulation before it can switch to the opposite limit.
|
|
240
|
+
- **Warm start:** The default `warm_start=True` uses the Newton solution and
|
|
241
|
+
control state as the initial point, as recommended by the paper.
|
|
242
|
+
|
|
243
|
+
## SVC control modes
|
|
244
|
+
|
|
245
|
+
The `.dat` `DCER` records use `P` for reactive-power control and `I` for
|
|
246
|
+
current control:
|
|
247
|
+
|
|
248
|
+
- `P`: `Vcontrolled - Vreference + slope * Q = 0`
|
|
249
|
+
- `I`: `Vcontrolled - Vreference + slope * Q / Vdevice = 0`
|
|
250
|
+
|
|
251
|
+
`Vreference` is the `DBAR` voltage of the controlled bus. Capability limits
|
|
252
|
+
scale with the square of the SVC terminal voltage. Both solvers handle
|
|
253
|
+
saturation by switching SVC operating regions.
|
|
254
|
+
|
|
255
|
+
## Tests
|
|
256
|
+
|
|
257
|
+
```
|
|
258
|
+
python -m unittest discover -s tests
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The test suite covers parser behavior, SVC `P/I` modes and saturation, and LCC
|
|
262
|
+
commutation overlap. It also covers `DCSC` series and bypass branches,
|
|
263
|
+
line-shunt placement, the LTC dead band, phase-shifter flow control, shunt
|
|
264
|
+
anti-hunting, and SVC region switching in the NLP.
|
|
265
|
+
|
|
266
|
+
## Formatting and linting
|
|
267
|
+
|
|
268
|
+
[prek](https://github.com/j178/prek) runs the hooks in
|
|
269
|
+
`.pre-commit-config.yaml`:
|
|
270
|
+
|
|
271
|
+
- **Builtin file checks:** trailing whitespace, end-of-file, LF line endings,
|
|
272
|
+
TOML/YAML/JSON validity, JSON formatting, merge conflicts, private keys, and
|
|
273
|
+
large files.
|
|
274
|
+
- **Python:** `ruff check --fix` and `ruff format`, configured in
|
|
275
|
+
`pyproject.toml`.
|
|
276
|
+
- **TOML:** `taplo` format and lint.
|
|
277
|
+
- **Docs and configs:** `prettier` for Markdown, MDX, CSS, JS/TS, and YAML.
|
|
278
|
+
- **Spelling:** `typos`.
|
|
279
|
+
|
|
280
|
+
The `data/` cases are excluded, so they are never rewritten.
|
|
281
|
+
|
|
282
|
+
`prek run --all-files` only checks files that git already tracks. To run every
|
|
283
|
+
hook on all non-ignored files, tracked or not, use:
|
|
284
|
+
|
|
285
|
+
```
|
|
286
|
+
./scripts/prek-all.ps1
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
The script runs `prek run --files` on every file from
|
|
290
|
+
`git ls-files --cached --others --exclude-standard`. Extra arguments are passed
|
|
291
|
+
to prek; for example, `./scripts/prek-all.ps1 ruff-format` runs only that hook.
|