Clamping

📐 Definition

For bounds $a \le b$ and scalar $x$,

$$\operatorname{clamp}(x; a,b) = \min(\max(x,a), b)$$

Copied

Domain and Codomain

Domain: real numbers (or componentwise on vectors). Codomain: $[a,b]$.

---

⚙️ Key Properties

Non-expansive: $|\operatorname{clamp}(x;a,b) - \operatorname{clamp}(y;a,b)| \le |x-y|$. Piecewise linear and idempotent: applying twice leaves the result unchanged.

---

When $a=-\infty$ or $b=\infty$, clamping reduces to one-sided thresholding. Choosing $a=b$ collapses all inputs to the constant bound.

---

🎯 Special Cases and Limits

• One-sided clamp corresponds to thresholding.
• $a=b$ yields a constant map.

---

🔗 Related Functions

Soft clamping replaces hard corners with smooth transitions; thresholding is the one-sided variant.

---

Usage in Oakfield

Oakfield uses clamping both as a low-level numeric utility and as part of operator “safety” policies:

• Warp continuity guards clamp or limit invalid warp-gradient samples via per-operator continuity settings (none|strict|clamped|limited) and clamp_min/clamp_max.
• Thermostat regulation optionally bounds regulated parameters (e.g. lambda_min/lambda_max, with a smooth clamp option).
• Integrator safety clamps adaptive timesteps to min_dt/max_dt.
• Math helpers in core/math_utils.h include sim_clamp_double and magnitude-preserving sim_clamp_complex.

---

Historical Foundations

📜 Projection onto an Interval

Clamping is the projection of a scalar onto the closed interval $[a,b]$, a basic operation in constrained optimization and numerical safeguards.

🌍 Modern Perspective

Hard clamps are commonly replaced by smooth clamps when differentiability is required, but the hard version remains a robust safeguard primitive.

---

📚 References

• Boyd & Vandenberghe, Convex Optimization