sepehr
88620790d6
Add analytic derivatives and C1 tests for smooth_max/min/clamp, document epsilon/width guidance, and declare flow_regularization as the HX reference pattern without changing component physics. Co-authored-by: Cursor <cursoragent@cursor.com>
63 lines
2.1 KiB
Markdown
63 lines
2.1 KiB
Markdown
# Flow regularization (zero-flow helpers)
|
||
|
||
Source: `crates/components/src/heat_exchanger/flow_regularization.rs`
|
||
Used by: **FloodedEvaporator** (full residual path); **Condenser** / **Evaporator** (smooth `|ṁ|` for live `C_sec`).
|
||
|
||
> **Standard:** This module is the **reference specialized pattern** for HX
|
||
> zero-flow residuals. The canonical general C¹ toolkit is
|
||
> `entropyk_core::smoothing` — see
|
||
> [phantom-gradient-regularization.md](./phantom-gradient-regularization.md).
|
||
> Do not move these helpers into core; do not duplicate `smooth_*` here.
|
||
|
||
---
|
||
|
||
## EN
|
||
|
||
### Why
|
||
|
||
Zero mass flow is a **valid** state (staging, circuit off, Newton trial steps). Hard branches like `if |m| < ε { Q = 0 }` create **Jacobian discontinuities**.
|
||
|
||
### API
|
||
|
||
| Function | Meaning |
|
||
|----------|---------|
|
||
| `flow_activity(m, ε)` | α = m²/(m²+ε²) ∈ [0,1), α(0)=0 |
|
||
| `flow_activity_derivative` | dα/dm |
|
||
| `effective_duty(Q, α_a, α_b)` | Q_eff = α_a · α_b · Q |
|
||
| `blend_transport_residual` | blend active transport residual with Δh hold |
|
||
| `blend_transport_partials` | analytic partials of the blend |
|
||
| `smooth_mass_magnitude` | C¹-ish smooth \|m\| for `C = \|ṁ\| · cp` |
|
||
| `smooth_mass_magnitude_derivative` | d\|m\|_smooth / dm |
|
||
|
||
Defaults: `DEFAULT_M_EPS_KG_S = 1e-4`, `DEFAULT_M_SCALE_KG_S = 0.05`.
|
||
|
||
### Interaction with rating mode (Flooded)
|
||
|
||
On **FloodedEvaporator system path** (live secondary): duty uses `effective_duty` with α_ref and α_sec.
|
||
On **Flooded rating path** (scalar C_sec only): residual energy uses **full Q** (no α_ref gate) so `ṁ_ref = 0` is not a trivial root when `C_sec > 0`.
|
||
|
||
### DoF rule
|
||
|
||
Regularization **must not** change `n_equations()`. It only reshapes residual values and derivatives.
|
||
|
||
---
|
||
|
||
## FR
|
||
|
||
### Pourquoi
|
||
|
||
Le débit nul est un état **valide**. Les `if |m| < ε` durs cassent le Newton.
|
||
|
||
### API
|
||
|
||
Voir le tableau EN.
|
||
|
||
### Rating vs système (Flooded)
|
||
|
||
- **Système (ports live)** : duty régularisée α_ref · α_sec · Q.
|
||
- **Rating (scalaires)** : Q **plein** dans le résidu énergie (pas de racine triviale ṁ=0).
|
||
|
||
### Règle DoF
|
||
|
||
La régularisation **ne change pas** `n_equations()`.
|