[0.81.0] NumPy 2.5.4, NumPy's own signatures, scalars and exception classes, 17 new np.* functions, TorchSharp interop, NumPy-parity fixes

.claude/CLAUDE.md

@@ -1,7 +1,7 @@
 # NumSharp Project Instructions
 
 NumSharp is a .NET port of Python's NumPy targeting 1-to-1 API and behavioral compatibility with NumPy 2.x; the oracle
-pins NumPy 2.4.2. `refs/numpy/` is a full clone of NumPy: the authority on API behavior, edge cases and implementation.
+pins NumPy 2.5.4. `refs/numpy/` is a full clone of NumPy: the authority on API behavior, edge cases and implementation.
 
 Area rules live in `.claude/rules/*.md` and load when Claude reads or edits a file in their area. The API index below
 names the rule for each area: read it before answering a question about that area without opening its files.
@@ -135,7 +135,7 @@ np                Static API class (like `import numpy as np`)
 
 ## API index
 
-Tested against NumPy 2.4.2. Each line: the `np.*` names, then the rule that holds the area's details.
+Tested against NumPy 2.5.4. Each line: the `np.*` names, then the rule that holds the area's details.
 - Array creation: `arange`, `array`, `asanyarray`, `asarray`, `asarray_chkfinite`, `ascontiguousarray`, `asfortranarray`,
   `asmatrix`, `bmat`, `copy`, `empty`, `empty_like`, `eye`, `frombuffer`, `full`, `full_like`, `geomspace`, `identity`,
   `linspace`, `logspace`, `matrix`, `meshgrid`, `mgrid`, `ndarray`, `ogrid`, `ones`, `ones_like`, `require`, `tri`,
@@ -144,23 +144,25 @@ Tested against NumPy 2.4.2. Each line: the `np.*` names, then the rule that hold
 - Shape manipulation: `append`, `array_split`, `atleast_1d`, `atleast_2d`, `atleast_3d`, `block`, `c_`, `column_stack`,
   `concat`, `concatenate`, `delete`, `dsplit`, `dstack`, `expand_dims`, `flatten`, `flip`, `fliplr`, `flipud`, `hsplit`,
   `hstack`, `insert`, `intersect1d`, `matrix_transpose`, `moveaxis`, `pad`, `permute_dims`, `r_`, `ravel`, `repeat`,
-  `reshape`, `resize`, `roll`, `rollaxis`, `rot90`, `setdiff1d`, `setxor1d`, `split`, `squeeze`, `stack`, `swapaxes`,
-  `tile`, `transpose`, `trim_zeros`, `union1d`, `unique`, `unique_all`, `unique_counts`, `unique_inverse`,
-  `unique_values`, `unstack`, `vsplit`, `vstack` → `creation-manipulation.md` (`unique.md` for `unique` and `unique_*`;
-  every axis argument: `axis-arguments.md`).
+  `reshape`, `resize`, `roll`, `rollaxis`, `rot90`, `row_stack`, `setdiff1d`, `setxor1d`, `split`, `squeeze`, `stack`,
+  `swapaxes`, `tile`, `transpose`, `trim_zeros`, `union1d`, `unique`, `unique_all`, `unique_counts`, `unique_inverse`,
+  `unique_values`, `unstack`, `vsplit`, `vstack`; `lib.stride_tricks.as_strided` / `sliding_window_view` →
+  `creation-manipulation.md` (`unique.md` for `unique` and `unique_*`; every axis argument: `axis-arguments.md`).
 - Broadcasting: `are_broadcastable`, `broadcast`, `broadcast_arrays`, `broadcast_to`.
