Documentation · Quickstart · Tutorials · PyPI

popo

Low-voltage network simulation and state estimation for distributed energy resource studies.

popo is Swahili for bat. It is a companion to twiga, Swahili for giraffe: twiga sees far, which is forecasting ahead in time; popo sees in the dark, which is inferring the state of a network that is not measured.

Low-voltage distribution is largely unobservable. There are measurements at the secondary substation and very little downstream, yet the decisions that matter, how much solar or how many electric vehicles a feeder can take, depend on what is happening at every customer terminal. This library is about reconstructing that from what little is metered, and about simulating what a network would do under a given level of DER uptake.

Install

The solvers are optional, because reading a network definition or checking a voltage limit against a standard needs neither:

uv add popo-flow                  # core: networks, standards, results
uv add popo-flow[opendss]         # + time-series power flow
uv add popo-flow[estimation]      # + weighted-least-squares state estimation
uv add popo-flow[all]

The distribution is named popo-flow because popo was already taken on PyPI; the package itself is still imported as import popo.

What is in it

Learn it

Three tutorial notebooks under notebooks/, each running end to end against vendored data:

• 01-opendss-lv-modeling.ipynb: build an LV circuit from scratch (transformer, linecodes, lines, loads), read it back with popo.network.Circuit and popo.powerflow.results, check compliance and list violations with popo.standards.VoltageLimits, and three worked network-expansion exercises.
• 02-timeseries-der-modeling.ipynb: a real 188-customer UK feeder with real household, PV and EV profiles, a time-series solve with popo.powerflow.solve_time_series, a hosting-capacity sweep with run_uk_sweep, every customer's voltage traced alongside the substation's, Volt-VAr, Volt-Watt and storage compared, and diversified against uncoordinated EV charging.
• 03-lv-state-estimation.ipynb: the same feeder converted to pandapower and checked against OpenDSS, then estimated from the substation, smart meters and line sensors with popo.estimation, including how many meters are enough and why a coherent substation forecast estimates better than three separate ones.

uv sync --all-extras installs everything the notebooks use.

Development

uv sync --all-extras          # environment with both solvers
make test                     # suite with the coverage gate, solvers deselected
make test-solver              # only the tests that need OpenDSS or pandapower
make lint                     # ruff check
make fmt                      # ruff format
make typecheck                # ty
make docs                     # serve the docs locally

Commits follow conventional commits, checked by commitizen through a pre-commit hook. Install the hooks once with uv run pre-commit install --install-hooks -t pre-commit -t commit-msg.

Status

Alpha, version 0.1.0. Nothing is published yet.

popo is cited in the thesis as \texttt{Popo} \cite{faustine2026popo} (Chapter 2, "The Three Simulated Datasets"). What it can reproduce today, of the three:

• DSS-US: SMART-DS AUS_P1U, 596 pole transformers, around 6 customers each through a 0.12 kV split-phase secondary, measured (not fixed-power-factor) P/Q, ANSI C84.1, mean customer power factor 0.911±0.041. Reproducible today: popo.powerflow.sweep.run_us_sweep, regression tested against a real recorded run in tests/integration/test_us_sweep_regression.py.
• DSS-UK: UK Generic Distribution System models, two substations selected by voltage sensitivity ("Feeder A", stiff, 21_1_1135, 157 customers, 315 kVA; "Feeder B", weak, 17_1_1149, 188 customers, 500 kVA), Low Carbon London demand ADMD-scaled to 0.8 kW/customer, PVWatts-driven PV, recorded EV charging sessions at constant 7.4 kW, and three modifications that decouple P from Q: independent customer power-factor profiles (0.88 to 0.995 lagging), a Q(U) droop on PV inverters (±0.33 pu per EN 50549-1/IEEE 1547), and an 11 kV source voltage that follows a demand-dependent profile within ±2% with a 0.5% tap-changer deadband. Reproducible today: popo.powerflow.sweep.run_uk_sweep, regression tested against a freshly generated real run in tests/integration/test_uk_sweep_regression.py.
• DSS-EU: a four-feeder Hybrid European MV-LV network (Deakin2021/Koirala2020 topology), AusNet demand/PV, Fachrizal2021 EV profiles, fixed power factor throughout with unity-PF PV inverters, EN 50160. Not reproducible: the generating script was never located in ml-energy-disaggregation, across two separate audits. See docs/simulations.md for the full account and docs/EXTRACTION_PLAN.md for the extraction history.

The core mechanics are extracted from ml-energy-disaggregation's two legacy power-flow runners and generalized across them: DER attachment and Volt-VAr control (popo.scenarios), the time-series solve loop with convergence reported rather than printed (popo.powerflow), transformer parsing and utilisation-based selection (popo.network), state estimation (popo.estimation), and named voltage/inverter standards replacing the runners' divergent bare constants (popo.standards). See docs/simulations.md for copy-pasteable end-to-end commands for DSS-US and DSS-UK, and docs/EXTRACTION_PLAN.md for the extraction this package is built from. Expect the API to change.

Licence

Apache-2.0.