chore: remove deprecated flow_boundary and update docs to match new architecture
This commit is contained in:
Sepehr
319
docs/migration/boundary-conditions.md
Normal file
319
docs/migration/boundary-conditions.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# Migration Guide: Boundary Conditions
|
||||
|
||||
## Overview
|
||||
|
||||
The `FlowSource` and `FlowSink` types have been replaced with typed alternatives that provide better type safety and more explicit fluid handling:
|
||||
|
||||
| Old Type | New Type | Use Case |
|
||||
|----------|----------|----------|
|
||||
| `FlowSource` | `RefrigerantSource` | Refrigerants (R410A, R134a, CO₂, etc.) |
|
||||
| `FlowSource` | `BrineSource` | Liquid heat transfer fluids (water, glycol, brine) |
|
||||
| `FlowSource` | `AirSource` | Humid air (HVAC applications) |
|
||||
| `FlowSink` | `RefrigerantSink` | Refrigerants |
|
||||
| `FlowSink` | `BrineSink` | Liquid heat transfer fluids |
|
||||
| `FlowSink` | `AirSink` | Humid air |
|
||||
|
||||
## Deprecation Timeline
|
||||
|
||||
| Version | Status |
|
||||
|---------|--------|
|
||||
| 0.2.0 | Deprecation warnings added |
|
||||
| 0.3.0 | Old types hidden behind feature flag |
|
||||
| 1.0.0 | Complete removal of old types |
|
||||
|
||||
## Migration Examples
|
||||
|
||||
### Water Source
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
use entropyk_components::FlowSource;
|
||||
|
||||
let source = FlowSource::incompressible("Water", 3.0e5, 63_000.0, port)?;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::BrineSource;
|
||||
use entropyk_core::{Pressure, Temperature, Concentration};
|
||||
use entropyk_fluids::CoolPropBackend;
|
||||
use std::sync::Arc;
|
||||
|
||||
let backend = Arc::new(CoolPropBackend::new());
|
||||
|
||||
let source = BrineSource::new(
|
||||
"Water", // Fluid name
|
||||
Pressure::from_pascals(3.0e5), // Pressure
|
||||
Temperature::from_celsius(15.0), // Temperature
|
||||
Concentration::zero(), // No glycol
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Glycol Mixture Source
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
use entropyk_components::FlowSource;
|
||||
|
||||
// MEG at 30% concentration, 3 bar, -5°C
|
||||
let source = FlowSource::incompressible("MEG", 3.0e5, 20_000.0, port)?;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::BrineSource;
|
||||
use entropyk_core::{Pressure, Temperature, Concentration};
|
||||
use entropyk_fluids::CoolPropBackend;
|
||||
use std::sync::Arc;
|
||||
|
||||
let backend = Arc::new(CoolPropBackend::new());
|
||||
|
||||
let source = BrineSource::new(
|
||||
"MEG", // Fluid name
|
||||
Pressure::from_pascals(3.0e5), // Pressure
|
||||
Temperature::from_celsius(-5.0), // Temperature
|
||||
Concentration::from_percent(30.0), // 30% glycol concentration
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Refrigerant Source
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
use entropyk_components::FlowSource;
|
||||
|
||||
// R410A at 10 bar, enthalpy 280 kJ/kg
|
||||
let source = FlowSource::compressible("R410A", 10.0e5, 280_000.0, port)?;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::RefrigerantSource;
|
||||
use entropyk_core::{Pressure, VaporQuality};
|
||||
use entropyk_fluids::CoolPropBackend;
|
||||
use std::sync::Arc;
|
||||
|
||||
let backend = Arc::new(CoolPropBackend::new());
|
||||
|
||||
// Option 1: Using pressure and vapor quality
|
||||
let source = RefrigerantSource::new(
|
||||
"R410A",
|
||||
Pressure::from_pascals(10.0e5),
|
||||
VaporQuality::from_fraction(0.5), // 50% vapor quality
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
|
||||
// Option 2: Using saturated vapor (quality = 1)
|
||||
let source = RefrigerantSource::new(
|
||||
"R410A",
|
||||
Pressure::from_pascals(10.0e5),
|
||||
VaporQuality::saturated_vapor(),
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Air Source
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
// Air sources were not available in the old API
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::AirSource;
|
||||
use entropyk_core::{Pressure, Temperature, RelativeHumidity};
|
||||
|
||||
// Option 1: From dry-bulb temperature and relative humidity
|
||||
let source = AirSource::from_dry_bulb_rh(
|
||||
Temperature::from_celsius(35.0), // Dry-bulb temperature
|
||||
RelativeHumidity::from_percent(50.0), // 50% relative humidity
|
||||
Pressure::from_pascals(101_325.0), // Atmospheric pressure
|
||||
port
|
||||
)?;
|
||||
|
||||
// Option 2: From dry-bulb and wet-bulb temperatures
|
||||
let source = AirSource::from_dry_and_wet_bulb(
|
||||
Temperature::from_celsius(35.0), // Dry-bulb temperature
|
||||
Temperature::from_celsius(25.0), // Wet-bulb temperature
|
||||
Pressure::from_pascals(101_325.0), // Atmospheric pressure
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Water Sink
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
use entropyk_components::FlowSink;
|
||||
|
||||
// Return header: 1.5 bar back-pressure
|
||||
let sink = FlowSink::incompressible("Water", 1.5e5, None, port)?;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::BrineSink;
|
||||
use entropyk_core::{Pressure, Concentration};
|
||||
use entropyk_fluids::CoolPropBackend;
|
||||
use std::sync::Arc;
|
||||
|
||||
let backend = Arc::new(CoolPropBackend::new());
|
||||
|
||||
let sink = BrineSink::new(
|
||||
"Water",
|
||||
Pressure::from_pascals(1.5e5), // Back-pressure
|
||||
None, // No fixed temperature (free enthalpy)
|
||||
None, // No concentration needed when temp is None
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Refrigerant Sink
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
use entropyk_components::FlowSink;
|
||||
|
||||
// R410A low-side: 8.5 bar
|
||||
let sink = FlowSink::compressible("R410A", 8.5e5, None, port)?;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::RefrigerantSink;
|
||||
use entropyk_core::Pressure;
|
||||
use entropyk_fluids::CoolPropBackend;
|
||||
use std::sync::Arc;
|
||||
|
||||
let backend = Arc::new(CoolPropBackend::new());
|
||||
|
||||
let sink = RefrigerantSink::new(
|
||||
"R410A",
|
||||
Pressure::from_pascals(8.5e5), // Back-pressure
|
||||
None, // No fixed vapor quality (free enthalpy)
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### Air Sink
|
||||
|
||||
**Before (deprecated):**
|
||||
```rust
|
||||
// Air sinks were not available in the old API
|
||||
```
|
||||
|
||||
**After:**
|
||||
```rust
|
||||
use entropyk_components::AirSink;
|
||||
use entropyk_core::Pressure;
|
||||
|
||||
// Simple back-pressure sink (free enthalpy)
|
||||
let sink = AirSink::new(
|
||||
Pressure::from_pascals(101_325.0), // Atmospheric pressure
|
||||
port
|
||||
)?;
|
||||
|
||||
// Or with fixed return temperature:
|
||||
let mut sink = AirSink::new(Pressure::from_pascals(101_325.0), port)?;
|
||||
sink.set_return_temperature(
|
||||
Temperature::from_celsius(25.0),
|
||||
RelativeHumidity::from_percent(50.0)
|
||||
)?;
|
||||
```
|
||||
|
||||
## Benefits of New Types
|
||||
|
||||
### 1. Type Safety
|
||||
|
||||
The fluid type is now explicit in the type name, making code more self-documenting:
|
||||
|
||||
```rust
|
||||
// Old: Unclear what type of fluid this is
|
||||
let source = FlowSource::incompressible("Water", ...);
|
||||
|
||||
// New: Clear that this is a brine/water source
|
||||
let source = BrineSource::new("Water", ...);
|
||||
```
|
||||
|
||||
### 2. Concentration Support
|
||||
|
||||
`BrineSource` supports glycol concentration natively:
|
||||
|
||||
```rust
|
||||
let source = BrineSource::new(
|
||||
"MEG",
|
||||
Pressure::from_pascals(3.0e5),
|
||||
Temperature::from_celsius(-10.0),
|
||||
Concentration::from_percent(40.0), // 40% MEG
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### 3. Vapor Quality Input
|
||||
|
||||
`RefrigerantSource` supports vapor quality input instead of raw enthalpy:
|
||||
|
||||
```rust
|
||||
// Saturated vapor at condenser outlet
|
||||
let source = RefrigerantSource::new(
|
||||
"R410A",
|
||||
Pressure::from_pascals(24.0e5),
|
||||
VaporQuality::saturated_vapor(),
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
|
||||
// Two-phase mixture
|
||||
let source = RefrigerantSource::new(
|
||||
"R410A",
|
||||
Pressure::from_pascals(8.5e5),
|
||||
VaporQuality::from_fraction(0.3), // 30% vapor
|
||||
backend.clone(),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
### 4. Psychrometrics
|
||||
|
||||
`AirSource` supports psychrometric calculations:
|
||||
|
||||
```rust
|
||||
// Outdoor air with humidity
|
||||
let source = AirSource::from_dry_bulb_rh(
|
||||
Temperature::from_celsius(35.0),
|
||||
RelativeHumidity::from_percent(50.0),
|
||||
Pressure::from_pascals(101_325.0),
|
||||
port
|
||||
)?;
|
||||
```
|
||||
|
||||
## Type Aliases Also Deprecated
|
||||
|
||||
The following type aliases are also deprecated:
|
||||
|
||||
| Old Alias | Replacement |
|
||||
|-----------|-------------|
|
||||
| `IncompressibleSource` | `BrineSource` |
|
||||
| `CompressibleSource` | `RefrigerantSource` |
|
||||
| `IncompressibleSink` | `BrineSink` |
|
||||
| `CompressibleSink` | `RefrigerantSink` |
|
||||
|
||||
**Note:** `AirSource` and `AirSink` are new types with no deprecated aliases.
|
||||
|
||||
## Need Help?
|
||||
|
||||
If you encounter issues during migration:
|
||||
|
||||
1. Check the API documentation for the new types
|
||||
2. Review the examples in the `examples/` directory
|
||||
3. Open an issue on GitHub with the `migration` label
|
||||
Reference in New Issue
Block a user