popo-flow 0.1.0__py3-none-any.whl

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.
popo/__init__.py ADDED
@@ -0,0 +1,25 @@
1
+ """popo: low-voltage network simulation and state estimation for DER studies.
2
+
3
+ Swahili for bat. Twiga sees far, which is forecasting ahead in time; popo sees in
4
+ the dark, which is inferring the state of a network that is not measured. Low
5
+ voltage distribution is largely unobservable, and this library is about
6
+ reconstructing what such a network is doing from the little that is metered, and
7
+ about simulating what it would do under a DER scenario.
8
+
9
+ The solvers are optional. Reading a network definition or checking a voltage
10
+ limit against a standard requires neither OpenDSS nor pandapower, so both are
11
+ imported lazily and declared as extras:
12
+
13
+ uv add popo-flow[opendss] # time-series power flow
14
+ uv add popo-flow[estimation] # weighted-least-squares state estimation
15
+ uv add popo-flow[all]
16
+
17
+ The distribution is ``popo-flow`` on PyPI (``popo`` was taken); the import name
18
+ is still ``popo``.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ __version__ = "0.1.0"
24
+
25
+ __all__ = ["__version__"]
popo/core/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """Cross-cutting machinery: configuration and utilities. Plotting is :mod:`popo.plotting`."""
@@ -0,0 +1,6 @@
1
+ """Pydantic configuration objects.
2
+
3
+ Studies are described by configuration rather than by editing module constants,
4
+ so a scenario is reproducible from a file and two studies can differ in exactly
5
+ one field.
6
+ """
@@ -0,0 +1 @@
1
+ """Logging, paths and small shared helpers."""
@@ -0,0 +1,43 @@
1
+ """State estimation from a sparse measurement set.
2
+
3
+ Low-voltage networks are largely unobservable: there are measurements at the
4
+ secondary substation and little downstream. Weighted least squares reconstructs
5
+ the network state from those few readings plus pseudo-measurements, whose
6
+ assumed uncertainty is the standing weakness of the method and the thing a
7
+ calibrated forecast can supply instead.
8
+
9
+ This is where a multi-target forecast is judged operationally rather than
10
+ statistically. A distribution operator does not consume a forecast of substation
11
+ active power, reactive power and voltage directly; it feeds them to an estimator
12
+ and acts on the network state that comes out. A triple whose marginals are each
13
+ well calibrated but which is jointly infeasible produces a worse estimate than
14
+ one that is mutually consistent, and no marginal score can see that.
15
+
16
+ pandapower is an optional extra, so both modules import it lazily.
17
+ """
18
+
19
+ from popo.estimation.model import check_conversion, set_loading, to_pandapower, true_state
20
+ from popo.estimation.study import ComparisonResult, run_comparison
21
+ from popo.estimation.wls import (
22
+ MeasurementNoise,
23
+ Observability,
24
+ estimate_voltages,
25
+ observability,
26
+ voltage_error,
27
+ zero_injection_buses,
28
+ )
29
+
30
+ __all__ = [
31
+ "ComparisonResult",
32
+ "MeasurementNoise",
33
+ "Observability",
34
+ "check_conversion",
35
+ "estimate_voltages",
36
+ "observability",
37
+ "run_comparison",
38
+ "set_loading",
39
+ "to_pandapower",
40
+ "true_state",
41
+ "voltage_error",
42
+ "zero_injection_buses",
43
+ ]
@@ -0,0 +1,173 @@
1
+ """Converting an OpenDSS feeder to a pandapower model and solving its true state.
2
+
3
+ State estimation needs a network model and a ground truth to be judged against.
4
+ Both come from the same circuit definition used for the time-series study, so
5
+ the estimator is scored against the network it is estimating rather than against
6
+ a separately built approximation of it.
7
+
8
+ The conversion is checked rather than trusted. pandapower's converter rates each
9
+ transformer winding at its bus's voltage base, which equals the turns ratio only
10
+ when the winding's rated voltage equals that base. A 0.416 kV secondary on a
11
+ 0.4 kV system is the common case where it does not, and the converted network
12
+ then loses the transformer's 4 % voltage boost: every bus sits about 0.04 pu
13
+ below the circuit it came from. :func:`to_pandapower` restores the nameplate
14
+ ratio, and :func:`check_conversion` compares the two engines bus by bus.
15
+
16
+ pandapower is imported lazily, so the package remains importable without it.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from typing import TYPE_CHECKING, Any
22
+ import warnings
23
+
24
+ import numpy as np
25
+ import pandas as pd
26
+
27
+ if TYPE_CHECKING: # pragma: no cover - typing only
28
+ from pathlib import Path
29
+
30
+
31
+ def to_pandapower(master: Path, transformer_index: int = 0, dss: Any = None) -> tuple[Any, int]:
32
+ """Convert an OpenDSS circuit and locate the busbar the study measures.
33
+
34
+ Each transformer's low-voltage rating is reset so its ratio is the nameplate
35
+ turns ratio, read from the circuit the converter has just compiled, rather
36
+ than the ratio of its buses' voltage bases.
37
+
38
+ Args:
39
+ master: Master ``.dss`` file of the circuit.
40
+ transformer_index: Which transformer's secondary is the measured
41
+ busbar. The default is the first, which on a single-substation LV
42
+ feeder is the only one.
43
+ dss: The ``opendssdirect`` module the converter compiled the circuit
44
+ into. Defaults to importing it; pandapower's converter needs it too.
45
+
46
+ Returns:
47
+ The pandapower network and the index of its low-voltage busbar.
48
+
49
+ Raises:
50
+ FileNotFoundError: If the master file does not exist.
51
+ ValueError: If the converted network carries no transformer, so there is
52
+ no busbar to measure at.
53
+ """
54
+ if not master.exists():
55
+ raise FileNotFoundError(f"no circuit definition at {master}")
56
+
57
+ from pandapower.converter.opendss.from_dss import from_opendss
58
+
59
+ with warnings.catch_warnings():
60
+ warnings.simplefilter("ignore")
61
+ net = from_opendss(str(master), solve=False)
62
+ if net.trafo.empty:
63
+ raise ValueError(f"{master} converted to a network with no transformer")
64
+ if isinstance(net.trafo, pd.DataFrame) and "name" in net.trafo.columns:
65
+ if dss is None:
66
+ import opendssdirect as dss
67
+ _restore_nameplate_ratios(net, dss)
68
+ return net, int(net.trafo.lv_bus.iloc[transformer_index])
69
+
70
+
71
+ def _restore_nameplate_ratios(net: Any, dss: Any) -> None:
72
+ """Set each converted transformer's low-voltage rating to its nameplate turns ratio.
73
+
74
+ The high-voltage rating the converter chose is kept, and the low-voltage
75
+ rating scaled so their ratio is the ratio of the highest to the lowest
76
+ winding voltage on the nameplate. A transformer the circuit does not name is
77
+ left as converted.
78
+ """
79
+ nameplates: dict[str, list[float]] = {}
80
+ index = dss.Transformers.First()
81
+ while index:
82
+ kvs = []
83
+ for winding in range(1, dss.Transformers.NumWindings() + 1):
84
+ dss.Transformers.Wdg(winding)
85
+ kvs.append(float(dss.Transformers.kV()))
86
+ nameplates[dss.Transformers.Name().lower()] = kvs
87
+ index = dss.Transformers.Next()
88
+ for row, name in net.trafo["name"].items():
89
+ kvs = nameplates.get(str(name).lower())
90
+ if kvs and min(kvs) > 0:
91
+ net.trafo.at[row, "vn_lv_kv"] = net.trafo.at[row, "vn_hv_kv"] * min(kvs) / max(kvs)
92
+
93
+
94
+ def check_conversion(net: Any, dss: Any = None) -> pd.DataFrame:
95
+ """Solve the converted network and the circuit it came from, and compare every bus.
96
+
97
+ Run this before anything else changes either model's loading: both engines
98
+ are solved as they stand. OpenDSS reports one voltage per phase, so its bus
99
+ voltage is the mean over the bus's phases; pandapower's converted model is
100
+ balanced and reports one. The difference that remains after the nameplate
101
+ correction is mostly that: an unbalanced feeder represented by a balanced
102
+ model, which bounds how closely any estimate built on it can match the
103
+ circuit.
104
+
105
+ Args:
106
+ net: A network from :func:`to_pandapower`, at its converted loading.
107
+ dss: The ``opendssdirect`` module with the same circuit compiled.
108
+ Defaults to importing it.
109
+
110
+ Returns:
111
+ One row per bus present in both: ``bus``, ``vm_opendss_pu``,
112
+ ``vm_pandapower_pu`` and ``difference_pu`` (pandapower minus OpenDSS).
113
+ """
114
+ import pandapower as pp
115
+
116
+ from popo.powerflow.results import bus_voltages
117
+
118
+ if dss is None:
119
+ import opendssdirect as dss
120
+
121
+ dss.Solution.Solve()
122
+ opendss = bus_voltages(dss).groupby("bus")["vmag_pu"].mean()
123
+ pp.runpp(net)
124
+ converted = pd.Series(net.res_bus.vm_pu.to_numpy(), index=net.bus.name.astype(str).str.lower())
125
+ common = converted.index.intersection(opendss.index)
126
+ frame = pd.DataFrame(
127
+ {"bus": common, "vm_opendss_pu": opendss[common].to_numpy(), "vm_pandapower_pu": converted[common].to_numpy()}
128
+ )
129
+ frame["difference_pu"] = frame["vm_pandapower_pu"] - frame["vm_opendss_pu"]
130
+ return frame
131
+
132
+
133
+ def set_loading(net: Any, active_mw: np.ndarray, reactive_mvar: np.ndarray) -> None:
134
+ """Set every load's demand for one time step.
135
+
136
+ Args:
137
+ net: A pandapower network.
138
+ active_mw: Active demand per load, in the order ``net.load`` holds them.
139
+ reactive_mvar: Reactive demand per load.
140
+
141
+ Raises:
142
+ ValueError: If either series does not have one entry per load.
143
+ """
144
+ if len(active_mw) != len(net.load) or len(reactive_mvar) != len(net.load):
145
+ raise ValueError(
146
+ f"expected {len(net.load)} values per series, got {len(active_mw)} active and {len(reactive_mvar)} reactive"
147
+ )
148
+ net.load["p_mw"] = np.asarray(active_mw, dtype=float)
149
+ net.load["q_mvar"] = np.asarray(reactive_mvar, dtype=float)
150
+
151
+
152
+ def true_state(net: Any, transformer_index: int = 0) -> tuple[np.ndarray, float, float]:
153
+ """Solve the power flow and return the state an estimator has to recover.
154
+
155
+ The substation flows are negated because pandapower reports power into the
156
+ transformer's low-voltage winding, whereas a meter at the busbar reads the
157
+ power leaving it towards the customers.
158
+
159
+ Args:
160
+ net: A pandapower network with its loading already set.
161
+ transformer_index: Transformer whose secondary flows are read.
162
+
163
+ Returns:
164
+ Per-unit voltage at every bus, active power in MW and reactive power in
165
+ Mvar at the measured busbar.
166
+ """
167
+ import pandapower as pp
168
+
169
+ pp.runpp(net, calculate_voltage_angles=True, init="flat")
170
+ voltages = net.res_bus.vm_pu.to_numpy(copy=True)
171
+ active = float(net.res_trafo.p_lv_mw.iloc[transformer_index])
172
+ reactive = float(net.res_trafo.q_lv_mvar.iloc[transformer_index])
173
+ return voltages, -active, -reactive
@@ -0,0 +1,289 @@
1
+ """Comparing coherent and incoherent substation forecasts, operationally.
2
+
3
+ A distribution operator does not consume a forecast of substation active
4
+ power, reactive power and voltage directly; it feeds the triple to a state
5
+ estimator and acts on the network state that comes out. :func:`run_comparison`
6
+ is the operational counterpart to a marginal distributional score: it asks
7
+ whether a forecast whose P, Q and V are mutually consistent produces a better
8
+ state estimate than one whose marginals are each individually well calibrated
9
+ but, taken together, describe no state the network can actually be in.
10
+
11
+ The comparison is between three substation measurement sets fed to the same
12
+ estimator at the same time step:
13
+
14
+ * ``truth`` -- the measurements a perfect forecast would report.
15
+ * ``coherent`` -- one perturbation applied to the load, propagated through a
16
+ power-flow solve, so the resulting P, Q and V triple remains a state the
17
+ network can realise.
18
+ * ``incoherent`` -- P, Q and V perturbed independently, which is what three
19
+ individually calibrated marginals produce when nothing enforces their joint
20
+ feasibility.
21
+
22
+ Everything that is network mechanics -- building the pandapower model, setting
23
+ loads, solving for the true state, and the weighted-least-squares estimate
24
+ itself -- is reused from :mod:`popo.estimation.model` and
25
+ :mod:`popo.estimation.wls`. What is new here is the construction of the three
26
+ measurement sets and the per-step bookkeeping that turns three estimates into
27
+ one comparable record.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ from dataclasses import dataclass
33
+ from typing import TYPE_CHECKING, Any
34
+
35
+ import numpy as np
36
+ import pandas as pd
37
+
38
+ from popo.estimation.model import set_loading, to_pandapower, true_state
39
+ from popo.estimation.wls import MeasurementNoise, estimate_voltages, voltage_error
40
+
41
+ if TYPE_CHECKING: # pragma: no cover - typing only
42
+ from pathlib import Path
43
+
44
+ __all__ = ["ComparisonResult", "run_comparison"]
45
+
46
+ DEFAULT_SEED = 20260904
47
+ # A domestic power factor used to derive reactive from active demand when the
48
+ # supplied load shapes carry active power only.
49
+ DEFAULT_POWER_FACTOR = 0.95
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class ComparisonResult:
54
+ """Outcome of comparing coherent and incoherent substation measurements.
55
+
56
+ Attributes:
57
+ records: One row per time step and measurement-set label (``truth``,
58
+ ``coherent``, ``incoherent``). A row carries ``converged=False``
59
+ and no error columns when the estimator did not converge for that
60
+ label, which is itself part of the answer rather than a failure to
61
+ discard.
62
+ non_converged: Number of (step, label) estimation attempts that did
63
+ not converge.
64
+ total_estimations: Estimation attempts made, three per time step for
65
+ which the underlying power flow itself solved.
66
+ """
67
+
68
+ records: pd.DataFrame
69
+ non_converged: int
70
+ total_estimations: int
71
+
72
+ @property
73
+ def converged_fraction(self) -> float:
74
+ """Share of estimation attempts that converged."""
75
+ if self.total_estimations == 0:
76
+ return 0.0
77
+ return 1.0 - self.non_converged / self.total_estimations
78
+
79
+ def summary(self) -> pd.DataFrame:
80
+ """Mean and median error per label, over the attempts that converged.
81
+
82
+ Returns:
83
+ A frame indexed by label with the mean and median of
84
+ ``rmse_vm_pu`` and ``max_abs_err_pu``. Empty if nothing converged.
85
+ """
86
+ converged = self.records[self.records["converged"]]
87
+ if converged.empty:
88
+ return pd.DataFrame()
89
+ return converged.groupby("input")[["rmse_vm_pu", "max_abs_err_pu"]].agg(["mean", "median"])
90
+
91
+
92
+ def _draw_customer_shapes(load_shapes: np.ndarray, n_load: int, rng: np.random.Generator) -> np.ndarray:
93
+ """Pick one per-unit load-shape column per customer, with replacement.
94
+
95
+ Args:
96
+ load_shapes: Per-unit household shapes, shape ``(steps, pool_size)``.
97
+ n_load: Number of customers on the feeder.
98
+ rng: Seeded generator.
99
+
100
+ Returns:
101
+ Column indices into ``load_shapes``, one per customer.
102
+ """
103
+ return rng.integers(0, load_shapes.shape[1], n_load)
104
+
105
+
106
+ def _coherent_measurements(
107
+ net: Any,
108
+ lv_bus: int,
109
+ p_mw: np.ndarray,
110
+ q_mvar: np.ndarray,
111
+ forecast_error: float,
112
+ rng: np.random.Generator,
113
+ ) -> tuple[float, float, float]:
114
+ """Perturb the load once and re-solve, so P, Q and V stay mutually consistent.
115
+
116
+ Args:
117
+ net: A pandapower network, currently loaded with the true demand.
118
+ lv_bus: Index of the measured busbar.
119
+ p_mw: True active demand per load.
120
+ q_mvar: True reactive demand per load.
121
+ forecast_error: Standard deviation of the perturbation, as a fraction
122
+ of the reading.
123
+ rng: Seeded generator.
124
+
125
+ Returns:
126
+ The perturbed-and-resolved substation voltage, active power and
127
+ reactive power.
128
+ """
129
+ scale = 1.0 + rng.normal(0.0, forecast_error)
130
+ set_loading(net, p_mw * scale, q_mvar * scale)
131
+ voltages, active_mw, reactive_mvar = true_state(net)
132
+ return float(voltages[lv_bus]), active_mw, reactive_mvar
133
+
134
+
135
+ def _incoherent_measurements(
136
+ v_true: float,
137
+ p_true: float,
138
+ q_true: float,
139
+ forecast_error: float,
140
+ rng: np.random.Generator,
141
+ ) -> tuple[float, float, float]:
142
+ """Perturb P, Q and V independently, as uncoupled marginals would.
143
+
144
+ Voltage is perturbed at a tenth of the power's error, since a forecast
145
+ marginal for a per-unit quantity close to 1.0 does not carry the same
146
+ fractional uncertainty as one for a signed power flow that can sit near
147
+ zero.
148
+
149
+ Args:
150
+ v_true: True substation voltage, in per unit.
151
+ p_true: True substation active power, in MW.
152
+ q_true: True substation reactive power, in Mvar.
153
+ forecast_error: Standard deviation of the perturbation, as a fraction
154
+ of the reading.
155
+ rng: Seeded generator.
156
+
157
+ Returns:
158
+ The three independently perturbed readings.
159
+ """
160
+ v_meas = v_true * (1.0 + rng.normal(0.0, forecast_error * 0.1))
161
+ p_meas = p_true * (1.0 + rng.normal(0.0, forecast_error))
162
+ q_meas = q_true * (1.0 + rng.normal(0.0, forecast_error))
163
+ return v_meas, p_meas, q_meas
164
+
165
+
166
+ def run_comparison(
167
+ master: Path,
168
+ load_shapes: np.ndarray,
169
+ steps: int,
170
+ smartmeter_frac: float,
171
+ forecast_error: float,
172
+ base_kw: float = 1.3,
173
+ power_factor: float = DEFAULT_POWER_FACTOR,
174
+ seed: int = DEFAULT_SEED,
175
+ noise: MeasurementNoise | None = None,
176
+ transformer_index: int = 0,
177
+ ) -> ComparisonResult:
178
+ """Compare state estimation from coherent versus incoherent substation input.
179
+
180
+ For each time step, the true demand is drawn from ``load_shapes`` and
181
+ solved for the true network state. Three substation measurement sets are
182
+ then built around that truth -- ``truth`` itself, a ``coherent``
183
+ perturbation propagated through a re-solve, and an ``incoherent``
184
+ perturbation of each quantity on its own -- and each is fed to the same
185
+ weighted-least-squares estimator, with the same smart-meter coverage, so
186
+ the only thing that differs between the three rows is whether the
187
+ measurement triple was ever a state the network could be in.
188
+
189
+ Args:
190
+ master: Master ``.dss`` file of the circuit to convert.
191
+ load_shapes: Per-unit household demand shapes, shape
192
+ ``(steps_available, pool_size)``, with ``steps_available >=
193
+ steps``. One column is drawn per customer and held fixed across
194
+ the whole run, as the original study did.
195
+ steps: Number of time steps to run.
196
+ smartmeter_frac: Fraction of customers whose meters are available as
197
+ pseudo-measurements, identical across all three labels so the
198
+ comparison isolates the effect of coherence rather than coverage.
199
+ forecast_error: Standard deviation of the measurement perturbation,
200
+ as a fraction of the reading.
201
+ base_kw: Nominal per-customer active-power scale; the load shapes
202
+ carry the time variation, this carries the magnitude.
203
+ power_factor: Assumed customer power factor, used to derive reactive
204
+ demand from the active-power shape.
205
+ seed: Seed for customer-shape assignment and for the perturbations
206
+ drawn during the run.
207
+ noise: Measurement deviations passed to the estimator; ``None`` uses
208
+ :class:`~popo.estimation.wls.MeasurementNoise`'s defaults.
209
+ transformer_index: Which transformer's secondary is the measured
210
+ busbar, passed through to :func:`~popo.estimation.model.to_pandapower`.
211
+
212
+ Returns:
213
+ A :class:`ComparisonResult` with one row per step and label.
214
+
215
+ Raises:
216
+ ValueError: If ``load_shapes`` has fewer rows than ``steps``.
217
+ """
218
+ if load_shapes.shape[0] < steps:
219
+ raise ValueError(f"load_shapes has {load_shapes.shape[0]} steps, need at least {steps}")
220
+
221
+ rng = np.random.default_rng(seed)
222
+ net, lv_bus = to_pandapower(master, transformer_index=transformer_index)
223
+ n_load = len(net.load)
224
+ pick = _draw_customer_shapes(load_shapes, n_load, rng)
225
+ reactive_ratio = np.tan(np.arccos(power_factor))
226
+
227
+ rows: list[dict[str, Any]] = []
228
+ non_converged = 0
229
+ total = 0
230
+
231
+ for step in range(steps):
232
+ shape = load_shapes[step, pick]
233
+ p_mw = shape * base_kw / 1000.0
234
+ q_mvar = p_mw * reactive_ratio
235
+ set_loading(net, p_mw, q_mvar)
236
+
237
+ try:
238
+ v_true, p_sub, q_sub = true_state(net)
239
+ except Exception: # noqa: BLE001, S112 - a non-converged power flow has nothing to estimate from # nosec B112
240
+ continue
241
+ v_sub_true = float(v_true[lv_bus])
242
+
243
+ try:
244
+ v_c_sub, p_c, q_c = _coherent_measurements(net, lv_bus, p_mw, q_mvar, forecast_error, rng)
245
+ except Exception: # noqa: BLE001, S112 # nosec B112
246
+ continue
247
+ finally:
248
+ set_loading(net, p_mw, q_mvar) # restore truth; the estimator is told the true topology state
249
+
250
+ v_i, p_i, q_i = _incoherent_measurements(v_sub_true, p_sub, q_sub, forecast_error, rng)
251
+
252
+ measurements = {
253
+ "truth": (v_sub_true, p_sub, q_sub),
254
+ "coherent": (v_c_sub, p_c, q_c),
255
+ "incoherent": (v_i, p_i, q_i),
256
+ }
257
+ for label, (voltage_pu, active_mw, reactive_mvar) in measurements.items():
258
+ total += 1
259
+ estimator_rng = np.random.default_rng(seed + step)
260
+ estimated = estimate_voltages(
261
+ net,
262
+ lv_bus,
263
+ voltage_pu,
264
+ active_mw,
265
+ reactive_mvar,
266
+ p_mw,
267
+ q_mvar,
268
+ smart_meter_fraction=smartmeter_frac,
269
+ rng=estimator_rng,
270
+ noise=noise,
271
+ )
272
+ if estimated is None:
273
+ non_converged += 1
274
+ rows.append({"step": step, "input": label, "converged": False})
275
+ continue
276
+ error = voltage_error(estimated, v_true)
277
+ rows.append(
278
+ {
279
+ "step": step,
280
+ "input": label,
281
+ "converged": True,
282
+ "rmse_vm_pu": float(np.sqrt(np.mean((estimated - v_true) ** 2))),
283
+ "max_abs_err_pu": error["max_abs_pu"],
284
+ "worst_bus_true": float(v_true.min()),
285
+ "worst_bus_est": float(estimated.min()),
286
+ }
287
+ )
288
+
289
+ return ComparisonResult(pd.DataFrame(rows), non_converged=non_converged, total_estimations=total)