sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/_bmad-output/implementation-artifacts/9-8-systemstate-dedicated-struct.md

9.2 KiB
Raw Permalink Blame History

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

  • Task 1: Create SystemState struct in entropyk_core (AC: 1, 3, 4)

    • Create crates/core/src/state.rs with SystemState struct
    • Implement new(edge_count), from_vec(), edge_count()
    • Implement pressure(), enthalpy() returning Option<Pressure/Enthalpy>
    • Implement set_pressure(), set_enthalpy() accepting typed values
    • Implement as_slice(), as_mut_slice(), into_vec()
    • Implement iter_edges() iterator

  • Task 2: Implement trait compatibility (AC: 2)

    • Implement AsRef<[f64]> for solver compatibility
    • Implement AsMut<[f64]> for mutable access
    • Implement From<Vec<f64>> and From<SystemState> for Vec<f64>
    • Implement Default trait

  • Task 3: Export from entropyk_core (AC: 5)

    • Add state module to crates/core/src/lib.rs
    • Export SystemState from crate root

  • Task 4: Migrate from type alias (AC: 5)

    • Remove pub type SystemState = Vec<f64>; from crates/components/src/lib.rs
    • Add use entropyk_core::SystemState; to components crate
    • Update solver crate imports if needed

  • Task 5: Add unit tests (AC: 3, 4)

    • Test new() creates correct size
    • Test pressure()/enthalpy() accessors
    • Test out-of-bounds returns None
    • Test from_vec() with valid and invalid data
    • Test iter_edges() iteration
    • Test From/Into conversions

  • Task 6: Add documentation (AC: 5)

    • Add rustdoc for struct and all public methods
    • Document layout: [P_edge0, h_edge0, P_edge1, h_edge1, ...]
    • Add inline code examples

Dev Notes

Current Implementation

// 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

// 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