Entropyk/_bmad-output/implementation-artifacts/7-2-energy-balance-validation.md

Story 7.2: energy-balance-validation

Status: in-progress

Story

As a simulation engineer, I want First AND Second Law verification across the thermodynamic system, so that thermodynamic consistency is guaranteed, giving me confidence in the simulation results.

Acceptance Criteria

1. Given converged solution When computing balances Then energy error \Sigma \dot{Q} + \dot{W} - \Sigma (\dot{m} \cdot h) < 1\mathrm{e-}6 kW (First Law)
2. Given converged solution When computing balances Then violations trigger a validation error with a breakdown of error contribution
3. Given converged solution When checking Second Law Then entropy generation \Sigma (\dot{m} \cdot s) - \Sigma \frac{\dot{Q}}{T} \geq 0
4. Given converged solution When checking Second Law Then trigger a warning (or error) if there is negative entropy destruction
5. Given converged solution When computing balances Then tests are added and checks are performed after every solve alongside mass balance.

Tasks / Subtasks

• Task 1: Component Trait Extension for Energy/Entropy (AC: 1, 3)
  • Add energy_transfers(&self, state: &SystemState) -> Option<(Power, Power)> (e.g. returning Heat \dot{Q} and Work \dot{W}) or similar to Component trait, or allow components to report \dot{Q} and \dot{W}.
  • Add default implementation for adiabatic/passive components (e.g., Pipes, Valves return 0.0).
  • Update components (Compressor, Condenser, Evaporator, etc.) to report their specific work and heat transfer.
  • Ensure entropy generation can be calculated (requires fetching Entropy from FluidBackend if not already exposed).
• Task 2: Implement check_energy_balance in System (AC: 1, 2)
  • Add check_energy_balance(&self, state: &StateSlice) to crates/solver/src/system.rs.
  • Iterate over all components/nodes, computing \Sigma \dot{Q} + \dot{W} and subtracting \Sigma (\dot{m} \cdot h_{out} - \dot{m} \cdot h_{in}).
  • Compare total energy residual against the 1\mathrm{e-}6 kW threshold.
• Task 3: Implement Second Law Check (AC: 3, 4)
  • Implement check_entropy_generation(&self, state: &StateSlice, backend: &dyn FluidBackend) to verify \Sigma \Delta s \geq 0.
  • Log a warning (tracing::warn!) if entropy generation is negative (impossible thermodynamic state).
• Task 4: Hook into Solver & Error Handling (AC: 2, 5)
  • Call both check_energy_balance and check_entropy_generation in solver.rs right after check_mass_balance.
  • Update ThermoError::Validation to properly report energy_error values, providing breakdowns if applicable.
• Task 5: Unit and Integration Testing (AC: 5)
  • Write a unit test test_energy_balance_pass with a known good state.
  • Write a unit test test_energy_balance_fail creating an artificial energy imbalance.
  • Write tests verifying Second Law warnings.

Review Follow-ups (AI)

• [AI-Review][High] No codebase implementation found for this story. All tasks and ACs remain undone.
• [AI-Review][Medium] No tests implemented.
• [AI-Review][High] 25 files modified in git, but File List in story is empty. Ensure changes are committed or documented.

Dev Notes

• Architecture Patterns & Constraints:
  • Zero-Panic Policy: Return ThermoError::Validation if energy balance fails. No unwraps in the validation logic.
  • Scientific Testing Patterns: Use approx::assert_relative_eq!(..., epsilon = 1e-6) for energy tolerance.
  • Physical Types: Ensure mathematical operations on Power, MassFlow, Enthalpy, Temperature, and Entropy are type-safe. Convert to primitive floats safely if doing aggregate sums, but ensure unit consistency (e.g. converting MassFlow * Enthalpy (kg/s * J/kg = W) to kW properly).
• Recent Git Intelligence (from Story 7.1):
  • In story 7.1 (check_mass_balance), a new trait method port_mass_flows(&self, state: &SystemState) was added to Component. We likely need a similar trait method or pair of methods (heat_transfer, work_transfer) to query individual component's energy interactions.
  • Ensure compatibility with MacroComponent if it needs to flatten energy balances.
• Source Tree Components to Touch:
  • crates/components/src/lib.rs (Component trait additions for energy/entropy)
  • Specific components like crates/components/src/compressor.rs, heat_exchanger/*.rs to implement the new trait methods.
  • crates/solver/src/system.rs (Energy and entropy balancing logic)
  • crates/solver/src/solver.rs (Hooks for validation after convergence)
  • crates/core/src/types.rs (If Entropy newtype is missing)
• Testing Standards:
  • All warnings (clippy -D warnings, etc.) must pass.
  • Validation requires checking the overall $\Sigma$-balances. For testing, it's easiest to mock a small 2-3 component topology or use the existing integration tests in tests/validation/energy_balance.rs mentioned in prior stories.

Project Structure Notes

• The changes squarely fit into the defined Component and System architecture boundary. Modifications are internal to the component and solver logic and do not violate any FFI boundaries directly.

References

• [Source: _bmad-output/planning-artifacts/epics.md] - Epic 7, Story 7.2 Requirements & FR36, FR39
• [Source: _bmad-output/planning-artifacts/architecture.md#Error-Handling-Strategy] - Error Handling
• [Source: _bmad-output/planning-artifacts/architecture.md#Scientific-Testing-Patterns] - Testing Patterns definition

Dev Agent Record

Agent Model Used

BMad Create Story Workflow (Claude 3.5 Sonnet / Antigravity)

Debug Log References

Completion Notes List

• The story 7-2-energy-balance-validation.md has been created adhering strictly to the architecture and context guidelines.

File List

• _bmad-output/implementation-artifacts/7-2-energy-balance-validation.md