# 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)