Skip to content

MaterialBalanceEvents¤

Check whether inputs and outputs balance (mass, energy, flow) per time window.

Module: ts_shape.events.engineering.material_balance
Guide: Process Engineering

When to Use¤

Use as a fundamental daily engineering check for any process. Validates conservation of mass/energy across inputs and outputs. Imbalances indicate leaks, measurement errors, or unaccounted streams. Essential for process accounting, yield tracking, and regulatory compliance.

Quick Example¤

from ts_shape.events.engineering.material_balance import MaterialBalanceEvents

checker = MaterialBalanceEvents(
    df=flow_data,
    uuid="input_flow_total"
)

# Check balance within 5% tolerance per hour
balance = checker.balance_check(window="1h", tolerance_pct=5.0)

# Track imbalance trend over time
trend = checker.imbalance_trend(window="1h")

# Detect sustained imbalance periods
exceedances = checker.detect_balance_exceedance(
    window="1h",
    tolerance_pct=5.0
)

# Break down each signal's contribution to the imbalance
breakdown = checker.contribution_breakdown(window="1h")

Key Methods¤

Method Purpose Returns
balance_check(window='1h', tolerance_pct=5.0) Balance pass/fail per window DataFrame with balance status
imbalance_trend(window='1h') Imbalance trend over time DataFrame with imbalance values
detect_balance_exceedance(window='1h', tolerance_pct=5.0) Sustained imbalance intervals DataFrame of exceedance events
contribution_breakdown(window='1h') Signal-level contributions DataFrame with per-signal breakdown

Tips & Notes¤

Start with contribution_breakdown when imbalance is detected

When balance_check() fails, use contribution_breakdown() to identify which specific input or output stream is responsible. This narrows the investigation to one sensor or pipe instead of chasing the entire process.

Related modules

See Also¤