Table of Contents

NumPy Compliance & Compatibility

NumSharp's compatibility target is NumPy 2.x, with the implementation and differential-test oracle currently pinned to NumPy 2.5.4. The target is both API compatibility and behavioral compatibility: dtype promotion, shape, strides, views, broadcasting, exceptions, special values, and output bytes all matter.

NumSharp is not claiming that every NumPy API is implemented or that the existence of a method proves exact behavior. This page separates three questions that used to be conflated:

  1. Is the public API present? The compiled assembly answers this through the generated NumPy API Coverage & Support dashboard.
  2. Does the behavior match? Unit tests and committed NumPy-oracle cases answer this per operation, dtype, layout, and edge case. See Unit Tests & Oracle.
  3. Does the operation need an optional backend? Most operations do not. Matrix factorizations do; the distinction is documented below.

The authoritative NumPy implementation is the pinned clone at refs/numpy/. Documentation and tests are derived from that source and from running NumPy 2.5.4, rather than from memory or from older NumSharp behavior.


API coverage and versioned evidence

The coverage dashboard reads the published inventory snapshot and identifies its source revision. Its headline scope and expanded module/class view are different inventories: use the expanded view for numpy.strings, numpy.char and chararray members.

An available mapping means a public C# API exists. An oracle-verified mapping additionally has a reviewed test contract; neither means every dtype or parameter combination is supported. Use the snapshot's revision when comparing results, and the individual guides for dtype, parameter and layout rules.

The inventory is generated by coverage/generate_coverage.py. NumSharp-only extensions are catalogued separately and do not inflate NumPy's denominator.


NumPy 2.x Type Promotion (NEP 50)

NumPy 1.x sometimes inspected a Python scalar's value when choosing a dtype. The historical NEP 50 example is:

# NumPy 1.x behavior
np.result_type(np.int8, 1)    # int8
np.result_type(np.int8, 255)  # int16: the value does not fit in int8

NumPy 2.x treats Python int, float, and complex values as weakly typed. Precision is chosen from the strongly typed array or NumPy scalar, subject to kind promotion and an in-range check. For example, NumPy 2.5.4 and NumSharp both keep this operation at uint8:

var a = np.array(new byte[] { 1, 2, 3 });
var b = a + 255;

// b.dtype == np.uint8
// b is [0, 1, 2] because uint8 arithmetic wraps

The corresponding NumPy array operation does not emit an overflow warning. NumPy's scalar expression np.uint8(1) + 255 does emit a RuntimeWarning; that is a different scalar execution path.

NumSharp's binary-operator and result_type paths implement NEP 50 promotion. C# primitive scalar arguments are the analogue of weak Python literals; an NDArray or explicit dtype remains strongly typed. Reductions also apply NumPy's accumulator rules, such as sum(int32) -> int64, while width-preserving operations such as abs(int32) remain int32.

Promotion is still verified per operation. The repository contains dedicated NEP 50 matrices and NumPy-generated oracle cases; the statement above does not imply that an untested API is correct merely because it calls a shared promotion helper.


NumPy 2.x API Additions and C# Spellings

The additions that the previous version of this page listed as missing are implemented:

NumPy 2.x API NumSharp mapping
np.concat Public np.concat overloads
np.permute_dims Public np.permute_dims API
np.isdtype Public overloads for NPTypeCode, Type, and NDArray
np.unique_values Returns an NDArray
np.unique_counts Returns values and counts
np.unique_inverse Returns values and inverse indices
np.unique_all Returns values, indices, inverse, and counts
ndarray.mT View that swaps the last two axes
ndarray.device Returns "cpu"
ndarray.to_device Accepts only the CPU device

NumPy 2.x's Array-API names exist under NumPy's spelling: np.acos, np.asin, np.atan, np.atan2, np.pow, np.bitwise_invert, np.bitwise_left_shift and np.bitwise_right_shift are the same functions as np.arccos … np.right_shift (in NumPy they are the same ufunc objects), and np.round is NumPy's name of rounding (np.round_, which NumPy 2.0 removed, is gone from NumSharp too). np.cumulative_sum / np.cumulative_prod and np.ndim / np.shape are NumPy's functions.

Removed NumPy 1.x aliases are not counted as current NumPy 2.5.4 requirements. Ported code should prefer the current names such as prod, any, and all.

A C# null stored as a VALUE is Python's None: a[i] = null, a.fill(null), np.full(shape, null, dtype), np.put, np.putmask, np.place, np.insert, np.fill_diagonal, the flat iterator and np.copyto(dst, (NDArray)null, casting: "unsafe") write what NumPy writes for None: NaN in a float array (NumPy's positive quiet NaN), nan+nanj in a complex one, False in a bool one, 'None' in a text one. An integer array raises NumPy's TypeError: int() argument must be a string, a bytes-like object or a real number, not 'NoneType'. Without a dtype, None would make NumPy build an object array, which NumSharp does not have, so np.full(shape, null) is refused.


