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.
@@ -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](https://img.shields.io/badge/docs-guides-0079c2?style=flat-square)](docs/) [![Python 3.12+](https://img.shields.io/badge/Python-3.12+-3776ab?logo=python&logoColor=white)](pyproject.toml) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![BSD 3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](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.
@@ -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](https://img.shields.io/badge/docs-guides-0079c2?style=flat-square)](docs/) [![Python 3.12+](https://img.shields.io/badge/Python-3.12+-3776ab?logo=python&logoColor=white)](pyproject.toml) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![BSD 3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](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.