POWER_FACTOR_CORRECTION
Drives the site power factor to a target by injecting or absorbing reactive power.
| Mode string | POWER_FACTOR_CORRECTION (EMS_OP_POWER_FACTOR_CORRECTION) |
| Dispatcher | ems_main.py → control_logic_updated.control_step_power_factor_correction |
| Config block | functions.Power_Factor_Correction |
| Queue action | set_reactive_kvar (via _pcs_connect_and_set_reactive_power_kvar) |
| Queue source tag | power_factor_correction |
| Status | Implemented, actuation gated off by default |
Purpose
Reads grid P, Q and power factor, computes the reactive power needed to move the power factor to
target_pf within pf_deadband, and applies it.
How it decides
_pf_correction_q_kvar(P, Q, pf, cfg) returns the required total kvar, or None when it cannot
compute:
Nonewhen P, Q or PF telemetry is missing.Nonewhentarget_pfis absent or non-positive.- When
|pf - target_pf| <= pf_deadbandthe correction is 0 — inside the deadband, nothing moves. - With
mode: "auto"the sign is chosen automatically so the correction always moves the actual PF towards the target rather than away from it (leading vs lagging depends on whether Q is already injective). - The result magnitude is bounded by
q_max_kvar.
If the computed command is None the step logs the reason and returns without actuating.
Configuration
functions.Power_Factor_Correction
| Key | Live value | Meaning |
|---|---|---|
enabled |
false |
Master switch. |
target_pf |
0.98 |
Target power factor. |
pf_deadband |
0.01 |
Deadband around the target; no action inside it. |
mode |
auto |
Direction selection (auto picks the sign). |
q_max_kvar |
null |
Reactive ceiling. null ⇒ no action. |
ramp_rate_limit_kvar_s |
null |
Ramp limit for the reactive setpoint. |
response_time_ms |
null |
Recorded; not used. |
soc_limits |
{null, null} |
SOC bounds. |
power_caps_kw |
{null, null} |
Active-power caps (reserved). |
priority_rule |
pf_correction_over_valley_arbitrage |
Outranks arbitrage/valley filling. |
reactive_power_actuation |
enabled: false |
Same gate as Volt-VAR — see below. |
The actuation gate
Identical mechanism to Voltage_Support: the required kvar is computed and logged
every cycle, but nothing is queued unless reactive_power_actuation.enabled is true and
register is non-null. Both a verified register in the PCS power sequence and an explicit operator
opt-in are required.
Safety
- Returns when
is_external_control_active(), whenenabledis false, or with no active PCS. - Returns when P/Q/PF telemetry is unavailable, or when
q_max_kvaris missing/invalid. - Deadband prevents hunting around the target.
- Total kvar split equally across active PCS; each clamped to that PCS's
reactive_power_limits.max_capacitive_kvar/max_inductive_kvarbefore queueing. - Only the newest unapplied reactive setpoint is retained in the queue.
Shared reactive slot: this mode and Volt-VAR share one reactive queue slot. Whichever runs most recently overwrites the other's pending command.
Outputs
_pcs_connect_and_set_reactive_power_kvar(cfg, pcs_id, kvar) → queue action set_reactive_kvar,
source power_factor_correction.