assign_household_profiles#

popo.scenarios.assign_household_profiles(dss, customers, profiles, rng, reactive_profiles=None, name_prefix='hh')#

Give each of a circuit’s existing base loads a time-varying demand shape.

This is the mechanism popo.powerflow.sweep.run_uk_sweep()/ run_us_sweep’s build_circuit callback needs to turn a household profile pool (popo.profiles) into something OpenDSS replays: it edits each existing Load element to reference a new loadshape, rather than creating a load the way attach_generation()/ attach_charging() do, because the feeder definition already carries each customer’s rated kW (and, for SMART-DS, kvar) – only the per-interval multiplier is missing.

Parameters:

  • dss (Any) – An opendssdirect module with a compiled circuit.

  • customers (Sequence[tuple[str, str]]) – (load name, bus) pairs to assign a shape to, e.g. from popo.network.transformers.residential_loads().

  • profiles (ndarray) – Active-power per-unit pool, shape (intervals, columns). A column is drawn per customer, with replacement, since there are usually far more customers than columns in the pool.

  • rng (Generator) – Seeded generator for the column draw.

  • reactive_profiles (ndarray | None) – Paired reactive-power per-unit pool, same shape as profiles and drawn with the same column index, e.g. from popo.profiles.smartds.load_pool(). None leaves the load’s existing kvar/power factor as the feeder definition set it, i.e. a fixed power factor.

  • name_prefix (str) – Loadshape name prefix, distinct per customer.

Return type:

int

Returns:

Number of loads assigned a shape. A customer whose drawn column is entirely zero is skipped, since a zero-peak shape cannot be normalised to per-unit.