Table of Contents

Namespace NumSharp.Utilities

Classes

ArrayConvert

Presents all possible combinations of array conversion of types supported by numpy.

Arrays
ArraysExtensions
ConcurrentHashset<T>
Converts

Provides various methods related to Convert.

Converts<T>

Provides various methods related to Convert based on give T.

DecimalMath

Provides transcendental math functions for decimal type. .NET does not provide these natively since decimal is designed for financial calculations.

Hashset<T>

Implementation notes: This uses an array-based implementation similar to Dictionary<T>, using a buckets array to map hash values to the Slots array. Items in the Slots array that hash to the same value are chained together through the "next" indices.

This implementation supports long indexing for collections exceeding int.MaxValue elements.

The capacity is always prime; so during resizing, the capacity is chosen as the next prime greater than double the last capacity (or 33% growth for very large sets above 1 billion elements).

The underlying data structures are lazily initialized. Because of the observation that, in practice, hashtables tend to contain only a few elements, the initial capacity is set very small (3 elements) unless the ctor with a collection is used.

The +/- 1 modifications in methods that add, check for containment, etc allow us to distinguish a hash code of 0 from an uninitialized bucket. This saves us from having to reset each bucket to -1 when resizing. See Contains, for example.

Set methods such as UnionWith, IntersectWith, ExceptWith, and SymmetricExceptWith modify this set.

Some operations can perform faster if we can assume "other" contains unique elements according to this equality comparer. The only times this is efficient to check is if other is a hashset. Note that checking that it's a hashset alone doesn't suffice; we also have to check that the hashset is using the same equality comparer. If other has a different equality comparer, it will have unique elements according to its own equality comparer, but not necessarily according to ours. Therefore, to go these optimized routes we check that other is a hashset using the same equality comparer.

A HashSet with no elements has the properties of the empty set. (See IsSubset, etc. for special empty set checks.)

A couple of methods have a special case if other is this (e.g. SymmetricExceptWith). If we didn't have these checks, we could be iterating over the set and modifying at the same time.

InfoOf

Static utility methods for type information.

InfoOf<T>

Provides a cache for properties of T that requires computation.

NDComplexMath

Complex-math helpers backing NumSharp's complex (complex128) unary ufuncs. Each entry point reproduces NumPy 2.4.2 bit-for-bit (or within 3 ULP on the finite interior), verified by a 504-point bit-exact sweep and a layout sweep (contiguous / F-contiguous / strided / transposed / reversed / sliced / broadcast / 0-d). Most are direct ports of NumPy's own routines in npy_math_complex.c.src (the FreeBSD msun implementations) because System.Numerics.Complex diverges on large magnitudes, the unit circle, tiny/subnormal values, branch cuts, and signed zeros. Every non-finite input additionally matches NumPy's exact NaN SIGN bit-for-bit (win-amd64 = MSVC UCRT complex functions): the "produce a NaN" slots emit the positive NPY_NAN; csqrt/clog/cnc_log1p/cexp PROPAGATE an input NaN's sign; csinh/ccosh CANONICALISE to +NaN (so csin/ccos follow the transform's negate), while ctanh propagates; and a genuine 0/0 · inf-inf · inf*0 keeps its x86-negative sign on both engines. Gated by the complex-unary NaN-contract oracle tier (raw-byte NaN compare).

Ported NumPy algorithms. Log(Complex) = npy_clog (four-regime rescale incl. the near-|z|=1 log1p path; drives Log10(Complex) and the engine's log2); Sinh(Complex)/ Cosh(Complex) = textbook sinh/cosh(x)·trig(y) with a y==0 guard (so a huge real part doesn't become inf·0 = NaN) and the C99 Annex G non-finite tables; Tanh(Complex) = Kahan's npy_ctanh (markedly more accurate than the BCL near ±π/2) + the |x|≥22 overflow-safe branch; Sin(Complex)/Cos(Complex)/ Tan(Complex) route through those exactly as NumPy defines csin/ccos/ctan; Atan(Complex) = the full npy_catanh (real atanh/atan on the axes, the log1p interior, and an exponent-classified real_part_reciprocal); Exp(Complex) = npy_cexp; Sqrt(Complex) = npy_csqrt; Expm1(Complex) = nc_expm1 with a Goldberg real expm1; Square(Complex) = vfmaddsub z·z (matches NumPy's SIMD complex multiply overflow/cancellation AND NaN sign); Reciprocal(Complex) = the CDOUBLE_reciprocal ufunc loop (division-form imaginary term, NaN-sign correct); Exp2(Complex)/Log1p(Complex) compose the above; Abs(Complex) = NumPy's SIMD simd_cabsolute (loops_unary_complex.dispatch: sqrt(fma(r, r, 1))·larger, with C99 hypot's rule that an infinite component yields +inf even alongside a NaN — the .NET 8 Complex.Abs returns NaN there).

