mambo-power 0.1.0__tar.gz

mambo_power-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.cache/
+site/
+.env
+.env.*
+
+# Windows/git-bash crash dumps and local tool state — recur in the main checkout each wave
+# (M3, M4 and M5 each swept these by hand; M4's continuation record asked for this entry).
+*.stackdump
+.playwright-cli/

mambo_power-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manho Joung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mambo_power-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: mambo-power
+Version: 0.1.0
+Summary: Fundamental Python package for power system analysis and electricity market modelling
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: highspy
+Requires-Dist: numpy
+Requires-Dist: pydantic>=2
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# mambo-power
+
+A fundamental Python package for power system analysis and electricity market modelling.
+It owns its network data model and implements its own solvers on numpy, scipy and HiGHS;
+pandapower and PyPSA serve only as test oracles.
+
+Documentation: **https://mambo10005.github.io/mambo-power/**
+
+## What it is
+
+- A JSON-native network model (pydantic v2): `Network` with buses, branches, generators
+  (with cost curves), loads, shunts, storage and zones; physical units, stable string ids,
+  all-issues validation with named error codes, JSON schema generated from the model.
+- Importers that speak only the model: MATPOWER `.m` cases and the native JSON format, plus
+  pandapower JSON, PyPSA, PSS/E RAW and CSV bundles.
+- Network matrices over scipy.sparse: `NetworkArrays` (the single per-unit conversion site),
+  Ybus, Bbus, PTDF, LODF with bridge detection.
+- Solvers: DC power flow and AC Newton-Raphson with Q-limit enforcement; DC optimal power flow
+  with duals on HiGHS; N-1 contingency screening; market clearing (nodal LMP, multiperiod with
+  storage, zonal with redispatch, agent-based bidding).
+- Typed, id-keyed results stamped with provenance (engine version, solver, timings), never
+  stored on the network; a stateless, JSON-serialisable `jobs.run(SolveRequest)` surface
+  designed to sit behind a service.
+- Narrative tutorial notebooks (execution-tested in CI), an automated changelog, and PyPI
+  trusted publishing.
+
+Free in both senses: an open-source stack end to end with no paid solvers or licences, and
+built, tested, documented and published entirely on free infrastructure (GitHub Actions,
+GitHub Pages, PyPI trusted publishing).
+
+## Status
+
+| Wave | Scope | State |
+| --- | --- | --- |
+| M1 | Installable package, `Network` model, MATPOWER import, Ybus/Bbus/PTDF/LODF, CI matrix | merged |
+| M2 | DC + AC Newton-Raphson power flow, typed results, `jobs` API, docs site, examples | merged |
+| M3 | DC optimal power flow with duals on HiGHS, N-1 branch-contingency screening | merged |
+| M4 | Nodal market: elastic-demand DC-OPF, LMP clearing, settlement | merged |
+| M5 | Multiperiod market: 24-period horizon, ramp coupling, storage SoC, per-period settlement | merged |
+| M6 | Zonal market: zonal clearing, min-cost redispatch, nodal-vs-zonal comparison | merged |
+| M7 | Agent-based bidding: strategies, offered-vs-true cost overlay, fixed-point loop | merged |
+| M8 | Interchange: pandapower JSON, PyPSA, PSS/E RAW, CSV bundle | merged |
+| M9 | Tutorials, semantic-release changelog, PyPI 0.1.0 trusted publishing | merged |
+
+Not yet on PyPI — this changes in the same action as the `v0.1.0` tag; see
+[Getting started](https://mambo10005.github.io/mambo-power/getting-started/) for the current
+install instructions, which is the live source of truth if this file is ever stale (this table
+is not covered by any automated freshness check — see the wave M9 continuation record if you're
+reading this after a release and it still says otherwise). Runtime dependencies are exactly
+`numpy`, `scipy`, `highspy`, `pydantic`; Python 3.11 or newer.
+
+## Install from source
+
+```bash
+git clone https://github.com/mambo10005/mambo-power.git
+cd mambo-power
+uv sync                    # runtime deps only; add --all-groups for dev + docs tooling
+```
+
+Without [uv](https://docs.astral.sh/uv/): `pip install -e .` in any Python >= 3.11 environment.
+
+## Quick start
+
+```python
+from mambo_power import pf
+from mambo_power.io import matpower
+
+net = matpower.load("fixtures/matpower/case14.m")  # validated Network, physical units
+result = pf.solve_dc(net)  # typed result keyed by ids, MW
+print(result.generators[0].p_mw)  # 219.0 -- slack generator balance
+print(result.branches[0].p_from_mw)  # 147.84 -- flow bus-1 -> bus-2
+print(result.provenance.version, result.provenance.solver)
+text = result.model_dump_json()  # exact JSON round-trip
+again = type(result).model_validate_json(text)
+assert again == result
+```
+
+Then: [Getting started](https://mambo10005.github.io/mambo-power/getting-started/) walks
+through loading, validating, solving and reading results with real output.
+
+## Tutorials and manual
+
+[Tutorials](https://mambo10005.github.io/mambo-power/tutorials/) are prose-heavy, narrative
+walkthroughs (a first power flow, DC-OPF + N-1, a nodal market, where to go next) — start there
+if you're new. The manual is the reference:
+
+- [Network model](https://mambo10005.github.io/mambo-power/manual/model/) — every entity,
+  field, unit, and validation code
+- [File formats](https://mambo10005.github.io/mambo-power/manual/formats/) — native JSON,
+  MATPOWER, pandapower JSON, PyPSA, PSS/E RAW, CSV bundles
+- [Numerics](https://mambo10005.github.io/mambo-power/manual/numerics/) — `NetworkArrays`,
+  Ybus, Bbus, PTDF, LODF and bridges
+- [Power flow](https://mambo10005.github.io/mambo-power/manual/power-flow/) — the DC
+  formulation and the AC solver's contract
+- [DC-OPF](https://mambo10005.github.io/mambo-power/manual/opf/) and
+  [N-1 screening](https://mambo10005.github.io/mambo-power/manual/n1/)
+- Market clearing: [nodal](https://mambo10005.github.io/mambo-power/manual/market/),
+  [multiperiod](https://mambo10005.github.io/mambo-power/manual/multiperiod/),
+  [zonal](https://mambo10005.github.io/mambo-power/manual/zonal/)
+- [Agent-based bidding](https://mambo10005.github.io/mambo-power/manual/agents/) — strategies,
+  offered-vs-true cost, the fixed-point loop
+- [Results](https://mambo10005.github.io/mambo-power/manual/results/) — result tables,
+  provenance, JSON round-trip, `to_arrays()`
+- [Jobs API](https://mambo10005.github.io/mambo-power/manual/jobs/) — the stateless
+  `SolveRequest` / `SolveResult` surface
+- [API reference](https://mambo10005.github.io/mambo-power/api/model/),
+  [Design](https://mambo10005.github.io/mambo-power/design/architecture/),
+  [Changelog](https://mambo10005.github.io/mambo-power/changelog/),
+  [Contributing](https://mambo10005.github.io/mambo-power/contributing/)
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                      # tiers: -m unit | parity | property
+uv run mkdocs serve                # docs at http://127.0.0.1:8000
+```
+
+Tests are tiered (`tests/unit`, `tests/parity` against pandapower/PyPSA/MATPOWER,
+`tests/property` with hypothesis). Every public symbol must carry a docstring; a unit test
+enforces it. The docs build with `mkdocs build --strict` in CI and deploy to GitHub Pages on
+pushes to `epic/01-foundation` and `main`.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Bundled MATPOWER cases under `fixtures/matpower/` are public
+IEEE test data as distributed by MATPOWER; see `fixtures/matpower/PROVENANCE.md`.

mambo_power-0.1.0/README.md

@@ -0,0 +1,128 @@
+# mambo-power
+
+A fundamental Python package for power system analysis and electricity market modelling.
+It owns its network data model and implements its own solvers on numpy, scipy and HiGHS;
+pandapower and PyPSA serve only as test oracles.
+
+Documentation: **https://mambo10005.github.io/mambo-power/**
+
+## What it is
+
+- A JSON-native network model (pydantic v2): `Network` with buses, branches, generators
+  (with cost curves), loads, shunts, storage and zones; physical units, stable string ids,
+  all-issues validation with named error codes, JSON schema generated from the model.
+- Importers that speak only the model: MATPOWER `.m` cases and the native JSON format, plus
+  pandapower JSON, PyPSA, PSS/E RAW and CSV bundles.
+- Network matrices over scipy.sparse: `NetworkArrays` (the single per-unit conversion site),
+  Ybus, Bbus, PTDF, LODF with bridge detection.
+- Solvers: DC power flow and AC Newton-Raphson with Q-limit enforcement; DC optimal power flow
+  with duals on HiGHS; N-1 contingency screening; market clearing (nodal LMP, multiperiod with
+  storage, zonal with redispatch, agent-based bidding).
+- Typed, id-keyed results stamped with provenance (engine version, solver, timings), never
+  stored on the network; a stateless, JSON-serialisable `jobs.run(SolveRequest)` surface
+  designed to sit behind a service.
+- Narrative tutorial notebooks (execution-tested in CI), an automated changelog, and PyPI
+  trusted publishing.
+
+Free in both senses: an open-source stack end to end with no paid solvers or licences, and
+built, tested, documented and published entirely on free infrastructure (GitHub Actions,
+GitHub Pages, PyPI trusted publishing).
+
+## Status
+
+| Wave | Scope | State |
+| --- | --- | --- |
+| M1 | Installable package, `Network` model, MATPOWER import, Ybus/Bbus/PTDF/LODF, CI matrix | merged |
+| M2 | DC + AC Newton-Raphson power flow, typed results, `jobs` API, docs site, examples | merged |
+| M3 | DC optimal power flow with duals on HiGHS, N-1 branch-contingency screening | merged |
+| M4 | Nodal market: elastic-demand DC-OPF, LMP clearing, settlement | merged |
+| M5 | Multiperiod market: 24-period horizon, ramp coupling, storage SoC, per-period settlement | merged |
+| M6 | Zonal market: zonal clearing, min-cost redispatch, nodal-vs-zonal comparison | merged |
+| M7 | Agent-based bidding: strategies, offered-vs-true cost overlay, fixed-point loop | merged |
+| M8 | Interchange: pandapower JSON, PyPSA, PSS/E RAW, CSV bundle | merged |
+| M9 | Tutorials, semantic-release changelog, PyPI 0.1.0 trusted publishing | merged |
+
+Not yet on PyPI — this changes in the same action as the `v0.1.0` tag; see
+[Getting started](https://mambo10005.github.io/mambo-power/getting-started/) for the current
+install instructions, which is the live source of truth if this file is ever stale (this table
+is not covered by any automated freshness check — see the wave M9 continuation record if you're
+reading this after a release and it still says otherwise). Runtime dependencies are exactly
+`numpy`, `scipy`, `highspy`, `pydantic`; Python 3.11 or newer.
+
+## Install from source
+
+```bash
+git clone https://github.com/mambo10005/mambo-power.git
+cd mambo-power
+uv sync                    # runtime deps only; add --all-groups for dev + docs tooling
+```
+
+Without [uv](https://docs.astral.sh/uv/): `pip install -e .` in any Python >= 3.11 environment.
+
+## Quick start
+
+```python
+from mambo_power import pf
+from mambo_power.io import matpower
+
+net = matpower.load("fixtures/matpower/case14.m")  # validated Network, physical units
+result = pf.solve_dc(net)  # typed result keyed by ids, MW
+print(result.generators[0].p_mw)  # 219.0 -- slack generator balance
+print(result.branches[0].p_from_mw)  # 147.84 -- flow bus-1 -> bus-2
+print(result.provenance.version, result.provenance.solver)
+text = result.model_dump_json()  # exact JSON round-trip
+again = type(result).model_validate_json(text)
+assert again == result
+```
+
+Then: [Getting started](https://mambo10005.github.io/mambo-power/getting-started/) walks
+through loading, validating, solving and reading results with real output.
+
+## Tutorials and manual
+
+[Tutorials](https://mambo10005.github.io/mambo-power/tutorials/) are prose-heavy, narrative
+walkthroughs (a first power flow, DC-OPF + N-1, a nodal market, where to go next) — start there
+if you're new. The manual is the reference:
+
+- [Network model](https://mambo10005.github.io/mambo-power/manual/model/) — every entity,
+  field, unit, and validation code
+- [File formats](https://mambo10005.github.io/mambo-power/manual/formats/) — native JSON,
+  MATPOWER, pandapower JSON, PyPSA, PSS/E RAW, CSV bundles
+- [Numerics](https://mambo10005.github.io/mambo-power/manual/numerics/) — `NetworkArrays`,
+  Ybus, Bbus, PTDF, LODF and bridges
+- [Power flow](https://mambo10005.github.io/mambo-power/manual/power-flow/) — the DC
+  formulation and the AC solver's contract
+- [DC-OPF](https://mambo10005.github.io/mambo-power/manual/opf/) and
+  [N-1 screening](https://mambo10005.github.io/mambo-power/manual/n1/)
+- Market clearing: [nodal](https://mambo10005.github.io/mambo-power/manual/market/),
+  [multiperiod](https://mambo10005.github.io/mambo-power/manual/multiperiod/),
+  [zonal](https://mambo10005.github.io/mambo-power/manual/zonal/)
+- [Agent-based bidding](https://mambo10005.github.io/mambo-power/manual/agents/) — strategies,
+  offered-vs-true cost, the fixed-point loop
+- [Results](https://mambo10005.github.io/mambo-power/manual/results/) — result tables,
+  provenance, JSON round-trip, `to_arrays()`
+- [Jobs API](https://mambo10005.github.io/mambo-power/manual/jobs/) — the stateless
+  `SolveRequest` / `SolveResult` surface
+- [API reference](https://mambo10005.github.io/mambo-power/api/model/),
+  [Design](https://mambo10005.github.io/mambo-power/design/architecture/),
+  [Changelog](https://mambo10005.github.io/mambo-power/changelog/),
+  [Contributing](https://mambo10005.github.io/mambo-power/contributing/)
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                      # tiers: -m unit | parity | property
+uv run mkdocs serve                # docs at http://127.0.0.1:8000
+```
+
+Tests are tiered (`tests/unit`, `tests/parity` against pandapower/PyPSA/MATPOWER,
+`tests/property` with hypothesis). Every public symbol must carry a docstring; a unit test
+enforces it. The docs build with `mkdocs build --strict` in CI and deploy to GitHub Pages on
+pushes to `epic/01-foundation` and `main`.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Bundled MATPOWER cases under `fixtures/matpower/` are public
+IEEE test data as distributed by MATPOWER; see `fixtures/matpower/PROVENANCE.md`.

mambo_power-0.1.0/fixtures/PROVENANCE-raw.md

@@ -0,0 +1,242 @@
+# PSS/E RAW v33 fixtures — provenance and hand derivations (M8 W4, AC-4)
+
+Two hand-authored files, both NOT upstream bytes and both consumed only by
+`tests/unit/test_io_psse_raw.py` through `mambo_power.io.psse_raw`. Neither
+carries a reference power-flow solution. The record layouts follow the v33
+field order recorded in `.bionic/docs/record/m8-research.md` §3 (from
+grg-pssedata `struct.py`, BSD-3, and MATPOWER `psse_convert.m` /
+`psse_convert_xfmr.m`, BSD-3); no upstream RAW file was copied (the only
+public IEEE-14 RAW found carries no detectable licence — spec "Rejected
+alternatives").
+
+Layout common to both: line 1 `IC, SBASE, REV, XFRRAT, NXFRAT, BASFRQ`
+(`IC=0`, `REV=33`), two title lines, then the sections in v33 order — bus,
+load, fixed shunt, generator, non-transformer branch, transformer, area,
+two-terminal DC, VSC DC, impedance correction, multi-terminal DC,
+multi-section line, zone, inter-area transfer, owner, FACTS, switched shunt,
+GNE, induction machine — each closed by a line whose first field is `0`, and
+`Q` at the end. Text after `/` outside quotes is a comment.
+
+## case14_v33.raw — transcription of `matpower/case14.m`
+
+Authored 2026-08-29 field by field from `fixtures/matpower/case14.m` (the
+verbatim MATPOWER file; its own provenance is in `fixtures/matpower/PROVENANCE.md`).
+`io.psse_raw.load(case14_v33.raw)` must equal `io.matpower.load(case14.m)` on
+every bus, branch (including `kind`), generator-limit and load field to 1e-9
+(AC-4). Every field of every record is one of: a `case14.m` cell (mapping
+below), a v33 default that the importer ignores, or a derived id.
+
+### Bus records (14) — `mpc.bus` row → bus record
+
+| RAW field | source | unit |
+| --- | --- | --- |
+| `I` | `BUS_I` | — |
+| `NAME` | `mpc.bus_name` row (informational; the model has no bus name) | — |
+| `BASKV` | `BASE_KV` = **0** in `case14.m` (CDF "unknown"); kept as 0 so that both importers apply the same `BASE_KV_REPLACED` repair to 1.0 — writing 138 kV would make `base_kv` differ from the `.m` import | kV |
+| `IDE` | `BUS_TYPE` (3 slack, 2 PV, 1 PQ) — same code table | — |
+| `AREA`, `ZONE` | `AREA`, `ZONE` (all 1) | — |
+| `OWNER` | 1 (default; ignored) | — |
+| `VM`, `VA` | `VM`, `VA` | pu, deg |
+| `NVHI`, `NVLO` | `VMAX`, `VMIN` (1.06 / 0.94) | pu |
+| `EVHI`, `EVLO` | copies of `VMAX`, `VMIN` (ignored by the importer) | pu |
+
+### Load records (11) — `PD`/`QD` of each bus row with a non-zero pair
+
+`I` = `BUS_I`, `ID` = `'1 '`, `STATUS` = 1, `AREA`/`ZONE` = the bus's,
+`PL` = `PD` (MW), `QL` = `QD` (MVAr), `IP IQ YP YQ` = 0 (no current- or
+admittance-type load in MATPOWER), `OWNER` 1, `SCALE` 1, `INTRPT` 0. Buses
+1, 7 and 8 have `PD = QD = 0` and get no record, exactly as `io.matpower`
+emits no `Load` for them. Importer id `load-<I>-<ID>` (`load-2-1`, …) versus
+matpower's `load-<I>`; the AC-4 test matches loads by bus.
+
+### Fixed shunt (1) — `GS`/`BS` of bus 9
+
+`9,'1 ',1, GL=0.000 (GS, MW), BL=19.000 (BS, MVAr)`; same sign convention as
+MATPOWER (positive `BL` injects). Only bus 9 has a non-zero `GS`/`BS` pair.
+
+### Generator records (5) — `mpc.gen` row → generator record
+
+| RAW field | source |
+| --- | --- |
+| `I`, `ID` | `GEN_BUS`, `'1 '` |
+| `PG`, `QG` | `PG`, `QG` (MW, MVAr) |
+| `QT`, `QB` | `QMAX`, `QMIN` |
+| `VS` | `VG` |
+| `IREG` | 0 (default; ignored) |
+| `MBASE` | `MBASE` = 100 (ignored by the model) |
+| `ZR ZX RT XT GTAP` | 0, 1, 0, 0, 1 (v33 defaults; ignored) |
+| `STAT` | `GEN_STATUS` |
+| `RMPCT` | 100 (default; ignored) |
+| `PT`, `PB` | `PMAX`, `PMIN` |
+| `O1..F4`, `WMOD`, `WPF` | 1,1.0,0,1.0,0,1.0,0,1.0,0,1.0 (defaults; ignored) |
+
+Costs: `mpc.gencost` has **no RAW representation** — no v33 section carries
+economic data (research §3) — so every imported generator has `cost=None` and
+the importer reports `RAW_NO_COSTS` once. `PC1..APF` of `mpc.gen` are not
+read by `io.matpower` either.
+
+### Non-transformer branch records (17) — `mpc.branch` rows with `TAP = 0`
+
+`I`=`F_BUS`, `J`=`T_BUS`, `CKT`=`'1 '`, `R`=`BR_R`, `X`=`BR_X`, `B`=`BR_B`
+(pu on SBASE = baseMVA = 100), `RATEA RATEB RATEC` = `RATE_A RATE_B RATE_C`
+= 0 (unrated → `rating_mva=None` in both importers), `GI BI GJ BJ` = 0,
+`ST` = `BR_STATUS`, `MET` 1, `LEN` 0, owners default. Importer id
+`branch-<I>-<J>-<CKT>`; matched by `(from, to)` in the test.
+
+### Two-winding transformer records (3) — `mpc.branch` rows 8, 9, 10 (`TAP ≠ 0`)
+
+case14's branches 4-7 (tap 0.978), 4-9 (0.969) and 5-6 (0.932) are written as
+four-line transformer records with **CW=1, CZ=1, CM=1** so the round-trip is
+exact by construction:
+
+- line 1: `I, J, K=0 (two-winding), CKT='1 ', CW=1, CZ=1, CM=1, MAG1=0, MAG2=0,
+  NMETR=2, NAME='', STAT=BR_STATUS, owners default, VECGRP=''`
+- line 2: `R1-2 = BR_R, X1-2 = BR_X` — with CZ=1 these are pu on system
+  SBASE, i.e. the `.m` values verbatim; `SBASE1-2 = 100` (unused for CZ=1)
+- line 3: `WINDV1 = TAP` — with CW=1 a pu turns ratio on the bus base, so
+  `tap = WINDV1 / WINDV2 = TAP / 1.0`; `NOMV1 = 0` (= bus base), `ANG1 = SHIFT
+  = 0`, `RATA1 = RATE_A = 0` (→ `None`), `RATB1 RATC1` 0, `COD1 = 0` (no
+  control), `CONT1 0`, `RMA1 RMI1 VMA1 VMI1` 1.1/0.9 (control limits; ignored),
+  `NTP1 33`, `TAB1 0`, `CR1 CX1 CNXA1` 0
+- line 4: `WINDV2 = 1.0, NOMV2 = 0`
+
+`BR_B` is 0 on all three rows, matching the transformer model (`b = 0`).
+`Branch.kind` is `"transformer"` for these records (set from the record type,
+not inferred from the tap) and `"line"` for the 17 branch records — equal to
+what `io.matpower` derives from the `TAP` column on this file.
+
+### Area, zone
+
+`1, ISW=1, PDES=0, PTOL=999.99, ARNAME='IEEE14'` (the importer keeps only the
+bus `AREA` label); zone `1,'1'` → `Zone(id="1", name="1")` (matpower yields
+`name=None`; zones are outside the AC-4 field comparison).
+
+## synthetic_quirks_v33.raw — hand-derived expected network
+
+Authored 2026-08-29; 4 buses, SBASE 100 MVA, 50 Hz header. Purpose: every
+conversion branch of the importer that `case14_v33.raw` does not reach.
+Quirks present: CZ=2 and CZ=3, CW=2 and CW=3, CM=2, a neutral-tap (1.0 / 0 deg)
+transformer, the four-line transformer
+record continuation, two circuits between one bus pair (`CKT '1'` / `'2'`),
+a ZIP load, two loads (plus one out-of-service) on one bus, a fixed shunt,
+branch end shunts (`BI`, `GJ`), a 9-field bus record (no `NVHI..EVLO`), a
+short generator record (no owner fields), a quoted name containing a comma,
+trailing `/` comments on data lines, an out-of-service generator, and ignored
+records: one owner, one switched shunt.
+
+### Buses
+
+| id | base_kv | type | vm | va | v_min | v_max | area | zone |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `bus-1` | 138 | slack | 1.00 | 0.0 | 0.9 | 1.1 | `"1"` | `"1"` |
+| `bus-2` | 138 | pq | 0.95 | -2.5 | 0.9 | 1.1 | `"1"` | `"1"` |
+| `bus-3` | 13.8 | pv | 1.02 | -1.0 | 0.95 | 1.05 | `"2"` | `"1"` |
+| `bus-4` | 13.8 | pq | 1.00 | -3.0 | `None` | `None` | `"2"` | `"2"` |
+
+Zones: `Zone("1", name="ZONE-A")`, `Zone("2", name="ZONE-B")`.
+
+### Loads (MATPOWER rule: `P = PL + IP·VM + YP·VM²`, same for Q, at the bus's VM)
+
+- `load-2-1` at `bus-2`, VM = 0.95: `p = 40 + 10·0.95 + 20·0.95² = 40 + 9.5 +
+  18.05 = 67.55` MW; `q = 10 + 2·0.95 + 4·0.9025 = 10 + 1.9 + 3.61 = 15.51`
+  MVAr; reported `RAW_LOAD_ZIP_FOLDED`.
+- `load-4-1`: 20 / 5; `load-4-2`: 5 / 1; `load-4-3`: 99 / 99 with
+  `in_service=False` (STATUS 0).
+
+### Shunts
+
+- `shunt-2-1` (fixed shunt): `g_mw = 1.0`, `b_mvar = 15.0`.
+- `shunt-branch-1-2-2-i` at `bus-1` from branch `1-2 '2'` end shunt `BI = 0.01`
+  pu: `b_mvar = 0.01 · 100 = 1.0`, `g_mw = 0`; `shunt-branch-1-2-2-j` at
+  `bus-2` from `GJ = 0.002` pu: `g_mw = 0.2`, `b_mvar = 0`. Reported
+  `RAW_BRANCH_END_SHUNT_FOLDED` (one entry per end).
+- `shunt-xfmr-2-3-1` at `bus-2` from T1's magnetising branch (CM=2, below):
+  `g_mw = 0.02`, `b_mvar = -0.9997999799959989`. Reported
+  `RAW_XFMR_MAGNETISING_FOLDED`.
+
+### Generators
+
+- `gen-1-1` at `bus-1`: p 50, q 0, q_max 100, q_min -100, v_set 1.0, p_max 200,
+  p_min 0, in service.
+- `gen-3-1` at `bus-3`: p 30, q 5, q_max 50, q_min -20, v_set 1.02, p_max 80,
+  p_min 10, in service.
+- `gen-3-2` at `bus-3` (18-field record): p 0, q 0, q_max 10, q_min -10, v_set
+  1.02, p_max 20, p_min 0, `in_service=False` (STAT 0).
+- All `cost=None`; `RAW_NO_COSTS` reported once.
+
+### Lines (non-transformer branch records)
+
+- `branch-1-2-1`: r 0.01, x 0.1, b 0.02, rating 150, kind `line`, no tap/shift.
+- `branch-1-2-2`: r 0.02, x 0.2, b 0.04, rating 100, kind `line`.
+
+### T1 — `branch-2-3-1`, CW=2, CZ=2, CM=2 (kind `transformer`)
+
+Record: `R1-2 = 0.005, X1-2 = 0.08, SBASE1-2 = 50`; `WINDV1 = 144.9` kV,
+`NOMV1 = 0` (→ bus 2 base 138 kV), `ANG1 = 0`, `RATA1 = 60`; `WINDV2 = 13.8`
+kV, `NOMV2 = 0`; `MAG1 = 20000` W, `MAG2 = 0.02`.
+
+- CZ=2: `R, X` are pu on `SBASE1-2` and `NOMV1`. Impedance base conversion
+  (`psse_convert_xfmr.m`): `factor = Zb_winding / Zb_system =
+  (NOMV1² / SBASE1-2) / (BASKV_I² / SBASE) = (138/138)² · 100/50 = 2`.
+  `r = 0.005 · 2 = 0.01`, `x = 0.08 · 2 = 0.16`.
+- CW=2: winding voltages in kV, each divided by its bus base:
+  `t1 = 144.9 / 138 = 1.05`, `t2 = 13.8 / 13.8 = 1.0`; `tap_ratio = t1 / t2
+  = 1.05`; `shift_deg = None` (ANG1 = 0).
+- CM=2: `MAG1` no-load loss in W, `MAG2` exciting current pu on `SBASE1-2`
+  and `NOMV1`. `G_w = 20000 / (1e6 · 50) = 0.0004`; `B_w = -sqrt(MAG2² −
+  G_w²) = -sqrt(0.0004 − 0.00000016) = -sqrt(0.00039984) =
+  -0.01999599959991998` (inductive, negative). To system base admittance
+  scales by `SBASE1-2 / SBASE = 0.5`, then to physical: `g_mw = 0.0004 · 0.5 ·
+  100 = 0.02` MW, `b_mvar = -0.01999599959991998 · 0.5 · 100 =
+  -0.9997999799959989` MVAr, placed at the from bus `bus-2` as
+  `shunt-xfmr-2-3-1`.
+- `rating_mva = 60`, `b = 0`, in service.
+
+### T2 — `branch-3-4-1`, CW=3, CZ=3, CM=1 (kind `transformer`)
+
+Record: `R1-2 = 10000` (W, load loss), `X1-2 = 0.12` (|Z| pu on `SBASE1-2`),
+`SBASE1-2 = 25`; `WINDV1 = 0.98` (pu of `NOMV1`), `NOMV1 = 14.49` kV,
+`ANG1 = 5.0`, `RATA1 = 30`; `WINDV2 = 1.0`, `NOMV2 = 0`; `MAG1 = MAG2 = 0`.
+
+- CZ=3: `R_w = 10000 / (1e6 · 25) = 0.0004` pu on the winding base;
+  `X_w = sqrt(0.12² − 0.0004²) = sqrt(0.0144 − 0.00000016) =
+  sqrt(0.01439984) = 0.11999933333148147`.
+  `factor = (NOMV1 / BASKV_3)² · SBASE / SBASE1-2 = (14.49/13.8)² · 100/25 =
+  1.05² · 4 = 1.1025 · 4 = 4.41`.
+  `r = 0.0004 · 4.41 = 0.001764`, `x = 0.11999933333148147 · 4.41 =
+  0.5291970599918333`.
+- CW=3: winding voltages in pu of nominal, converted to pu of bus base by
+  `NOMV / BASKV` (`NOMV = 0` → 1): `t1 = 0.98 · 14.49 / 13.8 = 0.98 · 1.05 =
+  1.029`, `t2 = 1.0`; `tap_ratio = 1.029`; `shift_deg = 5.0`.
+- CM=1 with `MAG1 = MAG2 = 0`: no magnetising shunt, no report entry.
+- `rating_mva = 30`, `b = 0`, in service.
+
+### T3 — `branch-2-4-1`, CW=1, CZ=1, CM=1, neutral tap (kind `transformer`; spec A7 / AC-6)
+
+Record: `R1-2 = 0.002, X1-2 = 0.05, SBASE1-2 = 100`; `WINDV1 = 1.0`, `NOMV1 = 0`,
+`ANG1 = 0`, `RATA1 = 40`; `WINDV2 = 1.0`, `NOMV2 = 0`; `MAG1 = MAG2 = 0`.
+
+- CZ=1: `r = 0.002`, `x = 0.05` verbatim (pu on SBASE).
+- CW=1: `t1 = 1.0`, `t2 = 1.0`; `tap_ratio = 1.0 / 1.0 = 1.0` — nominal; `shift_deg =
+  None` (ANG1 = 0). Nothing about the parameters distinguishes this branch from a
+  line: `kind = "transformer"` comes only from the record type, which is what the
+  fixture exists to prove (`Branch._default_kind` would infer `"line"` here).
+- `rating_mva = 40`, `b = 0`, in service; no magnetising shunt, no report entry.
+- Adds the loop 2-3-4-2; the network stays one island.
+
+### Ignored records (one report entry each)
+
+- owner `1,'OWNER ONE'` → `RAW_SECTION_IGNORED` naming section `owner`,
+  record `1`.
+- switched shunt at bus 4 (`BINIT = 5.0`) → `RAW_SWITCHED_SHUNT_IGNORED`
+  naming bus 4 (`BINIT` is **not** folded into a shunt; the entry says so).
+
+Areas (`AREA HV`, `AREA MV`) contribute nothing beyond the bus labels and are
+not reported (they are read, not ignored).
+
+### Not in this file
+
+A three-winding transformer (five-line record, `K ≠ 0`) is exercised by an
+inline text in `tests/unit/test_io_psse_raw.py` (each such record →
+`RAW_THREE_WINDING_IGNORED`, one entry), so this fixture stays a network the
+model accepts unchanged.

mambo_power-0.1.0/fixtures/case14_v33.raw

@@ -0,0 +1,85 @@
+0,   100.00, 33, 0, 0, 60.00     / hand-authored from fixtures/matpower/case14.m (see fixtures/PROVENANCE-raw.md)
+IEEE 14 BUS TEST CASE -- transcription of MATPOWER case14.m, PSS/E RAW v33 layout
+mambo-power fixture; BASKV 0 kept as in the source; no cost data exists in RAW
+     1,'Bus 1     HV',     0.0000,3,   1,   1,   1,1.06000,   0.0000,1.06000,0.94000,1.06000,0.94000
+     2,'Bus 2     HV',     0.0000,2,   1,   1,   1,1.04500,  -4.9800,1.06000,0.94000,1.06000,0.94000
+     3,'Bus 3     HV',     0.0000,2,   1,   1,   1,1.01000, -12.7200,1.06000,0.94000,1.06000,0.94000
+     4,'Bus 4     HV',     0.0000,1,   1,   1,   1,1.01900, -10.3300,1.06000,0.94000,1.06000,0.94000
+     5,'Bus 5     HV',     0.0000,1,   1,   1,   1,1.02000,  -8.7800,1.06000,0.94000,1.06000,0.94000
+     6,'Bus 6     LV',     0.0000,2,   1,   1,   1,1.07000, -14.2200,1.06000,0.94000,1.06000,0.94000
+     7,'Bus 7     ZV',     0.0000,1,   1,   1,   1,1.06200, -13.3700,1.06000,0.94000,1.06000,0.94000
+     8,'Bus 8     TV',     0.0000,2,   1,   1,   1,1.09000, -13.3600,1.06000,0.94000,1.06000,0.94000
+     9,'Bus 9     LV',     0.0000,1,   1,   1,   1,1.05600, -14.9400,1.06000,0.94000,1.06000,0.94000
+    10,'Bus 10    LV',     0.0000,1,   1,   1,   1,1.05100, -15.1000,1.06000,0.94000,1.06000,0.94000
+    11,'Bus 11    LV',     0.0000,1,   1,   1,   1,1.05700, -14.7900,1.06000,0.94000,1.06000,0.94000
+    12,'Bus 12    LV',     0.0000,1,   1,   1,   1,1.05500, -15.0700,1.06000,0.94000,1.06000,0.94000
+    13,'Bus 13    LV',     0.0000,1,   1,   1,   1,1.05000, -15.1600,1.06000,0.94000,1.06000,0.94000
+    14,'Bus 14    LV',     0.0000,1,   1,   1,   1,1.03600, -16.0400,1.06000,0.94000,1.06000,0.94000
+0 / END OF BUS DATA, BEGIN LOAD DATA
+     2,'1 ',1,   1,   1,    21.700,    12.700,     0.000,     0.000,     0.000,     0.000,   1,1,0
+     3,'1 ',1,   1,   1,    94.200,    19.000,     0.000,     0.000,     0.000,     0.000,   1,1,0
+     4,'1 ',1,   1,   1,    47.800,    -3.900,     0.000,     0.000,     0.000,     0.000,   1,1,0
+     5,'1 ',1,   1,   1,     7.600,     1.600,     0.000,     0.000,     0.000,     0.000,   1,1,0
+     6,'1 ',1,   1,   1,    11.200,     7.500,     0.000,     0.000,     0.000,     0.000,   1,1,0
+     9,'1 ',1,   1,   1,    29.500,    16.600,     0.000,     0.000,     0.000,     0.000,   1,1,0
+    10,'1 ',1,   1,   1,     9.000,     5.800,     0.000,     0.000,     0.000,     0.000,   1,1,0
+    11,'1 ',1,   1,   1,     3.500,     1.800,     0.000,     0.000,     0.000,     0.000,   1,1,0
+    12,'1 ',1,   1,   1,     6.100,     1.600,     0.000,     0.000,     0.000,     0.000,   1,1,0
+    13,'1 ',1,   1,   1,    13.500,     5.800,     0.000,     0.000,     0.000,     0.000,   1,1,0
+    14,'1 ',1,   1,   1,    14.900,     5.000,     0.000,     0.000,     0.000,     0.000,   1,1,0
+0 / END OF LOAD DATA, BEGIN FIXED SHUNT DATA
+     9,'1 ',1,     0.000,    19.000
+0 / END OF FIXED SHUNT DATA, BEGIN GENERATOR DATA
+     1,'1 ',   232.400,   -16.900,    10.000,     0.000,1.06000,    0,   100.000, 0.00000, 1.00000, 0.00000, 0.00000,1.00000,1,  100.0,   332.400,     0.000,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,0,1.0000
+     2,'1 ',    40.000,    42.400,    50.000,   -40.000,1.04500,    0,   100.000, 0.00000, 1.00000, 0.00000, 0.00000,1.00000,1,  100.0,   140.000,     0.000,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,0,1.0000
+     3,'1 ',     0.000,    23.400,    40.000,     0.000,1.01000,    0,   100.000, 0.00000, 1.00000, 0.00000, 0.00000,1.00000,1,  100.0,   100.000,     0.000,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,0,1.0000
+     6,'1 ',     0.000,    12.200,    24.000,    -6.000,1.07000,    0,   100.000, 0.00000, 1.00000, 0.00000, 0.00000,1.00000,1,  100.0,   100.000,     0.000,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,0,1.0000
+     8,'1 ',     0.000,    17.400,    24.000,    -6.000,1.09000,    0,   100.000, 0.00000, 1.00000, 0.00000, 0.00000,1.00000,1,  100.0,   100.000,     0.000,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,0,1.0000
+0 / END OF GENERATOR DATA, BEGIN BRANCH DATA
+     1,     2,'1 ', 0.01938, 0.05917, 0.05280,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     1,     5,'1 ', 0.05403, 0.22304, 0.04920,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     2,     3,'1 ', 0.04699, 0.19797, 0.04380,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     2,     4,'1 ', 0.05811, 0.17632, 0.03400,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     2,     5,'1 ', 0.05695, 0.17388, 0.03460,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     3,     4,'1 ', 0.06701, 0.17103, 0.01280,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     4,     5,'1 ', 0.01335, 0.04211, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     6,    11,'1 ', 0.09498, 0.19890, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     6,    12,'1 ', 0.12291, 0.25581, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     6,    13,'1 ', 0.06615, 0.13027, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     7,     8,'1 ', 0.00000, 0.17615, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     7,     9,'1 ', 0.00000, 0.11001, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     9,    10,'1 ', 0.03181, 0.08450, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+     9,    14,'1 ', 0.12711, 0.27038, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+    10,    11,'1 ', 0.08205, 0.19207, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+    12,    13,'1 ', 0.22092, 0.19988, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+    13,    14,'1 ', 0.17093, 0.34802, 0.00000,   0.00,   0.00,   0.00, 0.00000, 0.00000, 0.00000, 0.00000,1,1,   0.00,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000
+0 / END OF BRANCH DATA, BEGIN TRANSFORMER DATA
+     4,     7,     0,'1 ',1,1,1,  0.00000,  0.00000,2,'            ',1,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,'            '
+   0.00000,   0.20912,   100.00
+0.97800,   0.000,   0.000,     0.00,     0.00,     0.00,0,     0, 1.10000, 0.90000, 1.10000, 0.90000, 33, 0, 0.00000, 0.00000, 0.000
+1.00000,   0.000
+     4,     9,     0,'1 ',1,1,1,  0.00000,  0.00000,2,'            ',1,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,'            '
+   0.00000,   0.55618,   100.00
+0.96900,   0.000,   0.000,     0.00,     0.00,     0.00,0,     0, 1.10000, 0.90000, 1.10000, 0.90000, 33, 0, 0.00000, 0.00000, 0.000
+1.00000,   0.000
+     5,     6,     0,'1 ',1,1,1,  0.00000,  0.00000,2,'            ',1,   1,1.0000,   0,1.0000,   0,1.0000,   0,1.0000,'            '
+   0.00000,   0.25202,   100.00
+0.93200,   0.000,   0.000,     0.00,     0.00,     0.00,0,     0, 1.10000, 0.90000, 1.10000, 0.90000, 33, 0, 0.00000, 0.00000, 0.000
+1.00000,   0.000
+0 / END OF TRANSFORMER DATA, BEGIN AREA DATA
+     1,     1,     0.000,   999.990,'IEEE14      '
+0 / END OF AREA DATA, BEGIN TWO-TERMINAL DC DATA
+0 / END OF TWO-TERMINAL DC DATA, BEGIN VSC DC LINE DATA
+0 / END OF VSC DC LINE DATA, BEGIN IMPEDANCE CORRECTION DATA
+0 / END OF IMPEDANCE CORRECTION DATA, BEGIN MULTI-TERMINAL DC DATA
+0 / END OF MULTI-TERMINAL DC DATA, BEGIN MULTI-SECTION LINE DATA
+0 / END OF MULTI-SECTION LINE DATA, BEGIN ZONE DATA
+     1,'1           '
+0 / END OF ZONE DATA, BEGIN INTER-AREA TRANSFER DATA
+0 / END OF INTER-AREA TRANSFER DATA, BEGIN OWNER DATA
+0 / END OF OWNER DATA, BEGIN FACTS DEVICE DATA
+0 / END OF FACTS DEVICE DATA, BEGIN SWITCHED SHUNT DATA
+0 / END OF SWITCHED SHUNT DATA, BEGIN GNE DATA
+0 / END OF GNE DATA, BEGIN INDUCTION MACHINE DATA
+0 / END OF INDUCTION MACHINE DATA
+Q