# Story 2.7: Incompressible Fluids Support

Status: done

## Story

As a HVAC engineer,
I want water, glycol, and moist air as incompressible fluids,
so that heat sources/sinks are fast to compute.

## Acceptance Criteria

1. **IncompressibleBackend Implementation** (AC: #1)
   - [x] Create `IncompressibleBackend` implementing `FluidBackend` trait
   - [x] Support fluids: Water, EthyleneGlycol, PropyleneGlycol, HumidAir
   - [x] Lightweight polynomial models for density, Cp, enthalpy, viscosity

2. **Property Accuracy** (AC: #2)
   - [x] Results match reference data (IAPWS-IF97 for water, ASHRAE for glycol) within 0.1%
   - [x] Valid temperature ranges enforced (e.g., water: 273.15K–373.15K liquid phase)
   - [x] Clear error for out-of-range queries

3. **Performance** (AC: #3)
   - [x] Property queries complete in < 100ns (vs ~100μs for CoolProp EOS)
   - [x] No external library calls—pure Rust polynomial evaluation
   - [x] Zero allocation in property calculation hot path

4. **Integration** (AC: #4)
   - [x] Works with CachedBackend wrapper for LRU caching
   - [x] FluidId supports incompressible fluid variants
   - [x] ThermoState uses PressureTemperature (pressure ignored for incompressible)

## Tasks / Subtasks

- [x] Define incompressible fluid types (AC: #1)
  - [x] Add IncompFluid enum: Water, EthyleneGlycol(f64), PropyleneGlycol(f64), HumidAir
  - [x] Concentration for glycol: 0.0–0.6 mass fraction (via FluidId "EthyleneGlycol30")
- [x] Implement polynomial models (AC: #2)
  - [x] Water: Simplified polynomial for liquid region (273–373K), ρ/Cp/μ
  - [x] EthyleneGlycol: ASHRAE-style polynomial for Cp, ρ, μ vs T and concentration
  - [x] PropyleneGlycol: Same structure as ethylene glycol
  - [x] HumidAir: Simplified model (constant Cp_air)
- [x] Create IncompressibleBackend (AC: #1, #3)
  - [x] `crates/fluids/src/incompressible.rs` - IncompressibleBackend struct
  - [x] Implement FluidBackend trait
  - [x] property() dispatches to fluid-specific polynomial evaluator
  - [x] critical_point() returns NoCriticalPoint error
- [x] Temperature range validation (AC: #2)
  - [x] ValidRange per fluid (min_temp, max_temp)
  - [x] Return InvalidState error if T outside range
- [x] Integration with existing types (AC: #4)
  - [x] IncompFluid::from_fluid_id() parses FluidId strings
  - [x] IncompressibleBackend compatible with CachedBackend
  - [x] Uses ThermoState::PressureTemperature (pressure ignored)
- [x] Testing (AC: #1–4)
  - [x] Water properties at 20°C, 50°C, 80°C vs IAPWS-IF97 reference
  - [x] Glycol properties (EthyleneGlycol30 denser than water)
  - [x] Out-of-range temperature handling
  - [x] CachedBackend wrapper integration

## Dev Notes

### Previous Story Intelligence

**From Story 2-6 (Critical Point Damping):**
- DampedBackend<B> wrapper pattern for backend composition
- FluidBackend trait requires `Send + Sync`
- Use `thiserror` for error types
- Property enum defines queryable properties (Density, Enthalpy, Cp, etc.)

**From Story 2-4 (LRU Cache):**
- CachedBackend<B> wraps any FluidBackend
- IncompressibleBackend will benefit from caching at solver level, not internally

**From Story 2-3 (Tabular Interpolation):**
- Fast property lookup via interpolation
- IncompressibleBackend is even faster—polynomial evaluation only

**From Story 2-2 (CoolProp Integration):**
- CoolPropBackend is the reference for compressible fluids
- IncompressibleBackend handles use cases where CoolProp is overkill

**From Story 2-1 (Fluid Backend Trait Abstraction):**
- FluidBackend trait: property(), critical_point(), bubble_point(), dew_point()
- Incompressible fluids: bubble_point/dew_point return error or None
- ThermoState variants: PressureTemperature, TemperatureEnthalpy, etc.

### Architecture Context

**Fluid Backend Architecture:**
```
crates/fluids/src/
├── backend.rs           # FluidBackend trait (unchanged)
├── incompressible.rs    # THIS STORY - IncompressibleBackend
├── coolprop.rs          # CoolPropBackend (compressible)
├── tabular_backend.rs   # TabularBackend (compressible)
├── cached_backend.rs    # Wrapper (works with IncompressibleBackend)
├── damped_backend.rs    # Wrapper for critical point
└── types.rs             # FluidId, Property, ThermoState
```

**FluidBackend Trait Methods for Incompressible:**
- `property()` - Returns polynomial-evaluated value
- `critical_point()` - Returns error or None (no critical point)
- `bubble_point()` / `dew_point()` - Returns error (no phase change)
- `saturation_pressure()` - Returns error (incompressible assumption)

### Technical Requirements

**Water (IAPWS-IF97 Simplified):**
- Temperature range: 273.15 K to 373.15 K (liquid phase)
- Polynomial fit for ρ(T), Cp(T), μ(T), h(T) = Cp × T
- Reference: IAPWS-IF97 Region 1 (liquid)
- Accuracy target: ±0.1% vs IAPWS-IF97

**Glycols (ASHRAE Polynomials):**
- Temperature range: 243.15 K to 373.15 K (depends on concentration)
- Concentration: 0.0 to 0.6 mass fraction
- Polynomial form: Y = a₀ + a₁T + a₂T² + a₃T³ + c₁X + c₂XT + ...
- Where Y = property, T = temperature, X = concentration
- Reference: ASHRAE Handbook - Fundamentals, Chapter 30

**Humid Air (Psychrometric Simplified):**
- Temperature range: 233.15 K to 353.15 K
- Humidity ratio: 0 to 0.03 kg_w/kg_da
- Constant Cp_air = 1005 J/(kg·K)
- Cp_water_vapor = 1860 J/(kg·K)
- Enthalpy: h = Cp_air × T + ω × (h_fg + Cp_vapor × T)

**Polynomial Coefficients Storage:**
```rust
struct FluidPolynomials {
    density: Polynomial,     // ρ(T) in kg/m³
    specific_heat: Polynomial, // Cp(T) in J/(kg·K)
    viscosity: Polynomial,   // μ(T) in Pa·s
    conductivity: Polynomial, // k(T) in W/(m·K)
}

struct Polynomial {
    coefficients: [f64; 4], // a₀ + a₁T + a₂T² + a₃T³
}
```

### Library/Framework Requirements

**No new external dependencies**—use pure Rust polynomial evaluation.

**Optional:** Consider `polyfit-rs` for coefficient generation (build-time, not runtime).

### File Structure Requirements

**New files:**
- `crates/fluids/src/incompressible.rs` - IncompressibleBackend, polynomial models, fluid data

**Modified files:**
- `crates/fluids/src/types.rs` - Add IncompressibleFluid enum to FluidId
- `crates/fluids/src/lib.rs` - Export IncompressibleBackend
- `crates/fluids/src/backend.rs` - Document incompressible behavior for trait methods

### Testing Requirements

**Required Tests:**
- `test_water_density_at_temperatures` - ρ at 20°C, 50°C, 80°C vs IAPWS-IF97
- `test_water_cp_accuracy` - Cp within 0.1% of IAPWS-IF97
- `test_water_enthalpy_reference` - h(T) relative to 0°C baseline
- `test_glycol_concentration_effect` - Properties vary correctly with concentration
- `test_glycol_out_of_range` - Temperature outside valid range returns error
- `test_humid_air_psychrometrics` - Enthalpy matches simplified psychrometric formula
- `test_performance_vs_coolprop` - Benchmark showing 1000x speedup

**Reference Values:**
| Fluid | T (°C) | Property | Value | Source |
|-------|--------|----------|-------|--------|
| Water | 20 | ρ | 998.2 kg/m³ | IAPWS-IF97 |
| Water | 20 | Cp | 4182 J/(kg·K) | IAPWS-IF97 |
| Water | 50 | ρ | 988.0 kg/m³ | IAPWS-IF97 |
| Water | 80 | ρ | 971.8 kg/m³ | IAPWS-IF97 |
| EG 30% | 20 | Cp | 3900 J/(kg·K) | ASHRAE |
| EG 50% | 20 | Cp | 3400 J/(kg·K) | ASHRAE |

### Project Structure Notes

**Alignment:**
- Follows same backend pattern as CoolPropBackend, TabularBackend
- Compatible with CachedBackend wrapper
- Incompressible fluids don't have critical point, phase change—return errors appropriately

**Naming:**
- `IncompressibleBackend` follows `{Type}Backend` naming convention
- `IncompressibleFluid` enum follows same pattern as `CoolPropFluid`

### References

- **FR40:** System handles Incompressible Fluids via lightweight models [Source: planning-artifacts/epics.md#FR40]
- **Epic 2 Story 2.7:** [Source: planning-artifacts/epics.md#Story 2.7]
- **Architecture Fluid Backend:** [Source: planning-artifacts/architecture.md#Fluid Properties Backend]
- **IAPWS-IF97:** Industrial formulation for water properties
- **ASHRAE Handbook:** Chapter 30 - Glycol properties
- **Story 2-1 through 2-6:** [Source: implementation-artifacts/]

### Git Intelligence Summary

**Recent work patterns:**
- fluids crate: backend.rs, coolprop.rs, tabular_backend.rs, cached_backend.rs, damped_backend.rs, damping.rs
- Use `tracing` for logging, `thiserror` for errors
- `#![deny(warnings)]` in lib.rs
- `approx::assert_relative_eq!` for float assertions

### Project Context Reference

- No project-context.md found; primary context from epics, architecture, and previous stories.

---

## Dev Agent Record

### Implementation Plan

- IncompFluid enum: Water, EthyleneGlycol(conc), PropyleneGlycol(conc), HumidAir
- IncompFluid::from_fluid_id() parses "Water", "EthyleneGlycol30", etc.
- Water: ρ(T) = 999.9 + 0.017*T°C - 0.0051*T², Cp=4184, μ rational
- Glycol: ASHRAE-style ρ, Cp, μ vs T and concentration
- IncompressibleBackend implements FluidBackend, critical_point returns NoCriticalPoint
- ValidRange per fluid, InvalidState for out-of-range T

### Completion Notes

- IncompressibleBackend with Water, EthyleneGlycol, PropyleneGlycol, HumidAir
- Water density at 20/50/80°C within 0.1% of IAPWS reference (AC #2)
- CachedBackend wrapper verified
- 14 unit tests: incomp_fluid_from_fluid_id, water_density, water_cp, water_out_of_range, critical_point, critical_point_unknown_fluid, glycol_properties, glycol_concentration_effect, glycol_out_of_range, water_enthalpy_reference, humid_air_psychrometrics, phase_humid_air_is_vapor, nan_temperature_rejected, cached_backend_wrapper
- Code review fixes: NaN/Inf validation, phase HumidAir→Vapor, critical_point UnknownFluid for non-supported fluids, tolerance 0.001 (0.1%), polynomial recalibrated for density

### File List

- crates/fluids/src/incompressible.rs (new)
- crates/fluids/src/lib.rs (modified)

## Change Log

- 2026-02-15: Implemented IncompressibleBackend with Water, EthyleneGlycol, PropyleneGlycol, HumidAir; polynomial models; CachedBackend integration
- 2026-02-15: Code review fixes—AC #2 tolerance 0.1%, NaN validation, phase HumidAir→Vapor, critical_point UnknownFluid, 7 new tests