Class NDHeavisideMath
Scalar kernels backing NumSharp's np.heaviside binary ufunc — the Heaviside step function
heaviside(x1, x2), a port of NumPy's npy_heaviside
(numpy/_core/src/npymath/npy_math_internal.h.src):
heaviside(x, h0) = NaN if x is NaN
= h0 if x == 0 (includes -0.0, since IEEE -0.0 == 0.0)
= 0 if x < 0 (includes -inf)
= 1 if x > 0 (includes +inf)
Why a from-scratch helper and not a library call. There is no single BCL function for
this — it is a four-way branch on x alone. The branch ORDER matters and is
NumPy's exactly: the NaN test comes first, so an x of any NaN sign/payload yields a result
NaN, and only then does x == 0 return h0. h0 is consulted for the x == 0
case ALONE, so for every other x the value of h0 (even a NaN h0) is irrelevant,
matching NumPy.
Two NaN behaviours that are easy to get wrong, both bit-verified against NumPy 2.4.2.
(1) When x is NaN the result is the POSITIVE canonical quiet NaN NumPy stores
(NPY_NAN = 0x7ff8… / NPY_NANF = 0x7fc00000 / NPY_HALF_NAN =
0x7e00) — REGARDLESS of x's own NaN sign or payload; note .NET's NaN
is the NEGATIVE quiet NaN (0xfff8…), so returning it would flip the sign bit, hence the
explicit constants here. (2) When x == 0 the result is h0's EXACT bits, so a NaN
h0 keeps its own sign (heaviside(0, -NaN) is a negative NaN) and a -0.0
h0 keeps its sign — the opposite of case (1).
float16 computes directly (no float32 detour needed). NumPy's ee->e loop carries
astype={'e':'f'} — it widens to float32, runs npy_heavisidef, and narrows back — but
every heaviside output is an EXACT value (0, 1, the passed-through h0, or the canonical NaN),
and a Half h0 round-trips through float32 losslessly, so evaluating in
Half gives byte-identical bits (verified 0-diff over the adversarial half grid).
Decimal (no NumPy analog, NumSharp's gg->g stand-in) has no NaN/inf state, so it
carries only the == 0 / < 0 / else split.
The whole function is comparison-and-select with no transcendental, which is why the SIMD
driver (the Heaviside*F64 / Heaviside*F32 kernels of the sibling partial NDHeavisideMath.Simd.cs,
gated by SimdAvailable) can vectorize it branchlessly
and stay bit-identical to these scalars lane-for-lane — unlike NumPy, whose heaviside is a
scalar BINARY_LOOP with no SIMD on any platform.
public static class NDHeavisideMath
- Inheritance
-
NDHeavisideMath
- Inherited Members
Properties
SimdAvailable
Whether the vectorized heaviside fast path can run (hardware-accelerated Vector<T>). When false, callers use the scalar kernels.
public static bool SimdAvailable { get; }
Property Value
Methods
Heaviside(double, double)
The Heaviside step function for float64 (NumPy's dd->d loop / npy_heaviside).
public static double Heaviside(double x, double h0)
Parameters
xdoubleThe step argument: its sign selects the branch (NaN → NaN, 0 →
h0, negative → 0, positive → 1).h0doubleThe value returned when
xis exactly 0 (its bits pass through verbatim); ignored for every otherx.
Returns
- double
The step value; the positive canonical NaN when
xis NaN.
HeavisideContiguousF32(float*, float*, float*, long)
heaviside over two contiguous float32 arrays: r[i] = heaviside(x[i], h0[i]).
public static void HeavisideContiguousF32(float* x, float* h0, float* r, long n)
Parameters
xfloat*Contiguous step arguments.
h0float*Contiguous
x == 0fills.rfloat*Contiguous output.
nlongElement count.
HeavisideContiguousF64(double*, double*, double*, long)
heaviside over two contiguous float64 arrays: r[i] = heaviside(x[i], h0[i]).
public static void HeavisideContiguousF64(double* x, double* h0, double* r, long n)
Parameters
xdouble*Contiguous step arguments.
h0double*Contiguous
x == 0fills.rdouble*Contiguous output (may alias neither operand for the vector path).
nlongElement count.
HeavisideDecimal(decimal, decimal)
The Heaviside step function for decimal (NumSharp's extension; no NumPy dtype). Decimal has no
NaN/inf, so only the == 0 / < 0 / else split applies.
public static decimal HeavisideDecimal(decimal x, decimal h0)
Parameters
xdecimalThe step argument selecting the branch.
h0decimalThe value returned when
xis exactly 0.
Returns
- decimal
0 for negative, 1 for positive, and
h0for zero.
HeavisideF(float, float)
The Heaviside step function for float32 (NumPy's ff->f loop / npy_heavisidef).
See Heaviside(double, double); identical logic at single precision.
public static float HeavisideF(float x, float h0)
Parameters
Returns
- float
The step value; the positive canonical float NaN when
xis NaN.
HeavisideH0ScalarF32(float*, float, float*, long)
heaviside with a broadcast fill: r[i] = heaviside(x[i], h0) (float32).
public static void HeavisideH0ScalarF32(float* x, float h0, float* r, long n)
Parameters
xfloat*Contiguous step arguments.
h0floatThe single fill value (broadcast).
rfloat*Contiguous output.
nlongElement count.
HeavisideH0ScalarF64(double*, double, double*, long)
heaviside with a broadcast fill: r[i] = heaviside(x[i], h0) (the common
np.heaviside(arr, 0.5) shape). h0 is loaded once into a vector.
public static void HeavisideH0ScalarF64(double* x, double h0, double* r, long n)
Parameters
xdouble*Contiguous step arguments.
h0doubleThe single fill value (broadcast).
rdouble*Contiguous output.
nlongElement count.
HeavisideHalf(Half, Half)
The Heaviside step function for float16 (NumPy's ee->e loop, astype e->f). Computed
directly in Half because every output is an exact value that a Half can hold and
h0 round-trips losslessly — see the type remarks.
public static Half HeavisideHalf(Half x, Half h0)
Parameters
xHalfThe step argument selecting the branch.
h0HalfThe
x == 0fill (exact bits pass through, NaN sign included).
Returns
- Half
The step value; the positive canonical half NaN when
xis NaN.
HeavisideXScalarF32(float, float*, float*, long)
heaviside with a broadcast step argument: r[i] = heaviside(x, h0[i]) (float32).
Collapses to a fill or an h0 copy — see the float64 twin.
public static void HeavisideXScalarF32(float x, float* h0, float* r, long n)
Parameters
xfloatThe single step argument (broadcast).
h0float*Contiguous fills (only read when
xis exactly 0).rfloat*Contiguous output.
nlongElement count.
HeavisideXScalarF64(double, double*, double*, long)
heaviside with a broadcast step argument: r[i] = heaviside(x, h0[i]). Because a
single x selects ONE branch for the whole array, this collapses to a fill
(negative → 0, positive → 1, NaN → NaN) or, at x == 0, a straight copy of the
h0 bits — so it never even runs the select chain.
public static void HeavisideXScalarF64(double x, double* h0, double* r, long n)