Metadata-Version: 2.5
Name: popo-flow
Version: 0.2.1
Summary: Low-voltage network simulation and state estimation for DER studies.
Project-URL: Homepage, https://github.com/sambaiga/popo
Project-URL: Repository, https://github.com/sambaiga/popo
Project-URL: Documentation, https://sambaiga.github.io/popo-docs
Project-URL: Bug Tracker, https://github.com/sambaiga/popo/issues
Project-URL: Changelog, https://github.com/sambaiga/popo/blob/main/CHANGELOG.md
Author-email: sambaiga <sambaiga@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: der,distribution-networks,low-voltage,opendss,power-systems,state-estimation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: numpy>=2.4.4
Requires-Dist: pandas>=2.3.3
Requires-Dist: pyarrow>=23.0.0
Requires-Dist: pydantic>=2.13.0
Requires-Dist: rich>=15.0.0
Provides-Extra: all
Requires-Dist: great-tables>=0.21.0; extra == 'all'
Requires-Dist: matplotlib>=3.10.0; extra == 'all'
Requires-Dist: opendssdirect-py>=0.9.4; extra == 'all'
Requires-Dist: pandapower>=3.5.4; extra == 'all'
Requires-Dist: scienceplots>=2.1.1; extra == 'all'
Provides-Extra: estimation
Requires-Dist: pandapower>=3.5.4; extra == 'estimation'
Provides-Extra: notebooks
Requires-Dist: great-tables>=0.21.0; extra == 'notebooks'
Requires-Dist: matplotlib>=3.10.0; extra == 'notebooks'
Provides-Extra: opendss
Requires-Dist: opendssdirect-py>=0.9.4; extra == 'opendss'
Provides-Extra: plot
Requires-Dist: great-tables>=0.21.0; extra == 'plot'
Requires-Dist: matplotlib>=3.10.0; extra == 'plot'
Requires-Dist: scienceplots>=2.1.1; extra == 'plot'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://sambaiga.github.io/popo-docs/_static/img/logo.svg" alt="popo" width="320">
</p>

<p align="center">
  <a href="https://sambaiga.github.io/popo-docs"><b>Documentation</b></a> ·
  <a href="https://sambaiga.github.io/popo-docs/getting-started/quickstart.html">Quickstart</a> ·
  <a href="https://sambaiga.github.io/popo-docs/tutorials/index.html">Tutorials</a> ·
  <a href="https://pypi.org/project/popo-flow/">PyPI</a>
</p>

# popo

<img src="https://sambaiga.github.io/popo-docs/_static/img/overview.svg" alt="popo simulates a feeder forward under rooftop solar and EV uptake, and estimates its state from the few measurements that exist" width="100%">

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

**popo** is Swahili for bat. It is a companion to [twiga](https://sambaiga.github.io/twiga-docs),
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:

```bash
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

| module | purpose |
|---|---|
| `popo.network` | load an OpenDSS circuit as Python records, inspect topology, transformers and loads |
| `popo.powerflow` | time-series solves with convergence reported, result tables, penetration sweeps |
| `popo.scenarios` | household, PV, EV and storage scenarios, Volt-VAr and Volt-Watt control |
| `popo.standards` | EN 50160, ANSI C84.1, IEEE 1547 and EREC G99; verdicts, violations and events |
| `popo.estimation` | weighted-least-squares state estimation from a sparse measurement set |
| `popo.profiles` | household, PV and EV profile pools |
| `popo.plotting` | network diagrams, figure style and tables |

## Learn it

The [documentation](https://sambaiga.github.io/popo-docs) has a [quickstart](https://sambaiga.github.io/popo-docs/getting-started/quickstart.html),
a user guide for each module and three tutorials that run end to end on real feeders:

- [OpenDSS LV modelling](https://sambaiga.github.io/popo-docs/tutorials/notebooks/01-opendss-lv-modeling.html): build an LV
  circuit, read it back as records and tables, and check it against EN 50160.
- [Time series and DER](https://sambaiga.github.io/popo-docs/tutorials/notebooks/02-timeseries-der-modeling.html): hosting
  capacity on a real 188-customer UK feeder, every customer's voltage alongside the substation's,
  and Volt-VAr, Volt-Watt and storage compared.
- [LV state estimation](https://sambaiga.github.io/popo-docs/tutorials/notebooks/03-lv-state-estimation.html): how much has to
  be measured to know every customer's voltage.

## Development

```bash
uv sync --all-extras --group docs   # environment with both solvers and the docs tooling
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                           # build the docs, warnings as errors
make docs-serve                     # serve the docs locally, rebuilding on change
```

Commits follow [conventional commits](https://www.conventionalcommits.org),
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: the API may change before 1.0. Changes are listed in the
[changelog](https://sambaiga.github.io/popo-docs/changelog.html).

## Citation

If you use popo in your work, please cite it:

> Faustine, A. (2026). *popo: low-voltage network simulation and state estimation* (Version 0.2.1)
> [Computer software]. https://sambaiga.github.io/popo-docs

```bibtex
@software{faustine2026popo,
  author  = {Faustine, Anthony},
  title   = {popo: Low-Voltage Network Simulation and State Estimation},
  year    = {2026},
  version = {0.2.1},
  url     = {https://sambaiga.github.io/popo-docs},
  note    = {Python package \texttt{popo-flow}}
}
```

## Licence

Apache-2.0.
