material_balance

material_balance

MaterialBalanceEvents

MaterialBalanceEvents(
    dataframe: DataFrame,
    input_uuids: List[str],
    output_uuids: List[str],
    *,
    event_uuid: str = "eng:material_balance",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Material / Energy Balance

Check whether inputs and outputs balance (mass, energy, flow) per time window. The most fundamental daily engineering check for any process.

Methods: - balance_check: Per-window sum(inputs) vs sum(outputs). - imbalance_trend: Track whether imbalance is growing or shrinking. - detect_balance_exceedance: Sustained imbalance events. - contribution_breakdown: Each signal's share of total input/output.

balance_check

balance_check(
    window: str = "1h", tolerance_pct: float = 5.0
) -> pd.DataFrame

Per-window balance check: sum(inputs) vs sum(outputs).

Parameters:

Name	Type	Description	Default
window	str	Resample window.	'1h'
tolerance_pct	float	Maximum acceptable imbalance percentage.	5.0

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, total_input,
DataFrame	total_output, imbalance, imbalance_pct, balanced.

imbalance_trend

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

Track whether imbalance is growing, shrinking, or stable.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, imbalance_pct,
DataFrame	rolling_avg_imbalance, trend_direction.

detect_balance_exceedance

detect_balance_exceedance(
    window: str = "1h",
    tolerance_pct: float = 5.0,
    min_duration: str = "2h",
) -> pd.DataFrame

Detect sustained imbalance events.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	avg_imbalance_pct, max_imbalance_pct, duration_seconds,
DataFrame	likely_cause.

contribution_breakdown

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

Each signal's contribution to total input/output per window.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, uuid, role, value,
DataFrame	pct_of_total.