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

On PyPI as of v0.1.0. See 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 epic-close continuation record if you're reading this after a release and it still says otherwise; PyPI's own project page bakes in whatever this file said at the release that's currently latest, so a README.md fix here only reaches pypi.org on the next release, not retroactively). Runtime dependencies are exactly numpy, scipy, highspy, pydantic; Python 3.11 or newer.

Install

pip install mambo-power
# or: uv add mambo-power

The wheel ships only the package. The MATPOWER fixtures under fixtures/ and the test suite are in the sdist and the repository, not in the wheel, so the examples below assume a clone:

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: pip install -e . in any Python >= 3.11 environment.

Quick start

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 walks through loading, validating, solving and reading results with real output.

Tutorials and manual

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 — every entity, field, unit, and validation code
• File formats — native JSON, MATPOWER, pandapower JSON, PyPSA, PSS/E RAW, CSV bundles
• Numerics — NetworkArrays, Ybus, Bbus, PTDF, LODF and bridges
• Power flow — the DC formulation and the AC solver's contract
• DC-OPF and N-1 screening
• Market clearing: nodal, multiperiod, zonal
• Agent-based bidding — strategies, offered-vs-true cost, the fixed-point loop
• Results — result tables, provenance, JSON round-trip, to_arrays()
• Jobs API — the stateless SolveRequest / SolveResult surface
• API reference, Design, Changelog, Contributing

Development

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. Bundled MATPOWER cases under fixtures/matpower/ are public IEEE test data as distributed by MATPOWER; see fixtures/matpower/PROVENANCE.md.