# Story 1.10: Pipe Helpers for Water and Refrigerant

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a HVAC engineer modeling refrigerant and incompressible fluid circuits (water, seawater, glycol),
I want convenient constructors `Pipe::for_incompressible()` and `Pipe::for_refrigerant()` with explicit ρ/μ from a fluid backend,
So that I can create pipes without hardcoding fluid properties in the component.

**Architecture:** Fluid properties (ρ, μ) belong in the fluids crate (Story 2.7 IncompressibleBackend).
Pipe must NOT hardcode water/glycol properties—user obtains them from FluidBackend.

## Acceptance Criteria

1. **Pipe::for_incompressible** (AC: #1)
   - [x] `Pipe::for_incompressible(geometry, port_inlet, port_outlet, density, viscosity)` — explicit ρ, μ from backend
   - [x] Doc states: obtain ρ, μ from IncompressibleBackend (water, seawater, glycol)—do not hardcode
   - [x] Doc examples show water and glycol circuit usage

2. **Pipe::for_refrigerant** (AC: #2)
   - [x] `Pipe::for_refrigerant(geometry, port_inlet, port_outlet, density, viscosity)` — explicit ρ, μ at design point
   - [x] Doc states ρ, μ vary with P,T — design-point values from CoolProp/tabular
   - [x] Doc examples show refrigerant circuit usage

3. **Documentation** (AC: #3)
   - [x] Module-level doc: Pipe serves refrigerant and incompressible (water, seawater, glycol)
   - [x] "Fluid Support" section: refrigerant (ρ/μ from backend) vs incompressible (ρ/μ from IncompressibleBackend)
   - [x] No hardcoded fluid properties in components crate

## Tasks / Subtasks

- [x] Add Pipe::for_incompressible (AC: #1)
  - [x] Constructor accepting (geometry, ports, density, viscosity)
  - [x] Doc: obtain from IncompressibleBackend, do not hardcode
- [x] Add Pipe::for_refrigerant (AC: #2)
  - [x] Constructor accepting (geometry, ports, density, viscosity)
  - [x] Doc: design-point values from CoolProp/tabular
- [x] Update documentation (AC: #3)
  - [x] pipe.rs module doc: Fluid Support section
  - [x] Pipe struct doc: dual refrigerant/incompressible usage
  - [x] Doc tests for both constructors
- [x] Tests
  - [x] test_pipe_for_incompressible_creation
  - [x] test_pipe_for_incompressible_glycol
  - [x] test_pipe_for_refrigerant_creation
  - [x] test_pipe_inlet_outlet_same_fluid

## Dev Notes

### Previous Story Intelligence

**From Story 1.8 (Auxiliary & Transport):**
- Pipe uses Darcy-Weisbach, Haaland friction factor
- PipeGeometry: length_m, diameter_m, roughness_m
- Pipe::new(geometry, port_inlet, port_outlet, fluid_density, fluid_viscosity)
- Already validates inlet/outlet same FluidId

### Typical Values

| Fluid | ρ (kg/m³) | μ (Pa·s) |
|-------|-----------|----------|
| Water 20°C | 998 | 0.001 |
| Water 40°C | 992 | 0.00065 |
| R134a liquid 40°C | ~1140 | ~0.0002 |
| R410A liquid 40°C | ~1050 | ~0.00015 |

### References

- pipe.rs: Pipe::new, PipeGeometry
- port.rs: FluidId, Port
- Story 2.7: Incompressible fluids (water polynomial when done)

## Dev Agent Record

### Implementation Plan

- Added `Pipe::for_incompressible(geometry, port_inlet, port_outlet, density, viscosity)` — no hardcoding
- Added `Pipe::for_refrigerant(geometry, port_inlet, port_outlet, density, viscosity)`
- Module doc: Fluid Support section (refrigerant vs incompressible)
- Pipe struct doc: dual refrigerant/incompressible usage
- **Architecture**: Properties (ρ, μ) obtained from FluidBackend (IncompressibleBackend for water/glycol)

### Completion Notes

- for_incompressible and for_refrigerant: explicit ρ, μ from user (who gets from backend)
- No hardcoded water/glycol properties in components crate
- Unit tests: test_pipe_for_incompressible_creation, test_pipe_for_incompressible_glycol, test_pipe_for_refrigerant_creation

### Architecture Refactor (2026-02-15)

- **Removed** for_water, for_water_at_temp — hardcoded water-only properties (violated FR40, Story 2.7)
- **Replaced** with for_incompressible(density, viscosity) — user provides ρ, μ from IncompressibleBackend
- Water, seawater, glycol have different properties — must not hardcode in components

### Code Review Fixes (2026-02-21)

- Fixed solver bug where `jacobian_entries` unconditional numerical gradient calculation applied to `Off`/`Bypass` states.
- Fixed `compute_residuals` for `OperationalState::Bypass` to correctly output zero pressure drop (`p_in - p_out`).
- Fixed Haaland friction factor clipping the regularized Reynolds number improperly to `1.0`, breaking linear laminar pressure drop curve near 0 flow.
- Removed dead and unused code (`swamee_jain` and `simplified` friction factors).
- Refined numerical differentiation stepping `h` to avoid numerical instability for zero/tiny mass flows.

## File List

- crates/components/src/pipe.rs (modified)

## Change Log

- 2026-02-15: Implemented Pipe::for_water, Pipe::for_water_at_temp, Pipe::for_refrigerant
- 2026-02-15: Code review fixes
- 2026-02-15: **Architecture refactor** — Removed hardcoded water properties; replaced with Pipe::for_incompressible(density, viscosity). Properties from FluidBackend (Story 2.7).
- 2026-02-21: Fixed logic and numerical stability issues found during adversarial code review.