Dtypes

NumSharp supports the following array dtypes, with NumPy's behavior where there is a counterpart:

NPTypeCode C# storage type NumPy analogue Important boundary
Boolean bool bool_ Boolean is not in NumPy's numeric type hierarchy
SByte sbyte int8 Signed 8-bit integer
Byte byte uint8 Unsigned 8-bit integer
Int16 short int16
UInt16 ushort uint16
Int32 int int32
UInt32 uint uint32
Int64 long int64
UInt64 ulong uint64
Half System.Half float16 Scalar arithmetic where the BCL has no vector arithmetic
Single float float32 SIMD-capable on supported operations
Double double float64 SIMD-capable on supported operations
Complex System.Numerics.Complex complex128 No native complex64 storage dtype
Char char no general analogue Treated as an unsigned 16-bit value; .npy writes it as <U1
Decimal decimal none .NET extension; cannot be written as a NumPy .npy dtype
String packed bytes bytes_ (S) Fixed width in bytes; scalar access returns byte[]
String UCS-4 code points str_ (U) Fixed width in code points; scalar access returns string
String UTF-8 cells and payloads StringDType (T) Variable-width text with na_object and coerce settings

Operations accept the dtypes for which NumPy defines a loop. String widths and missing-value settings belong to the descriptor (arr.dtype), not the shared NPTypeCode.String value.

Text and character-array support

S, U and StringDType (T) are supported array dtypes. All three share NPTypeCode.String; the descriptor (arr.dtype) distinguishes byte strings, UCS-4 strings and variable-width UTF-8 with an NA policy. Creation, indexing, views, copies, movement, text ↔ number casts, printing, text I/O and .npy / .npz work. Comparisons, truth, concatenation, repetition, sorting, searching, unique values, membership and set routines compute over all three. Quantile methods that pick an element work, including weights= with method: "inverted_cdf"; interpolation can still raise because NumPy cannot subtract strings.

StringDType additionally computes concatenating sum / cumsum, lexical maximum / minimum, max / min and the arg-reductions with NumPy's missing-value rules. Fixed-width S / U have NumPy's refusals for those reduction loops; that is not missing string storage.

numpy.char is np.@char; chararray is NDCharArray. The module provides the stripping comparisons, construction, concatenation, repetition, split and join families. A split returns the specialized disposable NDListArray, not an arbitrary-object ndarray. Chararray members and operators follow the C# static type; public np.* functions apply their class rules to the runtime object. The separate Char dtype remains a 2-byte UTF-16 code unit, not a text dtype.

np.strings supplies elementwise lengths, substring search, stripping, padding, replacement, partitioning, character slicing, Unicode properties, case conversion, translation, formatting and encoding/decoding. np.@char provides the legacy interface and the corresponding chararray methods. The text guide describes their output widths, missing-value behavior and the operations that NumPy itself refuses. np.evaluate computes on text as NumPy's own functions do (comparisons, truth values, casts, searches, concatenation, np.where, reductions); the np.strings transformations (case, stripping, padding, replacement) are called directly.

NumPy dtype families not represented natively

  • complex64 has no NumSharp storage dtype. A .npy c8 array can be read, but its values widen to System.Numerics.Complex; writes use c16.
  • datetime64 and timedelta64 descriptors, including unit metadata, parse, promote and cast-check; array storage is not implemented.
  • Object, structured, subarray, and void dtypes are not implemented. NDListArray and the restricted StringDType pickle reader do not introduce a general object dtype.
  • The extended long double of NumPy's Linux and macOS builds (float128, complex256) has no .NET storage type. np.longdouble and np.clongdouble are their own classes stored like float64 and complex128, as on NumPy's Windows build (see C-type classes).

See Dtypes for scalar conversion, promotion, special-value, and casting details.


Memory Layout, Strides, and Views

