# Phantom-Gradient Regularization Standard

Canonical toolkit for C¹ (or smoother) replacements of hard clamps, `max`/`min`,
and absolute-value kinks on Newton unknowns. Owned by Epic 0 / Story 0.2
(`epics-solver-hp.md`, FR19).

Source code: `crates/core/src/smoothing.rs` (`entropyk_core::smoothing`).

---

## Decisions

| Layer | Location | Role |
|-------|----------|------|
| **Canonical general toolkit** | `entropyk_core::smoothing` | `smooth_max` / `smooth_min` / `smooth_abs` / `smooth_clamp` (+ analytic derivatives) |
| **Reference specialized pattern** | `heat_exchanger::flow_regularization` | Mass-flow activity / duty / transport blend for zero-flow HX residuals — **not** duplicated into core |
| **Verification harness** | `entropyk_components::jacobian_fd` | Central FD vs analytic (Story 0.1); CI gate is Story 0.5 |

**Banned** in residual / Jacobian paths on Newton unknowns:

- bare `.clamp(...)` whose derivative jumps `0 ↔ 1`
- hard `.max(0)` / early `Ok(0.0)` that zeros informative physics derivatives

Physical clamp → smooth migrations are Stories **0.3** (valve / EXV) and **0.4** (HX).
This standard ships toolkit + docs only; it does not change component physics.

DoF rule: regularization **must not** change `n_equations()`.

---

## API (core)

| Function | Continuity | Parameter |
|----------|------------|-----------|
| `smooth_max(a, b, k)` / `smooth_max_derivative` | C∞ | sharpness `k` (overshoot at equality = `k/2`) |
| `smooth_min(a, b, k)` / `smooth_min_derivative` | C∞ | same |
| `smooth_abs(x, eps)` / `smooth_abs_derivative` | C∞ | `eps` = value at `x=0` |
| `smooth_clamp(x, lo, hi, width)` / `smooth_clamp_derivative` | C¹ | transition `width` at each bound |
| `smoothstep` / `cubic_blend` / `quintic_blend` (+ derivatives) | C¹ / C² | correlation transition windows |

Degenerate parameters never panic: `k <= 0` → hard max/min; `eps <= 0` → hard `|x|`;
`width <= 0` or inverted bounds → hard clamp (bounds swapped if needed).

---

## ε / width selection guidance

| Primitive | Parameter | Physical meaning | Rule of thumb |
|-----------|-----------|------------------|---------------|
| `smooth_abs` | `eps` | Blend half-width; value at origin | ~1% of characteristic `\|x\|`, or smaller if the kink is far from the operating region |
| `smooth_max` / `smooth_min` | `k` | Softness; overshoot at equality = `k/2` | `k ≪ \|a − b\|` where you need the hard extremum; never large enough to shift equilibrium |
| `smooth_clamp` | `width` | Transition length at each bound | Prefer `width ≤ (hi − lo) / 2`. Keep Newton-visible band physically small |
| `flow_activity` | `m_eps` | Mass-flow activity scale | Keep HX default `DEFAULT_M_EPS_KG_S = 1e-4` (see [flow-regularization.md](./flow-regularization.md)) |

### Recommended starting widths (examples only)

| Quantity | Interval | Suggested `width` |
|----------|----------|-------------------|
| Valve / EXV opening | `[0, 1]` | `1e-3` … `1e-2` |
| Thermodynamic quality | `[0, 1]` | `1e-3` … `1e-2` |
| Fan actuator | `[0, 1.5]` | `~1e-2` |
| Flood level | `[0, 0.98]` | `~1e-2` (respect `width ≤ (hi−lo)/2`) |

Always pair value and derivative in both `compute_residuals` and `jacobian_entries`
(`smooth_clamp` + `smooth_clamp_derivative`, etc.).

---

## Relationship to flow regularization

`crates/components/src/heat_exchanger/flow_regularization.rs` is the **reference
implementation** for zero-flow-safe HX residuals. It builds on
`entropyk_core::smoothing::smooth_abs` and stays in `entropyk-components` because
it encodes residual units (watts) and characteristic mass-flow scales
(`m_scale`) that are HX-specific.

Do **not** move `flow_activity` / `blend_transport_residual` into core.
Do **not** invent a second smoothing module under `components/`.

Details: [flow-regularization.md](./flow-regularization.md).

---

## Verification

- Unit / FD continuity tests: `crates/core/src/smoothing.rs` (`#[cfg(test)]`).
- Component Jacobian health: `check_jacobian_health` (Story 0.1 audit harness).
- Envelope CI gate: Story 0.5.