numpy-ts 0.4.0 → 0.5.0

package/README.md

@@ -1,368 +1,274 @@
 # numpy-ts
 
-Complete NumPy implementation for TypeScript and JavaScript
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![npm version](https://img.shields.io/npm/v/numpy-ts)](https://www.npmjs.com/package/numpy-ts)
+![bundle size](https://img.shields.io/bundlephobia/minzip/numpy-ts)
 ![Under Construction](https://img.shields.io/badge/Under%20Construction-red)
 
-**⚠️ WARNING: Under active development. API may change.**
+```
+                                        _            
+ _ __  _   _ _ __ ___  _ __  _   _ ____| |_ ___ 
+| '_ \| | | | '_ ` _ \| '_ \| | | |____| __/ __)
+| | | | |_| | | | | | | |_) | |_| |    | |_\__ \
+|_| |_|\__,_|_| |_| |_| .__/ \__, |     \__(___/              
+                      |_|    (___/                
+```
 
----
+Complete NumPy implementation for TypeScript and JavaScript
 
-## What is numpy-ts?
+> **⚠️ Under active development** — API may change before v1.0
 
-A complete NumPy 2.0+ implementation for TypeScript/JavaScript, validated against Python NumPy.
+A faithful NumPy 2.0+ implementation for TypeScript/JavaScript, validated against Python NumPy. **128 of 333 NumPy functions (38.4% complete)** covering array creation, manipulation, linear algebra, reductions, and more.
 
-**Goals:**
-- **100% API Coverage** - All NumPy functions and operations
-- **Type Safety** - Full TypeScript support with inference
-- **Correctness** - Cross-validated against Python NumPy
-- **Cross-Platform** - Node.js and browsers
+```bash
+npm install numpy-ts
+```
 
-**Non-Goals:**
-- Matching NumPy's C-optimized performance (initially)
-- C API compatibility
+## Why numpy-ts?
 
----
+- **📊 Extensive API** — 120+ NumPy functions with 1365+ tests validated against Python NumPy
+- **✅ NumPy-validated** — 1365+ test cases cross-validated against Python NumPy
+- **🔒 Type-safe** — Full TypeScript support with shape and dtype inference
+- **🌐 Universal** — Works in Node.js and browsers with .npy/.npz file support
+- **🎯 Zero dependencies** — Pure TypeScript, no heavy external libraries
 
-## Quick Example
+## Quick Start
 
 ```typescript
 import * as np from 'numpy-ts';
 
-// Create arrays (default float64 dtype)
-const A = np.array([[1, 2], [3, 4]]);
-const B = np.zeros([2, 2]);
-
-// Create arrays with specific dtypes (11 types supported)
-const intArr = np.ones([3, 3], 'int32');
-const floatArr = np.arange(0, 10, 1, 'float32');
-const boolArr = np.array([1, 0, 1], 'bool');
-const bigIntArr = np.array([1n, 2n, 3n], 'int64');  // BigInt support
+// Array creation with dtype support
+const A = np.array([[1, 2], [3, 4]], 'float32');
+const B = np.ones([2, 2], 'int32');
 
-// All operations preserve dtype or follow NumPy promotion rules
-const result = intArr.add(5);  // Stays int32
-const promoted = intArr.add(floatArr);  // Promotes to float32
+// Broadcasting and chained operations
+const result = A.add(5).multiply(2);
 
-// Matrix operations
+// Linear algebra
 const C = A.matmul(B);
-const eigenvalues = np.linalg.eig(A);
-
-// Slicing (string-based syntax)
-const row = A.slice('0', ':');  // First row
-const col = A.col(1);            // Second column
-
-// Broadcasting (fully implemented!)
-const scaled = A.add(5).multiply(2);
-
-// Advanced broadcasting examples:
-const row = np.array([1, 2, 3, 4]);        // (4,)
-const col = np.array([[1], [2], [3]]);     // (3, 1)
-const result = col.multiply(row);           // (3, 4) via broadcasting!
-
-// Reductions
-const total = A.sum();                // Sum all elements
-const columnMeans = A.mean(0);        // Mean along axis 0
-const rowMaxs = A.max(1, true);       // Max along axis 1, keep dims
-
-// Comparisons (return boolean arrays as uint8)
-const mask = A.greater(5);            // Element-wise A > 5
-const equal = A.equal(B);             // Element-wise A == B
-const inRange = A.greater_equal(0);   // A >= 0
-
-// Tolerance comparisons (for floating point)
-const close = A.isclose(B);           // Element-wise closeness
-const allClose = A.allclose(B);       // True if all elements close
-
-// Reshape operations (view vs copy semantics)
-const reshaped = A.reshape(4, 1);     // View if C-contiguous, copy otherwise
-const flat = A.flatten();             // Always returns a copy
-const ravel = A.ravel();              // View if C-contiguous, copy otherwise
-const transposed = A.transpose();      // Always returns a view
-const squeezed = A.squeeze();          // Always returns a view
-const expanded = A.expand_dims(0);     // Always returns a view
-
-// View tracking (NumPy-compatible)
-const view = A.slice('0:2', '0:2');
-console.log(view.base === A);         // true - view tracks base array
-console.log(view.flags.OWNDATA);      // false - doesn't own data
-console.log(A.flags.OWNDATA);         // true - owns data
-
-// Memory layout flags
-console.log(A.flags.C_CONTIGUOUS);    // true - C-order (row-major)
-console.log(A.flags.F_CONTIGUOUS);    // false - not Fortran-order
-
-// Random
-const random = np.random.randn([100, 100]);
-
-// I/O (Node.js)
-np.save('matrix.npy', A);
-const loaded = np.load('matrix.npy');
-```
+const trace = A.trace();
 
----
-
-## Architecture
+// Reductions with axis support
+const colMeans = A.mean(0);  // [2.0, 3.0]
 
-Pure TypeScript implementation with three layers:
-
-```
-┌────────────────────────────────┐
-│    NumPy-Compatible API        │
-└────────────┬───────────────────┘
-             │
-┌────────────┴───────────────────┐
-│  NDArray (Memory & Views)      │
-│  Broadcasting, Slicing, DTypes │
-└────────────┬───────────────────┘
-             │
-┌────────────┴───────────────────┐
-│  TypeScript/JavaScript Core    │
-│  Computational Engine          │
-└────────────────────────────────┘
+// NumPy-style slicing with strings
+const row = A.slice('0', ':');    // A[0, :]
+const submatrix = A.slice('0:2', '1:');  // A[0:2, 1:]
 ```
 
-Built from scratch for correctness and NumPy compatibility.
-
----
+## Features
+
+### API Coverage
+
+Progress toward complete NumPy API compatibility:
+
+| Category | Complete | Total | Status |
+|----------|----------|-------|--------|
+| **Hyperbolic** | 6/6 | 100% | ✅ |
+| **Comparison** | 9/10 | 90% | 🟡 |
+| **Trigonometric** | 10/12 | 83% | 🟡 |
+| **Arithmetic** | 13/19 | 68% | 🟡 |
+| **Broadcasting** | 2/3 | 67% | 🟡 |
+| **Linear Algebra** | 6/9 | 67% | 🟡 |
+| **Array Creation** | 17/32 | 53% | 🟡 |
+| **Array Manipulation** | 18/35 | 51% | 🟡 |
+| **Reductions** | 11/30 | 37% | 🔴 |
+| **Indexing** | 3/20 | 15% | 🔴 |
+| **Bit Operations** | 0/9 | 0% | 🔴 |
+| **Exponential** | 0/9 | 0% | 🔴 |
+| **FFT** | 0/18 | 0% | 🔴 |
+| **Gradient** | 0/4 | 0% | 🔴 |
+| **I/O** | 0/8 | 0% | 🔴 |
+| **Linear Algebra (linalg)** | 0/19 | 0% | 🔴 |
+| **Logic** | 0/12 | 0% | 🔴 |
+| **Other Math** | 0/11 | 0% | 🔴 |
+| **Random** | 0/17 | 0% | 🔴 |
+| **Rounding** | 0/7 | 0% | 🔴 |
+| **Searching** | 0/6 | 0% | 🔴 |
+| **Set Operations** | 0/7 | 0% | 🔴 |
+| **Sorting** | 0/6 | 0% | 🔴 |
+| **Statistics** | 0/9 | 0% | 🔴 |
+
+**Overall: 128/333 functions (38.4% complete)**
+
+See the complete [API Reference](docs/API-REFERENCE.md) for detailed function list.
+
+### Data Types (dtypes)
+
+NumPy-compatible type system with automatic promotion:
+
+| DType | NumPy | numpy-ts | Notes |
+|-------|-------|----------|-------|
+| **Floating Point** ||||
+| `float64` | ✅ | ✅ | Default dtype |
+| `float32` | ✅ | ✅ | |
+| `float16` | ✅ | ⚠️ | Planned (half-precision) |
+| **Signed Integers** ||||
+| `int64` | ✅ | ✅ | Uses BigInt |
+| `int32` | ✅ | ✅ | |
+| `int16` | ✅ | ✅ | |
+| `int8` | ✅ | ✅ | |
+| **Unsigned Integers** ||||
+| `uint64` | ✅ | ✅ | Uses BigInt |
+| `uint32` | ✅ | ✅ | |
+| `uint16` | ✅ | ✅ | |
+| `uint8` | ✅ | ✅ | |
+| **Other Numeric** ||||
+| `bool` | ✅ | ✅ | Stored as uint8 |
+| `complex64` | ✅ | ❌ | Not yet supported |
+| `complex128` | ✅ | ❌ | Not yet supported |
+| **Non-Numeric** ||||
+| `str_` | ✅ | ❌ | Not planned |
+| `bytes_` | ✅ | ❌ | Not planned |
+| `object_` | ✅ | ❌ | Not planned |
+| `datetime64` | ✅ | ❌ | Future consideration |
+| `timedelta64` | ✅ | ❌ | Future consideration |
+
+**Supported: 11/20 numeric dtypes** • Complex and temporal types planned for future releases
+
+### NumPy Memory Model
+
+- **View tracking** — `base` attribute and `OWNDATA` flag
+- **Strided arrays** — C/F contiguous flags for memory layout
+- **Zero-copy ops** — Views for slicing, transpose, reshape (when possible)
 
-## Key Features
-
-### Comprehensive NumPy API
-- **Array creation**: `zeros`, `ones`, `arange`, `linspace`, `eye` (all support dtype parameter)
-- **Arithmetic operations**: `add`, `subtract`, `multiply`, `divide` with broadcasting
-- **Linear algebra**: `matmul`, `dot`, `transpose`
-- **Reductions**: `sum`, `mean`, `std`, `min`, `max` with axis support
-- **DTypes**: 11 types supported (float32/64, int8/16/32/64, uint8/16/32/64, bool)
-  - Full dtype preservation across operations
-  - NumPy-compatible type promotion
-  - BigInt support for int64/uint64
-- **View tracking**: `base` attribute tracks view relationships
-- **Memory flags**: `C_CONTIGUOUS`, `F_CONTIGUOUS`, `OWNDATA`
-- **Comparisons**: `greater`, `less`, `equal`, `isclose`, `allclose`
-- **Reshaping**: `reshape`, `flatten`, `ravel`, `transpose`, `squeeze`, `expand_dims`
-
-### TypeScript Native
 ```typescript
-// Full type inference
-const arr = np.zeros([3, 4]);  // Type: NDArray<Float64>
-arr.shape;  // Type: readonly [3, 4]
-arr.sum();  // Type: number
+const arr = np.ones([4, 4]);
+const view = arr.slice('0:2', '0:2');
 
-// Type-safe slicing
-arr.slice('0:2', ':');  // Returns NDArray
-arr.get([0, 1]);        // Returns number
+console.log(view.base === arr);      // true - view tracks base
+console.log(view.flags.OWNDATA);     // false - doesn't own data
+console.log(arr.flags.C_CONTIGUOUS); // true - row-major layout
 ```
 
-### Slicing Syntax
-
-Since TypeScript doesn't support Python's `arr[0:5, :]` syntax, we use strings:
-
-```typescript
-// String-based (primary)
-arr.slice('0:5', '1:3');     // arr[0:5, 1:3]
-arr.slice(':', '-1');        // arr[:, -1]
-arr.slice('::2');            // arr[::2]
+## Architecture
 
-// Convenience helpers
-arr.row(0);                  // arr[0, :]
-arr.col(2);                  // arr[:, 2]
-arr.rows(0, 5);              // arr[0:5, :]
-arr.cols(1, 3);              // arr[:, 1:3]
 ```
-
-### Broadcasting
-
-Automatic NumPy-style broadcasting:
-
-```typescript
-const a = np.ones([3, 4]);
-const b = np.arange(4);
-const c = a.add(b);  // (3, 4) + (4,) → (3, 4)
+┌───────────────────────────────────┐
+│  NumPy-Compatible API             │
+│  Broadcasting, DType Promotion    │
+└─────────────────┬─────────────────┘
+                  │
+┌─────────────────┴─────────────────┐
+│  NDArray (Views & Memory Mgmt)    │
+│  Strided Arrays, Base Tracking    │
+└─────────────────┬─────────────────┘
+                  │- - - - - - - - - - - - - - - - - - - ┐  
+┌─────────────────┴─────────────────┐  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ┴ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+│  TypeScript / JavaScript Core     │  │  WASM Compute Engine (Future)     │
+│  Computational Engine             │  │  Optimized BLAS / arithmetic      │
+└───────────────────────────────────┘  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
 ```
 
----
-
-## Installation
+Pure TypeScript implementation built from scratch for correctness and NumPy compatibility.
 
-```bash
-npm install numpy-ts
-```
+## Performance
 
-```typescript
-import * as np from 'numpy-ts';
-```
+![Benchmark Results](benchmarks/results/plots/latest.png)
 
----
+See [benchmarks/README.md](benchmarks/README.md) for detailed performance analysis.
 
-## Documentation
+## File I/O
 
-### User Documentation
-- [API-REFERENCE.md](https://github.com/dupontcyborg/numpy-ts/blob/main/docs/API-REFERENCE.md) - Complete API checklist
+Read and write `.npy` and `.npz` files with Node.js or browsers.
 
-### Developer Documentation
-- [TESTING-GUIDE.md](https://github.com/dupontcyborg/numpy-ts/blob/main/docs/TESTING-GUIDE.md) - How to add tests (unit, validation, benchmarks)
-- [benchmarks/README.md](https://github.com/dupontcyborg/numpy-ts/blob/main/benchmarks/README.md) - Performance benchmarking guide
+### Node.js
 
----
+```typescript
+import { load, save, savez, savez_compressed } from 'numpy-ts/node';
 
-## Testing
+save('array.npy', arr);
+const arr = load('array.npy');
 
-Two-tier testing strategy:
+savez('arrays.npz', { a: arr1, b: arr2 });
+const { a, b } = load('arrays.npz');
+```
 
-1. **Unit Tests** - Test our implementation
-2. **Python Comparison** - Validate against NumPy
+### Browser
 
 ```typescript
-// Unit test
-it('creates 2D array of zeros', () => {
-  const arr = np.zeros([2, 3]);
-  expect(arr.shape).toEqual([2, 3]);
-  expect(arr.sum()).toBe(0);
-});
-
-// NumPy validation (cross-checked against Python)
-it('matmul matches NumPy', () => {
-  const A = np.array([[1, 2], [3, 4]]);
-  const B = np.array([[5, 6], [7, 8]]);
-  const result = A.matmul(B);
-
-  const npResult = runNumPy(`
-    A = np.array([[1, 2], [3, 4]])
-    B = np.array([[5, 6], [7, 8]])
-    result = A @ B
-  `);
-
-  expect(result.toArray()).toEqual(npResult);
-});
-
-// Edge case validation
-it('int8 overflow wraps like NumPy', () => {
-  const arr = np.array([127], 'int8');
-  const result = arr.add(1);
-  expect(result.get([0])).toBe(-128);  // Wraps like NumPy
-});
-```
-
----
+import * as np from 'numpy-ts';
 
-## Design Decisions
+// Parse fetched .npy file
+const response = await fetch('array.npy');
+const arr = np.parseNpy(await response.arrayBuffer());
 
-**Pure TypeScript Implementation**
-- Built from scratch without heavy dependencies
-- Focus on correctness and NumPy compatibility
+// Serialize for download
+const bytes = np.serializeNpy(arr);
+```
 
-**BigInt for int64/uint64**
-- Exact representation over convenience
-- No precision loss (different type but fully accurate)
+> **Why separate imports?** The `/node` entry includes Node.js `fs` usage. Keeping it separate ensures browser bundles stay clean.
 
-**String-Based Slicing**
-- `arr.slice('0:5', ':')` instead of `arr[0:5, :]`
-- TypeScript limitation, Pythonic compromise
+## Examples
 
-**View Tracking**
-- Track base array with `base` attribute
-- Zero-copy optimizations where possible
-- Matches NumPy semantics
+### Broadcasting
 
-**Correctness First**
-- Validate against Python NumPy before optimizing
-- Performance improvements (WASM/SIMD) come later
+```typescript
+const matrix = np.ones([3, 4]);     // (3, 4)
+const row = np.arange(4);           // (4,)
+const result = matrix.add(row);     // (3, 4) - row broadcast to each row
 
----
+const col = np.array([[1], [2], [3]]);  // (3, 1)
+const grid = col.multiply(row);         // (3, 4) - outer product via broadcasting
+```
 
-## Contributing
+### Slicing
 
-Project is in early development. We welcome contributions!
+TypeScript doesn't support Python's `arr[0:5, :]`, so we use strings:
 
-### Setup
+```typescript
+arr.slice('0:5', '1:3');     // arr[0:5, 1:3]
+arr.slice(':', '-1');        // arr[:, -1]
+arr.slice('::2');            // arr[::2]
 
-```bash
-git clone https://github.com/dupontcyborg/numpy-ts.git
-cd numpy-ts
-npm install
-npm test
+// Convenience helpers
+arr.row(0);                  // arr[0, :]
+arr.col(2);                  // arr[:, 2]
 ```
 
-### Adding New Features
-
-1. Pick a function from [API-REFERENCE.md](https://github.com/dupontcyborg/numpy-ts/blob/main/docs/API-REFERENCE.md)
-2. Follow the [TESTING-GUIDE.md](https://github.com/dupontcyborg/numpy-ts/blob/main/docs/TESTING-GUIDE.md) to add:
-   - Implementation in `src/`
-   - Unit tests in `tests/unit/`
-   - NumPy validation tests in `tests/validation/`
-   - Performance benchmarks in `benchmarks/`
-3. Ensure all tests pass: `npm test`
-4. Run benchmarks: `npm run bench:quick`
-5. Submit a pull request
+### Type Safety
 
-See [TESTING-GUIDE.md](https://github.com/dupontcyborg/numpy-ts/blob/main/docs/TESTING-GUIDE.md) for detailed instructions on adding tests.
+```typescript
+const arr = np.zeros([3, 4]);  // Type: NDArray<Float64>
+arr.shape;  // Type: readonly [3, 4]
+arr.sum();  // Type: number
+```
 
----
 
 ## Comparison with Alternatives
 
 | Feature | numpy-ts | numjs | ndarray | TensorFlow.js |
 |---------|----------|-------|---------|---------------|
-| API Coverage | 100% NumPy | ~20% | Different | ML-focused |
-| TypeScript | Native | Partial | No | Yes |
-| .npy files | Yes | No | No | No |
-| Python-compatible | Yes | Mostly | No | No |
-| Size | TBD | Small | Tiny | Large |
-
----
-
-## Benchmarking
-
-Compare numpy-ts performance against Python NumPy with auto-calibrated benchmarks:
-
-```bash
-# Quick benchmarks (~2-3 min) - 1 sample, 50ms/sample
-source ~/.zshrc && conda activate py313 && npm run bench:quick
-
-# Standard benchmarks (~5-10 min) - 5 samples, 100ms/sample (default)
-source ~/.zshrc && conda activate py313 && npm run bench
-
-# View interactive HTML report with ops/sec comparison
-npm run bench:view
-```
+| NumPy API Coverage | 128/333 (38%) | ~20% | Different | ML-focused |
+| TypeScript Native | ✅ Full | Partial | ❌ No | ✅ Yes |
+| NumPy Validated | ✅ 1365+ tests | Mostly | ❌ No | ❌ No |
+| .npy/.npz Files | ✅ v1/v2/v3 | ❌ No | ❌ No | ❌ No |
+| Broadcasting | ✅ Full | Limited | Limited | ✅ Full |
+| Bundle Size | ~50kb | ~20kb | ~5kb | ~500kb |
 
-**Both modes use the same array sizes** - only sampling strategy differs (quick for speed, standard for accuracy).
-
-### Performance Overview
-
-![Benchmark Results](https://github.com/dupontcyborg/numpy-ts/blob/main/benchmarks/results/plots/latest.png)
-
-See [benchmarks/README.md](https://github.com/dupontcyborg/numpy-ts/blob/main/benchmarks/README.md) for detailed benchmarking guide.
-
----
+## Contributing
 
-## Performance Expectations
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on:
 
-**Current (v1.0)** - Pure TypeScript:
-- 10-100x slower than NumPy
-- Focus on correctness and API completeness
+- Setting up the development environment
+- Adding new functions with tests
+- Running benchmarks
+- Submitting pull requests
 
-**Future (v2.0+)** - Optimizations:
-- WASM for compute-intensive operations
-- SIMD for vectorized operations
-- Target: 2-20x slower than NumPy
+## Documentation
 
-Correctness and completeness first, then performance.
+- **[API Reference](docs/API-REFERENCE.md)** — Complete function checklist (120+ functions)
+- **[Feature Details](docs/FEATURES.md)** — Broadcasting, dtypes, views, slicing
+- **[Contributing Guide](CONTRIBUTING.md)** — How to contribute
+- **[Testing Guide](docs/TESTING-GUIDE.md)** — Testing strategy and examples
+- **[Architecture](docs/ARCHITECTURE.md)** — System design and internals
 
----
 
 ## License
 
-[MIT License](https://github.com/dupontcyborg/numpy-ts/blob/main/LICENSE) - Copyright (c) 2025 Nicolas Dupont
-
----
-
-## Links
-
-- **NumPy**: https://numpy.org/
-- **Issues**: https://github.com/dupontcyborg/numpy-ts/issues
+[MIT License](LICENSE) — Copyright (c) 2025 Nicolas Dupont
 
 ---
 
-**Ready to bring NumPy to TypeScript + JavaScript!** ⭐
+**Bring NumPy to TypeScript!** ⭐
+[GitHub](https://github.com/dupontcyborg/numpy-ts) • [Issues](https://github.com/dupontcyborg/numpy-ts/issues) • [NumPy Docs](https://numpy.org/)