sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/_bmad-output/implementation-artifacts/8-2-coolprop-fluids-extension-python-real-components.md

8.2 KiB
Raw Blame History

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
  • FlowSource/FlowSink 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

  • Task 1: Extend CoolProp fluid list (AC: #1)

    • 1.1 Add HFC refrigerants (R143a, R152A, R22, R23, R41, R245fa, R245ca)
    • 1.2 Add HFO/Low-GWP (R1234yf, R1234ze(E), R1234ze(Z), R1233zd(E), R1243zf, R1336mzz(E), R513A, R513B, R454B, R452B)
    • 1.3 Add natural refrigerants (R717/Ammonia, R1270/Propylene)
    • 1.4 Add predefined mixtures (R513A, R507A, R452B, R454C, R455A)
    • 1.5 Update fluid_name() mappings in coolprop.rs

  • Task 2: Create Python notebooks (AC: #2)

    • 2.1 Create fluids_examples.ipynb - 66+ fluids guide
    • 2.2 Create refrigerant_comparison.ipynb - refrigerant comparison by application
    • 2.3 Create solver_control_examples.ipynb - solver/control API
    • 2.4 Create complete_thermodynamic_system.ipynb - complete system with water circuits

  • [/] Task 3: Implement real thermodynamic components (AC: #3)

    • 3.1 Create python_components.rs with PyCompressorReal (AHRI 540)
    • 3.2 Implement PyExpansionValveReal (isenthalpic)
    • 3.3 Implement PyHeatExchangerReal (epsilon-NTU with water side)
    • 3.4 Implement PyPipeReal, PyFlowSourceReal, PyFlowSinkReal
    • 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:

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:

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

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)