scirs2-numpy 0.3.0

PyO3-based Rust bindings of the NumPy C-API (SciRS2 fork with ndarray 0.17 support)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# scirs2-numpy TODO

## Status: v0.3.0 Released (February 26, 2026)

## v0.3.0 Completed

### Core Array Types
- [x] `PyArray<T, D>` - Generic N-dimensional NumPy array wrapper
- [x] Fixed-rank aliases: `PyArray0` through `PyArray6`
- [x] `PyArrayDyn<T>` - Dynamic-rank arrays
- [x] `PyReadonlyArray` - Shared, read-only borrow of NumPy memory
- [x] `PyReadwriteArray` - Exclusive mutable borrow of NumPy memory
- [x] `PyArray0Methods` and `PyArrayMethods` traits

### Type Support
- [x] `f32`, `f64` - Single and double precision float
- [x] `i32`, `i64`, `u32`, `u64`, `i16`, `u16`, `i8`, `u8`
- [x] `Complex<f32>`, `Complex<f64>` (via `num-complex`)
- [x] Bool arrays
- [x] `datetime64`, `timedelta64` (via `datetime` module)

### Conversions
- [x] `ToPyArray` trait: `ndarray::Array<T,D>` -> `PyArray<T,D>` (zero-copy)
- [x] `as_array()`: `PyArray<T,D>` -> `ndarray::ArrayView<T,D>` (zero-copy when contiguous)
- [x] `as_array_mut()`: mutable ArrayViewMut via `PyReadwriteArray`
- [x] Automatic contiguous-buffer fallback for strided/non-contiguous arrays
- [x] C-order and Fortran-order layout detection and handling

### Type Coercion
- [x] `PyArrayLike<T, D, TypeConstraint>` - Accept array-like Python objects
- [x] `AllowTypeChange` - Implicit type coercion at boundaries
- [x] `TypeMustMatch` - Strict dtype checking
- [x] Fixed-rank `PyArrayLike0` through `PyArrayLike6` and `PyArrayLikeDyn`

### ndarray 0.17 Compatibility (Core Purpose)
- [x] All internal type references use ndarray 0.17 APIs
- [x] No ndarray 0.16 dependencies
- [x] Eliminates version conflict with `scirs2-linalg`, `scirs2-stats`, `scirs2-fft`, etc.
- [x] Direct `ArrayView`/`Array` interop with all SciRS2 crates

### Optional Features
- [x] `nalgebra` feature: `as_matrix()` / `as_matrix_mut()` for `nalgebra::MatrixView`
- [x] `ToPyArray` impl for `nalgebra::Matrix`

### Unsafe FFI
- [x] `npyffi` module: raw bindings to NumPy C API (`ndarraytypes.h`, `npy_common.h`, etc.)
- [x] `get_array_module()` - access the `numpy.core` Python module
- [x] Array metadata: `shape()`, `strides()`, `ndim()`, `len()`, `is_empty()`
- [x] Memory flags: `is_c_contiguous()`, `is_fortran_contiguous()`

### Strings
- [x] `strings` module: fixed-width string array support (`|S<N>` dtype)
- [x] `PyFixedUnicode` and `PyFixedString` for structured array string fields

### Error Handling
- [x] `NotContiguousError` for non-contiguous array access
- [x] `FromVecError` for invalid shape construction
- [x] All errors surface as Python exceptions via `PyErr`

## v0.4.0 Roadmap

### Full numpy API Compatibility
- [ ] `numpy.array_protocol` (`__array__` / `__array_interface__`) support
- [ ] Structured dtype support (record arrays with named fields)
- [ ] Masked array support (`numpy.ma`)
- [ ] Array subclass support (e.g., accepting `pandas.Series`)

### DLPack Support
- [ ] `__dlpack__` and `__dlpack_device__` protocol for zero-copy GPU/CPU tensor exchange
- [ ] PyTorch tensor interop via DLPack
- [ ] JAX array interop via DLPack
- [ ] Enable GPU tensors (CUDA) to be passed without CPU roundtrip

### Performance
- [ ] SIMD-accelerated copy for non-contiguous-to-contiguous coercion
- [ ] Benchmark conversion overhead vs upstream rust-numpy
- [ ] Profile allocation patterns for large array round-trips

### Type System
- [ ] `PyUntypedArray` for accepting arrays without known element type at compile time
- [ ] Runtime dtype inspection: `array.dtype_name()`, `array.itemsize()`
- [ ] Extended integer types: `i128`, `u128` where NumPy supports them

### Documentation and Tests
- [ ] Comprehensive doctests for all public APIs
- [ ] Python-side pytest tests comparing output with upstream rust-numpy behavior
- [ ] Migration guide: `rust-numpy` -> `scirs2-numpy`

## Known Issues

- Non-contiguous arrays (e.g., transposed NumPy arrays with non-standard strides) trigger a silent copy; this is correct behavior but worth documenting clearly.
- The `datetime64` support is incomplete for all NumPy datetime units; only `ns` (nanoseconds) is fully tested.
- `nalgebra` integration requires square-shaped arrays for `Matrix` types; dynamic-shape nalgebra matrices are supported via `DMatrix`.
- Mutable borrow (`PyReadwriteArray`) requires exclusive access; passing the same NumPy array to two `readwrite()` calls simultaneously will panic (this is intentional and enforced by Rust's borrow checker through PyO3's lifetime tracking).