ndarray-js

ndarray-js is a reimplementation of numpy for javascript that aims to make the coding experience as similar to numpy as possible.

Documentation and interactive demo: click here.

Features

The library implements a large subset of numpy operations (see the documentation website)

// Feature 1: A parsing system that can interpret numpy code as ndarray-js instructions
x = np`np.exp(0.5 * np.linspace(0, 1, 100).reshape(5, 4, 5)).mean(axis=0)`
y = np`(${x} * ${x}) / 2`

// Equivalent code:
x = np.exp(0.5 * np.linspace(0, 1, 100).reshape(5, 4, 5)).mean({axis:0})
y = np.divide(np.multiply(x * x), 2)


// Feature 2. Handling of args and kwargs following numpy order
x = np.geomspace(1, 10, 100).reshape([10,10])
x.mean({axis: -1, keepdims: true})
x.mean(-1, true)
x.mean(-1, {keepdims: true})
np.mean(x, {axis: -1})


// Feature 3. All types of indexing: (number, start:end:step, ':', '...', list of indices, NDArray boolean mask, NDArray boolean mask, NDArray indices)
y = x.index(2, ':', mask, '...', indices, '-1:-1:-2', -1);
y = np`${x}[2, :, ${mask}, ..., ${indices}, -1:-1:-2, -1]`;

// Feature 4. Broadcasting:
mu = np.array([1.5, 0]);
x = np.random.randn([100, 2]).add(x);
norm = x.pow(2).sum({axis: -1}).pow(0.5);
x.divide_assign(norm.index(':', 'None'));
for(let point2d of x){
  console.log(point2d.tolist(), point2d.norm(), point2d.max());
  if(np.all(point2d.equal(x.index(5)))) break;
}

// Feature 5. Most of numpy: all numeric dtypes (int8..uint64, float16..64, complex64/128), linalg, fft,
// numpy.polynomial, strings/char, npy/npz/text I/O, format_float_*, numpy-exact printing, and seeded random
// streams that reproduce numpy's (np.random.seed, RandomState, default_rng/PCG64 + SeedSequence).
np.random.seed(0);
np.random.rand(3);                                   // [0.5488135, 0.71518937, 0.60276338], like numpy
np.random.default_rng(0).integers(0, 10, 5);         // [0, 0, 1, 8, 6], like numpy
np.linalg.eigvals([[0, -1], [1, 0]]);                // complex128, like numpy
np.fft.fft(np.arange(8));

Installation

Numpy-js can be used in:

• web applications: <script src="https://cdn.jsdelivr.net/npm/ndarray-js@latest/dist/index.js"></script>
• node applications: npm install ndarray-js
• jupyter notebooks with ijavascript kernel. Example.

Check the documentation website for details.

Differences with numpy

• Dtypes: bool, int8-int64, uint8-uint64 (64-bit integers are stored as JS doubles, exact up to 2**53), float16/32/64, complex64/128 and object (plus string arrays). There is no datetime64 (the business-day functions take and return 'YYYY-MM-DD' strings). sum, prod and cumsum of ints/bools are int64, like in numpy.
• JS numbers do not distinguish 2 from 2.0: np.array([1, 2]) is int32. Inside the template parser, float literals are kept as floats: np`np.array([1., 2])` is float64.
• 0-d results are returned as plain JS numbers/booleans (inside the template parser they stay typed 0-d arrays, so npnp.arange(3) - np.arange(3).mean()`` is float, as in numpy).
• Reducers take keepdims as the third argument: x.sum(axis, keepdims, dtype, out).
• Indexing with several lists/masks is orthogonal (one per axis) instead of numpy's "zipped" fancy indexing.
• Python scalars are "weak" as in numpy 2: np.array([1, 2], 'float32') + 1.5 stays float32.

Development

npm install --legacy-peer-deps
npx vitest run                         # unit tests, and differential tests against real numpy
NDARRAYJS_PYTHON=/path/to/venv/bin/python npx vitest run   # python with numpy installed (default: python3)

The tests in tests/numpy/ evaluate the same numpy expression with python/numpy and with ndarray-js (through its numpy-syntax parser) and compare values, shapes and dtype kinds (and that both raise on invalid input). They are skipped when numpy is not available. Besides hand-written cases there are generated matrices (every ufunc x dtypes x broadcasting, every reduction x axes/keepdims, ...), random expression chains (tests/tools/gen_fuzz.py) and random indexed assignments through views (tests/tools/gen_fuzz_assign.py). tests/types/ holds type-level checks of the public API (npm run typecheck), tests/unit/ JS-only behaviour and performance sanity checks.

ToDo

Not provided (yet):

• numpy.ma (masked arrays), datetime64/timedelta64 and structured dtypes (the business-day functions work on 'YYYY-MM-DD' strings).
• Philox and SFC64 bit generators, Generator.multivariate_hypergeometric(method='count').
• True O(1) strided reads: views (slices, transposes) share memory with their base like in numpy, but reading a non-contiguous view first gathers its elements (a few times slower than a plain array).

Beyond numpy, np.group_by(keys, values?, axis?, func?) splits values by the distinct entries of keys:

const g = np.group_by(['b', 'a', 'b'], [10, 20, 30]);
g.keys.tolist();                        // ['a', 'b']
g.groups.map(x => x.tolist());          // [[20], [10, 30]]
np.group_by([1, 0, 1], [1, 2, 3], {func: np.sum}).values.tolist();  // [2, 4]