Still delegating to the BCL (at parity): Asin(Complex) and Acos(Complex) use Asin(Complex)/Acos(Complex) on the finite interior with signed-zero / branch-cut fixups, and the C99 non-finite tables otherwise.

Accepted residuals (pathological FINITE inputs only, beyond 3 ULP — NaN sign is NOT among them, it is byte-exact): arccos with a sub-DBL_MIN imaginary part flushes the denormal real part to 0 where NumPy's cacos hard-work kernel keeps it (~5.8e-309); sinh/cosh (and the sin/cos that route through them) at the |x|∈[710,710.13] overflow edge differ because Windows' CRT sinh overflows where .NET's stays finite.

Perf: each public entry point is a tiny finite-path wrapper marked AggressiveInlining so the JIT folds it into the IL-emitted unary kernel (no per-element call frame); the rare non-finite / special-value tables live in cold helpers marked AggressiveOptimization (kept out-of-line so the hot wrapper stays inlineable, fully optimized when hit). A benchmark of an IL-inlined variant vs this call-based form showed the per-element cost is dominated by the transcendental, so hand-emitting the formulas is not worth the duplication.

NDCoordinatesAxisIncrementor
NDCoordinatesIncrementor
NDCoordinatesIncrementorAutoResetting
NDCoordinatesLeftToAxisIncrementor
NDDivision

floor-division and remainder helpers matching NumPy's floor_div_@TYPE@ (loops_arithmetic.dispatch.c.src), integer remainder (loops_modulo.dispatch.c.src), and the floating-point npy_floor_divide@c@ / npy_remainder@c@ (Python-divmod port in npy_math_internal.h.src).

