citylearn.internal.electrical_limits module
Side-effect-free allocation of signed electrical-service requests, in kW.
Positive power imports/consumes; negative power exports/supplies. Callers provide their own base-load estimate and phase split. This calculation reduces requests proportionally; it neither dispatches devices nor guarantees that fixed loads alone satisfy the service limits. Device physics and sequential outage supply checks remain the runtime’s responsibility.
- class citylearn.internal.electrical_limits.ElectricalServiceAllocation(scales: 'Dict[str, float]', total_kw: 'float', phase_kw: 'Dict[str, float]', requested_violation_kw: 'float', residual_violation_kw: 'float')[source]
Bases:
object- phase_kw: Dict[str, float]
- requested_violation_kw: float
- residual_violation_kw: float
- scales: Dict[str, float]
- total_kw: float
- class citylearn.internal.electrical_limits.PowerRequest[source]
Bases:
TypedDict- request_phase_kw: Mapping[str, float]
- request_total_kw: float
- citylearn.internal.electrical_limits.allocate_electrical_service(base_total_kw: float, base_phase_kw: Mapping[str, float], controls: Mapping[str, PowerRequest], total_limits: Mapping[str, float | None], per_phase_limits: Mapping[str, Mapping[str, float | None]], phase_names: Sequence[str]) ElectricalServiceAllocation[source]
Return reductions and pressure without mutating any input or device.
Preserve the established eight-pass maximum, scope order (total, then the supplied phases) and import-before-export order. Every scope reads totals after earlier reductions; opposite-sign controls can couple scopes, requiring a later pass. Scales only decrease, preserving proportional sharing within each constrained group. There is no redistribution or service prioritisation.
- citylearn.internal.electrical_limits.electrical_service_violation_kw(total_kw: float, phase_kw: Mapping[str, float], total_limits: Mapping[str, float | None], per_phase_limits: Mapping[str, Mapping[str, float | None]], phase_names: Sequence[str]) float[source]
Sum requested/residual excess over total and phase limits, in kW.
This pressure metric counts each scope separately; it is not unmet energy. Missing/non-finite limits are unbounded, as in the service configuration.