242 lines
9.2 KiB
Markdown
242 lines
9.2 KiB
Markdown
# Story 9.8: SystemState Dedicated Struct
|
|
|
|
Status: done
|
|
|
|
## Story
|
|
|
|
As a Rust developer,
|
|
I want a dedicated `SystemState` struct instead of a type alias,
|
|
so that I have layout validation, typed access methods, and better semantics for the solver state.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. **Given** `SystemState` is currently `Vec<f64>` in `crates/components/src/lib.rs:182`
|
|
**When** the struct is created
|
|
**Then** `pressure(edge_idx)` returns `Pressure` type
|
|
**And** `enthalpy(edge_idx)` returns `Enthalpy` type
|
|
**And** `set_pressure()` and `set_enthalpy()` accept typed physical quantities
|
|
|
|
2. **Given** a `SystemState` instance
|
|
**When** accessing data
|
|
**Then** `AsRef<[f64]>` and `AsMut<[f64]>` are implemented for solver compatibility
|
|
**And** `From<Vec<f64>>` and `From<SystemState> for Vec<f64>` enable migration
|
|
|
|
3. **Given** invalid data (odd length vector)
|
|
**When** calling `SystemState::from_vec()`
|
|
**Then** panic with clear error message
|
|
|
|
4. **Given** out-of-bounds edge index
|
|
**When** calling `pressure()` or `enthalpy()`
|
|
**Then** returns `None` (safe, no panic)
|
|
|
|
5. **Given** all tests passing before change
|
|
**When** refactoring is complete
|
|
**Then** `cargo test --workspace` passes
|
|
**And** public API is unchanged for solver consumers
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [x] Task 1: Create `SystemState` struct in `entropyk_core` (AC: 1, 3, 4)
|
|
- [x] Create `crates/core/src/state.rs` with `SystemState` struct
|
|
- [x] Implement `new(edge_count)`, `from_vec()`, `edge_count()`
|
|
- [x] Implement `pressure()`, `enthalpy()` returning `Option<Pressure/Enthalpy>`
|
|
- [x] Implement `set_pressure()`, `set_enthalpy()` accepting typed values
|
|
- [x] Implement `as_slice()`, `as_mut_slice()`, `into_vec()`
|
|
- [x] Implement `iter_edges()` iterator
|
|
|
|
- [x] Task 2: Implement trait compatibility (AC: 2)
|
|
- [x] Implement `AsRef<[f64]>` for solver compatibility
|
|
- [x] Implement `AsMut<[f64]>` for mutable access
|
|
- [x] Implement `From<Vec<f64>>` and `From<SystemState> for Vec<f64>`
|
|
- [x] Implement `Default` trait
|
|
|
|
- [x] Task 3: Export from `entropyk_core` (AC: 5)
|
|
- [x] Add `state` module to `crates/core/src/lib.rs`
|
|
- [x] Export `SystemState` from crate root
|
|
|
|
- [x] Task 4: Migrate from type alias (AC: 5)
|
|
- [x] Remove `pub type SystemState = Vec<f64>;` from `crates/components/src/lib.rs`
|
|
- [x] Add `use entropyk_core::SystemState;` to components crate
|
|
- [x] Update solver crate imports if needed
|
|
|
|
- [x] Task 5: Add unit tests (AC: 3, 4)
|
|
- [x] Test `new()` creates correct size
|
|
- [x] Test `pressure()`/`enthalpy()` accessors
|
|
- [x] Test out-of-bounds returns `None`
|
|
- [x] Test `from_vec()` with valid and invalid data
|
|
- [x] Test `iter_edges()` iteration
|
|
- [x] Test `From`/`Into` conversions
|
|
|
|
- [x] Task 6: Add documentation (AC: 5)
|
|
- [x] Add rustdoc for struct and all public methods
|
|
- [x] Document layout: `[P_edge0, h_edge0, P_edge1, h_edge1, ...]`
|
|
- [x] Add inline code examples
|
|
|
|
## Dev Notes
|
|
|
|
### Current Implementation
|
|
|
|
```rust
|
|
// crates/components/src/lib.rs:182
|
|
pub type SystemState = Vec<f64>;
|
|
```
|
|
|
|
**Layout**: Each edge in the system graph has 2 variables: `[P0, h0, P1, h1, ...]`
|
|
- `P`: Pressure in Pascals
|
|
- `h`: Enthalpy in J/kg
|
|
|
|
### Proposed Implementation
|
|
|
|
```rust
|
|
// crates/core/src/state.rs
|
|
|
|
pub struct SystemState {
|
|
data: Vec<f64>,
|
|
edge_count: usize,
|
|
}
|
|
|
|
impl SystemState {
|
|
pub fn new(edge_count: usize) -> Self;
|
|
pub fn from_vec(data: Vec<f64>) -> Self; // panics on odd length
|
|
pub fn edge_count(&self) -> usize;
|
|
|
|
pub fn pressure(&self, edge_idx: usize) -> Option<Pressure>;
|
|
pub fn enthalpy(&self, edge_idx: usize) -> Option<Enthalpy>;
|
|
pub fn set_pressure(&mut self, edge_idx: usize, p: Pressure);
|
|
pub fn set_enthalpy(&mut self, edge_idx: usize, h: Enthalpy);
|
|
|
|
pub fn as_slice(&self) -> &[f64];
|
|
pub fn as_mut_slice(&mut self) -> &mut [f64];
|
|
pub fn into_vec(self) -> Vec<f64>;
|
|
pub fn iter_edges(&self) -> impl Iterator<Item = (Pressure, Enthalpy)> + '_;
|
|
}
|
|
```
|
|
|
|
### Architecture Compliance
|
|
|
|
- **NewType Pattern**: Consistent with architecture requirement for type-safe physical quantities
|
|
- **Zero-Allocation in Hot Path**: Internal `Vec<f64>` is pre-allocated; no allocation in accessors
|
|
- **Error Handling**: Out-of-bounds returns `Option::None`, not panic (except `from_vec` with odd length)
|
|
|
|
### Files to Touch
|
|
|
|
| File | Action |
|
|
|------|--------|
|
|
| `crates/core/src/state.rs` | Create |
|
|
| `crates/core/src/lib.rs` | Add `pub mod state;` and re-export |
|
|
| `crates/components/src/lib.rs` | Remove type alias, add import from core |
|
|
| `crates/solver/src/*.rs` | Update imports if needed (may work via re-export) |
|
|
|
|
### Project Structure Notes
|
|
|
|
- `SystemState` belongs in `entropyk_core` (shared between solver and components)
|
|
- Physical types (`Pressure`, `Enthalpy`) already exist in `entropyk_core`
|
|
- Solver uses `AsRef<[f64]>` trait - no breaking change
|
|
|
|
### Testing Standards
|
|
|
|
- Use `approx` crate for float comparisons
|
|
- Tolerance: 1e-9 for exact values (matches NFR determinism requirement)
|
|
- Run `cargo test --workspace` to verify no regressions
|
|
|
|
### References
|
|
|
|
- [Source: architecture.md#Core-Architectural-Decisions] - NewType pattern requirement
|
|
- [Source: epics.md#Story-9.8] - Story definition
|
|
- [Source: crates/components/src/lib.rs:182] - Current type alias location
|
|
|
|
## Dev Agent Record
|
|
|
|
### Agent Model Used
|
|
|
|
Claude 3.5 Sonnet (via OpenCode)
|
|
|
|
### Debug Log References
|
|
|
|
N/A
|
|
|
|
### Completion Notes List
|
|
|
|
1. Created `SystemState` struct in `crates/core/src/state.rs` with:
|
|
- Typed accessor methods (`pressure()`, `enthalpy()`)
|
|
- Typed setter methods (`set_pressure()`, `set_enthalpy()`)
|
|
- `From<Vec<f64>>` and `From<SystemState> for Vec<f64>` conversions
|
|
- `AsRef<[f64]>` and `AsMut<[f64]>` implementations
|
|
- `Deref<Target=[f64]>` and `DerefMut` for seamless slice compatibility
|
|
- `Index<usize>` and `IndexMut<usize>` for backward compatibility
|
|
- `to_vec()` method for cloning data
|
|
- 25 unit tests covering all functionality
|
|
|
|
2. Updated Component trait to use `&StateSlice` (type alias for `&[f64]`) instead of `&SystemState`:
|
|
- This allows both `&Vec<f64>` and `&SystemState` to work via deref coercion
|
|
- Updated all component implementations
|
|
- Updated all solver code
|
|
|
|
3. Added `StateSlice` type alias for clarity in method signatures
|
|
|
|
### File List
|
|
|
|
- `crates/core/src/state.rs` (created)
|
|
- `crates/core/src/lib.rs` (modified)
|
|
- `crates/components/src/lib.rs` (modified)
|
|
- `crates/components/src/compressor.rs` (modified)
|
|
- `crates/components/src/expansion_valve.rs` (modified)
|
|
- `crates/components/src/fan.rs` (modified)
|
|
- `crates/components/src/pump.rs` (modified)
|
|
- `crates/components/src/pipe.rs` (modified)
|
|
- `crates/components/src/node.rs` (modified)
|
|
- `crates/components/src/flow_junction.rs` (modified)
|
|
- `crates/components/src/refrigerant_boundary.rs` (modified)
|
|
- `crates/components/src/python_components.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/exchanger.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/evaporator.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/evaporator_coil.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/condenser.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/condenser_coil.rs` (modified)
|
|
- `crates/components/src/heat_exchanger/economizer.rs` (modified)
|
|
- `crates/solver/src/system.rs` (modified)
|
|
- `crates/solver/src/macro_component.rs` (modified)
|
|
- `crates/solver/src/initializer.rs` (modified)
|
|
- `crates/solver/src/strategies/mod.rs` (modified)
|
|
- `crates/solver/src/strategies/sequential_substitution.rs` (modified)
|
|
- `crates/solver/tests/*.rs` (modified - all test files)
|
|
- `demo/src/bin/*.rs` (modified - all demo binaries)
|
|
|
|
## Senior Developer Review (AI)
|
|
|
|
**Reviewer:** Claude 3.5 Sonnet (via OpenCode)
|
|
**Date:** 2026-02-22
|
|
**Outcome:** Changes Requested → Fixed
|
|
|
|
### Issues Found
|
|
|
|
| # | Severity | Issue | Resolution |
|
|
|---|----------|-------|------------|
|
|
| 1 | HIGH | Clippy `manual_is_multiple_of` failure (crate has `#![deny(warnings)]`) | Fixed: `data.len() % 2 == 0` → `data.len().is_multiple_of(2)` |
|
|
| 2 | HIGH | Missing serde support for JSON persistence (Story 7-5 dependency) | Fixed: Added `Serialize, Deserialize` derives to `SystemState` and `InvalidStateLengthError` |
|
|
| 3 | MEDIUM | Silent failure on `set_pressure`/`set_enthalpy` hides bugs | Fixed: Added `#[track_caller]` and `debug_assert!` for early detection |
|
|
| 4 | MEDIUM | No fallible constructor (`try_from_vec`) | Fixed: Added `try_from_vec()` returning `Result<Self, InvalidStateLengthError>` |
|
|
| 5 | MEDIUM | Demo binaries have uncommitted changes | Noted: Unrelated to story scope |
|
|
|
|
### Fixes Applied
|
|
|
|
1. Added `InvalidStateLengthError` type with `std::error::Error` impl
|
|
2. Added `try_from_vec()` fallible constructor
|
|
3. Added `#[track_caller]` and `debug_assert!` to `set_pressure`/`set_enthalpy`
|
|
4. Added `Serialize, Deserialize` derives (serde already in dependencies)
|
|
5. Added 7 new tests:
|
|
- `test_try_from_vec_valid`
|
|
- `test_try_from_vec_odd_length`
|
|
- `test_try_from_vec_empty`
|
|
- `test_invalid_state_length_error_display`
|
|
- `test_serde_roundtrip`
|
|
- `test_set_pressure_out_of_bounds_panics_in_debug`
|
|
- `test_set_enthalpy_out_of_bounds_panics_in_debug`
|
|
|
|
### Test Results
|
|
|
|
- `entropyk-core`: 90 tests passed
|
|
- `entropyk-components`: 379 tests passed
|
|
- `entropyk-solver`: 211 tests passed
|
|
- Clippy: 0 warnings
|