Semantics replicated exactly:

  • Integer divide/modulo by zero returns 0 (NumPy raises a RuntimeWarning but yields 0, never throwing — C#'s DivideByZeroException must not surface).
  • Signed integer floor-division rounds toward negative infinity (Python //), not toward zero like C# /; MIN // -1 wraps to MIN (overflow), matching NumPy's npy_set_floatstatus_overflow(); return NPY_MIN.
  • Signed integer remainder uses the floored (Python) sign convention: the result has the sign of the divisor; MIN % -1 == 0.
  • Float floor-division/modulo follow CPython's divmod (fmod, sign-fixup, snap-to-nearest-integer), so a // 0.0 is ±inf/nan (not forced NaN) and edge cases like 0.7 // 0.1 == 6.0 and -2.0 // inf == -1.0 match.
NDExtendedCoordinatesIncrementor
NDFloatMath

Transcendental helpers backing NumSharp's float unary ufuncs. Unlike the BCL's MathF/Math (which route to the platform libm and are only ~correctly rounded), each entry point here is a port of the kernel NumPy 2.4.2 actually runs, so the result is bit-identical to NumPy rather than merely within a couple of ULP.

Most of these are float32-only, because at float64 the platform libm already agrees with NumPy bit-for-bit on this host and there is nothing to port. Tanh(double) is the exception: NumPy ships its own kernel at both widths, so both diverged from the BCL and both are ported.

Exp(float) = simd_exp_FLOAT, Log(float) = simd_log_FLOAT (numpy/_core/src/umath/loops_exponent_log.dispatch.c.src, the SIMD_AVX2_FMA3 instantiation). NumPy's own algorithm: clamp/flag the overflow and underflow ends, Cody-Waite range reduction y = x - k·ln2 with k = rint(x·log2(e)), evaluate exp(y) as the ratio of a 5th-order over a 2nd-order Remez minimax polynomial, then scale by 2^k. It is NOT correctly rounded — NumPy documents a max error of 2.52 ULP (at x = 0xc2781e37) — so reproducing NumPy means reproducing that error, operation for operation, in the same order.

Why this is lane-width independent. Every step is elementwise (no cross-lane reduction, shuffle or horizontal op), and the whole-vector if inside NumPy's fma_scalef_ps is followed by a per-lane blend whose non-denormal lanes are unchanged by the taken branch. This scalar entry point therefore yields the same bits the 8-lane __m256 kernel yields — as do the Vector{128,256,512} overloads in NDFloatMath.Simd.cs, which the IL kernels prefer when the host has FMA.

The FMA contraction is part of the answer, not an optimization. NumPy writes the quadrant as _mm256_mul_ps(x, log2e) followed by _mm256_add_ps(quadrant, magic), but the wheel's compiler (MSVC 19.44, the numpy==2.5.4 win-amd64 build, as 2.4.2's) contracts that pair into a single vfmadd. The difference is observable: at x = 0xc26d0e6c the un-contracted product lands on the exact tie -85.5 and the magic-constant rint takes it to -86 (half-to-even), while the fused form keeps the extra bits of -85.4999987495703 and rounds to -85 — a 1-ULP difference in the result. Hence FusedMultiplyAdd(float, float, float) here, matching the binary NumPy ships.

Specials (probed against 2.4.2, and a consequence of NumPy zeroing the NaN lanes before the range comparisons, which makes the three masks mutually exclusive): any NaN — quiet or signalling, either sign, any payload — returns the canonical 0x7fc00000; x ≥ 88.72283935546875 (incl. +inf) returns +inf; x ≤ -103.97208404541015625 (incl. -inf) returns +0; ±0 returns 1. Results between those ends denormalize gracefully through the ScalefDenormal(float, float) path. NumPy additionally raises the FP overflow/underflow status flags (surfacing as a RuntimeWarning); NumSharp models no FP status word, so that signalling is absent — a pre-existing, engine-wide difference, not one this port introduces.

Verified exhaustively: all 2^32 float32 bit patterns agree with NumPy 2.4.2 (chunked checksum sweep), not a sample. Perf: the finite path is AggressiveInlining so the JIT folds it into the IL-emitted unary kernel with no per-element call frame; the NaN/overflow/underflow ends and the denormal scale-back live in NoInlining cold helpers so the hot path stays inlineable.

NDGcdLcm

Greatest-common-divisor / lowest-common-multiple element helpers for np.gcd and np.lcm — a line-for-line port of NumPy 2.4.2's npy_gcd@c@ / npy_lcm@c@ (numpy/_core/src/npymath/npy_math_internal.h.src) driving the integer @TYPE@_gcd / @TYPE@_lcm loops (loops.c.src). One helper per NumSharp integer dtype, mirroring the NDDivision Fmod* layout, so the IL kernels resolve a single call per element (DirectILKernelGenerator.EmitGcdLcmOperation). gcd/lcm have integer loops ONLY — bool/float/complex/decimal are rejected at the np.* boundary before any kernel runs, so no float helper exists here.

Algorithm (NumPy verbatim). The unsigned helpers are the core: gcd(a,b) is the iterative Euclidean remainder loop while(a!=0){c=a; a=b%a; b=c;} return b; and lcm(a,b) = gcd==0 ? 0 : a/gcd*b (divide-BEFORE-multiply, to widen the exactly-divisible factor out first — the product can still overflow the dtype and WRAPS, matching NumPy). The signed helpers delegate to the unsigned core on the operands' magnitudes exactly as NumPy does (npy_gcd(a,b) = npy_gcdu(a<0?-a:a, b<0?-b:b)), then reinterpret the unsigned result back to the signed type.

Two consequences that look like bugs but are NumPy-exact (probed against 2.4.2, so do NOT "fix" them): the result of a signed gcd/lcm can be negative when the unsigned magnitude wraps the signed range — e.g. gcd(int8 -128, -128) == -128 (the magnitude 128 has no positive int8), lcm(int32.MinValue, 1) == int32.MinValue; and an overflowing lcm product wraps silently — e.g. lcm(int16 21000, 14000) == -23536, lcm(uint32.MaxValue, MaxValue-1) == 2. The |MIN| magnitude is obtained by the C idiom (U)(unchecked(-x)): negating the signed minimum wraps back to itself, and its bit pattern reinterpreted as unsigned IS 2^(width-1) (the true magnitude) — which is why every negate/cast below is unchecked.

Why the 8/16-bit helpers may compute in their own width rather than promoting to int32 (as NumPy's BYTE_gcd does via C integer promotion): for gcd, all Euclidean intermediates are bounded by max(|a|,|b|) and so never exceed the width; for lcm, |a|/gcd is exact and both it and |b| are < 2^width, and modular multiplication is width-invariant ((x*y) mod 2^w == ((x mod 2^w)*(y mod 2^w)) mod 2^w), so narrowing the int32-domain product gives the identical wrapped byte/short result. C# already widens byte/ushort/char operands to int for %/*, so the narrowing cast on store closes the equivalence.

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.

NDHypotMath

Scalar kernel backing NumSharp's np.hypot binary ufunc — sqrt(x12 + x22) computed without spurious overflow/underflow, the length of the hypotenuse of a right triangle.

Why a from-scratch algorithm instead of a library call. NumPy's hypot ufunc is a scalar BINARY_LOOP that calls npy_hypot (npy_math_internal.h.src). On the win-amd64 NumPy 2.4.2 wheel NPY_BLOCK_HYPOT is not defined (it is set only for MinGW and 32-bit MSVC — npy_config.h), so npy_hypot forwards straight to the MSVC UCRT hypot/hypotf. The BCL has no Math.Hypot, and the one hypot in the framework — the private helper behind Abs(Complex) — is the naive large·sqrt(1+(small/large)²) "block" form, which diverges from UCRT's hypot on ~19% of inputs (1–2 ULP). So there is no managed call that reproduces the NumPy value, and the loop is scalar-only either way (no SIMD hypot exists in NumPy on this platform).

Every float dtype is BIT-EXACT with NumPy. UCRT's hypot is only faithfully rounded (it disagrees with the correctly rounded result on 8.7% of float64 inputs), because it is the plain sqrt(x*x + y*y) — two products, a sum and a square root, each rounded — with an exact power-of-two rescale only where x*x would overflow or lose y*y to underflow. Probed through ucrtbase (parity QA-25): that model equals UCRT's hypot on every one of 1.7M pairs spanning every exponent, subnormals and the corners, and np.hypot with it. Hypot(double, double) is that model, so float64 np.hypot returns NumPy's bits — including where they are 1 ULP from the correctly rounded value (np.hypot(0.1, 0.1) is 0x3fc21a1851ff630b). Until parity QA-25 this kernel was Borges' correctly rounded FMA algorithm, more accurate than NumPy and excused in the oracle. The ff->f and (via float32, astype e->f) ee->e loops round the double result down to float, which reproduces UCRT's hypotf exactly (0 of 300,000 float32 pairs differ; a float operand's square is exact in double, so the double sum leaves no room for a float32 rounding difference).

Decimal (no NumPy analog) computes the highest-precision result natively via Sqrt(decimal) with the overflow-safe scaled form.

NDIntegerPower

Integer power helpers matching NumPy's @TYPE@_power loop in loops.c.src. Uses repeated-squaring with native dtype wraparound (e.g. uint8 ** 8 = 0).

These helpers assume the exponent is non-negative. NumPy raises ValueError("Integers to negative integer powers are not allowed.") for any negative integer exponent, regardless of base value; the caller is responsible for that pre-check (see DefaultEngine.Power).

NDLog1pExpm1Math

Scalar kernels backing NumSharp's float32 / float64 np.log1p and np.expm1, and the log1p inside np.logaddexp / np.logaddexp2 (NDLogAddExpMath): models of the MSVC UCRT routines that NumPy 2.4.2's win-amd64 wheel calls (npy_log1p / npy_expm1 forward to the C library; the AVX-512 SVML loops that would replace them are not built into that wheel).

log1p / log1pf are BIT-EXACT with NumPy. Probed against np.log1p (parity QA-22, 2026-11-05): the UCRT's log1p is Goldberg's correction over its own log, u = 1 + x; log(u) - ((u - 1) - x) / u, applied for every u (also above 2), and log1pf is the same statements in float32 over logf. Log(double) / Log(float) ARE the UCRT's log / logf, so the model equals NumPy on all 320,000 finite inputs per dtype of the probe (tiny and subnormal, small, (-1, 1), near -1, [1, 10], up to the largest finite value), and the specials are pinned by hand: a NaN comes back untouched (a signalling NaN stays signalling, sign and payload kept), log1p(-1) = -inf, log1p(+inf) = +inf, and every x < -1 (-inf included) gives the POSITIVE quiet NaN (.NET's Math.Log of a negative is the negative one). Faithfully rounded, not correctly rounded: about 6% of float64 results sit one ULP from the true value, exactly where NumPy's do.

