Namespace NumSharp.Utilities
Classes
- ArrayConvert
Presents all possible combinations of array conversion of types supported by numpy.
- 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
Tthat 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 innpy_math_complex.c.src(the FreeBSD msun implementations) becauseSystem.Numerics.Complexdiverges 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 positiveNPY_NAN;csqrt/clog/cnc_log1p/cexpPROPAGATE an input NaN's sign;csinh/ccoshCANONICALISE to +NaN (socsin/ccosfollow the transform's negate), whilectanhpropagates; and a genuine0/0 · inf-inf · inf*0keeps 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|=1log1ppath; drives Log10(Complex) and the engine'slog2); Sinh(Complex)/ Cosh(Complex) = textbooksinh/cosh(x)·trig(y)with ay==0guard (so a huge real part doesn't becomeinf·0 = NaN) and the C99 Annex G non-finite tables; Tanh(Complex) = Kahan'snpy_ctanh(markedly more accurate than the BCL near±π/2) + the|x|≥22overflow-safe branch; Sin(Complex)/Cos(Complex)/ Tan(Complex) route through those exactly as NumPy definescsin/ccos/ctan; Atan(Complex) = the fullnpy_catanh(realatanh/atanon the axes, thelog1pinterior, and an exponent-classifiedreal_part_reciprocal); Exp(Complex) =npy_cexp; Sqrt(Complex) =npy_csqrt; Expm1(Complex) =nc_expm1with a Goldberg realexpm1; Square(Complex) =vfmaddsubz·z(matches NumPy's SIMD complex multiply overflow/cancellation AND NaN sign); Reciprocal(Complex) = theCDOUBLE_reciprocalufunc loop (division-form imaginary term, NaN-sign correct); Exp2(Complex)/Log1p(Complex) compose the above; Abs(Complex) = NumPy's SIMDsimd_cabsolute(loops_unary_complex.dispatch:sqrt(fma(r, r, 1))·larger, with C99hypot's rule that an infinite component yields+infeven alongside a NaN — the .NET 8Complex.Absreturns 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):
arccoswith a sub-DBL_MINimaginary part flushes the denormal real part to 0 where NumPy'scacoshard-work kernel keeps it (~5.8e-309);sinh/cosh(and thesin/costhat route through them) at the|x|∈[710,710.13]overflow edge differ because Windows' CRTsinhoverflows 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.
- NDDivision
floor-division and remainder helpers matching NumPy's
floor_div_@TYPE@(loops_arithmetic.dispatch.c.src), integerremainder(loops_modulo.dispatch.c.src), and the floating-pointnpy_floor_divide@c@/npy_remainder@c@(Python-divmod port innpy_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 // -1wraps toMIN(overflow), matching NumPy'snpy_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), soa // 0.0is±inf/nan(not forced NaN) and edge cases like0.7 // 0.1 == 6.0and-2.0 // inf == -1.0match.
- Integer divide/modulo by zero returns
- 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, theSIMD_AVX2_FMA3instantiation). NumPy's own algorithm: clamp/flag the overflow and underflow ends, Cody-Waite range reductiony = x - k·ln2withk = rint(x·log2(e)), evaluateexp(y)as the ratio of a 5th-order over a 2nd-order Remez minimax polynomial, then scale by2^k. It is NOT correctly rounded — NumPy documents a max error of 2.52 ULP (atx = 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
ifinside NumPy'sfma_scalef_psis 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__m256kernel yields — as do theVector{128,256,512}overloads inNDFloatMath.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 singlevfmadd. The difference is observable: atx = 0xc26d0e6cthe un-contracted product lands on the exact tie-85.5and the magic-constant rint takes it to-86(half-to-even), while the fused form keeps the extra bits of-85.4999987495703and 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;±0returns1. Results between those ends denormalize gracefully through the ScalefDenormal(float, float) path. NumPy additionally raises the FP overflow/underflow status flags (surfacing as aRuntimeWarning); 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.gcdandnp.lcm— a line-for-line port of NumPy 2.4.2'snpy_gcd@c@/npy_lcm@c@(numpy/_core/src/npymath/npy_math_internal.h.src) driving the integer@TYPE@_gcd/@TYPE@_lcmloops (loops.c.src). One helper per NumSharp integer dtype, mirroring the NDDivisionFmod*layout, so the IL kernels resolve a singlecallper element (DirectILKernelGenerator.EmitGcdLcmOperation). gcd/lcm have integer loops ONLY — bool/float/complex/decimal are rejected at thenp.*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 loopwhile(a!=0){c=a; a=b%a; b=c;} return b;andlcm(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 IS2^(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_gcddoes via C integer promotion): for gcd, all Euclidean intermediates are bounded bymax(|a|,|b|)and so never exceed the width; for lcm,|a|/gcdis 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 widensbyte/ushort/charoperands tointfor%/*, so the narrowing cast on store closes the equivalence.
- NDHeavisideMath
Scalar kernels backing NumSharp's
np.heavisidebinary ufunc — the Heaviside step functionheaviside(x1, x2), a port of NumPy'snpy_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
xalone. The branch ORDER matters and is NumPy's exactly: the NaN test comes first, so anxof any NaN sign/payload yields a result NaN, and only then doesx == 0returnh0.h0is consulted for thex == 0case ALONE, so for every otherxthe value ofh0(even a NaNh0) is irrelevant, matching NumPy.Two NaN behaviours that are easy to get wrong, both bit-verified against NumPy 2.4.2. (1) When
xis NaN the result is the POSITIVE canonical quiet NaN NumPy stores (NPY_NAN=0x7ff8…/NPY_NANF=0x7fc00000/NPY_HALF_NAN=0x7e00) — REGARDLESS ofx'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) Whenx == 0the result ish0's EXACT bits, so a NaNh0keeps its own sign (heaviside(0, -NaN)is a negative NaN) and a-0.0h0keeps its sign — the opposite of case (1).float16 computes directly (no float32 detour needed). NumPy's
ee->eloop carriesastype={'e':'f'}— it widens to float32, runsnpy_heavisidef, and narrows back — but every heaviside output is an EXACT value (0, 1, the passed-throughh0, or the canonical NaN), and a Halfh0round-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->gstand-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*F32kernels of the sibling partialNDHeavisideMath.Simd.cs, gated by SimdAvailable) can vectorize it branchlessly and stay bit-identical to these scalars lane-for-lane — unlike NumPy, whoseheavisideis a scalarBINARY_LOOPwith no SIMD on any platform.
- NDHypotMath
Scalar kernel backing NumSharp's
np.hypotbinary 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
hypotufunc is a scalarBINARY_LOOPthat callsnpy_hypot(npy_math_internal.h.src). On the win-amd64 NumPy 2.4.2 wheelNPY_BLOCK_HYPOTis not defined (it is set only for MinGW and 32-bit MSVC —npy_config.h), sonpy_hypotforwards straight to the MSVC UCRThypot/hypotf. The BCL has noMath.Hypot, and the one hypot in the framework — the private helper behind Abs(Complex) — is the naivelarge·sqrt(1+(small/large)²)"block" form, which diverges from UCRT'shypoton ~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
hypotis only faithfully rounded (it disagrees with the correctly rounded result on 8.7% of float64 inputs), because it is the plainsqrt(x*x + y*y)— two products, a sum and a square root, each rounded — with an exact power-of-two rescale only wherex*xwould overflow or losey*yto underflow. Probed throughucrtbase(parity QA-25): that model equals UCRT'shypoton every one of 1.7M pairs spanning every exponent, subnormals and the corners, andnp.hypotwith it. Hypot(double, double) is that model, so float64np.hypotreturns NumPy's bits — including where they are 1 ULP from the correctly rounded value (np.hypot(0.1, 0.1)is0x3fc21a1851ff630b). Until parity QA-25 this kernel was Borges' correctly rounded FMA algorithm, more accurate than NumPy and excused in the oracle. Theff->fand (via float32,astype e->f)ee->eloops round the double result down to float, which reproduces UCRT'shypotfexactly (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@_powerloop inloops.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 (seeDefaultEngine.Power).
- NDLog1pExpm1Math
Scalar kernels backing NumSharp's float32 / float64
np.log1pandnp.expm1, and thelog1pinsidenp.logaddexp/np.logaddexp2(NDLogAddExpMath): models of the MSVC UCRT routines that NumPy 2.4.2's win-amd64 wheel calls (npy_log1p/npy_expm1forward 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'slog1pis Goldberg's correction over its ownlog,u = 1 + x; log(u) - ((u - 1) - x) / u, applied for everyu(also above 2), andlog1pfis the same statements in float32 overlogf. Log(double) / Log(float) ARE the UCRT'slog/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 everyx < -1(-infincluded) gives the POSITIVE quiet NaN (.NET'sMath.Logof 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.5and the subtraction loses nothing, the UCRT returns exactlyexp(x) - 1(expf(x) - 1ffor 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'ss_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.0keeps its sign,expm1(-inf) = -1.The naive forms these replace,
Exp(x) - 1andLog(1 + x)(also what .NET'sExpM1/LogP1compute), cancel catastrophically near zero:expm1(1e-8)kept 8 digits,expm1(1e-300)andlog1p(1e-300)were 0, and-0.0became+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.nextafterbinary 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'slog1p.nextafter is BIT-EXACT. BitIncrement(double) / BitDecrement(double) (and the MathF twins) compose to exactly the ucrtbase
nextafter/nextafterfNumPy calls (verified 0-diff over 6M random pairs). Half is a straight port ofnpy_half_nextafteron 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/expfNumPy calls; the only divergence is Log1p(double) — an fdlibm port that agrees with the (closed) ucrtbaselog1pto ≤1 ULP. So float64logaddexpis ≤1 ULP,logaddexp2≤2 ULP (theLOG2E·log1pproduct), float32logaddexpis bit-exact andlogaddexp2≤1 ULP. The catastrophic small-value case that a naivelog(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'see->ehalf loops which promote to float. Decimal (no NumPy analog) bridges through double.
- NonGenericConvert
Provides a way to convert boxed object from known time to specific type.
- 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
- 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>.