217 lines
8.2 KiB
Markdown
217 lines
8.2 KiB
Markdown
# Story 8.2: CoolProp Fluids Extension & Python Real Components
|
|
|
|
Status: in-progress
|
|
|
|
## Story
|
|
|
|
As a **simulation user (Alice)**,
|
|
I want **66+ refrigerants available in CoolProp backend and real thermodynamic components in Python (not placeholders)**,
|
|
so that **I can simulate complete heat pump/chiller systems with accurate physics and multiple refrigerant options**.
|
|
|
|
## Acceptance Criteria
|
|
|
|
### AC1: Extended CoolProp Fluid List
|
|
**Given** the CoolProp backend
|
|
**When** querying available fluids
|
|
**Then** 66+ fluids are available including:
|
|
- HFC refrigerants (R134a, R410A, R32, R407C, R404A, R22, R143a, R152A, R245fa, etc.)
|
|
- HFO/Low-GWP (R1234yf, R1234ze(E), R1233zd(E), R513A, R454B, R452B)
|
|
- Natural refrigerants (R717/Ammonia, R290/Propane, R744/CO2, R1270/Propylene)
|
|
- Predefined mixtures (R513A, R507A, R452B, R454C, R455A)
|
|
- Non-refrigerant fluids (Water, Air, Nitrogen, etc.)
|
|
|
|
### AC2: Python Notebooks with Real Physics
|
|
**Given** Jupyter notebooks in `bindings/python/`
|
|
**When** running the notebooks
|
|
**Then** they demonstrate:
|
|
- Fluid properties comparison across refrigerants
|
|
- Newton/Picard solver usage
|
|
- Constraint system (superheat, subcooling, capacity)
|
|
- BoundedVariables for inverse control
|
|
- Complete thermodynamic system with refrigerant AND water circuits
|
|
|
|
### AC3: Real Thermodynamic Components in Python
|
|
**Given** Python bindings
|
|
**When** using components from Python
|
|
**Then** they use real CoolProp physics (not placeholders):
|
|
- Compressor with AHRI 540 model
|
|
- Expansion valve with isenthalpic throttling
|
|
- Heat exchanger with epsilon-NTU method and water side
|
|
- Pipe with pressure drop
|
|
- RefrigerantSource/RefrigerantSink for boundary conditions
|
|
|
|
### AC4: Complete System with Water Circuits
|
|
**Given** a heat pump simulation
|
|
**When** building the system
|
|
**Then** it includes BOTH:
|
|
- Refrigerant circuit (compressor, condenser, valve, evaporator)
|
|
- Water circuits (source side and load side)
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [x] Task 1: Extend CoolProp fluid list (AC: #1)
|
|
- [x] 1.1 Add HFC refrigerants (R143a, R152A, R22, R23, R41, R245fa, R245ca)
|
|
- [x] 1.2 Add HFO/Low-GWP (R1234yf, R1234ze(E), R1234ze(Z), R1233zd(E), R1243zf, R1336mzz(E), R513A, R513B, R454B, R452B)
|
|
- [x] 1.3 Add natural refrigerants (R717/Ammonia, R1270/Propylene)
|
|
- [x] 1.4 Add predefined mixtures (R513A, R507A, R452B, R454C, R455A)
|
|
- [x] 1.5 Update fluid_name() mappings in coolprop.rs
|
|
|
|
- [x] Task 2: Create Python notebooks (AC: #2)
|
|
- [x] 2.1 Create `fluids_examples.ipynb` - 66+ fluids guide
|
|
- [x] 2.2 Create `refrigerant_comparison.ipynb` - refrigerant comparison by application
|
|
- [x] 2.3 Create `solver_control_examples.ipynb` - solver/control API
|
|
- [x] 2.4 Create `complete_thermodynamic_system.ipynb` - complete system with water circuits
|
|
|
|
- [/] Task 3: Implement real thermodynamic components (AC: #3)
|
|
- [x] 3.1 Create `python_components.rs` with PyCompressorReal (AHRI 540)
|
|
- [x] 3.2 Implement PyExpansionValveReal (isenthalpic)
|
|
- [x] 3.3 Implement PyHeatExchangerReal (epsilon-NTU with water side)
|
|
- [x] 3.4 Implement PyPipeReal, PyFlowSourceReal, PyFlowSinkReal
|
|
- [x] 3.5 Update `components.rs` to use real components
|
|
- [/] 3.6 Fix compilation errors (in progress)
|
|
- [ ] 3.7 Build and test Python module
|
|
|
|
- [ ] Task 4: Test complete system (AC: #4)
|
|
- [ ] 4.1 Run notebooks with real physics
|
|
- [ ] 4.2 Verify solver convergence
|
|
- [ ] 4.3 Check energy balance
|
|
- [ ] 4.4 Validate against known values
|
|
|
|
## Dev Notes
|
|
|
|
### Changes Made (2026-02-22)
|
|
|
|
#### 1. CoolProp Fluids Extension
|
|
|
|
**File:** `crates/fluids/src/coolprop.rs`
|
|
|
|
Extended `available_fluids` vector from 12 to 66+ fluids:
|
|
```rust
|
|
FluidId::new("R134a"),
|
|
FluidId::new("R410A"),
|
|
FluidId::new("R32"),
|
|
// ... 60+ more fluids
|
|
```
|
|
|
|
Updated `fluid_name()` mappings for CoolProp internal names:
|
|
- Added HFC: R143a, R152A, R22, R23, R41, R245fa, R245ca
|
|
- Added HFO: R1234yf, R1234ze(E), R1234ze(Z), R1233zd(E), R1243zf, R1336mzz(E)
|
|
- Added blends: R513A, R513B, R454B, R452B, R507A
|
|
- Added naturals: R717 (Ammonia), R1270 (Propylene)
|
|
|
|
Fixed bugs:
|
|
- Duplicate pattern `"r152a" | "r152a"` → `"r152a"`
|
|
- Missing `props_si_px` function for P-Q inputs (used instead of non-existent `props_si_pq`)
|
|
- Moved helper methods `property_mixture`, `phase_mix`, `is_mixture_supported`, `is_fluid_available` to impl block (not trait)
|
|
|
|
#### 2. Python Notebooks
|
|
|
|
**Files created:**
|
|
- `bindings/python/fluids_examples.ipynb` - Guide to 66+ available fluids
|
|
- `bindings/python/refrigerant_comparison.ipynb` - Compare refrigerants by application (HVAC, commercial, industrial)
|
|
- `bindings/python/solver_control_examples.ipynb` - Newton/Picard solvers, constraints, inverse control
|
|
- `bindings/python/complete_thermodynamic_system.ipynb` - Full system with refrigerant + water circuits
|
|
|
|
#### 3. Real Thermodynamic Components
|
|
|
|
**File:** `crates/components/src/python_components.rs` (new)
|
|
|
|
Implemented real components with CoolProp physics:
|
|
|
|
```rust
|
|
pub struct PyCompressorReal {
|
|
// AHRI 540 coefficients
|
|
n: [f64; 10],
|
|
suction_port: usize,
|
|
discharge_port: usize,
|
|
// ...
|
|
}
|
|
|
|
pub struct PyHeatExchangerReal {
|
|
ua: f64, // Overall heat transfer coefficient [W/K]
|
|
water_inlet_temp: f64,
|
|
water_flow_rate: f64,
|
|
water_cp: f64, // Specific heat [J/kg/K]
|
|
refrigerant_port: usize,
|
|
water_port: usize,
|
|
}
|
|
```
|
|
|
|
**File:** `crates/components/src/lib.rs`
|
|
- Added `mod python_components;`
|
|
- Exported real component types
|
|
|
|
**File:** `bindings/python/src/components.rs`
|
|
- Rewrote to use `PyCompressorReal`, `PyHeatExchangerReal`, etc.
|
|
- Removed `SimpleAdapter` placeholder usage
|
|
|
|
**File:** `bindings/python/Cargo.toml`
|
|
- Added `[features]` section with `coolprop = ["entropyk-fluids/coolprop"]`
|
|
|
|
#### 4. Compilation Status
|
|
|
|
Current errors being fixed:
|
|
- `FluidBackend` trait requires `is_fluid_available()` method
|
|
- Helper methods moved to impl block (not trait methods)
|
|
|
|
### Architecture Context
|
|
|
|
**Key files modified:**
|
|
```
|
|
crates/fluids/src/coolprop.rs - Fluid list + name mappings
|
|
crates/components/src/python_components.rs - Real component implementations
|
|
crates/components/src/lib.rs - Module exports
|
|
bindings/python/src/components.rs - Python wrapper using real components
|
|
bindings/python/Cargo.toml - Feature flags
|
|
bindings/python/*.ipynb - Jupyter notebooks
|
|
```
|
|
|
|
**State vector layout (for reference):**
|
|
```
|
|
[P_edge0, h_edge0, P_edge1, h_edge1, ..., internal_state..., control_vars...]
|
|
```
|
|
|
|
### Critical Constraints
|
|
|
|
1. **CoolProp Feature Flag**: Must build with `--features coolprop` for real physics
|
|
2. **Type-State Pattern**: Original Rust components use type-state; Python wrappers use separate types
|
|
3. **FluidBackend Trait**: All trait methods must be implemented
|
|
4. **No Panics**: All errors must be returned as `FluidResult<T>`
|
|
|
|
### References
|
|
|
|
- [Story 2.2: CoolProp Integration](file:///Users/sepehr/dev/Entropyk/_bmad-output/implementation-artifacts/2-2-coolprop-integration-sys-crate.md)
|
|
- [Story 6.2: Python Bindings](file:///Users/sepehr/dev/Entropyk/_bmad-output/implementation-artifacts/6-2-python-bindings-pyo3.md)
|
|
- [Architecture: Fluid Backend](file:///Users/sepehr/dev/Entropyk/_bmad-output/planning-artifacts/architecture.md#Fluid-Backend)
|
|
|
|
## Dev Agent Record
|
|
|
|
### Agent Model Used
|
|
|
|
claude-3-5-sonnet (via opencode)
|
|
|
|
### Completion Notes List
|
|
|
|
- CoolProp fluid extension complete (66+ fluids)
|
|
- Python notebooks created (4 files)
|
|
- Real component implementations created
|
|
- Compilation errors being fixed
|
|
|
|
### Change Log
|
|
|
|
- 2026-02-22: Initial implementation - extended fluids, created notebooks, implemented real components
|
|
- 2026-02-22: Fixed compilation errors - duplicate patterns, missing functions, trait method issues
|
|
- 2026-02-22: Moved helper methods to impl block (not trait)
|
|
|
|
### File List
|
|
|
|
- `crates/fluids/src/coolprop.rs` - Extended fluid list, fixed mappings
|
|
- `crates/components/src/python_components.rs` - Real component implementations (new)
|
|
- `crates/components/src/lib.rs` - Module exports
|
|
- `bindings/python/src/components.rs` - Rewritten for real components
|
|
- `bindings/python/Cargo.toml` - Added coolprop feature
|
|
- `bindings/python/fluids_examples.ipynb` - Fluid guide (new)
|
|
- `bindings/python/refrigerant_comparison.ipynb` - Refrigerant comparison (new)
|
|
- `bindings/python/solver_control_examples.ipynb` - Solver/control examples (new)
|
|
- `bindings/python/complete_thermodynamic_system.ipynb` - Complete system (new)
|