expm1 / expm1f are bit-exact outside a band and within 2-3 ULP inside it. Outside [-ln 2, ln 1.5], where |expm1(x)| >= 0.5 and the subtraction loses nothing, the UCRT returns exactly exp(x) - 1 (expf(x) - 1f for float32, whose band ends at the float32 roundings of the same constants): those results are NumPy's bit for bit. Inside the band the UCRT runs an undocumented approximation no public formula reproduces (see Expm1Sun(double)), so the band runs Sun's s_expm1.c — accurate to one ULP of the true value, equal to NumPy on about 58% of float64 and 57% of float32 in-band inputs, never more than 2 (float64) / 3 (float32) ULP from it. A NaN comes back untouched, -0.0 keeps its sign, expm1(-inf) = -1.

The naive forms these replace, Exp(x) - 1 and Log(1 + x) (also what .NET's ExpM1 / LogP1 compute), cancel catastrophically near zero: expm1(1e-8) kept 8 digits, expm1(1e-300) and log1p(1e-300) were 0, and -0.0 became +0.0. A platform pin, like NDHypotMath: Linux NumPy calls glibc's routines, which round differently.

NDLogAddExpMath

Scalar kernels backing NumSharp's np.logaddexp / np.logaddexp2 / np.nextafter binary ufuncs. Each entry point reproduces the exact NumPy 2.4.2 algorithm (npy_math_internal.h.src / ieee754 / halffloat.cpp), operation for operation, so the result matches NumPy on this platform to within the accuracy of the one primitive NumSharp cannot reproduce bit-for-bit — the CRT's log1p.

nextafter is BIT-EXACT. BitIncrement(double) / BitDecrement(double) (and the MathF twins) compose to exactly the ucrtbase nextafter/nextafterf NumPy calls (verified 0-diff over 6M random pairs). Half is a straight port of npy_half_nextafter on the raw 16-bit pattern.

logaddexp / logaddexp2 are ≤2 ULP. Exp(double), Exp2(double) and Exp(float) are already bit-identical to the ucrtbase exp/exp2/expf NumPy calls; the only divergence is Log1p(double) — an fdlibm port that agrees with the (closed) ucrtbase log1p to ≤1 ULP. So float64 logaddexp is ≤1 ULP, logaddexp2 ≤2 ULP (the LOG2E·log1p product), float32 logaddexp is bit-exact and logaddexp2 ≤1 ULP. The catastrophic small-value case that a naive log(1+exp(-tmp)) loses (logaddexp(0,-50) = 1.93e-22, not 0) is fully recovered.

Half is computed in float32 ((Half)F((float)x,(float)y)), matching NumPy's ee->e half loops which promote to float. Decimal (no NumPy analog) bridges through double.

NDOffsetIncrementor
NDOffsetIncrementorAutoresetting
NonGenericConvert

Provides a way to convert boxed object from known time to specific type.

NpFunc
NumberInfo
SteppingExtension
TypelessConvert

Provides a way to convert boxed object from known input type to known output type. By making it receive and return object - It is suitable for a common delegate: see TypelessConvertDelegate

UnmanagedBuffer

Provides low-level memory copy operations for unmanaged types.

UnmanagedSpanExtensions

Extension methods for UnmanagedSpan{T} and ReadOnlyUnmanagedSpan{T}. These provide SIMD-accelerated operations where possible. All methods support full 64-bit indexing natively.

py

Implements Python utility functions that are often used in connection with numpy

Structs

Hashset<T>.Enumerator
ReadOnlyUnmanagedSpan<T>

ReadOnlyUnmanagedSpan represents a contiguous region of arbitrary memory. Unlike arrays, it can point to either managed or native memory, or to memory allocated on the stack. It is type-safe and memory-safe.

ReadOnlyUnmanagedSpan<T>.Enumerator

Enumerates the elements of a ReadOnlyUnmanagedSpan<T>.

UnmanagedSpan<T>

UnmanagedSpan represents a contiguous region of arbitrary memory. Unlike arrays, it can point to either managed or native memory, or to memory allocated on the stack. It is type-safe and memory-safe.

UnmanagedSpan<T>.Enumerator

Enumerates the elements of a UnmanagedSpan<T>.

ValueCoordinatesIncrementor
ValueCoordinatesIncrementorAutoResetting
ValueOffsetIncrementor
ValueOffsetIncrementorAutoresetting

Delegates

TypelessConvertDelegate
ValueCoordinatesIncrementor.EndCallbackHandler