HardTanh Saturation Distance Tool

Description

Clamp x into [lower,upper] as nearest; distance=abs(x-nearest), saturated when x<=lower or x>=upper.

Hardtanh clamps its input to supplied lower and upper output bounds. Interior outputs have one preimage, while each saturated endpoint corresponds to an unbounded input ray. An endpoint can have zero excess distance while still being classified as saturated.

Clamp x into [lower,upper] as nearest; distance=abs(x-nearest), saturated when x<=lower or x>=upper.

When to use this tool

Use HardTanh Saturation Distance when checking the stated clamped-tanh saturation or inverse-region convention.

How to use the tool and how it works

Enter x, lower, upper. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read distance, saturated, nearest. Inspect saturated before interpreting the associated values.

Require lower<upper. Clamp x into [lower,upper] as nearest; distance=abs(x-nearest), saturated when x<=lower or x>=upper.^[1]

Input field	Meaning and units	Accepted input
x	Finite scalar input coordinate; use the mathematical scale specified above.	Required. Finite number.
lower	Lower	Required. Finite number.
upper	Upper	Required. Finite number.

Output field	Interpretation	Returned shape
distance	Distance outside the closed clamp interval, zero everywhere inside.	Required. Finite number.
saturated	True at or beyond either endpoint, including zero-distance endpoint cases.	Required. Boolean.
nearest	Nearest	Required. Finite number.

json

{
  "input": {
    "x": 3,
    "lower": -1,
    "upper": 1
  },
  "output": {
    "distance": 2,
    "saturated": true,
    "nearest": 1
  }
}

Limitations and assumptions

An endpoint has zero distance but saturated=true; distance measures excess outside the range, not distance to the nearest breakpoint for interior points.
Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Use the complete explicit function and the intended parameter, branch and numerical conventions for symbolic, tensor or model-level differentiation; assess training behavior independently.

References

Calculation and input contract: activation/hardtanh-saturation-distance — tool.io

Similar or alternative tools

Activation: HardTanh Inverse Preimage
Outputs outside [lower,upper] have no preimage; lower gives a lower-ray, upper an upper-ray and strict interior a singleton.
Hardshrink Zero Preimage Interval Tool
Return the closed interval mapped to zero by the strict-outside-threshold hard-shrink convention.