-- Math, arithmetic: `abs`, `absolute`, `acosh`, `add`, `arccos`, `arccosh`, `arcsin`, `arcsinh`, `arctan`, `arctan2`,
-  `arctanh`, `asinh`, `atanh`, `cbrt`, `ceil`, `clip`, `convolve`, `correlate`, `cos`, `cosh`, `deg2rad`, `degrees`,
-  `divide`, `divmod`, `exp`, `exp2`, `expm1`, `fabs`, `fix`, `float_power`, `floor`, `floor_divide`, `fmod`, `gcd`, `lcm`,
-  `log`, `log10`, `log1p`, `log2`, `mod`, `modf`, `multiply`, `negative`, `positive`, `power`, `rad2deg`, `radians`,
-  `reciprocal`, `remainder`, `rint`, `sign`, `sin`, `sinc`, `sinh`, `spacing`, `sqrt`, `square`, `subtract`, `tan`, `tanh`,
-  `true_divide`, `trunc` → `ufuncs.md` and `float-math.md`.
-- Math, reductions: `all`, `amax`, `amin`, `any`, `argmax`, `argmin`, `average`, `average_returned`, `count_nonzero`,
-  `cov`, `cumprod`, `cumsum`, `diff`, `ediff1d`, `max`, `mean`, `median`, `min`, `percentile`, `prod`, `ptp`, `quantile`,
-  `std`, `sum`, `var` → `reductions.md` (median / percentile / quantile: `quantile.md`).
+- Math, arithmetic: `abs`, `absolute`, `acos`, `acosh`, `add`, `arccos`, `arccosh`, `arcsin`, `arcsinh`, `arctan`,
+  `arctan2`, `arctanh`, `asin`, `asinh`, `atan`, `atan2`, `atanh`, `cbrt`, `ceil`, `clip`, `convolve`, `correlate`, `cos`,
+  `cosh`, `deg2rad`, `degrees`, `divide`, `divmod`, `exp`, `exp2`, `expm1`, `fabs`, `fix`, `float_power`, `floor`,
+  `floor_divide`, `fmod`, `gcd`, `interp`, `lcm`, `log`, `log10`, `log1p`, `log2`, `mod`, `modf`, `multiply`, `negative`,
+  `positive`, `pow`, `power`, `rad2deg`, `radians`, `reciprocal`, `remainder`, `rint`, `sign`, `sin`, `sinc`, `sinh`,
+  `spacing`, `sqrt`, `square`, `subtract`, `tan`, `tanh`, `true_divide`, `trunc` → `ufuncs.md` and `float-math.md`
+  (`acos`, `asin`, `atan`, `atan2`, `pow`: NumPy 2.0's Array-API names, forwarding to the originals).
+- Math, reductions: `all`, `amax`, `amin`, `any`, `argmax`, `argmin`, `average`, `count_nonzero`, `cov`, `cumprod`,
+  `cumsum`, `cumulative_prod`, `cumulative_sum`, `diff`, `ediff1d`, `max`, `mean`, `median`, `min`, `percentile`, `prod`,
+  `ptp`, `quantile`, `std`, `sum`, `var` → `reductions.md` (median / percentile / quantile: `quantile.md`).
 - Math, NaN-aware: `nanmax`, `nanmean`, `nanmedian`, `nanmin`, `nanpercentile`, `nanprod`, `nanquantile`, `nanstd`,
   `nansum`, `nanvar` → `reductions.md` (the nan quantile forms: `quantile.md`).
-- Bitwise: `bitwise_and`, `bitwise_or`, `bitwise_xor`, `invert`, `left_shift`, `right_shift` → `ufuncs.md`.
+- Bitwise: `bitwise_and`, `bitwise_invert`, `bitwise_left_shift`, `bitwise_or`, `bitwise_right_shift`, `bitwise_xor`,
+  `invert`, `left_shift`, `right_shift` → `ufuncs.md`.
 - Comparison and logic: `all`, `allclose`, `any`, `array_equal`, `equal`, `fmax`, `fmin`, `greater`, `greater_equal`,
   `isclose`, `iscomplex`, `iscomplexobj`, `isfinite`, `isin`, `isinf`, `isnan`, `isreal`, `isrealobj`, `isscalar`,
   `iterable`, `less`, `less_equal`, `logical_and`, `logical_not`, `logical_or`, `logical_xor`, `maximum`, `minimum`,
@@ -204,17 +206,19 @@ Tested against NumPy 2.4.2. Each line: the `np.*` names, then the rule that hold
   `shuffle`, `standard_cauchy`, `standard_exponential`, `standard_gamma`, `standard_normal`, `standard_t`, `triangular`,
   `uniform`, `vonmises`, `wald`, `weibull`, `zipf`, plus `Generator`/`default_rng` → `random.md`.
 - File I/O: `fromfile`, `fromstring`, `load`, `load_npy`, `load_npz`, `loadtxt`, `save`, `savetxt`, `savez`,
-  `savez_compressed`, `tofile`; printing: `array2string`, `array_repr`, `array_str`, `format_float_positional`,
+  `savez_compressed`, `tofile`, the `np.lib.format` module; printing: `array2string`, `array_repr`, `array_str`, `format_float_positional`,
   `format_float_scientific`, `get_printoptions`, `printoptions`, `set_printoptions` → `io-printing.md` (the text
   functions: `text-io.md`).
-- Other: `around`, `asscalar`, `copyto` (`creation-manipulation.md`), `round_`, `size`, `multithreading`.
+- Other: `around`, `asscalar`, `copyto` (`creation-manipulation.md`), `ndim`, `round`, `shape`, `size`, `multithreading`,
+  the `np.lib.array_utils` module (`axis-arguments.md`).
 - Operators: arithmetic `+`, `-`, `*`, `/`, `%`, unary `-`; comparison `==`, `!=`, `<`, `>`, `<=`, `>=` (they return
   `NDArray<bool>`); logical `&`, `|`, `!`.
 - Indexing: integers and slice strings (`nd[0]`, `nd["1:3"]`, `nd["::-1"]`), boolean masks (`nd[mask]`, and
   `nd[mask] = v`), fancy indexing (`nd[indices]`). A raw `int[]`/`long[]` as the ONLY index is fancy (`nd[new int[]{0,2}]` selects rows 0 and 2); `nd[0,2]`
   is a coordinate, and coordinate access by array is `nd.GetData(int[]/long[])` → `selection-indexing.md`.
-- Interop packages (OpenBLAS, ONNX Runtime, ML.NET, System.Numerics.Tensors, pythonnet) → `openblas.md`,
-  `interop-packages.md`. ParquetNet is UNRELEASED: no package, no docs, no mention in release notes.
+- Interop packages (OpenBLAS, ONNX Runtime, ML.NET, System.Numerics.Tensors, TorchSharp, pythonnet) → `openblas.md`,
+  `interop-packages.md`. ParquetNet is UNRELEASED: no package, no docs, no mention in release notes (TorchSharp ships
+  from 0.81.0).
 
 ## Build and test
 
@@ -344,15 +348,15 @@ Create issues on `SciSharp/NumSharp` with `gh issue create` (`GH_TOKEN` through
 | Rule | Holds |
 |------|-------|
 | `openblas.md` | the `IBlasBackend` seam; `NumSharp.Interop.OpenBLAS`: why it exists, the bundled binary and discovery order, the macOS loader, the build-time override, what decides the result bits, API, gates, examples |
-| `interop-packages.md` | the unreleased-package policy; ONNX Runtime, ML.NET, System.Numerics.Tensors (sources, verbs, dtypes, lifetime, gates); the pythonnet examples |
+| `interop-packages.md` | the unreleased-package policy; ONNX Runtime, ML.NET, System.Numerics.Tensors, TorchSharp (sources, verbs, dtypes, lifetime, gates; TorchSharp's state-matrix oracle and coverage recipe); the pythonnet examples |
 | `kernels.md` | the two IL generators' contracts, shared infrastructure, coverage, kernel rules, float16 techniques, NaN operand order, the 2-D block kernel and its stationary-out mode, broadcast pattern stages, reversed runs |
 | `memory-views.md` | `Shape` (fields, flags, sharing), Slice / broadcasting / operator internals, views and aliases, allocation from a view's Shape, the buffer pool |
 | `creation-manipulation.md` | `np.arange`, `np.ndarray`, the `as*` family, object-list coercion, full / ones / eye, `np.frombuffer`, linspace / logspace / geomspace, set routines, flips / transposes, stacking, resize / tolist, allocation and reshape guards, `np.copyto` |
 | `unique.md` | `np.unique` (`UniqueResult`, the axis path, NumPy's flat routes) and the Array-API unique family, the hash path |
 | `axis-arguments.md` | `Shape.check_and_adjust_axis` / `normalize_axis_tuple`, the rules every axis argument follows, NumPy's errors around axes |
 | `matrix.md` | `NDMatrix`: static type versus object (woven mechanisms), scalars, indexing, operators and scaling, reductions, construction, divergences, gates |
 | `ufuncs.md` | the ufunc surface (`dtype=`, `out=`, `where=`), the result layout, fix, fabs, clip, divmod, float_power, power's float loops, gcd / lcm, bitwise |
-| `float-math.md` | correlate / convolve, inverse hyperbolic, sinc, the float32 kernels ported from NumPy, exp2, expm1 / log1p, complex128 NaN signs |
+| `float-math.md` | correlate / convolve, np.interp's fill values, inverse hyperbolic, sinc, the float32 kernels ported from NumPy, exp2, expm1 / log1p, complex128 NaN signs |
 | `reductions.md` | the reduce prologue, sum / mean, var / std, numpy.ma mean / var, max / min / ptp schedules and keywords, float16 HALF loops, the scans, cov, the NaN-aware family |
 | `quantile.md` | the quantile family: `q`'s dtype and the lerp, `out=`, the nan forms, `weights=`, the partition |
 | `masked-arrays.md` | numpy.ma: semantics by result kind, the fill value, the set routines, `ma.put`, text and `StringDType` |

.claude/commands/np-function.md

@@ -1,14 +1,14 @@
 ---
 name: np-function
-description: Implement a NumPy np.* function in NumSharp with full API parity, optimizations, and variation coverage (NumPy 2.4.2 source of truth).
+description: Implement a NumPy np.* function in NumSharp with full API parity, optimizations, and variation coverage (NumPy 2.5.4 source of truth).
 argument-hint: <np.function_name or description>
 ---
 
 When user requests /np-function, you are to follow these instructions carefully!:
 
 # np-function command
 
-We are looking to support NumPy's np.* to the fullest. we are aligning with NumPy 2.4.2 as source of truth and are to provide exact same API (np.* overloading) as NumPy does.
+We are looking to support NumPy's np.* to the fullest. we are aligning with NumPy 2.5.4 (the pin in `numpy-version.txt`) as source of truth and are to provide exact same API (np.* overloading) as NumPy does.
 This session we focusing on: """$ARGUMENTS"""
 You job is around interacting with np.* functions - no more than one unless they are closely related.
 

.claude/rules/axis-arguments.md

@@ -1,10 +1,12 @@
 ---
 paths:
   - "src/NumSharp.Core/View/Shape.Axes.cs"
+  - "src/NumSharp.Core/View/NDAxis.cs"
   - "src/NumSharp.Core/Exceptions/AxisError.cs"
-  - "src/NumSharp.Core/Exceptions/AxisOutOfRangeException.cs"
   - "src/NumSharp.Core/Backends/Default/Math/Reduction/ReductionArguments.cs"
   - "test/NumSharp.Tests/Manipulation/AxisArgumentParity.Test.cs"
+  - "test/NumSharp.Tests/APIs/KeptAxisOverloads.cs"
+  - "test/NumSharp.Tests.Build.Analyzer/AxisOverloadResolutionTests.cs"
 ---
 
 # Axis arguments
@@ -21,7 +23,59 @@ type-strict, zero-excuse `axis_args.jsonl` oracle tier, the `evaluate.jsonl` tie
 - `Shape.normalize_axis_tuple(axis, ndim, argname, allow_duplicate)` is NumPy's function: a NEW array (the caller's is
   never rewritten), every axis range-checked before the repeat check, a repeat NumPy's `ValueError "repeated axis"` /
   `"repeated axis in \`{argname}\` argument"` (never silently removed).
-- `AxisOutOfRangeException` is `[Obsolete]` and derives from `AxisError`: nothing in NumSharp raises it.
+- `AxisError` is the only axis exception: the legacy `AxisOutOfRangeException` (parenthesized text, never raised) is
+  deleted, as is every removed member (no `[Obsolete]` shims).
+- `np.lib.array_utils` (`APIs/np.lib.array_utils.cs`) is NumPy's public module over these ports:
+  `normalize_axis_index(axis, ndim, msg_prefix)` is `Shape.check_and_adjust_axis`, `normalize_axis_tuple(axis, ndim,
+  argname, allow_duplicate)` `Shape.normalize_axis_tuple` (an `NDAxis`, with the kept `int` and `int[]` forms), and
+  `byte_bounds(a)` the `(low, high)` byte addresses NumPy derives from `__array_interface__` (a C-contiguous array's
+  `size * itemsize`, else `(n - 1) * stride` per axis to the low or the high end, then one item).
+- `NDAxis` (`View/NDAxis.cs`, the owner's OD1) is NumPy's axis argument as one type: a function whose NumPy default is
+  `axis=None` takes `NDAxis? axis = null`, one whose axis is required `NDAxis axis` (np.expand_dims, np.moveaxis). It
+  converts implicitly from `int` (lifted: an `int?` too, null = None), `int[]` (a null array is None for `NDAxis?` and an
+  ArgumentNullException for `NDAxis`), `(int, int)` and `(int, int, int)`, and has public constructors for the same
+  values. It only HOLDS the axes as given: each function normalizes them itself, because NumPy's functions read an axis
+  four ways - `normalize_axis_tuple` (`NDAxis.Normalize`; flip, expand_dims, moveaxis, the quantile family, average,
+  trim_zeros, size, gradient, roll with `allow_duplicate`: every range, then "repeated axis"), the ufunc reduction (sum /
+  prod / max / min / all / any / ptp / the nan reductions / the sum behind count_nonzero: the out / where converters,
+  every range, then "duplicate value in 'axis'", and the INTEGER axis 0 / -1 of a 0-d input), `_count_reduce_items`
+  (np.mean / var / std: each item's range from the count, the repeat only from the sum after its out check, so
+  `np.mean(a, (0, 0), out=read_only)` is the read-only error and `np.var`'s the repeat) and `PyArray_ConvertMultiAxis`
+  (squeeze: each item's range and repeat in order, so `(0, 0, 5)` is the repeat); np.argmax / argmin take ONE integer
+  (a tuple of any length is `TypeError "'tuple' object cannot be interpreted as an integer"`, before the out), and so do
+  np.nanargmax / nanargmin, whose NumPy statements reduce the NaN mask over the tuple first (`np.all(mask, axis)`: its
+  AxisError, "duplicate value in 'axis'" and "All-NaN slice encountered" come before the TypeError; an integer or empty
+  input has no mask) and chararray.argmax / argmin (the TypeError before the finalize error). `IsTuple`
+  tells `1` from `(1,)` (Python's `1 != (1,)`); `default(NDAxis)` and `new NDAxis()` are the EMPTY tuple. Trap: the null
+  literal converts to `NDAxis` through the `int[]` operator, so `flag ? null : someAxis` is typed `NDAxis` and throws -
+  write `(NDAxis?)null`. NumSharp.Build hands an `NDAxis` axis to a `[ReducesThrough]` collapse as it is
+  (`NDSubclass.CollapseAxes`, the weaver's `EmitAxisValue`), so `matrix._collapse` keeps a tuple's kept-dims matrix (the
+  1 x 1 matrix for `(0, 1)`, the whole matrix for `()`); an `int` / `int?` axis keeps `Collapse`.
+- The KEPT INTEGER OVERLOADS (the owner's API-parity batch-6 decision, "keep the int and int[] overloads ... for
+  allllll overloads", after a resolution proof): every public np / ndarray / chararray / np.fft / np.linalg member that
+  takes NumPy's axis as `NDAxis?` / `NDAxis` has an `int axis` and an `int[] axis` overload beside it, WITHOUT defaults
+  (a parameter before the axis loses its default too: norm's `ord`, trim_zeros' `trim`, gradient's spacing), each a
+  documented one-line forward that casts to the NDAxis member (every answer, error, layout and subclass result is that
+  member's; the woven matrix arm is reached through it). A one-integer axis (argmax / argmin / nanargmax / nanargmin,
+  ndarray and chararray methods included) keeps `int? axis` instead (no int[]: NumPy refuses a tuple). moveaxis keeps
+  `(int, int)` and `(int[], int[])`. The engine (`TensorEngine` members) and numpy.matrix (its static-type `int`
+  overloads) are outside the decision. The binding rules this gives, proven at C# 12 (net8.0) and C# 14 (net10.0) on
+  mimics (scratchpad probe_axis) and pinned against the real members at C# 12 by
+  `Build.Analyzer/AxisOverloadResolutionTests.cs`: an int-typed argument (a literal, an int / short / byte / char
+  variable) binds `int`; an `int[]` and a bare `null` bind `int[]` (null converts to `int[]` better than to `NDAxis?`; a
+  null array is None); every other spelling (tuples, NDAxis values, an `int?` variable, an omitted axis) binds the NDAxis
+  member. Why the kept integer is `int`, never `int?`, beside an `int[]`: with `int?`, `f(a, null)` is CS0121 ambiguous.
+  Why a one-integer axis keeps `int?`: with a plain `int`, `f(a, default)` would silently be axis 0. The one spelling the
+  three overloads refuse is `f(a, default)` (CS0121, `int` vs `int[]`) - a compile error, never a silent answer. A
+  NumPy-signature test or tool counts overloads WITHOUT the kept forwards: `KeptAxisOverloads.WithoutKeptIntegerForms`
+  (tests), `drop_kept_axis_forwards` (tools/api-parameter-parity/signature_diff.py, coverage/signature_parity.py) - a
+  structural rule (integer-typed axis parameters AND an NDAxis sibling with otherwise the same parameter names and types),
+  never a list, so a stray integer overload without its NDAxis member still counts.
+- The reductions route a tuple by `ReductionArguments.TryIntegerForm`: a set of ONE axis takes the integer route and a
+  set of EVERY axis the None route (NumPy builds the same flags, so the exact schedules and the text routes are reused);
+  every other tuple (two axes or more short of every axis, the empty tuple of an input with dimensions, or a tuple NumPy
+  refuses) takes the function's NumPy statements over the set, which raise in NumPy's order
+  (`Default.Reduction.AxisSet.cs`, `reductions.md`).
 
 Rules every caller follows:
 - Never wrap then test. `while (axis < 0) axis += ndim` accepts `-ndim - 1` (wrapping twice, to the last axis) and
@@ -30,8 +84,8 @@ Rules every caller follows:
 - Check before every shortcut. `ReductionArguments.CheckReduceAxis` (PyUFunc_GenericReduction's integer branch: a 0-d
   input takes 0 / -1 and nothing else) runs first in prod / max / min / nanmax / nanmin, whose 0-d and one-element
   shortcuts would otherwise answer any axis; likewise cumsum / cumprod / argmax / argmin / compress.
-- 0-d inputs: the ufunc reductions, `count_nonzero` and `squeeze` accept axis 0 / -1 of a 0-d input (no axis selected)
-  and report every other axis against rank 0; the `PyArray_CheckAxis` functions (argmax / argmin / argsort / cumsum /
+- 0-d inputs: the ufunc reductions, `count_nonzero` and `squeeze` accept the INTEGER axis 0 / -1 of a 0-d input (no axis
+  selected; a tuple `(0,)` is an AxisError, `()` selects nothing) and report every other axis against rank 0; the `PyArray_CheckAxis` functions (argmax / argmin / argsort / cumsum /
   cumprod / take / compress / repeat / packbits / unpackbits) ravel a 0-d input first and report rank 1; `np.sort`,
   `np.rollaxis`, the tuple forms and `np.linalg.norm` / `vector_norm` (a tuple reduce) refuse every axis.
 - Python's IndexError where NumPy reads `a.shape[axis]` first: `np.split` / `np.array_split` (before the sections