87 lines
6.0 KiB
Markdown
87 lines
6.0 KiB
Markdown
# Story 7.2: energy-balance-validation
|
|
|
|
Status: in-progress
|
|
|
|
<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
|
|
|
|
## 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`
|