NumSharp is not C-order-only. Shape records dimensions, element strides, a base offset, and cached C-contiguous, F-contiguous, ownership, alignment, writeability, and broadcast flags.

  • Fresh arrays default to C order, and APIs that accept order: 'F' can allocate Fortran-order arrays. np.asfortranarray is implemented.
  • Transposes, negative-stride slices, stepped slices, and other non-contiguous views retain their strides and offset instead of being silently densified.
  • Slicing returns a view that shares the underlying buffer. Call .copy() when independent storage is required.
  • Broadcast views use zero strides and are read-only, matching NumPy's protection against writing one physical element through many logical coordinates.
  • Order-aware creation and conversion paths resolve the relevant C, F, A, or K mode as NumPy does: K keeps the operand's memory order, so a copy of a permuted view is a dense array with the same axis permutation.
  • Fresh results are laid out as NumPy lays them out. An elementwise ufunc result follows NumPy's trivial loop (C, or F for F-contiguous operands) or its iterator's K order (the operands' memory order, C winning a conflict), so np.negative(a.transpose(1, 0, 2)) keeps the transpose's strides; reductions place their axes (and a kept keepdims axis) the same way, and a zero-size array NumPy allocates has all-zero strides. .strides of a fresh result therefore match NumPy's.

Kernel paths distinguish contiguous, strided, broadcast, and offset views. Correctness tests cover C- and F-contiguous arrays, transposes, positive and negative strides, sliced offsets, and broadcast reads. See Broadcasting and Buffering & Memory.


Python Array API Features

NumSharp uses the Array API features that NumPy exposes in its main namespace as compatibility targets, but it does not claim independent certification as a Python Array API implementation. The C# public surface cannot be substituted for a Python namespace object without an interop layer.

The formerly missing Array API additions isdtype, concat, permute_dims, the four unique_* functions, mT, device, and to_device are present. NumSharp is CPU-only: device is "cpu", creation functions that expose a device argument accept only null or "cpu", and to_device cannot transfer to a GPU.

The generated NumPy coverage dashboard is the current inventory. The old hand-maintained claim of "74% Array API coverage" and its 133-function denominator have been removed because they mixed a particular specification revision with NumPy API aliases and became stale.


Random Number Generation

NumSharp implements both NumPy random APIs:

  • The legacy np.random/RandomState surface uses MT19937, including NumPy-compatible state, array seeding, cached Gaussian state, and legacy distribution algorithms (randint's masked per-dtype sampler, shuffle/permutation/choice with the legacy messages and the C long dtype, modelled as int64 — see below). An unseeded RandomState() draws OS entropy through SeedSequence, as NumPy's does.

  • Every legacy distribution is a line-by-line port of NumPy's frozen legacy-distributions.c (and the shared distributions.c samplers it calls: Poisson PTRS, HRUA hypergeometric, random_loggam, …; its BTPE binomial is the legacy copy that keeps the original Stirling error terms, which NumPy 2.5 corrected for Generator only), so RandomState(seed).<method>(...) is byte-identical to NumPy for every sampler, including gamma with shape < 1, binomial, negative_binomial, f, pareto, standard_cauchy, multinomial (which shares binomial's setup cache, as NumPy's does) and dirichlet. Parameters are validated with NumPy's constraints and messages (ValueError: scale < 0, -0.0 rejected where NumPy tests the sign bit, NaN accepted where NumPy accepts it) before anything is drawn. multivariate_normal follows NumPy's SVD algorithm and is byte-identical when NumSharp.Interop.OpenBLAS supplies LAPACK's gesdd; without it a managed Jacobi SVD stands in and a singular vector's sign can differ.

  • The legacy integers are C long in NumPy, and NumSharp models ONE width for all of them: a 64-bit long, NumPy's Linux/macOS (LP64) build, which it matches exactly. That covers randint's default dtype, random_integers, permutation(n), choice's indices and multinomial's counts (all int64), the discrete samplers, and the integer parameters (multinomial's n, binomial's n, the counts of hypergeometric). NumPy's Windows build (32-bit long) returns the same values as int32 wherever both builds accept the input, but it rejects bounds past 2**31 (randint(0, 2**40), random_integers(0, 2**31), choice(2**40)), raises for multinomial(2**31, …), and differs where that width overflows inside a sampler (zipf near a = 1, poisson above 2**31, tomaxint's range, negative_binomial with an infinite mean). permutation(n) also reproduces NumPy's arange length arithmetic at the int64 edge: a length whose double rounds to 2**63 gives an empty range, as on NumPy's x86 builds.

  • RandomState(bit_generator) runs the legacy samplers on any bit generator (np.random.RandomState(new PCG64(42))), with NumPy's str() (RandomState(PCG64)), seed() refused on a non-MT19937 engine (TypeError), and both state forms: get_state() returns the legacy MT19937 tuple, get_state(legacy: false) the dict (NumPyRandom.State: the bit generator's state plus the cached Gaussian), and set_state accepts either. Consuming the cached Gaussian zeroes it, as NumPy's legacy_gauss does. get_bit_generator() and set_bit_generator(bitgen) read and hot-swap the np.random singleton's engine (the swap discards the cached Gaussian), and after a swap the module's np.random.seed(x) re-seeds the new engine as NumPy's module function does (set_state of type(engine)(x)'s state, which also discards the cached Gaussian) — only that singleton: any other RandomState over a non-MT19937 engine refuses to re-seed, NumPy's method behaviour. Seed records the last legacy seed as a uint, NumPy's [0, 2**32 - 1]. tomaxint, ranf and sample (each also taking the size as one Shape, as NumPy's random_sample(size) does) complete the legacy surface. Two NumPy inputs never return (zipf(a) for a >= 1025, vonmises once 4*kappa^2 overflows); NumSharp returns the distribution's limit there instead of hanging.

  • Sized legacy draws are fast without changing a bit.

    • Read-ahead uniforms. They come through a buffer bulk-filled by the bit generator's vectorized FillDouble, which never draws past what NumPy's per-value calls would.
    • Setup hoisted. Per-parameter setup that NumPy recomputes for every value runs once per call: Marsaglia-Tsang's 1/sqrt(9b), exp(-lam) and the PTRS constants, log(1-p), 2^(a-1), the von Mises envelope, and HRUA's sqrt and four loggams.
    • Memoized sub-terms. Deterministic sub-terms are memoized: the binomial inversion's CDF walk, BTPE's Step50 and Step52 bounds, HRUA's per-candidate loggam sums, zipf's acceptance power and the small-sample urn walk's ratios. multinomial also memoizes the per-category binomial setups that NumPy's single-entry cache thrashes on.
    • Two-phase Gaussian fills. The polar Gaussian fills (standard_normal, normal, lognormal, standard_cauchy, wald) run in two phases, so their log/sqrt chains overlap.

    Every memoized value is the same expression over the same inputs, so the streams stay byte-identical. Measured against NumPy 2.4.2 (NPY/NS, one pinned P-core, turbo off, min over repeated sweeps):

    • Most samplers: 1.5–5.6×. HRUA hypergeometric 4–5.6×, zipf 2–2.7×, poisson 1.6–2.3×, lognormal ~2×, the gamma family, chi-square, F and t with shapes ≥ 1 at 1.5–1.7×.
    • BTPE-sized binomial, and multinomial with such categories: ~1.4–1.5×.
    • CRT-bound samplers: 1.2–1.5×. This covers weibull, power, vonmises and gamma with shape < 1 (Johnk's algorithm), plus what builds on that gamma: beta with a shape ≤ 1, standard_t with df < 2, negative_binomial with n < 1 and dirichlet with alpha < 1. Their remaining work is the same MSVC pow/log/exp/cos call NumPy makes per value, and a bit-identical faster one does not exist.
  • np.random.default_rng(seed) returns a Generator backed by PCG64 and SeedSequence, with the modern ziggurat and bounded-integer algorithms used by NumPy 2.5.4.

  • The Generator has NumPy's whole distribution surface, on NumPy's modern algorithms rather than the legacy ones. That covers beta, binomial, chisquare, dirichlet, f, geometric, gumbel, hypergeometric, laplace, logistic, lognormal, logseries, multinomial, multivariate_hypergeometric, multivariate_normal, negative_binomial, noncentral_chisquare, noncentral_f, pareto, poisson, power, rayleigh, standard_cauchy, standard_t, triangular, vonmises, wald, weibull and zipf. The modern details are reproduced:

    • Ziggurat normals and exponentials under the gamma family.
    • The BTPE binomial with NumPy 2.5's corrected Stirling error terms (the legacy samplers keep the old ones).
    • beta's tiny-shape and log-space paths.
    • The HRUA hypergeometric with its logfactorial table, and an int64 zipf with its acceptance window.
    • vonmises' wrapped-normal fallback above kappa = 1e6.
    • noncentral chi-square's NaN short-circuit.
    • Int64 integer outputs.

    Every sampler matches default_rng(seed) bit for bit. The oracle checks 100 branch-reaching parameter sets, 222 constraint corners (NumPy's messages and check order), 66 streams of 20000 draws and 185 byte-parity corpus cases. multinomial has NumPy's vector path: counts broadcast against the probabilities' leading axes, with size required to equal the broadcast shape. Array parameters pass NumPy's 'safe' casting gate, so a float or uint64 count, or complex probabilities, raise NumPy's TypeError. Two documented exceptions:

    • pareto and power. They call the C runtime's expm1. NumSharp reproduces it exactly outside [-ln 2, ln 1.5], but inside that band Windows' ucrtbase uses a closed approximation. Values there can differ by up to 2 ulp for pareto. power raises the result to 1/a, which scales the difference: measured ≤1 ulp at a = 2.5 and 9 ulp at a = 0.3.
    • multivariate_normal. It is byte-identical with NumSharp.Interop.OpenBLAS, which supplies NumPy's own gesdd/syevd/potrf. Without it, managed factorizations are exact for diagonal covariances and agree to rounding for cholesky. For svd/eigh they may pick the other sign of an eigenvector: still a valid sample, but not NumPy's.

    The sized draws use the legacy sampler's techniques (read-ahead draws, per-fill setups, memoized deterministic sub-terms) without changing a bit. Two are specific to the modern algorithms: HRUA's setup is hoisted and each candidate's logfactorial sum memoized, and the urn walk keeps its 32-bit read-ahead in registers. Measured against NumPy 2.4.2 (NPY/NS, one pinned P-core, turbo off, min over repeated sweeps):

    • 1.5–3.1×. zipf 2.3–3.1×, standard_cauchy 2.3–2.5×, multinomial 2.1–2.3×, HRUA hypergeometric 2.1–2.2×, geometric inversion 2–2.3×, multivariate_normal 2–2.3×, standard_t 2×, lognormal 1.9×, noncentral_f and noncentral_chisquare (df > 1) 1.8–1.9×, dirichlet (alpha >= 0.1) up to 1.8×, and chisquare, f, beta with shapes above 1 and small-mean binomial at 1.5–1.7×.
    • 1.1–1.5×. BTPE binomial 1.4–1.5×, the urn-walk hypergeometric 1.35–1.4×, logseries, poisson, the geometric search, triangular, wald, laplace, gumbel, logistic and rayleigh, multivariate_hypergeometric 1–1.3×.
    • About 1× (the CRT ceiling). pareto, power, weibull, vonmises, and Johnk's gamma/beta (a shape below 1), with what builds on them: dirichlet with tiny alphas, noncentral_chisquare with df <= 1, negative_binomial. They measure 0.96–1.2×. Each value's cost is the pow/log/exp/cos/expm1 call NumPy makes too.
    • multinomial's broadcast path when every position brings a new (count, probability) pair: about 0.9×. This is the same per-position BTPE setup NumPy runs. When pairs recur, it measures 2.2×.
  • Every sampler that takes parameters accepts them as arrays, on both RandomState and Generator, broadcast the way NumPy broadcasts them. That covers beta, binomial, chisquare, exponential, f, gamma, geometric, gumbel, hypergeometric, laplace, logistic, lognormal, logseries, negative_binomial, noncentral_chisquare, noncentral_f, normal, pareto, poisson, power, rayleigh, standard_gamma, standard_t, triangular, uniform, vonmises, wald, weibull and zipf: rs.normal(locs, 2.0), g.poisson(column, new Shape(k, k)). The flow is NumPy's cont/disc:

    • Each parameter converts under NumPy's 'safe' rule, so a complex parameter or a float count raises NumPy's TypeError. When every parameter is 0-d the call takes the scalar path, so a 0-d array behaves exactly like a number. A null stands for Python's None: the default where NumPy has one (loc, scale, lam, …), otherwise NumPy's None handling.
    • Constraints are checked over the whole array before anything is drawn, in NumPy's order and with its array messages: lam value too large for a NaN mean, -0.0 rejected wherever NumPy tests the sign bit.
    • The output shape is size when given, else the parameters' broadcast shape. NumPy's shape mismatch and Output size (1,) is not compatible with broadcast dimensions of inputs (3,). errors are reproduced; default stands for size=None and Shape.Scalar for size=(). A given size is allocated before the parameters are broadcast against it, as NumPy's np.empty(size) is. So a size that is too big to allocate and also incompatible reports array is too big, not the shape mismatch.
    • One value is drawn per output position, in C order, with that position's parameters, so the values and the stream position after the call are byte-identical to NumPy. The oracle replays 834 legacy and 851 Generator array-parameter cases, 507 of them NumPy's constraint and broadcast errors. A mutation sweep over the read-ahead decisions, the constraint scans and the per-run setup sharing is caught in full.
    • The legacy samplers keep mtrand's own rules where they differ from the Generator's. uniform accepts reversed bounds (only the range must be finite), hypergeometric checks ngood + nbad < nsample first and has no 10^9 caps, negative_binomial has no Poisson-mean bound, and binomial's n is a C long. laplace, gumbel and logistic run the modern samplers on the MT19937 stream, as mtrand does.
    • Legacy integer results model NumPy's LP64 long, as the scalar samplers do. NumPy's Windows build (32-bit long) truncates or rejects some of those inputs, and its legacy HRUA hypergeometric never returns for a population past 2**31 (hypergeometric(2e9, 1.5e9, 12)).
    • NumPy's legacy samplers never return for two inputs: zipf with a >= 1025 and vonmises with kappa >= 2**511, where 4*kappa*kappa overflows. NumSharp returns the distribution's limit there without drawing, as its scalar samplers do.

    Measured against NumPy 2.4.2 (NPY/NS, one pinned P-core, turbo off, best of 7, 1K / 100K / 1M values):

    • Parameters that repeat along the walk: the scalar samplers' speed. This is a column against a row, or a parameter stretched over a larger size. It is drawn run by run, each run of equal parameters like a scalar fill: NumPy's per-call statements are computed once per run, and a long run also gets HRUA's, zipf's and the urn walk's memos. Most samplers measure 1.5–5.3× (legacy HRUA hypergeometric 5.3×, uniform 3.6–4.4×, zipf 2.9×, binomial 2.6–2.8×, normal 2.4–3.6×). The Generator's poisson, f, wald and negative_binomial measure 1.1–1.4×, and the CRT-bound vonmises, power and pareto 1.06–1.35×, as their scalar fills do.
    • One transform per value: 1.3–4.4×. This covers normal, lognormal, exponential, uniform, laplace, logistic, gumbel, rayleigh, triangular, wald and standard_t, with any parameter layout.
    • A new parameter at every position: 0.88–1.8×, per-call parity. NumPy recomputes each sampler's per-call setup for every value (sqrt/log/exp, and PTRS's, BTPE's or HRUA's constants), and so does NumSharp. The fill's advantages (shared setups, memos) do not apply. The Generator's cells sit at the low end because NumPy's PCG64 call path is cheap: hypergeometric 0.88–1.1×, poisson 0.91–1×, and beta, zipf, logseries, vonmises and power 0.95–1.2×. Legacy binomial measures 0.91–1×. Its setups go through RandomState's single-entry binomial cache, kept exactly as NumPy's because what one call leaves in it is visible to the next. The Generator's binomial keeps a per-fill memo of recurring keys and measures 1.2–2.4×.
  • All five NumPy bit generators exist — PCG64, PCG64DXSM, Philox, SFC64 and MT19937 — each a BitGenerator with NumPy's surface: random_raw, state (typed PCG64.State, Philox.State, …), seed_seq, lock and spawn. NumPy's spelling np.random.Generator(np.random.Philox(seed)) works verbatim — np.random carries a factory for every class NumPy's module exposes (MT19937, PCG64, PCG64DXSM, Philox, SFC64, SeedSequence, Generator), each mirroring every constructor overload — as does new Generator(new Philox(seed)), and either reproduces NumPy's stream byte for byte. PCG64, PCG64DXSM and Philox have advance(delta) (any BigInteger, wrapped like NumPy's wrap_int) and jumped(n); Philox also takes an explicit key/counter (new Philox(key: 5), NumPy's integer and array forms and error texts included). As in NumPy, new MT19937(42) seeds through SeedSequence; the legacy stream of RandomState(42) is mt._legacy_seeding(42), and MT19937.jumped(n) advances a copy by n * 2**128 draws with NumPy's jump polynomial.

  • SeedSequence has NumPy's whole surface, with NumPy's types: spawn(n) (child spawn_keys — Python ints, so BigIntegers — and n_children_spawned, a uint32_t), pool_size (a Py_ssize_t: long), pool and generate_state(n_words, dtype) (uint32/uint64 NDArrays over a 64-bit count, with NumPy's allocation errors), state, entropy (the 128-bit OS entropy of an unseeded sequence, to log for reproducibility) and NumPy's repr. Entropy and spawn keys coerce exactly as NumPy's _coerce_to_uint32_array does: nested sequences flatten, a "0x…" string is hex and a string that starts with a digit is decimal ("012" is 12 — there is no octal reading), a string key is a sequence of one-character strings. BitGenerator.spawn(n) and Generator.spawn(n) derive independent children from it — the recommended way to hand streams to parallel workers. Any ISeedSequence is accepted as a bit generator's seed (a SeedlessSeedSequence is refused as NumPy refuses it: seedless SeedSequences cannot generate state); every engine names its parameter seed as NumPy does, and a null one — a null literal or a typed null array alike — is NumPy's seed=None (fresh OS entropy).

  • default_rng accepts every NumPy seed form: an integer (up to any BigInteger), a sequence or integer array, a SeedSequence, a BitGenerator (wrapped), a Generator (passed through) or a legacy RandomState (its engine is wrapped, as default_rng(RandomState) does). Every overload names its parameter seed, NumPy's only parameter, and a null argument of any type is default_rng(None).

  • Generator.integers and the legacy randint take NumPy's array bounds (g.integers(lows, highs), rs.randint(0, highs, dtype: np.uint8)) through NumPy's own broadcast path: each bound is checked against the dtype and against the other in NumPy's order and words (low is out of bounds for uint64, high <= 0, low >= high, cannot convert float NaN to integer) before anything is drawn, the draws continue one buffered stream across positions, and NumPy's two quirks carry over — a size smaller than the bounds' broadcast takes the first positions, and 64-bit float bounds in a non-C layout come out in NumPy's scrambled order. Bounds past long/ulong are BigIntegers, NumPy's Python ints: g.integers(0, BigInteger.Pow(2, 64), dtype: np.uint64) is the full-range idiom, and anything beyond a dtype raises NumPy's out-of-bounds message.

  • Every Generator and RandomState draw holds the bit generator's lock, so one generator (or several over the same bit generator) can be shared between threads: each call consumes a contiguous piece of the one stream.

  • The whole random surface is oracle-checked, overload by overload. Every public member — each overload of RandomState, Generator, the five bit generators and their State classes, SeedSequence, SeedlessSeedSequence and default_rng, 493 in all (four NumSharp-only members exempt) — is replayed against NumPy 2.5.4 by its exact C# signature: every legacy sampler on the legacy MT19937 and on RandomState(engine) for each engine, every Generator member on all five engines, under 10 fixed seeds, comparing NumPy's result AND the generator's full state after the call (so drawing one value too many or too few fails, not only a wrong value). CI gates prove the coverage itself — every overload, every parameter (omitted, non-default, null, every accepted dtype/method value, NumPy's parameter names in NumPy's order), every engine, every seed — and a nightly job replays the same families under 10 fresh seeds. About 26,600 cases; the few intended differences (the modern pareto/power within a few ULP where the Windows CRT's in-band expm1 differs, and states NumPy would store and then read outside an array) are listed in the fuzz README. A replay that invokes overloads by reflection cannot tell whether NumPy's CALL compiles in C# and binds the right overload, so 1,793 of NumPy's spellings were also compiled verbatim and compared: every legacy sampler whose parameters all default takes size: alone or any keyword subset, a null seed binds everywhere, and NumPy's size=None is spelled size: default (a Shape is a struct, so size: null cannot compile).

The familiar legacy example matches NumPy:

np.random.seed(42);
var a = np.random.rand(5);
// [0.37454012, 0.95071431, 0.73199394, 0.59865848, 0.15601864]

The oracle suite separates portable byte-parity cases from distributions whose transforms depend on the platform math library. MT19937/PCG64 bit streams and purely integer/exactly-rounded paths are hard-gated across hosts. Host-libm cases are byte-pinned on the matching Windows AMD64 host and are inconclusive elsewhere. Therefore, "same seed" is a tested stream guarantee for the corresponding NumPy API, but it is not a blanket promise that every transformed distribution has identical last bits on every operating system.


.npy and .npz Interoperability

The .npy implementation is a port of NumPy 2.5.4's format code and is tested against files written by real NumPy. For supported dtypes and layouts, NumSharp's writer produces the same header and data bytes as NumPy's writer.

  • Format versions 1.0, 2.0, and 3.0 are read and written. Automatic writes choose the oldest format that can represent the header.
  • C- and F-order files are supported. A strictly F-contiguous array is written with fortran_order: True and loads as F-contiguous.
  • Little- and big-endian numeric files load. Big-endian data is converted to native byte order because NumSharp has no byte-swapped dtype metadata.
  • bool, all eight integer widths, float16, float32, float64, complex128, and the fixed-width string dtypes (|S5, <U3) have round-trip mappings. complex64 loads by widening to complex128. Char is written as <U1, which reads back as a <U1 string array.
  • A StringDType array is written as NumPy writes it: a '|O' header and NumPy's protocol-4 pickle of the array, byte for byte (frames, memo and batches included). It loads with allow_pickle: true, with its NA values, na_object and coerce. .npz members follow the same rules.
  • Decimal cannot be saved because NumPy has no decimal dtype. Other object arrays (any pickle that is not a StringDType array's), structured, subarray, datetime/timedelta, void, zero-width string, and unsupported extended-precision descriptors are rejected with a capability-specific error.
  • np.load(..., mmap_mode: ...) supports read-only, read-write, and copy-on-write mapping for a .npy file path. Streams and byte arrays cannot be memory-mapped.

np.savez and np.savez_compressed write uncompressed and deflated ZIP archives. np.load_npz opens members lazily and caches loaded arrays; the returned NpzFile owns resources and should be disposed. np.load detects .npy versus .npz from magic bytes and returns either NDArray or NpzFile, while np.load_npy and np.load_npz provide typed entry points.

allow_pickle defaults to false for loading and to true for saving, as in NumPy. With allow_pickle: true, NumSharp reads exactly one kind of pickle: the one NumPy writes for a StringDType array (numpy._core.multiarray._reconstruct with the array's state, and _convert_to_stringdtype_kwargs for its descriptor). Any other pickle is refused, with a message that names it. NumSharp has no general unpickler, adds no object dtype, and never calls a Python function that a file names. Without allow_pickle, loading such a file raises NumPy's text Object arrays cannot be loaded when allow_pickle=False, and np.save(..., allow_pickle: false) of a StringDType array raises ValueError: Object arrays cannot be saved when allow_pickle=False after the header, as NumPy does. A StringDType file cannot be memory-mapped.


Linear Algebra and Optional OpenBLAS

NumSharp's numerical kernels in NumSharp.Core are implemented in managed C# and do not require a third-party native library. Core does contain a Windows-only P/Invoke to VirtualAlloc/VirtualFree for large zero-initialized buffer allocation; that is a memory-management fast path, not a numerical backend. Matrix products such as dot, matmul, inner, vdot, vecdot, matvec, and vecmat have managed implementations and remain available without an optional package.

The separate NumSharp.Interop.OpenBLAS package installs an IBlasBackend. It accelerates and, for supported floating/complex routes, can reproduce NumPy's BLAS accumulation order. Referencing the package is the normal opt-in; removing or disabling the backend leaves managed matrix products available.

Matrix factorizations are different. Core does not carry managed LU, QR, SVD, or eigensolver kernels. These public APIs validate inputs and then require a backend implementation:

  • cholesky
  • det and slogdet
  • eig, eigvals, eigh, and eigvalsh
  • inv and solve
  • lstsq and qr
  • svd and svdvals

The OpenBLAS package implements those operations through LAPACK. Without a serving backend they throw OpenBlasMissingBackendException; they are not null-returning stubs. APIs built from an SVD or solve, such as pinv, matrix_rank, negative matrix_power, and spectral/nuclear matrix norms, inherit that backend requirement.

Pure compositions such as non-negative matrix_power, multi_dot, ordinary matrix products, and non-SVD norm orders work in Core. See OpenBLAS interoperability for supported dtypes, delivery, parity, and configuration details.


FFT

The complete 18-callable np.fft inventory is implemented in Core: complex, real, Hermitian, 1-D, 2-D, and N-D transforms, frequency helpers, and shift helpers. Compute runs through a managed port of NumPy 2.5.4's vendored pocketfft engine; it does not require OpenBLAS.

The double/complex128 path preserves pocketfft's operation order and is covered by byte-parity oracles across contiguous, transposed, strided, negative-stride, and broadcast-read inputs. NumSharp evaluates pocketfft the way NumPy's x86-64 wheels do: each product rounded separately, with twiddle factors from the platform's math library. On x86-64 it therefore matches the NumPy running beside it, checked live on Windows and Linux. NumPy's own arm64 wheels are the exception. They are compiled with the compiler's default floating-point contraction for a baseline that has fused multiply-add, so pocketfft's twiddle and butterfly multiply-adds round once there. Most bins of an arm64 NumPy transform sit an ULP or so from NumSharp's, which is the literal evaluation. Because the twiddles come from the platform's math library, whose last bits differ between operating systems, a large transform's exact bits can also differ between hosts. NumSharp's are no exception. NumSharp also has a single-precision pocketfft engine, but it has no complex64 storage dtype: float16/float32 transform results are therefore exposed as complex128, where NumPy exposes complex64. The FFT oracle treats that as a documented dtype divergence while still checking the values. As elsewhere, public API availability does not replace the per-dtype oracle evidence.


Execution Engine and SIMD

SIMD is not future roadmap work. Core emits runtime-specialized IL kernels and selects V128, V256, or V512 paths when the operation, dtype, hardware, and layout permit it. Contiguous numeric arrays take the fast paths; strided and broadcast operands use general iterator paths. Half, Complex, and Decimal use scalar arithmetic where the .NET BCL has no suitable vector operation.

The optional OpenBLAS package is the only native numerical backend. The Windows virtual-memory calls described above only allocate and release buffers. Installing OpenBLAS does not replace the tensor engine; it fills the engine's settable backend seam, and unsupported operand combinations fall back to Core for matrix products.


Known Gaps

The generated dashboard is the exhaustive API list. The important capability-level gaps are:

  • no native complex64, datetime/timedelta, object, structured or void array storage;
  • no general object-array formatting inputs; np.evaluate has no node for the np.strings transformations (upper, strip, replace, center, ...): call them directly, and their result can then enter an expression, whose other nodes compute on text as NumPy does;
  • no GPU device or DLPack import (np.from_dlpack is missing).

The dashboard identifies other API gaps per published revision. A method that exists can still have parameter, layout or dtype-specific differences; the text guide lists those for strings, including hash-order differences in unique_values, chararray's static dispatch and operations that NumPy itself refuses. Text support does not imply support for every np.* function on text.

When exact parity matters, search the coverage dashboard for API presence and the test dashboard for oracle depth. Do not infer support from this summary alone.


Reporting a Compatibility Difference

A useful report includes:

  1. The NumPy 2.5.4 code and observed output or exception.
  2. The equivalent NumSharp code and observed output or exception.
  3. Input dtype, shape, strides/layout, and whether the input is a view or broadcast array.
  4. Raw floating-point or complex bytes when the difference is below display precision.

The preferred fix is a test generated from real NumPy output, followed by an implementation that matches NumPy's source structure and handles contiguous, strided, broadcast, sliced-offset, empty, scalar, and dtype edge cases.


References