control_loop_health

control_loop_health ¤

ControlLoopHealthEvents ¤

ControlLoopHealthEvents(
    dataframe: DataFrame,
    setpoint_uuid: str,
    actual_uuid: str,
    *,
    output_uuid: Optional[str] = None,
    event_uuid: str = "eng:control_loop_health",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Control Loop Health

Continuously assess PID/control loop health from setpoint + actual pairs, independent of setpoint changes. Computes error integrals, detects oscillation in the error signal, and checks for valve saturation.

Methods: - error_integrals: Per-window IAE, ISE, ITAE, bias. - detect_oscillation: Sustained oscillation in the error signal. - output_saturation: Valve pegged at limits. - loop_health_summary: Shift-level report card.

error_integrals ¤

error_integrals(window: str = '1h') -> pd.DataFrame

Per-window error integrals for control loop performance.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window (e.g. '1h', '8h').	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, iae, ise, itae, bias,
`DataFrame`	sample_count.

detect_oscillation ¤

detect_oscillation(
    window: str = "5min", min_crossings: int = 4
) -> pd.DataFrame

Detect sustained oscillation in the error signal.

Parameters:

Name	Type	Description	Default
`window`	`str`	Analysis window size.	`'5min'`
`min_crossings`	`int`	Minimum zero-crossings to flag oscillation.	`4`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, uuid, is_delta,
`DataFrame`	crossing_count, estimated_period_seconds, amplitude,
`DataFrame`	damping_direction.

output_saturation ¤

output_saturation(
    high_limit: float = 100.0,
    low_limit: float = 0.0,
    window: str = "1h",
) -> pd.DataFrame

Detect when controller output is pegged at limits.

Requires output_uuid in constructor.

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, pct_time_at_high,
`DataFrame`	pct_time_at_low, pct_time_saturated, longest_saturation_seconds.

loop_health_summary ¤

loop_health_summary(window: str = '8h') -> pd.DataFrame

Shift-level report card combining all loop health metrics.

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, iae, bias,
`DataFrame`	oscillation_count, pct_saturated, health_grade.